# Runbook: Database Migration Release

Last updated: 2026-06-24

## Purpose

Use this runbook for every release that adds, changes or removes database migrations.

## Before Approval

1. Generate the release migration plan:

```bash
cd backend
go run ./cmd/migration-plan -dir migrations -format json -require-rollback
```

2. Attach the generated JSON to the release evidence package.
3. Run the migrations against a staging or production-like clone.
4. Verify application smoke checks, ledger invariant tests and critical admin reads.
5. Verify every new `.up.sql` migration has a matching `.down.sql` rollback file.
6. Record the dry-run result and rollback evidence in `database_release_migration_plans`.
7. Fill the `Database Migrations` section in `docs/release-notes-template.md`.

## Production Execution

1. Confirm the GitHub `production-migration-approval` environment approval is complete.
2. Confirm the `migration-plan.json` artifact matches the commit being deployed.
3. Run migrations through the approved release pipeline or controlled DBA process.
4. Keep application instances out of write traffic during incompatible migration windows.
5. Run `/readyz`, login, account list, transfer list and admin dashboard smoke checks.
6. Record execution status and evidence reference.

## Rollback

1. Stop new write traffic for affected product areas.
2. Restore from PITR or apply approved `.down.sql` files only when rollback is known safe.
3. Re-run ledger and wallet/account invariant checks.
4. Reconcile any provider callbacks or webhooks received during the window.
5. Link rollback evidence to the release record and incident/change ticket.

## Escalation

Escalate to engineering, finance operations, security and compliance if migration failure affects money movement, ledger integrity, audit records, authentication, KYC/AML, cards, crypto or customer PII.