Built for existing databases
Collector docs
Collector: audit.json from a running database.
When the database already exists, the collector gathers performance evidence into audit.json so the report can rank slow queries, index risk, table growth, and maintenance signals.
Upload-ready audit.json
Evidence-rich review
Works with managed Postgres
Collector evidence flow
Collect, validate, hand off, upload.
Run the CLI locally, review the files, then attach audit.json to a project before planning changes.
- Choose restricted database user
- Collect audit.json locally
- Validate file shape
- Generate handoff.md
- Upload to project audit
Collect audit.json locallydeterministic checksreview before cluster testWhen to use the collector
Use this path after you have a real production or staging database and want the report to work from your own evidence. If you are still planning the schema, start in the project builder first. The collector fits the moment when performance questions are already tied to live tables, queries, and maintenance history.
Fast path to audit.json
1. Choose a database user that can read the statistics your policy allows. 2. Run the collector from a trusted machine: npx postgresaudit collect --url "$DATABASE_URL" --out audit.json. 3. Validate the file: npx postgresaudit validate --file audit.json. 4. Generate the handoff: npx postgresaudit handoff --file audit.json --out handoff.md. 5. Review both files locally, then upload audit.json from the Tool workflow or a project audit workflow before planning a change. The uploaded file becomes a project artifact.
What it collects
The collector reads relation size, table scan counts, index usage, dead-row signals, pg_stat_statements query statistics when available, and selected settings. That evidence gives the live review enough context to separate noisy symptoms from the issues most worth inspecting.
Access checklist
Use a user that can connect to the target database and read the statistics views needed for the review. Before collection, confirm the session behavior with SQL such as: SET default_transaction_read_only = on; SHOW default_transaction_read_only; SELECT current_user;. If your policy requires schema limits, keep access scoped to the schemas you want reviewed.
Keep changes under your control
The collector prepares evidence for review. It does not upload automatically and does not write to production. Index creation, VACUUM decisions, setting changes, EXPLAIN runs, staging tests, and production rollout decisions stay with your database owner or engineering team.
Public GitHub toolkit
The public GitHub toolkit exposes the local postgresaudit layer at https://github.com/daanaagua/postgresaudit: CLI commands, synthetic examples, schemas, permission notes, privacy guidance, and tests. The private SaaS app, auth, billing, and AI workflow stay outside that repository.
Project artifact and compare loop
Upload the first audit.json as baseline collector evidence in a project. After your team applies an approved change outside the app, rerun the collector and upload the post-change audit.json. The project keeps raw JSON and summary markdown artifacts so you can download the evidence package and compare audits.
Recommended command
After you have picked the target database, user, and file handling path, run: npx postgresaudit collect --url "$DATABASE_URL" --out audit.json. Then run: npx postgresaudit validate --file audit.json. If validation passes, create review notes with: npx postgresaudit handoff --file audit.json --out handoff.md.
Managed PostgreSQL differences
RDS, Cloud SQL, Supabase, Neon, and other managed PostgreSQL platforms expose statistics differently. Some block superuser-only checks, extension installation, or provider-owned schemas. That is acceptable: the collector should export the evidence it can read and mark missing signals instead of asking for write access.
When pg_stat_statements is missing
If pg_stat_statements is missing, disabled, or not readable, query-level ranking has less signal. You can still upload audit.json for table, index, dead-row, scan, and settings signals. Copyable SQL prompt: SELECT * FROM pg_stat_statements LIMIT 1; if that fails, ask your database owner or provider whether the extension is enabled for the database.
Common failures and next steps
Connection refused usually means the URL, network allowlist, or SSL mode needs review. Permission denied usually means the restricted user cannot read a statistics view. Empty query findings usually means pg_stat_statements is missing or reset. Next step: fix the smallest access or configuration issue, rerun the collector, then compare the new audit.json before upload.
Copyable SQL prompts
Useful evidence-focused checks: SHOW server_version; SHOW default_transaction_read_only; SELECT current_database(), current_user; SELECT schemaname, relname, n_live_tup, n_dead_tup, last_analyze, last_autoanalyze FROM pg_stat_user_tables LIMIT 20; SELECT * FROM pg_stat_statements LIMIT 1;
Expected output file
The expected collector output is audit.json: a valid JSON object written locally. The validate step confirms the file shape before upload. The handoff step writes handoff.md with coverage notes, top findings, EXPLAIN requests, and upload next steps. After project upload, audit.json is saved as a project artifact; rerun after approved changes and compare audits before acting on any recommendation.
FAQ
Frequently asked questions
These answers describe the product focus: careful database evidence, clear findings, and team-approved next steps.
Do I need superuser access to run the collector?
No. The intended workflow uses a database user with enough access to gather statistics and export JSON locally.
What if pg_stat_statements is not enabled?
The collector still exports table and index signals, but query-level prioritization is much stronger when pg_stat_statements data is available. Missing pg_stat_statements should be treated as a coverage note, not a reason to grant unsafe access.
Can I use this against managed PostgreSQL services?
Yes. Managed PostgreSQL services differ: RDS, Cloud SQL, Supabase, Neon, and similar platforms may hide provider-owned schemas or block extension checks. The collector should keep the export evidence-focused and report missing evidence clearly.
What should I do after a permission failure?
Keep the user restricted. Identify the missing statistics view, grant the smallest read permission your policy allows, rerun the collector, and upload the refreshed audit.json only after local review.
Will the collector change production settings or run maintenance?
No. The collector creates evidence for review, does not upload automatically, and does not write to production. Your team decides which checks, staging tests, or maintenance steps come after the report.
What happens after I upload audit.json to a project?
The upload becomes project collector evidence. You can download the raw JSON and summary markdown from Project artifacts, rerun after an approved external change, and compare the baseline audit with the post-change audit.