Readyset Docs

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.

Targets

A target is a named database connection. Use --target <name> to select it, or set a default with rdst configure default <name>.

Targets contain an engine, host, port, database, user, and password environment variable name. Passwords come from that variable or the operating system's keychain. They're never saved in config.toml.

Add targets with configure, fleet import or discovery, or the desktop app. The target list is local to the operating system user.

The query registry

The query library records SQL from monitoring, top, Ask, and analysis. You can also add SQL yourself.

Queries are normalized before hashing. Different literal values for the same query shape share an identity across the desktop app, CLI, and MCP tools.

rdst query list
rdst query list --filter customer_id
rdst query show a1b2c3d4e5f6
rdst analyze --hash a1b2c3d4e5f6 --target prod-orders
rdst query add order-detail -q "SELECT * FROM orders WHERE id = 42"

Saved names and analyses remain available after database statistics reset. Monitoring and Ask save queries in the same library.

The semantic layer

The semantic layer describes tables, columns, relationships, and business terms for a target. It helps Ask interpret questions such as which order statuses count as completed sales.

rdst schema init --target prod-orders
rdst schema annotate --target prod-orders --use-llm
rdst schema show --target prod-orders
rdst schema edit --target prod-orders
rdst schema refresh --target prod-orders

Review generated descriptions and add meanings the schema can't provide. Desktop Ask uses the same per-target descriptions.

The LLM

AI generates query explanations, candidate rewrites, SQL for Ask, audit insights, and schema annotations.

AI calls can include query text, execution plans, schema metadata, semantic context, and parameter values. Query result rows and connection passwords aren't included. See AI access for provider selection and usage limits.

Recommendations can vary. Check suggested SQL and test it against representative data before using it in your application.

Audits and snapshots

An audit collects a database's health, sizing, query activity, and recommendations. Fleet audits run this across several targets.

Audits save snapshots. Use snapshots and diff to read an earlier run or compare changes. Audit snapshots are separate from monitoring's nightly reports.

Readyset caches

Cache deployment starts an application-facing Readyset instance and registers a <target>-cache connection. Add and manage cached queries using that cache target.

cache-compare takes the source database target and prepares a temporary local sandbox for benchmarking. It doesn't require a deployed cache target.

Cache targets are restricted targets

Use source database targets for analysis, Ask, top, audits, and monitoring. Use cache targets for rdst cache add, show, delete, drop-all, and remove.

Where state lives

The desktop app and CLI share ~/.rdst under the same operating system user. RDST_DATA_DIR selects another data directory. It holds targets, library.db, semantic layers, and audit snapshots. Monitoring also uses monitor.db and agent_activity.db.

Database connections and AI calls use the network. Cloud discovery calls the provider API, and the audit email flow sends a report for delivery.

RDST Agent

Configure RDST Agent in the desktop app or rdst web. There isn't an rdst monitor command. rdst top samples queries during its run; it doesn't start background monitoring or produce Inbox items.

When your account's AI usage limit is reached, AI monitoring stops gracefully. Local monitoring keeps running, and the app asks you to contact us.