Backups Restore and Retention

Backups, Restore, and Retention

A backup is useful only when it is consistent, verified, protected, and restorable. CCAM provides two related mechanisms with different goals.

Choose the artifact

Artifact	Best for	Important property
SQLite online backup	Disaster recovery of a deployment	Exact database-level recovery
Versioned JSON export	Moving or merging supported dashboard records	Idempotent, non-destructive import; not a byte-for-byte restore

Production database backup

The deployment helper uses SQLite's online backup API and verifies integrity:

./deployments/scripts/db-backup.sh \
  --env production \
  --namespace agent-monitor-production \
  --output ./backups/

Keep the generated compressed database and SHA-256 checksum together. Store copies outside the host or cluster and encrypt them according to transcript sensitivity.

Restore discipline

Restore requires downtime because the database must have one writer. The supported helper verifies checksum and integrity, creates a pre-restore backup, scales the writer down, replaces the database, removes stale WAL/SHM files, restores one replica, and checks health.

./deployments/scripts/db-restore.sh \
  --env production \
  --namespace agent-monitor-production \
  --input ./backups/agent-monitor_production_TIMESTAMP.db.gz

Practice this in a non-production namespace. Record actual recovery time and verify representative sessions, costs, alert rules, and settings afterward.

JSON export and import

npx ccam export ccam-export.json
npx ccam import-data ccam-export.json

Import is idempotent and non-destructive: existing sessions are skipped rather than overwritten. Use it for portability, not for replacing a corrupted production database.

Retention policy

Define retention from privacy, investigation, capacity, and compliance requirements. Before cleanup:

1. measure database and backup growth;
2. confirm which records the operation removes;
3. create and verify a backup;
4. test the same policy on a copy;
5. document recovery limits;
6. run during a quiet window and verify health.

Do not delete raw provider history until you know whether it is your only recovery source. Avoid unreviewed cron jobs that call broad cleanup or destructive commands.

See the exact deployment backup and restore contract.