Backup and recovery

nyxdb-backup is the supported single-node recovery tool. It captures the catalog WAL, newest committed catalog and parts checkpoints, and immutable parts referenced by that checkpoint. A backup becomes visible only after its objects and manifest are durably published.

Current scope

The v1 backend is a local directory and supports the synthesized default disk rooted at --data-dir. If a checkpoint references another disk or mirror placement, creation fails with the part and disk identity rather than producing an incomplete backup.

Native object-store transport, continuous remote backup, and automatic cross-node disaster recovery are not current capabilities.

Create

Backup creation is online:

nyxdb-backup create \
  --data-dir /var/lib/nyxdb \
  --repository /mnt/nyxdb-backups

Record the output:

manifest_id=4452d21e-c15d-42a4-86c7-a3e021737d95
frontier_sequence=8192000
pitr_min_sequence=8191500
objects=143
bytes=1074812534
fence_us=932
lag_bytes=32768

The descriptor fence is not a global write lock. The tool captures stable file descriptors and lengths, retries namespace races, then copies and hashes outside the fence. It trims an active WAL copy to a CRC-valid logical commit boundary.

Creation fails closed on a missing checkpoint-listed part, malformed checkpoint, WAL gap or mid-log corruption, inaccessible namespace, or exhausted capture retries. It never edits the source data directory.

List and inspect

nyxdb-backup list --repository /mnt/nyxdb-backups

Only committed backup directories are listed. Incomplete work remains under .staging and is not restorable. Preserve manifest.json, manifest.sha256, and status.json as one immutable recovery record.

Alert on:

• any failure record;
• a missed scheduled backup;
• rising or sustained lag_bytes;
• repeated descriptor-fence retry exhaustion;
• repository capacity/availability; and
• absence of a recent successful restore drill.

Restore latest

Stop the destination engine. Restore into a path that does not contain a database:

nyxdb-backup restore \
  --repository /mnt/nyxdb-backups \
  --manifest 4452d21e-c15d-42a4-86c7-a3e021737d95 \
  --target-data-dir /var/lib/nyxdb-restored

Restore verifies:

• manifest checksum and catalog identity;
• every object length and SHA-256;
• checkpoint CRC32C frames;
• the required WAL sequence chain; and
• structural replay of typed catalog records and logical batches.

It publishes RESTORE_READY only after the target is complete and fsynced. A failed or interrupted restore keeps RESTORE_IN_PROGRESS and no ready marker. Retry the same manifest and target after fixing availability; matching objects are reused and incomplete/mismatched objects are replaced.

Restore rejects a non-empty unmarked directory and rejects applying a different manifest/target sequence over an existing restore. Choose a new empty target.

Point-in-time recovery

PITR targets an inclusive unified-journal sequence:

nyxdb-backup restore \
  --repository /mnt/nyxdb-backups \
  --manifest 4452d21e-c15d-42a4-86c7-a3e021737d95 \
  --target-data-dir /var/lib/nyxdb-at-sequence \
  --target-sequence 8191800

The target must satisfy:

pitr_min_sequence <= target_sequence <= frontier_sequence

It must also be a logical commit boundary. For a multi-record commit, select the commit-manifest sequence, not a member record. The tool rejects targets that would expose a partial logical batch or require undoing checkpointed state.

Do not derive a sequence from filesystem timestamps. Record the desired sequence from application commit metadata or use a freshly printed backup frontier.

Retention

nyxdb-backup prune \
  --repository /mnt/nyxdb-backups \
  --keep-last 14 \
  --max-age-hours 168

Count and age are additive: the newest 14 and every backup younger than 168 hours are retained. Eligible backup directories move atomically to .trash before deletion.

Run prune only after a restore drill proves at least one retained manifest is usable. Repository retention is independent of source WAL garbage collection.

Recovery drill

At a minimum, schedule:

1. a normal online create under representative ingest;
2. restore of the newest manifest into a new empty path;
3. protocol/query validation against that restored copy;
4. keyed and append row/key checks plus catalog comparison;
5. a PITR restore at a known commit boundary;
6. interruption/resume and checksum-corruption failure tests;
7. measured wall time, copied bytes, recovered frontier, and data equality; and
8. cleanup only after the evidence is archived.

Publish RPO and RTO from recent drills on the production storage and machine class—not from an ADR estimate.