---
name: db-migration
description: >
  Playbook for safe database schema changes. Use whenever adding, altering, or
  dropping a table/column/index, or writing a migration file.
---

# Database Migrations

## Rules
- Migrations are forward-only and reversible-by-design (write the down path).
- Never drop a column in the same release that stops writing it — use expand/contract.
- Backfills run in batches; no single statement locks a hot table.

## Expand / contract (the default for breaking changes)
1. Expand: add the new column/table, dual-write, deploy.
2. Migrate: backfill in batches; verify.
3. Contract: switch reads, stop writing the old, drop it in a LATER release.

## Checklist before merge
- [ ] Up and down both tested on a copy of prod-shaped data.
- [ ] No long-held locks (check with EXPLAIN / lock analysis).
- [ ] Indexes created CONCURRENTLY where the engine supports it.
- [ ] Audit/ledger tables are never destructively altered.

Keep engine-specific lock notes in references/ (tier-3).