Backup, Restore & Version Upgrades¶

Complete Backup Procedure¶

Execute regular backups of relational data, graph lineage, vector snapshots, and workflow state:

# 1. Create backups directory
mkdir -p ./backups/$(date +%F)
BACKUP_DIR="./backups/$(date +%F)"

# 2. PostgreSQL Relational Backup (VDA & Keycloak databases)
docker exec -t vda-postgres pg_dump -U vda -d vda -F c -b -v -f /tmp/vda_pg.dump
docker cp vda-postgres:/tmp/vda_pg.dump $BACKUP_DIR/vda_pg.dump

# 3. SurrealDB Graph Lineage Export
docker exec -t vda-surrealdb surreal export \
  --conn http://localhost:8000 \
  --user root \
  --pass "${SURREAL_PASS}" \
  --ns "${SURREAL_NS:-vda}" \
  --db "${SURREAL_DB:-vda}" \
  /data/surreal_export.surql
docker cp vda-surrealdb:/data/surreal_export.surql $BACKUP_DIR/surreal_lineage.surql

# 4. Qdrant Vector Collection Snapshot
curl -s -X POST "http://localhost:6333/collections/cdm_metadata/snapshots"
docker cp vda-qdrant:/qdrant/storage/snapshots $BACKUP_DIR/qdrant_snapshots

Restore Procedure¶

To restore the platform to a new host or previous snapshot:

# 1. Restore PostgreSQL
docker cp ./backups/2026-10-13/vda_pg.dump vda-postgres:/tmp/vda_pg.dump
docker exec -t vda-postgres pg_restore -U vda -d vda --clean --if-exists /tmp/vda_pg.dump

# 2. Restore SurrealDB Graph Lineage
docker cp ./backups/2026-10-13/surreal_lineage.surql vda-surrealdb:/data/surreal_export.surql
docker exec -t vda-surrealdb surreal import \
  --conn http://localhost:8000 \
  --user root \
  --pass "${SURREAL_PASS}" \
  --ns "${SURREAL_NS:-vda}" \
  --db "${SURREAL_DB:-vda}" \
  /data/surreal_export.surql

Version Upgrade Workflow¶

Perform rolling upgrades without losing persistent volume data:

Perform a Pre-Upgrade Backup: Run the backup commands detailed above.

Update Image Tags in .env:

sed -i 's/GIT_SHA=.*/GIT_SHA=v2.2.0/' .env

Pull or Load New Images:
```
docker compose pull
```

Apply Database Schema Migrations:

# Run Prisma relational migrations
docker exec -it vda-server npx prisma migrate deploy

Recreate Platform Services:

docker compose --env-file .env up -d --remove-orphans

Verify Post-Upgrade Health: Execute the checks on the Verify the Installation page.