Backup & Restore
/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.
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 queryrelata backupwith 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/backupon 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 backuploads the server configuration, so run it with the same authentication settings you use forserve.relata restorereplaces 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 upgradecommand. 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 TIMEhistory andWITH PROVENANCEoutput 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 --toselects 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).
Related
- Capacity planning and WAL retention
- SIEM/SOC migration, which uses backup and restore as its rollback boundary
- 3.0 evidence status