Readyset Docs

Deploy Readyset locally, remotely over SSH, or in Kubernetes. Register a cache target automatically.

rdst cache deploy starts a Readyset process pointed at an existing database target, then registers a new RDST target for that Readyset instance (typically named <original>-cache).

Common usage

# Local Docker deployment
rdst cache deploy --target prod-orders --mode docker

# Remote host via SSH (still Docker-mode, but on another machine)
rdst cache deploy --target prod-orders --mode docker \
    --host 10.0.1.50 --ssh-user ubuntu --ssh-key ~/.ssh/prod.pem

# Systemd service on the local or remote machine
rdst cache deploy --target prod-orders --mode systemd --host 10.0.1.50 \
    --ssh-user ubuntu --ssh-key ~/.ssh/prod.pem

# Kubernetes deployment
rdst cache deploy --target prod-orders --mode kubernetes \
    --namespace readyset --kubeconfig ~/.kube/config

# Generate the deploy script but don't run it
rdst cache deploy --target prod-orders --mode docker --script-only

What `cache deploy` does

Pulls the Readyset Docker image (only if not already present)
Starts a container pointed at your database target, with correct wire-protocol port and credentials
Waits for Readyset to finish its initial snapshot
Registers a new RDST target (<original>-cache) pointing at the container
Prints connection info so you can point your application at it

Remote Docker (--host) runs the same flow, just via SSH on the remote host.

Copies the Readyset binary to the host
Writes a systemd unit file with your target's connection details
Enables and starts the service
Waits for the initial snapshot
Registers a new RDST target pointing at the service
Prints connection info and the systemctl commands to manage it

Use --host + --ssh-user + --ssh-key to deploy to a remote systemd host.

Applies a Deployment, Service, and ConfigMap in the namespace you specify
Configures the Deployment to connect to your target (credentials via Kubernetes Secret)
Waits for the pod to report ready
Registers a new RDST target pointing at the in-cluster Service
Prints the Service DNS name so you can point your application at it

If you want custom resource limits, node selectors, etc., use --script-only to generate the manifests and edit before applying.

Accessibility matters

RDST needs network access to the Readyset instance it just deployed in order to run rdst cache add, rdst cache show, or any other follow-up command against it.

If you deploy to a target RDST can't reach directly over the network, follow-up cache commands will fail. Common causes:

The Readyset port (5432 for Postgres-wire, 3306 for MySQL-wire) is closed on the remote host's firewall or security group.
The remote host is only reachable over SSH — RDST can deploy through SSH but does not tunnel every subsequent command through SSH.
A Kubernetes Service is ClusterIP-only and not exposed outside the cluster.

Before running rdst cache deploy --host <remote>, confirm you can reach the target port from your laptop (e.g. nc -zv <host> 5432). For cluster-only deployments, plan to run rdst cache add from inside the cluster.

After deployment

RDST prints the connection string and the name of the new target it registered:

✓ Readyset deployed (mode: docker, container: readyset-prod-orders)
✓ Initial snapshot complete (12s)
✓ Registered target: prod-orders-cache

Connection string:
  postgresql://rdst:*****@localhost:5434/orders

Next steps:
  rdst cache add <query-hash> --target prod-orders-cache
  rdst query cache-compare <query-hash> --target prod-orders

You interact with the cache through the new target (prod-orders-cache), not the original (prod-orders). Every rdst cache command takes --target <cache-target>.

Script-only mode

--script-only is useful when you want to:

Review exactly what will run before running it
Adapt the deploy script for an environment RDST doesn't natively support (Nomad, custom CI, etc.)
Deploy in a context where RDST can't reach the target (e.g., an air-gapped host)

rdst cache deploy --target prod-orders --mode docker --script-only > deploy.sh
# Review deploy.sh, edit as needed, run it yourself
bash deploy.sh

When you use --script-only, RDST does not register the cache target for you. You'll need to register it manually with rdst configure add pointing at the deployed Readyset instance.

Configs

--config <name> picks between Readyset deployment profiles:

Config	What it is
`readyset` (default)	Standard Readyset — shallow caching
`readyset-squeepy`	Readyset with SQueePy preset — tuned defaults for specific workloads

Most users should stick with the default.

Flags reference

Flag	What it does
`--target <name>`	Which database target to cache
`--mode {docker,systemd,kubernetes}`	Deployment mode (required)
`--config {readyset,readyset-squeepy}`	Deployment config preset
`--host <ip>`	Remote host for SSH deployment (omit for local)
`--ssh-user <user>`	SSH username (default: `root`)
`--ssh-key <path>`	SSH private key path
`--port <port>`	Override Readyset listen port
`--namespace <ns>`	Kubernetes namespace
`--kubeconfig <path>`	Path to kubeconfig for Kubernetes deployment
`--script-only`	Generate deployment script without executing
`--json`	Machine-readable output

Tearing down

To stop and remove a local cache deployment entirely:

rdst cache remove --target prod-orders-cache

This stops the Docker container (or systemd service, or Kubernetes deployment), removes the persistent state, and unregisters the <original>-cache RDST target.

Use rdst cache drop-all --target <name> instead if you want to remove cached queries but keep Readyset running. See Managing caches.

rdst cache deploy