Backup and Restore

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

Pulling an artifact to your workstation (GCP-hosted instances)

Two scripts in the repo serve one specific topology — a Trinity instance on a GCP VM managed from a workstation with gcloud and a deploy.config (copy deploy.config.example and fill in GCP_PROJECT, GCP_ZONE, GCP_INSTANCE, REMOTE_DIR). They are not general-purpose backup tools:

• •./scripts/deploy/backup-database.sh [backup_dir] — does not create a backup. It finds the newest automatic artifact (trinity-backup-*.db or .dump) under ~/trinity-data/backups on the VM, downloads it with gcloud compute scp into ./backups/ (or the directory you pass), and verifies it locally (PRAGMA quick_check for SQLite if sqlite3 is installed, the PGDMP magic bytes for PostgreSQL). If no artifact exists it points you at the backup status block.
• •./scripts/deploy/restore-database.sh <backup_file> — SQLite only. Asks for confirmation, uploads the file to the VM, stops backend and scheduler with docker compose -f docker-compose.prod.yml, removes stale -wal/-shm/-journal sidecars, copies the file over ~/trinity-data/trinity.db, starts both services again, and waits ten seconds.

For any other host, use the commands in this page directly, or the Ops Agent's backup.sh (online backup to ~/backups/ on the instance, SQLite or bundled PostgreSQL).

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

# Hosted
docker compose -f docker-compose.hosted.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. On a bind-mount install, run the rm -f and cp directly against ${TRINITY_DATA_PATH}/.)

3. Restart services

# Development
docker compose start backend scheduler

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

# Hosted
docker compose -f docker-compose.hosted.yml start backend scheduler

4. Verify health

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