Getting Started
Install RDST, configure your first target, and walk through every core workflow — query analysis, audit, and Readyset caching.
This page takes you from a fresh machine to running every core RDST workflow against a real database.
Requirements
| Requirement | Notes |
|---|---|
| Python | 3.10 or newer |
| Database | PostgreSQL 13+ or MySQL 8.0+ |
| LLM access | Your own Anthropic API key, or a free RDST trial set up during rdst init |
| Optional | Docker for rdst demo, local Readyset cache deploys, and the guided tour |
RDST never writes to your primary database. It issues read-only diagnostic queries
(EXPLAIN, EXPLAIN ANALYZE, pg_stat_statements, performance_schema, and
pg_stat_activity or SHOW PROCESSLIST for live monitoring). Query text, plans,
and schema metadata are streamed to an LLM; result rows are never sent.
Install
pip install rdstuv tool install rdstIf you do not have uv:
curl -LsSf https://astral.sh/uv/install.sh | shgit clone https://github.com/readysettech/readyset.git
cd readyset/rdst
uv pip install -e .Verify with rdst version.
To upgrade later:
pip install --upgrade rdst # or: uv tool upgrade rdstRun the setup wizard
rdst initThe wizard handles four things, in order:
LLM provider. Either paste an Anthropic API key or sign up for the free RDST
trial (email-verified: $5 in credits for business emails, $1.50 for personal
addresses). You can change this later with rdst init --force.
Your first target. Enter a short name (e.g. prod-orders), database type
(postgresql or mysql), host, port, database name, and username. For the
password, enter the name of an environment variable that holds it (e.g.
PROD_ORDERS_PASSWORD). RDST never reads or stores the password itself — it
only remembers the variable name.
Test the connection. The wizard runs a read-only query to confirm the env var is set and the database is reachable.
Optionally deploy a local Readyset cache. After the target is verified, the
wizard offers to start a local Docker-based Readyset cache for it and register
the resulting <target>-cache target. Say yes for the fastest path to trying
caching; say no and you can always run
rdst cache deploy later. Skipped automatically when the
cache already exists, when the target is itself a Readyset target, or when
you're not in an interactive terminal.
Export the password in your shell before running any command:
export PROD_ORDERS_PASSWORD='your-password'If you want to try RDST without pointing at your own database, rdst demo setup && rdst demo load spins up a local PostgreSQL container with a 2-million-row DBA
StackExchange dataset. rdst demo tour walks you through every workflow against
it.
1. Find your slow queries (rdst top)
rdst top --target prod-orderstop reads pg_stat_activity (Postgres) or SHOW FULL PROCESSLIST (MySQL) every
few seconds, groups identical query shapes together, and ranks them by total time
consumed. Pass --historical to read from pg_stat_statements or
performance_schema instead for a lifetime-of-the-database view.
# Hash Total time Calls Avg time Query
1 a1b2c3d4e5f6 00:04:17 4,812 53.4 ms SELECT * FROM orders WHERE customer_id = $1 ORDER BY ...
2 f6e5d4c3b2a1 00:02:48 1,204 139.6 ms SELECT o.*, c.name FROM orders o JOIN customers c ...
3 9a8b7c6d5e4f 00:01:22 51,003 1.6 ms SELECT 1 FROM session_cache WHERE ...Every query surfaced by top is saved to the query
registry. The short hash in the first column is
what you hand to rdst analyze --hash <id> in the next step.
2. Analyze a slow query (rdst analyze)
rdst analyze --hash a1b2c3d4e5f6 --target prod-ordersRDST runs EXPLAIN and EXPLAIN ANALYZE against the query, collects relevant
schema context (including index definitions and row estimates), and produces a
structured report with a performance rating, key issues, up to three candidate
indexes, up to three semantically-equivalent rewrites, and a Readyset cache-fit
score.
Query Analysis: a1b2c3d4e5f6
Performance: FAIR (65/100)
Execution time: 412.1 ms
Rows examined: 2,847,201 (38.2% of orders)
Scan efficiency: INEFFICIENT
Key Issues
• Full index scan on orders_created_at_idx; composite needed
• Sort step: 41% of execution time
Index Recommendations
1. CREATE INDEX idx_orders_status_created
ON orders (status, created_at DESC)
WHERE status = 'shipped';
Expected impact: cuts scan ~90%, -300ms (~73%)
Readyset Cache Fit
Candidate: YES (confidence: high)
Next step: rdst cache add a1b2c3d4e5f6 --target prod-orders-cache3. Ask a question in plain English (rdst ask)
rdst ask "What were our top 10 customers by revenue last month?" --target prod-ordersRDST uses your schema — and your semantic layer,
if configured — to generate a read-only, LIMIT-bounded SQL query, show it to you
for confirmation, execute it with a timeout, and render the result.
Generated SQL:
SELECT c.id, c.name, SUM(o.total_cents) AS revenue_cents
FROM customers c
JOIN orders o ON o.customer_id = c.id
WHERE o.created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month')
AND o.created_at < DATE_TRUNC('month', NOW())
GROUP BY c.id, c.name
ORDER BY revenue_cents DESC
LIMIT 10;
Execute? [Y/n]For ambiguous or multi-step questions, add --agent to let RDST explore the schema
iteratively before generating SQL.
4. Audit the database (rdst audit)
rdst audit is the fastest way to get a complete health report — sizing verdict,
top queries, index coverage, Readyset cache opportunity score, and LLM insights.
rdst audit --target prod-orders --duration 5m--duration tells RDST to also capture live queries for a five-minute window, then
deploy a local Readyset cache (in Docker) and run each captured query through both
the upstream database and the cache for comparison. The cache-fit section of the
report is then based on real measured performance, not just plan analysis.
Default output is email. The first rdst audit run on a new machine prompts
you to verify an email address. Every subsequent audit sends the HTML report
there automatically, with a link back to a hosted version. A terminal summary is
printed either way so you always see actionable next-step commands inline. Pass
--verbose to print the full report to the terminal instead of email.
Every audit is saved. Browse past runs with rdst audit list, open one with
rdst audit show <run_id>.
5. Try Readyset caching (rdst cache)
If rdst init did not deploy a cache for you, do it now:
rdst cache deploy --target prod-orders --mode dockerThis starts a Readyset container, waits for its initial snapshot, and registers a
new RDST target named prod-orders-cache. Add the query from step 2 to the cache:
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache6. Measure the impact (rdst query cache-compare)
rdst query cache-compare a1b2c3d4e5f6 --target prod-orders --count 500 -c 10This runs 500 executions of the query against the upstream database and against the Readyset cache, with 10 concurrent workers on each side, then prints a side-by-side comparison:
Resolving targets ...
Upstream: prod-orders (PostgreSQL)
Cache: prod-orders-cache (Readyset)
Running 500 executions per target, concurrency 10 ...
[==============================] 500/500 upstream
[==============================] 500/500 cache
Results
────────────────────────────────────────────────────────────────────
Query: SELECT * FROM orders WHERE customer_id = $1 ORDER BY ...
Upstream Cache Improvement
─────────────────────── ─────────── ──────────────── ──────────────
Total executions 500 500
Total time 00:04:12 00:00:08
Throughput 2.0 qps 62.5 qps 31x
Avg latency 412 ms 13 ms 32x
p50 latency 389 ms 11 ms 35x
p95 latency 512 ms 18 ms 28x
p99 latency 847 ms 41 ms 21x
Errors 0 0
Verdict
✓ Cache provides substantial latency and throughput improvements.
✓ Tail latency (p99) improves significantly, suggesting the cache absorbs
variable load effectively.What next?
Core Concepts
Targets, the registry, the semantic layer, and how Readyset fits in.
Query Analysis
Deep-dive on top, analyze, ask, and scan.
Fleet and Audit
Audit a single database or an entire fleet. Diff snapshots over time.
Readyset Cache
Deployment modes, cache management, and benchmarking.
Claude Code integration
Drive RDST from inside Claude Code over MCP.
Getting help without leaving your terminal
rdst help answers natural-language questions about RDST itself using RDST's
bundled documentation.
rdst help # show top-level commands and common patterns
rdst help "how do I analyze a query?"
rdst help "how do I find slow queries without running a benchmark?"
rdst help "how do I set up a cache for a MySQL target?"With an LLM key configured, rdst help uses Anthropic's Haiku model to give a
tailored answer pulled from the bundled docs. Without a key, it still works —
it falls back to a keyword search of the same docs and prints the most relevant
sections. Useful when you don't have ANTHROPIC_API_KEY set yet or haven't
signed up for the free trial.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
rdst: command not found | pip/uv bin directory not on PATH | Restart your shell, or add ~/.local/bin to PATH |
Authentication failed on any command | Target's password_env points at an unexported variable | export <VAR>=... in the shell you run RDST from |
LLM timeout on rdst analyze | Large EXPLAIN plan or a slow LLM round-trip | Retry with --fast to skip EXPLAIN ANALYZE |
Import errors when running python3 rdst.py | Running from the wrong directory | Run from readyset/rdst/ |
No AWS credentials found on rdst fleet discover | AWS CLI or SSO session not configured | aws configure sso or export AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY |
If you hit something this table does not cover, run
rdst report to send feedback with
your version, redacted config, and most recent error.
RDST
A command-line toolkit for PostgreSQL and MySQL that diagnoses slow queries, recommends indexes and rewrites, answers natural-language questions about your data, audits database health across single targets or whole fleets, and deploys Readyset caches with head-to-head benchmarking.
Core Concepts
The mental model behind RDST — targets, the query registry, the semantic layer, how the LLM is used, audits and snapshots, Readyset caches, and data agents.