Backup and Restore

Checking backup status (no shell needed)

As an admin:

curl -s -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/settings/retention | jq .backup

Returns the last run's status, the last success time and age, artifact count and total bytes, retention settings — and scope: "same-disk" (see below).

Scope — what the automatic backups do and do not protect

Artifacts live on the same disk as the database. That protects against the realistic common failures — a stray write corrupting the database file, a fat-fingered delete, a bad migration — but not against loss of the disk or host. For disaster recovery, ship artifacts off-host on your own schedule (rsync/cron of /data/backups/, or your infrastructure's disk snapshots).

Tuning

# .env (all forwarded by both compose files)
DB_BACKUP_ENABLED=true      # false disables backups entirely (nightly + boot pre-migration)
DB_BACKUP_HOUR=3            # UTC
DB_BACKUP_MINUTE=30
DB_BACKUP_PG_DUMP_TIMEOUT_SECONDS=1800

Retention is deliberately not an env var — it is an ops setting (backup_retention_days) so it is validated (1–3650; 0 is rejected — disabling backups is DB_BACKUP_ENABLED=false, never “keep forever”).

Back up .env (manual, do this once per change)

cp .env ~/backups/trinity-env-$(date +%Y%m%d).bak
chmod 600 ~/backups/trinity-env-$(date +%Y%m%d).bak

Store it in a secure location (password manager, encrypted storage). Never commit it to git.

SQLite — use the safe online-backup primitive, never cp a live database (a raw copy of a file mid-write, ignoring its journal, can produce a torn or stale backup):

docker run --rm \
  -v trinity_trinity-data:/data \
  -v ~/backups:/backup \
  alpine sh -c "apk add -q sqlite && \
    sqlite3 /data/trinity.db \".backup '/backup/trinity-$(date +%Y%m%d-%H%M%S).db'\""

PostgreSQL (DATABASE_URL set):

# Bundled dev container
docker exec trinity-postgres pg_dump -U trinity -Fc trinity \
  > ~/backups/trinity-pg-$(date +%Y%m%d-%H%M%S).dump
# Managed/external PostgreSQL: use your provider's snapshot tooling,
# or pg_dump -Fc against the host with your connection string

Verify a backup

sqlite3 ~/backups/trinity-YYYYMMDD-HHMMSS.db "PRAGMA quick_check;"   # expect: ok

(The automatic job verifies every artifact — PRAGMA quick_check for SQLite, the PGDMParchive magic for PostgreSQL — before it is kept.)

1. Stop both database writers — backend AND scheduler

# Development
docker compose stop backend scheduler

# Production
docker compose -f docker-compose.prod.yml stop backend scheduler

2. Remove stale journal sidecars beside the target, then copy the artifact in

A leftover -wal/-shm/-journal file beside a restored .db is a corruption hazard — SQLite would try to replay a journal that belongs to the old database. Harmless if absent:

docker run --rm \
  -v trinity_trinity-data:/data \
  -v ~/backups:/backup \
  alpine sh -c "rm -f /data/trinity.db-wal /data/trinity.db-shm /data/trinity.db-journal && \
    cp /backup/trinity-backup-YYYYMMDD.db /data/trinity.db"

(To restore from an automatic artifact without copying it off-host first, the source path is /data/backups/trinity-backup-YYYYMMDD.db inside the same volume: cp /data/backups/trinity-backup-YYYYMMDD.db /data/trinity.db after the same rm -f step.)

3. Restart services

# Development
docker compose start backend scheduler

# Production
docker compose -f docker-compose.prod.yml start backend scheduler

4. Verify health

curl -s http://localhost:8000/health