database-migrationlisted

# Database migration A migration is the one change that **cannot be rolled back by reverting the commit**. Code reverts; data that has already moved does not. Treat every migration as one-way until you have proven otherwise. Where a platform skill exists, use it — `axiom-database-migration`, `axiom-swiftdata-migration`, or the auditor for your store. **External and optional**; missing → follow this file. ## Before you write it 1. **Enumerate every writer and every reader of the affected data** (`defect-hunting` §1). The migration that stops one layer short is FC-001, and this is the surface where it costs most. 2. **Name the old and new shape explicitly**, including what happens to rows that violate the new constraint *today*. There are always some. 3. **Decide expand or contract.** Almost always expand first: - *Expand*: add the new column nullable, write both, backfill, read new with fallback to old. - *Contract*: only after every deployed client and server writes the new shape. On mobile that means **after the oldest supported app version is gone**, which is months, not the next sprint. 4. **Say how you roll back.** If the answer is "restore a backup", say that explicitly — it is a real answer, and it changes the deploy plan. ## Writing it - **Forward-only, versioned, and ordered.** Never edit a migration that has run anywhere. - **Idempotent**: safe to run twice, because it will be. - **Transactional** where the engine allows it, and where it doe