Readyset Docs

After rdst cache deploy registers a cache target (typically named <original>-cache), the remaining rdst cache commands act on that target.

Add a cache

# From the query registry (preferred)
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache

# Direct SQL
rdst cache add "SELECT * FROM orders WHERE customer_id = ?" --target prod-orders-cache

# Check cacheability without actually adding
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache --dry-run

# Tag the query in the registry while adding
rdst cache add a1b2c3d4e5f6 --target prod-orders-cache --tag high-priority

rdst cache add uses Readyset's CREATE CACHE command under the hood. Passing a hash from the registry is preferred because RDST can show you exactly which query will be cached and verify it's still cacheable before acting.

What "cacheable" means

Readyset supports a specific subset of SQL features for caching. If rdst cache add reports a query is not cacheable, the reason is printed:

$ rdst cache add f6e5d4c3b2a1 --target prod-orders-cache --dry-run

Checking cacheability for query f6e5d4c3b2a1 ...

  SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '7 days'

✗ NOT CACHEABLE
  Reason: Query contains non-deterministic function NOW() which cannot be
          parameterized for caching. Consider parameterizing the time cutoff:
          WHERE created_at > $1

Use rdst analyze --hash <id> for the full cacheability analysis including suggestions to make a query cacheable.

List caches

# Every cache on the target
rdst cache show --target prod-orders-cache

# JSON output for scripting
rdst cache show --target prod-orders-cache --json

Caches on prod-orders-cache (3 total)

  Hash      Cache Name      Query                                                 Type     TTL
  ────────  ──────────────  ────────────────────────────────────────────────────  ───────  ─────
  a1b2c3d4  q_01            SELECT * FROM orders WHERE customer_id = ?            shallow  10s
  f6e5d4c3  q_02            SELECT o.id, o.total_cents FROM orders o JOIN cu...   shallow  10s
  9a8b7c6d  session-lookup  SELECT 1 FROM session_cache WHERE token = ?           shallow  10s

Readyset Connection String
  postgresql://rdst:${PROD_ORDERS_PASSWORD}@localhost:5434/orders

  Compare: rdst query cache-compare a1b2c3d4 --target prod-orders --count 100

The Hash column is the first 8 characters of the query's registry hash — pass it to rdst query cache-compare to benchmark the upstream query against the cache. The Cache Name is what you hand to rdst cache delete.

Delete a cache

# By cache name (from the "Cache Name" column of `rdst cache show`)
rdst cache delete q_01 --target prod-orders-cache

To remove every cache from a Readyset instance without tearing the instance down:

rdst cache drop-all --target prod-orders-cache --yes

The --yes flag skips the confirmation prompt. Without it, RDST lists everything that will be removed first.

Tear down the whole deployment

To remove Readyset entirely (stops the container, cleans up persistent state, unregisters the -cache target):

rdst cache remove --target prod-orders-cache

This is the inverse of rdst cache deploy. Use it when you are done testing a cache and want to clean up the artifacts.

Command	What goes away	Readyset still running?
`rdst cache delete <id>`	One cached query	Yes
`rdst cache drop-all`	All cached queries	Yes
`rdst cache remove`	Readyset itself + all caches + the `-cache` target	No

Flags reference

Flag	Purpose
`query`	Hash (12 hex chars) or direct SQL
`--target <name>`	Readyset target (usually `<original>-cache`)
`--tag <tag>`	Tag the query in the registry while adding
`--dry-run`	Check cacheability without adding
`--json`	JSON output

Flag	Purpose
`--target <name>`	Readyset target
`--json`	JSON output

Flag	Purpose
`cache_id`	Cache ID from `rdst cache show`
`--target <name>`	Readyset target
`--json`	JSON output

Flag	Purpose
`--target <name>`	Readyset target
`--yes`	Skip confirmation prompt
`--json`	JSON output

Flag	Purpose
`--target <name>`	Readyset target to tear down
`--yes`	Skip confirmation prompt

Managing caches