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 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.

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. 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.

3. Restart the server and ship the archive off-host (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 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 a 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 confirm readiness:

cortexdb 3141 <fresh_target_dir>
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 shape:

• 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.

Related docs

• Export & Import — logical event export (distinct from a full backup)
• Enterprise Security
• Deployment Presets