rdst audit
Run a health audit on one database. RDST records its query activity and metrics, then uses AI to suggest improvements.
rdst audit collects database metrics, query activity, and recommendations in
a one-off report. For ongoing reports, use
RDST Agent.
Use a read-only account and choose a capture window that suits the workload.
Common usage
# Quick audit (no live capture)
rdst audit --target prod-orders
# Audit with a five-minute live capture of running queries
rdst audit --target prod-orders --duration 5m
# Print the full report to the terminal instead of emailing
rdst audit --target prod-orders --verbose
# Save under a friendly name for later diffing
rdst audit --target prod-orders --save march-baseline
# Compare today against an earlier baseline
rdst audit --target prod-orders --diff march-baseline
# JSON output for scripting
rdst audit --target prod-orders --json
# Skip LLM insights (faster, useful when you just want raw metrics)
rdst audit --target prod-orders --no-insightsWhat the audit collects
- Database metrics: version, database size, connection pool state, cache hit rate, read/write ratio
- Sizing assessment: cross-references instance size and utilization to
classify as
oversized,right-sized, orunder-provisioned - Cache opportunity score: a 0 to 100 score for how much Readyset caching would likely help, driven by query mix and cacheability
- Top queries: ranked by total time and call frequency, with EXPLAIN plans and rewrite suggestions
- LLM insights: structured health summary, bottleneck analysis, index recommendations, Readyset candidates, prioritized next steps
Everything above, plus:
- Live query capture: RDST watches
pg_stat_activityor the MySQL equivalent for the entire window. Queries observed during sampling are captured with wall-clock duration. - Time-series patterns: how query patterns change across the window (e.g., batch jobs kicking off at :00)
- Captured-query insights: the LLM analyzes the actual running workload, not just historical stats. Use it to compare active work with cumulative statistics.
The email-first flow
By default, RDST emails you the full HTML report and prints an actionable terminal summary. This is how it works:
$ rdst audit --target prod-orders
This is your first audit on this machine.
Enter your email: ellen@example.com
We sent a verification link to ellen@example.com. Click the link to continue ...
Waiting for verification ... ✓ Email verified.
Running audit on prod-orders ...
✓ Metrics collected
✓ Top queries ranked
✓ LLM insights generated
✓ Snapshot saved as audit_prod-orders_20260421_120402
Audit Summary - prod-orders
────────────────────────────────────────────────────────────────
Size: 482 GB → right-sized
Cache opportunity: 82/100 (HIGH)
Top query: SELECT * FROM orders WHERE customer_id = $1 ...
4.8k calls, 412ms avg
Biggest win: Deploy Readyset cache for hash a1b2c3d4e5f6
↳ rdst cache deploy --target prod-orders --mode docker
↳ rdst cache add a1b2c3d4e5f6 --target prod-orders-cache
Full report emailed to ellen@example.com
→ View Full Report: https://rdst.readyset.io/audit/01HY...The terminal summary includes commands for analyzing queries and testing caching candidates. Follow those links in the report or use the printed query hashes in your next command.
Later runs skip the verification step:
$ rdst audit --target prod-orders --duration 2m
Running audit on prod-orders (capturing queries for 2m) ...
[==========================================================] 120/120s
✓ Captured 4,837 query executions
✓ LLM insights generated
✓ Snapshot saved as audit_prod-orders_20260421_154212
Full report emailed to ellen@example.com.Print to terminal instead with --verbose
rdst audit --target prod-orders --verbose--verbose skips the email flow entirely and prints the full report inline as Rich
panels. The snapshot is still saved. There's no separate --no-email flag, verbose
is the no-email mode.
Capturing a live workload
Use --duration to sample running queries alongside cumulative statistics.
Sampling can miss queries that finish between readings.
# Quick smoke test
rdst audit --target prod-orders --duration 30s
# Representative workload capture
rdst audit --target prod-orders --duration 5m
# Long capture across a batch window
rdst audit --target prod-orders --duration 1hLive capture reads pg_stat_activity (Postgres) or SHOW FULL PROCESSLIST
(MySQL) every few seconds. Both are already-running internal views, so the
overhead on the database is minimal. Even so, generate application load into
the database while the capture is running, a 5-minute capture of an idle
database tells you very little.
Captured queries are benchmarked against a Readyset cache
During --duration, RDST also runs a built-in benchmark. If a
Readyset cache is deployed for the target (<target>-cache
exists), the captured queries are added to that cache and run against it. If no
cache is deployed, RDST offers to spin up a local Docker cache for the benchmark,
cache the captured queries there, and tear it down after the audit.
The result is a head-to-head performance block in the audit report: you see the upstream latency for each captured query alongside the latency through Readyset, without having to set any of this up manually.
Captured Query Benchmark - 5m window, 2,847 executions across 18 query shapes
──────────────────────────────────────────────────────────────────────────────────
Hash Calls Upstream avg Cache avg Speedup Cached?
──────── ────── ───────────── ─────────── ──────── ─────────
a1b2c3d4 834 412.1 ms 13.2 ms 31x ✓
f6e5d4c3 217 139.6 ms 9.8 ms 14x ✓
9a8b7c6d 1,204 1.6 ms 0.9 ms 1.8x ✓
4d3c2b1a 312 74.1 ms - - ✗ not cacheable
...
Cache verdict
✓ 5 of 18 captured queries would produce substantial speedups if cached
(total time saved ≈ 3m 42s over the 5m window).
✗ 3 queries are not cacheable in Readyset today (non-deterministic functions,
unsupported SQL features) - see per-query notes.The same numbers drive the Readyset cache opportunity score at the top of the
report. You can verify any individual line with rdst query cache-compare <hash> --target <name> afterward.
Diffing against a baseline
Use --save <name> to name a snapshot, then --diff <name> later to compare:
# Today: save a baseline
rdst audit --target prod-orders --duration 5m --save march-baseline
# Next month: compare against it
rdst audit --target prod-orders --duration 5m --diff march-baselineThe diff report highlights:
- Metrics that changed (database size, connection count, cache hit rate)
- Queries that got slower (and by how much)
- New top queries that weren't in the baseline
- Changes to the Readyset cache opportunity score
- Schema changes (new tables, dropped indexes, etc.)
See Snapshots and diff for more patterns.
Exports
The audit report is the headline output, but for ad-hoc investigation you can also extract the raw query text:
| Flag | Exports |
|---|---|
--export-queries | Captured queries or top queries (whichever is richer) |
--export-top-queries | Cumulative top queries from stats only |
--export-captured-queries | Queries captured during a --duration window only |
Each flag produces a CSV with full query text, parameters, timing, and source file info where available.
Flags reference
| Flag | What it does |
|---|---|
-t, --target <name> | Target database |
--duration <spec> | Live capture window (e.g. 30s, 5m, 1h) |
--source {auto,pg_stat_statements,activity} | Override where to read from |
--limit <N> | Top-N queries to include in LLM analysis (default 50) |
--no-insights | Skip LLM analysis (faster; metrics + top queries only) |
--save <name> | Save the snapshot under a friendly name |
--no-save | Don't persist the snapshot |
--diff <baseline> | Compare this run against a saved snapshot |
--export-queries | Export top or captured queries to CSV |
--export-top-queries | Export cumulative top queries only |
--export-captured-queries | Export only the --duration capture |
--json | JSON output (for scripting) |
-y, --yes | Auto-accept any cache-deploy prompts |
--verbose | Print full report to terminal instead of emailing |
Audit subcommands
rdst audit list # all past audit runs
rdst audit list --target prod-orders # only runs for a specific target
rdst audit show audit_prod-orders_... # view a saved audit
rdst audit show <run_id> --export-captured-queriesSee Snapshots and diff for the full snapshot lifecycle.
See also
- Setting up a fleet: so you can run audits against more than one target at a time
rdst fleet audit: the same workflow, fanned out concurrentlyrdst cache deploy: the natural next step after an audit recommends Readyset caching