skills.rest
zakariaf
zakariafCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

shed-migrations

Writes forward-only additive Drift schema migrations with generated snapshots and verifier matrix tests.

Updated Jul 27, 2026
Search Tags:#code generation#sqlite#drift#flutter#schema migration#offline-first#database versioning
One-click install
npx skills add https://github.com/zakariaf/Shed-Book --skill shed-migrations-zakariaf
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: shed-migrations
Source: https://github.com/zakariaf/Shed-Book/tree/main/.claude/skills/shed-migrations
Command: npx skills add https://github.com/zakariaf/Shed-Book --skill shed-migrations-zakariaf

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing a SQLite schema migration for an offline mobile app is risky: a committed migration step and snapshot live on users' phones forever, with no server, no backfill, and no way to recall a bad release. This Skill enforces the five non-negotiable rules (forward-only, additive, never destructive, never re-meaning a column, one commit for bump plus generation plus tests) so a schema change ships without corrupting on-device data. ## Core Features & Use Cases - Migration step authoring: Guides the hand-written from<N>To<N+1> step in lib/core/db/migrations.dart, including the historical-schema trap (read schema.*, never db.* or today's table class) and the 12-step alterTable rebuild via drift's TableMigration. - Snapshot and codegen discipline: Runs make gen so drift_schemas/drift_schema_v<N>.json and generated test helpers land in the same commit as the version bump, with CI re-running generators and failing on any diff. - Verifier matrix extension: Extends the from-to migration matrix so every pair validates with PRAGMA foreign_key_check empty and quick_check ok, plus data-integrity tests for N-1 to N and every alterTable hop. - Use Case: When adding a new column to the ewes table, invoke this Skill to bump kSchemaVersion by one, write the additive step, regenerate the snapshot, and prove the whole from-to matrix still passes in a single commit. ## Quick Start Ask the AI to write a Shed Book schema migration for the new column you just defined, bumping the schema version and regenerating the drift snapshots and tests in one commit.

Frequently Asked Questions about shed-migrations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a Drift schema migration step in Flutter?▼

Bump kSchemaVersion by exactly one, add a from<N>To<N+1> callback to stepByStep() in migrations.dart using only createTable, addColumn, and createIndex, then run make gen and the drift test suite. Commit the bump, generated snapshot, and tests together.

How do I change a column type or add NOT NULL in SQLite with Drift?▼

Use await m.alterTable(TableMigration(schema.tableName)) instead of hand-rolling the 12-step rebuild, which corrupts triggers, views, and foreign keys. A columnTransformer is only for SQL storage changes, never for supplying values.

Why does my Drift migration break after a later schema version ships?▼

The step likely referenced db.* or today's table class instead of the historical schema.* object handed to the callback. Steps must read only the versioned schema so a v1 to v2 step still works when v9 adds columns.

Can I drop a column or table in a SQLite migration for an offline app?▼

No. Destructive changes on tables that held user records are forbidden because there is no server-side backfill. Dead columns are simply no longer written; dead tables are renamed with a _deprecated_v<N> suffix and dropped no earlier than two major versions later.

Why is PRAGMA foreign_keys not working inside my migration?▼

PRAGMA foreign_keys is a no-op inside a transaction, and Drift wraps migrations in one. Use PRAGMA defer_foreign_keys = ON inside the step and close it with PRAGMA foreign_key_check to validate deferred constraints.

What should I do when a shipped migration corrupts user data?▼

Never edit the committed step or snapshot, since phones that ran it will not run it again. Ship a repair as a new step at N+1 that may re-derive structural values but never invents domain data, and add a permanent regression test.

Related Skills

Explore More Software Engineering Skills→
zakariafzakariaf

eng-add-drift-table-or-migration

Manage SQLite/Drift schema changes and migrations with integrity checks.

Community
Advanced
rakibulismrakibulism
2

deploy-checklist

Generate a pre-deployment verification checklist with rollback criteria and monitoring steps.

Community
Intermediate
chris-prenerchris-prener

r-dependencies

Manages R package dependencies using renv lockfiles and DESCRIPTION conventions.

Community
Intermediate
sklonelysklonely
2

Unified Queue Design

Queue offline client actions in IndexedDB for retry against the server.

Community
Advanced