Backup, Restore, and Disaster Drills

~18 min · chroma, operations

Level 0Scout

0 XP0/41 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Chroma's on-disk format is a SQLite + parquet pair

The chroma_store/ directory contains a SQLite metadata DB and per-collection parquet files. "Backup" means "copy this directory while the writer is paused." "Restore" means "point a fresh PersistentClient at the copied directory."

The backup recipe that survives in production

Pause writes (or accept that writes during backup may be lost).
tar -cf chroma-$(date +%F).tar chroma_store/ or rsync to a sibling directory.
Verify by opening the copy with a fresh client and counting documents.
Push the archive to off-host storage (S3, NAS, another Mac).

Recovery drill

Once a quarter, restore last week's backup into chroma_store_recovery/, point a script at it, and confirm that retrieval still works. A backup you have never restored from is not a backup.

Code

Snapshot the store while writes are quiesced·text

# 1. Stop the writer process (or set the API to read-only).
# 2. Snapshot:
rsync -a --delete chroma_store/ chroma_store_$(date +%F)/
# 3. Tar + compress for off-host:
tar -czf chroma_$(date +%F).tar.gz chroma_store_$(date +%F)/
# 4. Resume writes.

Verify a backup loads cleanly·python

client_test = chromadb.PersistentClient(path='./chroma_store_2026-05-03')
for c in client_test.list_collections():
    coll = client_test.get_collection(c.name)
    print(f'{c.name}: {coll.count()} rows')
    sample = coll.peek(2)
    print(f'  sample id={sample["ids"][0] if sample["ids"] else None}')

External links

Exercise

Schedule a daily backup of your chroma_store/ to a sibling directory using cron, launchd, or a scheduler of your choice. Then run a recovery drill: open the most recent snapshot with a fresh client, run 3 queries, confirm results match the live store.