Operator reference for verified cold backups and restore of a CortexDB data directory.

Backups & Disaster Recovery

The supported backup path for CortexDB is a verified cold backup of the data directory, using the scripts/cold_backup.py tool that ships in the source repository:

  • cold — the server must be stopped; the tool refuses to archive a data directory that a running CortexDB process still holds open
  • byte-for-byte — the complete data directory is archived, including the WAL (the source of truth) and every derived index
  • verified — the archive carries a per-file SHA-256 manifest; restore only completes after every file's digest verifies

Online/hot backups, scheduled backup jobs, object-store upload targets, and point-in-time recovery (PITR) are not implemented in the current server. They are a separate, planned project — do not build a recovery plan around them today.

Taking a backup

  1. Stop the CortexDB server.
  2. Archive the data directory:
python scripts/cold_backup.py backup <data_dir> <archive.tar.gz>

The tool walks the data directory, hashes every file (SHA-256), and writes a tar.gz containing the files plus a CORTEX_BACKUP_MANIFEST.json manifest. If a RocksDB LOCK file is still held by a live process, the backup is refused — a copy taken while the server is writing would not be consistent.

  1. Restart the server and ship the archive off-host (your object store, backup system, or vault — the upload step is yours to operate).

Verifying an archive

python scripts/cold_backup.py verify <archive.tar.gz>

Recomputes every file digest against the manifest. Tampered or truncated archives fail verification. Run this after transferring an archive between hosts and periodically against your retained backups.

Restoring

python scripts/cold_backup.py restore <archive.tar.gz> <fresh_target_dir>
  • The restore target must be fresh — the tool refuses to restore over an existing, non-empty directory.
  • Every file is digest-verified before the restore is considered complete. A failed restore leaves the target absent rather than half-written.
  • Exit code 0 means the restore completed and verified; non-zero means it did not.

After a successful restore, point the server at the restored directory and start it:

cortexdb 3141 <fresh_target_dir>

Confirm the instance is serving with the readiness endpoint:

curl http://localhost:3141/v1/admin/ready

Recovery point and scheduling

Because backups are cold and manual, your recovery point objective (RPO) is set by how often you can afford the stop-backup-start window. Typical shapes:

  • schedule a nightly maintenance window: stop, backup, start, upload
  • verify the archive after upload, and again before you rely on it
  • retain multiple generations off-host; a backup you have never test-restored is not a backup

What about the old [security.backup] config?

Earlier documentation described scheduled backups, cloud upload targets (s3 / gcs / azure), WAL archival, and PITR configured under [security.backup]. That capability is not present in the current server; the config-driven online backup system and PITR are planned work. The cold backup tool above is the supported and tested path.

Related docs