Readyset Docs

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-insights

What 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, or under-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_activity or 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.
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 1h

Live 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-baseline

The 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:

FlagExports
--export-queriesCaptured queries or top queries (whichever is richer)
--export-top-queriesCumulative top queries from stats only
--export-captured-queriesQueries 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

FlagWhat 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-insightsSkip LLM analysis (faster; metrics + top queries only)
--save <name>Save the snapshot under a friendly name
--no-saveDon't persist the snapshot
--diff <baseline>Compare this run against a saved snapshot
--export-queriesExport top or captured queries to CSV
--export-top-queriesExport cumulative top queries only
--export-captured-queriesExport only the --duration capture
--jsonJSON output (for scripting)
-y, --yesAuto-accept any cache-deploy prompts
--verbosePrint 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-queries

See Snapshots and diff for the full snapshot lifecycle.

See also