Restore
By the end of this page you will have rebuilt a fresh ScramDB instance from a base backup, replaying every available WAL segment, and verified it against a real query.
This page covers a full restore: rebuild everything the backup and its WAL can give you, with no target point. If you want to stop replay at a specific LSN or timestamp instead, see Point-in-time recovery, it is the same command with one extra flag.
Before you start
You need:
- A base backup taken with
scramdb backup(see Backups), reachable at a local path or object storage URL. - A config file whose
storage.basedirpoints at an empty or nonexistent directory. Restore refuses to write into a directory that already has content in it, so do not reuse the original instance's basedir unless you have emptied it first.
Step by step
-
Prepare a restore config file naming a fresh basedir. For example,
/etc/scramdb/restore-config.toml:toml[storage]basedir = "/var/lib/scramdb/restored"Confirm that directory is empty or does not exist yet:
bashls /var/lib/scramdb/restored 2>/dev/nullExpect either "No such file or directory" or an empty listing.
-
Run
scramdb restorepointing--backupat your backup destination. Since this is a full restore, you still need to satisfy the CLI's target requirement (see Point-in-time recovery if you want to bound it); to replay everything currently available, target a timestamp far enough in the future, or use the most recent timestamp you know is covered by your WAL:bashscramdb restore --config /etc/scramdb/restore-config.toml \--backup file:///var/lib/scramdb/backups/2026-08-02 \--target-time 2026-08-02T12:00:00ZIf your WAL archive lives at a different location than the backup itself, add
--wal-source:bashscramdb restore --config /etc/scramdb/restore-config.toml \--backup file:///var/lib/scramdb/backups/2026-08-02 \--wal-source file:///var/lib/scramdb/wal-archive \--target-time 2026-08-02T12:00:00Z--wal-sourcedefaults to the same value as--backupif you omit it, since a backup and its WAL archive commonly share a destination root. -
Check the output. A successful restore logs:
textrestore complete: replayed to lsn=<LSN>, target config=/etc/scramdb/restore-config.tomlThe
lsnvalue is your verification anchor. Compare it against thebase_lsnyour original backup reported, it should be equal to or ahead of it, reflecting however much WAL got replayed.If replay finds that one table's own data no longer matches what it committed (a torn or truncated segment, for example), the restore does not fail for every other table over it: it prints one extra line per affected table and goes on.
texttable orders is quarantined: catalogued with 14 page(s) but the file holds only 0 - torn or truncated - restore it from a backup, or DROP and recreate it, to clear the quarantineA quarantined table refuses every read and write (it never serves partial data); every other table in the restore is unaffected. See If it fails for how to clear it.
-
Start the restored instance:
bashscramdb --config /etc/scramdb/restore-config.toml -
Verify with a real query. Connect and check the data is what you expect:
bashpsql "host=127.0.0.1 port=5432 user=scramdb dbname=scramdb" -c "SELECT count(*) FROM your_table;"Compare the row count (and, ideally, a spot-checked row or two you know the value of) against what you expected from the source instance at the time of the backup plus replayed WAL. A clean server start with no error output, plus a query that returns the row counts you expect, is your sign the restore worked.
If it fails
| Symptom | Likely cause | What to do |
|---|---|---|
restore target data directory '<dir>' already exists and is not empty | storage.basedir in your restore config points at a directory with existing content | Point at a genuinely empty or nonexistent directory |
backup manifest format_version N is not supported | The manifest is from an incompatible or corrupt backup | Re-take the backup, or use a build of scramdb that matches the manifest's format |
backup was taken with WAL format version N but this build reads versions A to B | The backup was taken by a build whose WAL format this build does not read: a newer one, or one older than the oldest it reads | Restore with a build that reads that format, or re-take the backup with the current build |
no WAL segments of timeline N available at the configured WAL source starting from file_id N | Neither --backup nor --wal-source has the WAL segments needed to replay forward from the backup's recorded position | Check --wal-source points at the right archive location, and that retention has not pruned the segments you need |
| A file's checksum mismatch during restore | The backup's data/ tree was corrupted or partially copied | Re-take the backup; restore verifies every file's checksum as it lands and fails loud rather than restoring silently-corrupt data |
table '<name>' is quarantined: ... | That one table's on-disk state did not match what its own log said was committed (its data diverged, unrelated to the rest of the restore) | Restore just that table's data from a backup that predates the divergence, or DROP TABLE and recreate it in the restored instance; querying it before then fails loud instead of returning partial data |
Every file restore writes is checksum-verified against the manifest as it lands, so a corrupted backup fails loudly during restore rather than producing a silently-broken instance. A quarantined table is the one exception to "fails loudly": restore keeps every other table's data rather than failing the whole restore over one table's own divergence, and says so in its output (see above).
Next
- Point-in-time recovery: the same command, aimed at an exact LSN or timestamp instead of the latest available point.
- Branching: fork a database as of a past moment on a running server, without a separate restore step.