Backup & Restore

Relata DB 3.0
This page describes Relata DB 3.0, the current release. Paths use the new /v1 prefix; see the route restructure.

This page covers the open single-machine edition. Point-in-time disaster recovery, shared-store and cluster recovery are Enterprise features.

Restore is not yet qualified
Backup and restore have not passed the release qualification (tracked as #5686). A recorded run reproduced a completed HTTP restore reverting after SIGKILL and WAL replay, so a row written after the backup reappeared on restart. The HTTP whole-store restore creation route (POST /admin/restore) is therefore disabled and returns 503. The CLI restore commands remain available but are not a qualified recovery path. Validate recovery after a restart before routing traffic; a completed job alone is not a verified recovery point.

What a backup is

A backup artefact is a point-in-time JSON row snapshot of the live RELATA_DATA_DIR dataset, including bi-temporal history and provenance references, with a SHA-256 integrity digest. It is not a copy of the whole data directory. The data directory or bucket is the live store, not an independent backup: keep recovery artefacts in a separately controlled failure domain.

Authoritative state that is not in any backup, and must be protected separately:

  • config/tokens.json, the token registry. After losing it every client needs a new token.
  • The audit log. Ship sealed segments to an audit archive destination (Governance and audit).
  • The signed integrity anchors and the GDPR purge log.
  • Operational files such as ingest control state, media work state and saved rules.

Referenced blob bytes are written as hash-verified sidecars (a blobs/ directory next to the artefact), not inside the payload. Vector and derived-index snapshots are separate, and a restored node rebuilds what it must.

Take, verify and restore

Stop the server first for the offline commands; both backup and restore take the exclusive data-directory lease.

export RELATA_DATA_DIR=/var/lib/relata
 
relata backup /safe/place/pre-cutover.json         # writes the artefact and a .sha256 sidecar
relata verify-backup /safe/place/pre-cutover.json  # recomputes the digest; non-zero exit on mismatch
# copy the artefact (and its blobs/ sidecar) to a separate failure domain
 
# after a loss: empty the data directory, then
rm -rf "$RELATA_DATA_DIR" && mkdir -p "$RELATA_DATA_DIR"
relata restore /safe/place/pre-cutover.json        # verifies the digest first; refuses a corrupt artefact
relata serve                                       # then check counts and an AS OF SYSTEM TIME query
  • relata backup with no path writes a timestamped artefact and manifest under ~/.relata/backups/.
  • relata restore --to "<RFC3339>" --dir <backup_dir> selects a recovery point from a local backup directory.
  • A running instance can be captured through POST /admin/backup on the loopback admin listener, with the admin token. It closes normal HTTP admission during capture (health routes stay available) and a drain phase has a 30-second timeout.
  • relata backup loads the server configuration, so run it with the same authentication settings you use for serve.
  • relata restore replaces live data. Restore into a fresh directory and verify before routing traffic. The prior WAL is kept as a safety copy; rollback is not automatic.
  • The restore summary count is not a reconciliation: a recorded run printed 0 row(s) for a backup that held rows. Reconcile against the served data instead.
  • There is no relata upgrade command. Moving versions is a package or binary swap, and the supported rollback is restoring a backup taken before the swap.

Scheduled backups

relata backup-schedule --once --dir "$RELATA_BACKUP_DIR" runs the scheduler once (suitable for cron). The relevant settings are RELATA_BACKUP_DIR (default .relata/backups), RELATA_BACKUP_FULL_INTERVAL_SECS (86400), RELATA_BACKUP_INCR_INTERVAL_SECS (3600) and RELATA_BACKUP_RETENTION_DAYS (30). Retention never deletes a full backup while a retained incremental still depends on it.

Recovery drill and evidence

The repository's drill test drives the real binary through the runbook above on one node with a local filesystem, and compares the restored instance with the original. It shows that:

  • current rows, AS OF SYSTEM TIME history and WITH PROVENANCE output are equal after delete-the-data-directory and restore (non-empty golden sets);
  • a hot admin backup restores to exactly its capture boundary and excludes later writes;
  • restore --to selects the earlier of two recovery points;
  • bit-flipped, value-swapped, truncated and sealed-without-key artefacts are refused and leave an empty target untouched.

A measured single run (debug build, one laptop, 20,000 rows, plaintext) took 131 s for backup, dominated by offline WAL replay, and 8.1 s for restore, with a 16.8 MB artefact. That is not a published number. RPO is the interval between the backups you schedule: there is no continuous WAL shipping in this edition.

Not covered: vector and index snapshots, restoring a backup from a newer build into an older one, shared-object-store or cluster recovery, and Linux backup and restore qualification (not run).