Backup and upgrades

Backup

Keep the database running and write a custom-format backup outside the volume:

docker compose --env-file .env.prod -f compose.yaml -f compose.prod.yaml \
  exec -T postgres pg_dump -U abada -d abada_engine -Fc > abada-engine.dump
shasum -a 256 abada-engine.dump > abada-engine.dump.sha256

On the single-VM server, use --env-file .env.server and compose.server.yaml, and also back up the Keycloak database and .env.server, which holds the only copy of the generated secrets:

docker compose --env-file .env.server -f compose.yaml -f compose.server.yaml \
  exec -T keycloak-db pg_dump -U keycloak -d keycloak -Fc > keycloak.dump

Test restore into a separate environment. For an in-place restore, stop the engine first, verify the checksum, and stream the backup to PostgreSQL:

shasum -a 256 -c abada-engine.dump.sha256
docker compose --env-file .env.prod -f compose.yaml -f compose.prod.yaml stop abada-engine
docker compose --env-file .env.prod -f compose.yaml -f compose.prod.yaml \
  exec -T postgres pg_restore -U abada -d abada_engine --clean --if-exists < abada-engine.dump

Upgrade

1. Read every intervening release note and take a tested backup.
2. Download the new release archive and verify its SHA-256 checksum.
3. Copy your .env.prod, set ABADA_VERSION to the exact new version, and run ./release/abada-platform doctor prod --env-file .env.prod.
4. Pull the images, then run the explicit production up command. On the server profile, set the four ABADA_*_IMAGE tags in .env.server to the new version and run ./release/abada-platform up server.
5. Wait for health, verify Flyway, start and complete a canary workflow, and inspect the Studio Operations tab history before removing the prior archive.

Never edit a released Flyway migration or downgrade a database without a release-specific rollback procedure. Image rollback alone cannot undo a schema migration.

Upgrading to 1.1.0-rc.2

Upgrade the engine, Studio and the Agent Worker together. Flyway applies seven additive migrations, V27 to V33: tool servers and credentials, the agent step journal, call-process lineage, model prices and evidence, tool approvals, delegation and the event stream.

Before you upgrade	Why
Set ABADA_ENCRYPTION_KEY and keep it with your backups	Tool credentials and journaled payloads are encrypted with it
Set ABADA_AGENT_ALLOWED_TOOLS on the worker	Agents call only the tool servers the operator allows
Check Settings → Model Prices (from 1.1.1 the public catalog fills the gaps; add your own price for a negotiated rate)	A step with budget_usd fails closed for an unpriced model

Going back to 1.1.0-rc.1 requires restoring the backup you took before the upgrade. Details: docs/operations/upgrading.md in the repository.

Upgrading to 1.1.0-rc.1

Upgrade the engine and the Agent Worker together. Flyway applies four migrations:

Migration	Change	Action
V23	Execution tokens move to their own table	None: each running instance is converted the first time it moves
V24, V25	Incidents and bounded loops	New deployments must give every cycle a repeat limit; deployed processes keep running
V26	Timeouts, service levels and model fallback	sla_hours is now enforced, and a step whose work fails for good opens an incident

Going back to 1.0.0-rc.8 works without restoring the backup, with two precautions: cancel instances that have an open incident (rc.8 does not know them), and run the two SQL clean-ups listed in the release notes (pending timeout/SLA jobs, retired external tasks). Details: docs/operations/upgrading.md in the repository.