docs: pre-release (v0.8.0) docs updates

Author: radim

README.md

@@ -247,6 +247,7 @@ See the [Tutorial](TUTORIAL.md) for live database setup, SSE transport, and Clau
 - **[Tutorial](TUTORIAL.md)** for offline, online, and multi-node workflows with full tool reference
 - **[Multi-node statistics](docs/multi-node-stats.md)** for cluster-wide stats collection, aggregation rules, and replica imbalance detection
 - **[Configuration reference](docs/dryrun-toml.md)** for `dryrun.toml` profiles, conventions, and lint rules
+- **[Security overview](SECURITY.md)** for the CLI/MCP split, masking, and telemetry opt-out
 - **[boringSQL](https://boringsql.com)**, the blog and project home
 - **[RegreSQL](https://github.com/boringsql/regresql)**, SQL regression testing and **`dryrun`**'s companion tool
 

TUTORIAL.md

@@ -103,7 +103,7 @@ Privileges:
 dryrun init --db "$DATABASE_URL"
 ```
 
-Creates `dryrun.toml`, the `.dryrun/` directory, and `.dryrun/schema.json`. Snapshot history lives in `~/.dryrun/history.db` (shared across projects, keyed by `(project_id, database_id)`).
+Creates `dryrun.toml`, the `.dryrun/` directory, and `.dryrun/schema.json`. Snapshot history lives in `~/.dryrun/history.db` (shared across projects, keyed by `(project_id, database_id)`). If a `data-masking-policy.yml` resolves, `init` masks planner stats in-process before writing; for projects with PII, set `require_masks = true` in `dryrun.toml` to fail closed when the policy is missing. See [SECURITY.md](SECURITY.md).
 
 ### 3. Snapshots and diffing
 
@@ -151,15 +151,15 @@ All tools available including EXPLAIN ANALYZE (runs in rolled-back transactions,
 
 For setups with one primary and N replicas serving different query patterns. Activity counters (`seq_scan`, `idx_scan`, `n_dead_tup`) differ per node and only live where the queries actually run, on the replicas. dryrun captures schema + planner stats from the primary and activity stats from each replica, then aggregates them.
 
-In v0.6.0 a snapshot is split into three rows in `~/.dryrun/history.db`: `schema`, `planner_stats`, `activity_stats`. `snapshot take` writes the first two from the primary; `snapshot activity` writes one `activity_stats` row per replica, tagged with `--label`.
+A snapshot is split into three rows in `~/.dryrun/history.db`: `schema`, `planner_stats`, `activity_stats`. `snapshot take` writes all three from the primary, with the activity row labeled `primary`. `snapshot activity` writes one additional `activity_stats` row per replica, tagged with `--label`. Planner stats are masked per `data-masking-policy.yml` at capture time; see [SECURITY.md](SECURITY.md).
 
-### 1. Schema + planner stats from the primary
+### 1. Schema + planner + activity from the primary
 
 ```sh
 dryrun --profile primary snapshot take
 ```
 
-Refuses to run on a standby. Writes `schema` (DDL) + `planner_stats` (`reltuples`, `relpages`, `pg_statistic`) to history.
+Refuses to run on a standby. Writes `schema` (DDL), `planner_stats` (`reltuples`, `relpages`, `pg_statistic`; masked per policy), and one `activity_stats` row labeled `primary`.
 
 ### 2. Activity stats from each replica
 
@@ -293,6 +293,6 @@ GRANT pg_monitor TO your_readonly_user;
 
 **"invalid schema JSON"** - The file must be a valid SchemaSnapshot. If you renamed fields or edited by hand, re-dump from the database.
 
-**Multi-node stats not showing** - Run `dryrun snapshot list` and confirm you see both `schema` rows (from `snapshot take` on the primary) and `activity_stats` rows (from `snapshot activity --label ...` on each replica) sharing the same `schema_ref_hash`. Activity captured before any schema exists needs `--allow-orphan` and won't reattach automatically.
+**Multi-node stats not showing** - Run `dryrun snapshot list` and confirm you see a `schema` row plus `activity_stats` rows for each node sharing the same `schema_ref_hash`. The primary contributes its own `activity_stats` row (labeled `primary`) via `snapshot take`; each replica contributes one via `snapshot activity --label ...`. Activity captured before any schema exists needs `--allow-orphan` and won't reattach automatically.
 
 

docs/multi-node-stats.md

@@ -6,13 +6,13 @@ dryrun merges statistics from every node in your cluster into one snapshot, then
 
 ## Collecting stats
 
-A snapshot in v0.6.0 is split into three rows in `~/.dryrun/history.db`:
+A snapshot is split into three rows in `~/.dryrun/history.db`:
 
 - **`schema`**: DDL (tables, columns, constraints, indexes, partitions, functions, enums, extensions, GUCs).
-- **`planner_stats`**: what the planner uses (`reltuples`, `relpages`, `pg_statistic`).
+- **`planner_stats`**: what the planner uses (`reltuples`, `relpages`, `pg_statistic`). Masked per `data-masking-policy.yml` at capture time; see [SECURITY.md](../SECURITY.md).
 - **`activity_stats`**: runtime counters (`seq_scan`, `idx_scan`, `n_dead_tup`, `last_vacuum`).
 
-`snapshot take` writes `schema` + `planner_stats` from the primary. `snapshot activity` writes one `activity_stats` row per replica, tagged with a `--label`. Activity rows attach to the most recent matching schema by `schema_ref_hash`.
+`snapshot take` writes all three rows from the primary, with the activity row labeled `primary`. `snapshot activity` writes one `activity_stats` row per replica, tagged with a `--label`. Activity rows attach to the most recent matching schema by `schema_ref_hash`.
 
 ```
 ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
@@ -22,7 +22,9 @@ A snapshot in v0.6.0 is split into three rows in `~/.dryrun/history.db`:
 └─────┬───────┘     └──────┬──────┘     └──────┬──────┘
       │                    │                    │
       │ schema +           │ activity_stats     │ activity_stats
-      │ planner_stats      │ (label=replica1)   │ (label=replica2)
+      │ planner_stats +    │ (label=replica1)   │ (label=replica2)
+      │ activity_stats     │                    │
+      │ (label=primary)    │                    │
       ▼                    ▼                    ▼
             ~/.dryrun/history.db
        (joined by schema_ref_hash)
@@ -34,7 +36,7 @@ A snapshot in v0.6.0 is split into three rows in `~/.dryrun/history.db`:
 dryrun --profile primary snapshot take
 ```
 
-Refuses to run on a standby (`pg_is_in_recovery() = false` required). Writes one `schema` row and one `planner_stats` row.
+Refuses to run on a standby (`pg_is_in_recovery() = false` required). Writes one `schema` row, one `planner_stats` row (masked per policy), and one `activity_stats` row labeled `primary`.
 
 ### Activity stats from replicas
 
@@ -152,7 +154,7 @@ A connection pooler is supposed to round-robin across three replicas, but `compa
 
 ## Automating collection
 
-Activity captures are lightweight and safe for cron. Take the primary snapshot first so activity rows have a `schema_ref_hash` to attach to:
+Activity captures are lightweight and safe for cron. Take the primary snapshot first so replica activity rows have a `schema_ref_hash` to attach to:
 
 ```sh
 # /etc/cron.d/dryrun-stats
@@ -162,16 +164,10 @@ Activity captures are lightweight and safe for cron. Take the primary snapshot f
 15 2 * * * app dryrun --profile replica3 snapshot activity --from "$REPLICA3_DB" --label replica3
 ```
 
-`snapshot take` is idempotent on a quiet schema; repeated runs produce the same `schema_ref_hash`, so re-attaching activity rows is automatic. Run it nightly alongside activity captures, or only after migrations if you want fewer rows in history.
+`snapshot take` already captures the primary's own activity row (labeled `primary`), so there is no separate `snapshot activity` line for the primary, and the command itself refuses to run on the primary. `snapshot take` is idempotent on a quiet schema: repeated runs produce the same `schema_ref_hash`, so re-attaching activity rows is automatic. Run it nightly alongside activity captures, or only after migrations if you want fewer rows in history.
 
 ## Snapshot storage
 
-Snapshots live in `~/.dryrun/history.db`, keyed by `(project_id, database_id, kind, schema_ref_hash, node_label)`. Activity rows from `snapshot activity` carry their `--label` in `node_label`; rows from `snapshot take` use an empty label. `is_standby` is auto-detected from `pg_is_in_recovery()` and enforced by the CLI: `take` requires false, `activity` requires true.
+Snapshots live in `~/.dryrun/history.db`, keyed by `(project_id, database_id, kind, schema_ref_hash, node_label)`. Activity rows from `snapshot activity` carry their `--label` in `node_label`; the activity row from `snapshot take` uses `primary`. `is_standby` is auto-detected from `pg_is_in_recovery()` and enforced by the CLI: `take` requires false, `activity` requires true.
 
-To export a snapshot for sharing or archiving:
-
-```sh
-dryrun snapshot export
-```
-
-Writes `{project_id}/{database_id}/{timestamp}-{hash}.json.zst`. The zstd-compressed JSON contains the schema row plus all attached planner and activity rows.
+To share a snapshot across machines, use `snapshot push` / `snapshot pull`. They move `history.db` byte-for-byte between stores without re-masking or re-transforming. See [SECURITY.md](../SECURITY.md) for the sharing trust model.