Readyset Docs

Configuration

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

Use rdst configure, rdst schema, and rdst query to manage RDST. The desktop app shares the same configuration under the same operating system user.

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

RDST asks you to name the target and enter its connection details. For the password, give the name of the environment variable that holds it.

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 stores passwords in the operating system's keychain or reads them from a named environment variable. The environment wins when set. config.toml records the variable name, never the password.

Connection security

Each target in ~/.rdst/config.toml takes these settings:

SettingDefaultMeaning
tlsfalseRequire TLS. Without it, RDST uses TLS when the server offers it.
tls_verifyfalseCheck the server's certificate and hostname. Turns tls on.
tls_canoneCA bundle for tls_verify, for a private CA such as the RDS bundle.

Without tls, the connection can be unencrypted: MySQL connects in plaintext, and PostgreSQL uses TLS only when the server offers it. Without tls_verify, TLS encrypts the connection but anyone who can intercept it can pose as the server, so turn it on wherever you have the CA certificate. For either, RDST warns once per target in a terminal, and a connection test in the app says so, unless the database is on this machine or reached through an SSH tunnel.

When you change a saved database's host, port, user, engine or SSH jump host in the app, enter its password again: RDST sends a saved password only to the server it was saved for.

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. See Database permissions for the minimum grants, optional monitoring access, and PostgreSQL and MySQL examples.

LLM provider

Sign in to Readyset for hosted AI:

rdst account login
rdst account status

Finish the browser sign-in opened by the command. The app shows your account's AI usage. When a usage limit is reached, AI monitoring stops gracefully, local monitoring keeps running, and the app asks you to contact us.

You can also use your own Anthropic key:

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

The saved provider preference controls routing. With Anthropic selected, RDST uses the environment key before the keychain. With Readyset selected, it uses your account even if the environment key is set. Without a saved preference, RDST checks the environment, keychain, then Readyset sign-in.

Use the desktop AI access settings to review or switch the saved provider. Monitoring change checks and query classification always use Readyset's service.

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. Add business meanings and review generated descriptions before relying on them.

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

VariableUsed byPurpose
ANTHROPIC_API_KEYMost commandsAnthropic API key, subject to the saved provider preference
<YOUR_TARGET>_PASSWORDEvery targetWhatever name you set when adding the target
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGIONrdst fleet discoverAWS credentials for RDS discovery
AWS_PROFILErdst fleet discoverAlternative to explicit AWS keys (SSO/profiles)
EDITORrdst schema edit, rdst query edit, rdst guard editWhich editor to launch
RDST_DATA_DIRCLI and desktop backendOverride the default local data directory
RDST_LOG_LEVELAll commandsdebug, info (default), warn, error

Security model

What gets sent to the LLM

DataSent?Notes
Query text (SQL)yesMay include real parameter values used during analysis
EXPLAIN / EXPLAIN ANALYZE plansyesIncludes row estimates and operator details
Schema metadata (table, column, index names, types)yesFor index and rewrite reasoning
Row count estimatesyesFor scale-aware recommendations
Semantic layer descriptionsyes (if present)To improve NL-to-SQL and analysis quality
Result rowsnoQuery output is never sent to the LLM
CredentialsnoPasswords are only used to open the database connection

Review generated recommendations

RDST validates suggestions against schema context, but recommendations can vary. Review rewrites and index definitions, and test them before deployment.

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"
FlagPurpose
--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 / --negativeMark sentiment
--include-queryInclude raw SQL
--include-planInclude execution plan

See also