Snapshotting

Deep caches are maintained from a snapshot of your database's tables plus a continuous replication stream. Snapshotting copies the data of every table into Readyset's storage directory. Deep caches require every table to finish the initial snapshot. Shallow caches do not depend on snapshotting.

Monitoring snapshot progress

Check overall snapshotting progress by connecting a SQL shell to Readyset and running:

SHOW READYSET STATUS;

The row labeled Status shows Snapshot In Progress until every table finishes snapshotting, then Online:

name               | value
-------------------+---------
...
Status             | Online
Replication Status | Running
...

For per-table detail, use SHOW READYSET TABLES:

SHOW READYSET TABLES;

table            | status       | description
-----------------+--------------+------------
"public"."small" | Online       |
"public"."big"   | Snapshotting | 43.21%
"public"."huge"  | Initializing |
(3 rows)

Tables waiting for their turn report Initializing. In-progress tables report Snapshotting with an estimated progress percentage in description, then Compacting while finalizing. Online means the table is fully snapshotted and replicating; restarts do not re-snapshot online tables. Add ALL to also list upstream tables Readyset is not replicating, with the reason in description.

The Readyset log reports when each table's snapshot starts, with an estimated row count, and when it finishes, with the number of rows copied. While a table is snapshotting, the log reports its progress every 30 seconds.

Tables Readyset does not replicate

Some upstream tables are never replicated at all. For example, on PostgreSQL, Readyset does not support tables with generated columns: PostgreSQL versions before 18 cannot send generated columns over logical replication, and Readyset publications does not yet support the publish_generated_columns option added in PostgreSQL 18.

Tables like these are refused when Readyset first sees them, during the initial snapshot or when a CREATE TABLE event arrives during replication. SHOW READYSET ALL TABLES lists them as Not replicated and names the reason, for example Tables with generated columns are not supported. Queries against a non-replicated table fall through to the upstream database.

Restarting during snapshotting

When Readyset restarts against an existing storage directory, snapshot progress is preserved per table:

• Tables whose snapshot completed before a clean shutdown are kept. Their data is read from the storage directory and they are not re-snapshotted; replication resumes from the position recorded for each table when its snapshot began.
• Tables that had not finished snapshotting start over from the beginning of that table. Rows already copied for that table are discarded.
• After an abrupt exit, such as a crash or SIGKILL, tables that finished snapshotting during that run may be snapshotted again.

If your deployment restarts routinely, avoid restarting while table snapshotting is in progress, for example during initial snapshotting or after changes to the ignored tables described in Limiting which tables are snapshotted.

Parallel snapshotting

Readyset snapshots multiple tables in parallel, up to --max-parallel-snapshot-tables (default: number of available cores - 1). Each table being snapshotted takes its own connection to the upstream database. Tables are snapshotted independently, so overall snapshot time is at least as long as the slowest single table.

Limiting which tables are snapshotted

By default, Readyset snapshots and replicates every table in the upstream database. To narrow the scope, include only the tables your deep caches need with --replication-tables, or exclude specific tables with --replication-tables-ignore. See Config Options for the accepted formats and eligibility behavior.

To add previously excluded or omitted tables to a running deployment, use ALTER READYSET ADD TABLES:

ALTER READYSET ADD TABLES db.table, db.table2;

Readyset snapshots the added tables; tables that already finished snapshotting are not re-snapshotted. While the added tables snapshot, SHOW READYSET STATUS reports Snapshot In Progress again, and existing deep caches keep serving results but do not receive upstream changes until snapshotting completes.

When a table snapshot fails

If a table fails to snapshot, Readyset continues with the rest, and the deployment can still reach Online. Queries against the failed table fall through to the upstream database, so results stay correct but are not cached. Check SHOW READYSET ALL TABLES to find it: on PostgreSQL it is listed as Not replicated with the error, and is not retried; on MySQL it is retried automatically but can stay Initializing until the underlying problem is fixed.

Once the problem is fixed, add the table back with ALTER READYSET ADD TABLES:

ALTER READYSET ADD TABLES db.table;

Readyset re-snapshots the added table, and the deployment reports Snapshot In Progress until it finishes. Restarting Readyset also recovers the table: restarts preserve tables whose snapshot completed and start over from the beginning for the rest, as described in Restarting during snapshotting.

Re-snapshotting a table

To re-copy a single table's data, use:

ALTER READYSET RESNAPSHOT TABLE db.table;

For behavior when the upstream database fails over to a new primary, including the full resnapshot PostgreSQL requires after a replication slot is lost, see Failover.