Readyset Docs

Run a deep health audit on a single database target. Captures metrics, top queries, live workload, and LLM insights.

rdst audit is the fastest way to get a complete picture of a database's health. It's safe to run on a live production database — all queries are read-only and the impact on the target is minimal.

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–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. Every query that runs is 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. This is the best signal for "what should I cache today".

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 always prints actionable next-step commands (rdst analyze --hash, rdst query show, rdst cache deploy). These are intentionally CLI-first: you will rarely want to open a browser, read a recommendation, and then come back to the terminal to type the command by hand.

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 is no separate --no-email flag — verbose is the no-email mode.

Capturing a live workload

The single biggest lever for audit quality is --duration. Without it, the LLM only sees cumulative pg_stat_statements / performance_schema data. With it, the LLM also sees what is actually running on the database right now.

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

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

See Snapshots and diff for the full snapshot lifecycle.

rdst audit