# run-migration

> Claude/Codex skill by [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars · Updated 2026-09-23

Runs the forward-only Drift/SQLite schema-migration ritual — the most dangerous deterministic operation in an offline-first app: a bad migration silently destroys on-device rows that exist nowhere else. Enforces the exact ordered sequence: take a pre-migration file snapshot before the database is opened, bump schemaVersion by exactly one, write an append-only stepByStep forward step (never edit a shipped step, never write a down migration), commit the drift\_dev make-migrations schema snapshot, regenerate, then prove it with tests covering every from→to path (incl. multi-version jumps), a write-at-v(n)/read-at-v(n+1) content test, PRAGMA integrity\_check + foreign\_key\_check, and a forced mid-migration throw that restores the snapshot. Manual, side-effecting workflow. Use when adding or altering a Drift table, column, index, or CHECK; bumping schemaVersion; editing onUpgrade/stepByStep; or writing migration tests.

Tags: agent-skills, ai-agents, best-practices, claude-code, codex, coding-agent, cursor, dart, dartlang, developer-tools, drift, flutter, flutter-architecture, github-copilot, go-router, llm, material-design, mvvm, riverpod, skills

## Install

```sh
git clone https://github.com/zakariaf/Flutter-Skills /tmp/Flutter-Skills && ln -s /tmp/Flutter-Skills/skills/run-migration ~/.claude/skills/run-migration
```

## From README

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 Take the pre-migration snapshot FIRST — before the database is opened. Do it at the composition boundary that opens AppDatabase, never inside onUpgrade: PRAGMA walcheckpoint(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.

## Links

- HTML page: https://omgskills.com/library/zakariaf/flutter-skills/skills/run-migration/
- GitHub: https://github.com/zakariaf/Flutter-Skills
- Author: [@zakariaf](https://omgskills.com/library/zakariaf/index.md)

## More from this repo

- [accessibility-as-code](https://omgskills.com/library/zakariaf/flutter-skills/skills/accessibility-as-code/index.md) — Enforces accessibility as a correctness property authored into each widget — Semantics(button/label) or...
   - [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars
- [adaptive-layout](https://omgskills.com/library/zakariaf/flutter-skills/skills/adaptive-layout/index.md) — Enforces adapting layout by available CONSTRAINTS/size, never device or platform checks — LayoutBuilder +...
   - [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars
- [ads-and-iap-monetization](https://omgskills.com/library/zakariaf/flutter-skills/skills/ads-and-iap-monetization/index.md) — Enforces opt-in, rewarded-first monetization over the service seam — a rewarded view grants exactly one benefit and...
   - [@zakariaf](https://omgskills.com/library/zakariaf/index.md) · 61 stars