Create audit, EXPLAIN, benchmark spec, fixture prep, benchmark artifact, and handoff files locally. Dry-run stays non-executing; fixture writes and measured benchmark runs stay sandbox/staging only.
The CLI does not upload automatically, store credentials, tune the database, or execute production changes. It prepares review files your team can inspect before attaching them to a project.
npx postgresaudit collect --url "$DATABASE_URL" --out audit.jsonnpx postgresaudit explain --url "$DATABASE_URL" --query-file query.sql --out explain.jsonnpx postgresaudit benchmark-plan --schema schema.sql --original-query before.sql --optimized-query after.sql --target-rows 10000000 --environment sandbox --out benchmark.jsonnpx postgresaudit benchmark-plan --schema schema.sql --original-query before.sql --optimized-query after.sql --target-rows 10000000 --environment sandbox --fixture-config fixture-config.json --out benchmark.jsonnpx postgresaudit benchmark-prepare --spec benchmark.json --dry-run --out fixture-prep.jsonnpx postgresaudit benchmark-prepare --spec benchmark.json --url "$BENCHMARK_DATABASE_URL" --i-understand-benchmark-runs-sql --out fixture-prep.jsonnpx postgresaudit benchmark-run --spec benchmark.json --dry-run --out benchmark-artifact.jsonnpx postgresaudit benchmark-run --spec benchmark.json --url "$BENCHMARK_DATABASE_URL" --i-understand-benchmark-runs-sql --out benchmark-artifact.jsonnpx postgresaudit validate --file audit.jsonnpx postgresaudit handoff --file audit.json --out handoff.mdThe explain command runs EXPLAIN (FORMAT JSON, BUFFERS) and does not run your query. It accepts only one query: a single SELECT / WITH statement. It rejects mutation, DDL, and multiple statements before writing explain.json.
The benchmark-plan command reads local schema, original query, and optimized query files, then writes a benchmark spec. It does not connect to a database, does not execute SQL, and does not support production benchmark execution. Use --environment sandbox or --environment staging for the plan. The spec now includes a schema-aware fixture SQL plan that turns parsed tables and columns into reviewable insert statements. For simple DDL it follows foreign-key dependency order, tags enum/status distributions, and derives simple CHECK-derived enum values for review. It also tags basic hotspot dimension columns and recent-heavy time-series columns so the generated fixture SQL is less uniform by default; it is still a plan, not an automatic data load. For stronger repeatability, pass --fixture-config fixture-config.json. The config uses postgresaudit-fixture-config-v1 and can set fixture distribution config fields like hot_key_percent, hot_row_percent, recent_row_percent, recent_days, history_days, and referenced_key_space. Invalid percentages or unsafe values are rejected, and the config hash is written into the benchmark spec inputs.
First use benchmark-prepare --dry-run to review schema import and generated fixture SQL. Live benchmark-prepare requires --url "$BENCHMARK_DATABASE_URL", --i-understand-benchmark-runs-sql, and a sandbox/staging spec; it imports schema and fills fixture data locally. Then benchmark-run --dry-run reads benchmark.json and writes benchmark-artifact.json with planned steps, hashes, and an inconclusive verdict. Dry-run does not connect to a database and does not execute SQL. A measured run requires --url "$BENCHMARK_DATABASE_URL", --i-understand-benchmark-runs-sql, and a sandbox/staging spec; it runs local EXPLAIN ANALYZE only. Both benchmark-prepare and benchmark-run artifacts include fixture_plan_summary with target rows, table count, distribution_strategies, and column role counts, so reviewers can see the fixture data shape before trusting benchmark evidence. Measured benchmark-run artifacts also keep per-run samples for execution time, planning time, rows, buffers, temp writes, and scan type, which the Web app can show as a run samples trend. The Web app does not execute SQL.
Use measured benchmark mode only against an already prepared sandbox or staging database. It sets timeouts, uses read-only session settings, rejects production benchmark specs, and records aggregate before/after metrics for review before upload.
Adding --analyze will run the query, so the CLI also requires explicit confirmation with --i-understand-analyze-runs-query. Use it only after review, staging checks, owner approval, and a manual check for side-effecting functions inside the SELECT / WITH query.
The CLI writes audit.json, explain.json, and handoff.md on your machine. Upload stays manual through the Tool workflow after your team approves the file contents. explain.json can be uploaded manually as EXPLAIN evidence. No automatic upload. In a project audit workflow, uploaded JSON is saved as a project artifact with raw JSON and summary markdown downloads.
Upload baseline audit.json, apply the approved change outside the app, rerun the collector, upload the post-change audit, then compare audits in the project.
The handoff includes coverage notes, top findings, EXPLAIN requests, and upload next steps so a database owner, project owner, or DBA can continue the review without guessing what evidence is missing.
The CLI prepares evidence and review notes only. Index creation, VACUUM decisions, setting changes, EXPLAIN ANALYZE runs, staging tests, rollbacks, and production rollout stay with your engineering team.