run-migration

Run migration (forward-only Drift schema migration)

Apply a schema change to a local Drift/SQLite database by following the exact ordered ritual below. In an offline-first app there is no server and no re-sync path, so the on-device DB is the single source of truth: a migration that drops or corrupts a column permanently destroys hand-entered records that exist nowhere else, and with no telemetry nobody ever reports it — the user just uninstalls. This is a manual, low-freedom, human-run workflow. Execute the steps in order; do not improvise, reorder, or skip.

Non-negotiable rules

1. Take the pre-migration snapshot FIRST — before the database is opened. Do it at the composition boundary that opens AppDatabase, never inside onUpgrade: PRAGMA wal_checkpoint(TRUNCATE) any live handle so the -wal is folded into the main file, then copy the DB file and its -wal/-shm sidecars while nothing holds the file open. Opening the database is what triggers the migration. Never copy or overwrite bytes under a live connection. The snapshot is the only "rollback" SQLite has; restore it on any failure.
2. Forward-only. Never write a down migration. SQLite has no true down migration and you must not pretend to. "Rollback" means restore the snapshot, nothing else.
3. Steps are append-only — NEVER edit a shipped step. Editing a released step corrupts data for every user who skips versions. To fix a bug in a prior step, add a new step and bump schemaVersion — never back-edit history.
4. Bump schemaVersion by exactly one per shipped schema change, and add the matching fromNToM branch. A schema changed without a version bump means no migration runs at all on the user's device — a CI gate must catch it.
5. Commit the versioned schema snapshot. Run drift_dev make-migrations (or schema dump), commit the exported snapshot under drift_schemas/, and commit schema_versions.dart. The delta becomes a reviewable diff and the test suite diffs live schema against it.
6. The open is wrapped in try/restore, entirely outside any connection. If opening the database throws, the migration failed and that connection is dead: close it, restore the snapshot file(s) taken before the open, and rethrow. All file operations happen while nothing has the DB open — never overwrite the live file from inside onUpgrade.
7. A green shape check is necessary, never sufficient. migrateAndValidate compares CREATE statements only — it never reads a row. A migration that rebuilds a table perfectly and copies zero rows passes it, green. The content test is the deliverable, not the shape test.
8. No migration merges without the full test suite green — every from → to path (including multi-version jumps), a content test per new pair, PRAGMA integrity_check == ok, PRAGMA foreign_key_check empty, and a forced mid-migration throw that restores the snapshot.
9. Store canonical values only in any new column (integer minor units for money keyed to the ISO-4217 exponent, SI integers for quantities, UTC epoch millis for instants, a local serial-day integer for a calendar date). Never add a float-money, display-string, or localized-numeral column.