Database migration
Use before changing any persisted schema — by backend-developer on a server store, by web-developer on a client or server store, and by reliability-engineer when reviewing a change that migrates data. Triggers on the first column, field, index or model change, not on the deploy.From its SKILL.md
npx -y skills add vmobifystudio/app-dev-team --skill database-migrationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.9 KB, as published. Nobody here has run it
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
- 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. - Name the old and new shape explicitly, including what happens to rows that violate the new constraint today. There are always some.
- 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.
- 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 does not (many
ALTER TABLEpaths), say so and make each step independently safe. - Never
DROPin the same release that stops using the column. Two releases, minimum. - Backfill in batches with a bound, not in one statement that locks the table.
- A
NOT NULLcolumn gets a default or a backfill in the same migration — this is the single most common way a migration fails in production and not in dev.
Proving it
- Run it against a copy of real-shaped data with the awkward rows in it — nulls, duplicates, the pre-unicode row, the one from the first version. A migration tested only on a fresh database has been tested on the one case that never occurs.
- Run it twice and confirm the second run is a no-op.
- Run the previous application version against the migrated schema. During any rollout both exist at once, and this is the check that catches it.
- Count rows before and after, and state both. "It seemed to work" is not a result.
Output
The migration file, plus in the ticket: old shape, new shape, expand-or-contract, rollback plan, row counts before and after, and the awkward-data cases you ran it against.