Skip to content

0016 — Migrations apply on merge, after a verified backup

Status: accepted (2026-10-12) — supersedes 0015

Context

0015 split migration out of the backend deploy. deploy-backend refused to deploy while anything was pending, and migrate-production applied migrations only under an armed manifest that was commit-bound, list-bound, operator-bound and single-use. A release carrying a migration took three runs (deploy, which built and then refused; migrate; deploy again), plus an arming commit before and a disarming commit after.

This repository has one operator. 0015 said plainly that its gate was not four-eyes approval: the same account armed and spent every authorization. It added friction without adding independent review. The platform is pre-launch and its migrations are additive. On 2026-10-12 the owner decided the gate was not worth keeping.

Decision

deploy-backend.yml applies pending migrations again. After its existing verified pg_dump backup, it runs migration:show (logged), then migration:run:prod from the image it has just pulled, then checks again. It refuses to deploy, before restarting anything, if that check errors, lists no applied migrations, or still shows anything pending. Only then does it run docker compose up -d.

migrate-production.yml stays as a plain manual tool. It is workflow_dispatch only and dry_run defaults to true. Applying needs a typed MIGRATE confirmation, takes its own verified pre-migrate-* backup, runs migration:run:prod and checks that nothing is still pending. It needs no authorization.

The authorization manifest, its verifier and the verifier's spec are removed. There is no arming, no consumed ledger and no disarming.

Consequences

  • A schema change needs no separate approval. Merging a pull request to main that touches aim-digigold-real/** triggers deploy-backend, which applies every pending migration. The operations portal's Build Tools "backend" button dispatches the same workflow, so it migrates too. If the GitHub production Environment has required reviewers, the deploy job still waits for approval. That is a repository setting; this workflow does not enforce it.
  • A bad migration reaches production on merge. Three things mitigate it. CI's backend_integration job applies every migration to a real PostgreSQL on every pull request. TypeORM applies the pending set in one transaction, so a failure part-way rolls the whole set back and the old containers keep serving on the old image. The verified pre-deploy-* backup taken first is the restore point.
  • Migrations must stay additive and forward-only. If a migration succeeds and a later step of the deploy fails, the previous containers keep serving against the new schema. The warning in 0004 applies again: a generated DROP will be executed in production if merged.
  • Revisit this before real customer money moves through the system, and once a second operator exists who could review independently.