Readyset Docs

Manage targets, LLM keys, passwords, and the query registry through RDST commands and environment variables.

RDST is configured entirely through commands and environment variables. You do not edit config files by hand — rdst configure, rdst schema, and rdst query manage everything for you.

Targets

A target is a named database connection. Every analysis command takes --target <name> so you never have to pass connection details on the command line.

Add a target

rdst configure add

Prompts for name, engine, host, port, database, user, and the name of the password environment variable.

rdst configure add \
    --target prod-orders \
    --engine postgresql \
    --host db.example.com \
    --port 5432 \
    --database orders \
    --user rdst_ro \
    --password-env PROD_ORDERS_PASSWORD

rdst fleet import --from fleet.csv --password-env FLEET_PASS

See Setting up a fleet for the CSV format.

rdst fleet discover --regions us-east-1,us-west-2

See Setting up a fleet for AWS-specific details.

RDST never stores passwords. It remembers the name of the environment variable you use to hold each target's password, and expects you to export the value in your shell before each session. Passwords follow your normal shell and secret-management practices; RDST does not add a new thing to audit.

Use a target

Export the password, then run any command against it:

export PROD_ORDERS_PASSWORD='...'
rdst top      --target prod-orders
rdst analyze  --hash abc123 --target prod-orders
rdst audit    --target prod-orders

Manage targets

rdst configure list                   # list all targets
rdst configure edit <name>            # edit a target
rdst configure remove <name>          # delete a target
rdst configure default <name>         # set the default target (used when --target is omitted)
rdst configure test <name>            # verify connectivity and permissions

Use a read-only database user for your RDST targets. RDST only runs diagnostic queries (EXPLAIN, system views), so it never needs write permissions on your application data.

LLM provider

Most RDST commands call a large language model for reasoning. You have two options, set up interactively during rdst init:

During rdst init, choose "Sign up for free RDST trial". You enter your email, RDST sends you a link, you click it, and the page that opens shows a trial token you paste back into the CLI. Analysis calls then route through a Readyset-hosted proxy.

Email type	Credits
Business domain	$5.00
Personal (gmail, etc.)	$1.50

Re-run rdst init --force later if you want to change provider.

Export your key before running RDST:

export ANTHROPIC_API_KEY="sk-ant-..."

Add the line to your shell profile (~/.bashrc, ~/.zshrc, etc.) so it persists across sessions. RDST detects the variable automatically.

Semantic layer

The semantic layer describes your schema to the LLM in plain language: what each table represents, what enum values mean, and how tables relate. It is the single biggest lever for improving rdst ask and rdst analyze quality on unfamiliar databases.

rdst schema init      --target mydb                 # introspect
rdst schema annotate  --target mydb --use-llm       # AI-generated descriptions
rdst schema show      --target mydb                 # review
rdst schema edit      --target mydb                 # hand-edit in $EDITOR
rdst schema refresh   --target mydb                 # pick up new indexes, keep annotations
rdst schema profile   --target mydb                 # collect column stats (nulls, distinct, top values)
rdst schema export    --target mydb --format yaml   # export for source control
rdst schema list                                     # list all configured semantic layers
rdst schema delete    --target mydb

Query registry

The query registry is RDST's local catalog of SQL queries. It's populated automatically by rdst top, rdst scan, and rdst analyze --save-as. Browse it through the CLI:

rdst query list                    # list all saved queries
rdst query list --filter "users"   # filter by text
rdst query show <hash-or-name>     # show SQL and metadata
rdst query add <name> -q "SQL..."  # manually add
rdst query import -f file.sql      # bulk import from a .sql file
rdst query edit <name>             # edit in $EDITOR
rdst query delete <hash-or-name>   # remove

Running queries for load generation

# Round-robin run 500 executions of a saved query
rdst query run my-saved-query --target prod-orders --count 500

# Sustained 10 concurrent executions for 2 minutes
rdst query run my-saved-query --target prod-orders -c 10 --duration 120

# Run a CSV of queries through the target
rdst query run --file queries.csv --target prod-orders --duration 300

Use rdst query cache-compare for the benchmarking variant that compares upstream against a Readyset cache.

Audit and fleet snapshots

Every audit and fleet-audit run is persisted. Manage them through the CLI:

rdst audit list                                 # past single-target audits
rdst audit show <run_id>                        # view a saved audit
rdst fleet snapshots                            # past fleet audits
rdst fleet diff snap1 snap2                     # compare two snapshots

See Snapshots and diff for patterns.

Environment variables

Variable	Used by	Purpose
`ANTHROPIC_API_KEY`	Most commands	Claude API key (when not using free trial)
`OPENAI_API_KEY`	Some commands	OpenAI key (alternative)
`<YOUR_TARGET>_PASSWORD`	Every target	Whatever name you set when adding the target
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION`	`rdst fleet discover`	AWS credentials for RDS discovery
`AWS_PROFILE`	`rdst fleet discover`	Alternative to explicit AWS keys (SSO/profiles)
`EDITOR`	`rdst schema edit`, `rdst query edit`, `rdst guard edit`	Which editor to launch
`RDST_LOG_LEVEL`	All commands	`debug`, `info` (default), `warn`, `error`

Security model

What gets sent to the LLM

Data	Sent?	Notes
Query text (SQL)	yes	This is the core of the analysis
EXPLAIN / EXPLAIN ANALYZE plans	yes	Includes row estimates and operator details
Schema metadata (table, column, index names, types)	yes	For index and rewrite reasoning
Row count estimates	yes	For scale-aware recommendations
Semantic layer descriptions	yes (if present)	To improve NL-to-SQL and analysis quality
Result rows	no	Query output is never sent to the LLM
Credentials	no	Passwords are only used to open the database connection

Determinism

All analysis calls use temperature=0.0 and an explicit validation layer. Running the same rdst analyze against the same query and schema produces the same recommendations. This is deliberate: recommendations need to be reproducible for code review, CI checks, and audit trails.

Feedback and bug reports

File feedback directly from the CLI. RDST attaches your version, OS, and the most recent error (without secrets) for context.

# Report an issue
rdst report --negative -r "Index suggestion was incorrect"

# Positive feedback
rdst report --positive -r "Great recommendation!"

# Include specific query context
rdst report --hash abc123 --include-query -r "Unexpected result"

Flag	Purpose
`--hash <id>`	Query hash to provide feedback on
`-r, --reason <text>`	Description of the issue (or open a prompt if omitted)
`-e, --email <addr>`	Email for follow-up
`--positive` / `--negative`	Mark sentiment
`--include-query`	Include raw SQL
`--include-plan`	Include execution plan

Configuration