Getting Started
Install RDST and connect your first database. Analyze a query, run an audit, and test Readyset caching.
Install the CLI, configure a target, then run the commands below. For Continuous monitoring, use the desktop setup.
Requirements
| Requirement | Notes |
|---|---|
| Platform | macOS or glibc-based Linux on x86_64 or arm64 |
| Downloader | curl or wget |
| Database | PostgreSQL 13+ or MySQL 8.0+ |
| LLM access | A Readyset sign-in or your own Anthropic API key |
| 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.
Use a dedicated read-only account. Database permissions lists the baseline grants and the optional privileges needed to observe other users' query activity.
Install
Desktop app
Follow desktop installation for the tray app and RDST Agent.
Command line
curl -fsSL https://downloads.readyset.io/packages/rdst-cli/install.sh | shThe installer uses user-owned directories and doesn't require sudo, pip, or a preinstalled Python. Open a new shell after installation.
uv tool install rdst
# or: pipx install rdstRDST leaves these installations under the control of their package manager.
Verify with rdst version.
Installer-managed RDST installations update when you request it. Check for or install a release explicitly:
rdst update --check
rdst updateWhen the installed version is current, rdst update returns without replacing
the managed environment. For package-manager installations, use uv tool upgrade rdst or
pipx upgrade rdst instead.
Run the setup wizard
rdst initThe wizard handles four things, in order:
AI access. Sign in with rdst account login for hosted AI, or set your
Anthropic key. See Configuration
for provider selection and usage limits.
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 records the variable name in its config. It can also read a password
saved in the operating system's keychain.
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. To deploy later, 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 totals since the last statistics reset.
# 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
report with a performance rating, findings, candidate indexes and 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 collects database health, sizing, top queries, index coverage,
and caching recommendations in a one-off report.
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. Deploy an application cache (rdst cache)
This step is optional. Benchmarking in the next step prepares its own sandbox. To deploy a separate Readyset instance for application traffic, run:
rdst cache deploy --target prod-orders --mode dockerThis starts a Readyset container, waits for it to become ready, 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 a temporary Readyset sandbox, with 10 concurrent workers on each side, then prints a side-by-side comparison:
Resolving targets ...
Upstream: prod-orders (PostgreSQL)
Cache: temporary Readyset sandbox
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.Command guides
Core Concepts
Learn how RDST connects to databases and saves queries. Add schema context for AI analysis and see where Readyset caching fits.
Query Analysis
Choose a query command and look up how to use it.
Fleet and Audit
Audit a single database or an entire fleet. Diff snapshots over time.
Readyset Cache
Deploy Readyset and manage its cached queries. Measure how much faster queries run through the cache.
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 in to Readyset.
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 |
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 doesn't cover, run
rdst report to send feedback with
your version, redacted config, and most recent error.
RDST CLI
Use RDST to diagnose slow queries and ask questions about your PostgreSQL or MySQL data. Audit your databases and test queries with Readyset caching.
Core concepts
Learn how RDST connects to your databases and keeps queries for later use. See how schema context helps AI analysis and how audits guide caching.