Skip to main content

Backup, Recovery, PITR and Branching

By the end of this page you will know which of ScramDB's three recovery mechanisms fits the job in front of you, and whether your instance is already configured to use it.

ScramDB ships three distinct, complementary mechanisms. They share some machinery under the hood, but they solve different problems and you reach for them in different moments. Keep them separate in your head:

MechanismWhat it isReach for it when
Base backup + restoreA cold, offline snapshot of a stopped instance's data directory, plus a tool to rebuild a fresh instance from itThe server, volume, or host is gone and you need to rebuild it
Point-in-time recovery (PITR)scramdb restore targeted at an exact LSN or timestamp instead of replaying every WAL segmentYou know (or can bound) the exact moment things went wrong and want the state right before that
BranchingCREATE DATABASE ... CLONE ... or CREATE DATABASE ... FROM ... AT TIMESTAMP ...: instant, copy-on-write forks of a database while the server is runningYou want a working, connectable copy of the database right now, for testing, debugging, CI, or an agent sandbox

How they relate​

Backup and restore are the disaster-recovery layer: a cold snapshot of the data directory (scramdb backup) and a tool that rebuilds an instance from it (scramdb restore). PITR is not a separate tool, it is scramdb restore called with --target-lsn or --target-time so it stops replaying WAL at a specific point instead of replaying everything available.

Branching operates one level up, at the SQL level, and while the server is running. CREATE DATABASE child CLONE parent forks the current state of parent instantly, with zero configuration, by sharing storage until either side writes new data. CREATE DATABASE child FROM parent AT TIMESTAMP '...' forks a past state of parent, and internally it reuses the same base-backup-plus-WAL-replay machinery as scramdb restore, materializing the result into a new database instead of a fresh data directory.

That gives you one dependency worth understanding up front: present-state branching (CLONE) always works out of the box. As-of-a-past-moment branching (FROM ... AT TIMESTAMP) is a capability you turn on by taking a base backup and, usually, keeping WAL archiving enabled.

Is your instance configured for this?​

Run through this checklist before you need any of these mechanisms in a hurry.

  1. Is WAL archiving on? The shipped Docker image sets [storage.wal.archive].enabled = true by default, specifically so branching and PITR work out of the box. If you are running a hand-rolled config, check for this section:

    [storage.wal.archive]
    enabled = true

    If enabled = true and no destination is set, ScramDB archives WAL to {data_dir}/wal-archive, a subdirectory of the data volume itself. That is fine for a single-volume deployment; if you want the archive somewhere else (a separate disk or object storage), set destination explicitly. See Point-in-time recovery for the full key reference.

  2. Is a base backup location configured? This one is not set by default. CREATE DATABASE ... FROM ... AT TIMESTAMP (and its function form scram.branch_at) refuse to run until [storage.wal.backup].destination points somewhere:

    [storage.wal.backup]
    destination = "file:///var/lib/scramdb/base-backup"

    Without this, CLONE still works fine (it needs nothing), but FROM ... AT TIMESTAMP fails loud, naming this exact key, until you set it and take a backup there. See Backups.

  3. Have you actually taken a backup at that location? Configuring the key is not the same as having a backup. FROM ... AT TIMESTAMP and PITR-via-archive both need a real backup on disk (or in object storage) at the configured destination, with WAL history reaching back to your target moment. See Backups.

Where to go next​

  • Backups: take and verify a base backup, understand what is and is not included.
  • Restore: rebuild a fresh instance from a backup, step by step, with verification.
  • Point-in-time recovery: restore to an exact LSN or timestamp instead of the latest available point.
  • Branching: instant, copy-on-write database forks for testing, debugging, CI, and agent sandboxes.