drizzle-migrationslisted

How to safely add, edit, and verify Drizzle migrations in the skills-observability backend (PostgreSQL + Drizzle ORM). Covers the schema-first generation flow, the strict monotonicity invariant of `_journal.json` `when` timestamps (whose violation has silently skipped migrations in production), idempotent SQL patterns, and how to verify on a fresh DB before merging. Use this skill whenever the user edits `backend/src/db/schema.ts`, runs `bun run migrate:generate` or `bun run migrate:run`, hand-edits anything under `backend/src/db/migrations/` (including `meta/_journal.json`), asks about adding or altering a database column / table / index / constraint, debugs a migration that "didn't apply" or "ran in dev but not prod", or resolves a merge conflict in the migration journal. Trigger this even if the user only mentions a small schema tweak — the journal pitfall is the kind of bug where everything looks fine until production silently diverges, and the right time to apply this guidance is before the schema edit,
PackmindHub/skillsight · ★ 8 · API & Backend · score 75

Install: claude install-skill PackmindHub/skillsight

# Drizzle Migrations — skills-observability backend This skill exists because we lost meaningful production time to a class of migration bug that produces no error, no warning, and no test failure — until prod and dev silently disagree about what tables exist. The rules below are designed to keep that from happening again. Where a rule looks heavy-handed, the **Why** explains the real failure it prevents, so you can apply judgment at the edges. ## The Golden Path (schema-first) When a database change is needed, follow this exact sequence. Do not deviate without reading the rest of this document first. ``` 1. Edit backend/src/db/schema.ts (the source of truth) 2. cd backend && bun run migrate:generate (Drizzle writes the SQL + journal entry) 3. Open the generated *.sql and review it (catch destructive ops, missing IF NOT EXISTS) 4. Optionally tighten the SQL for idempotency (see "SQL idempotency" below) 5. Commit BOTH the .sql file AND the updated meta/_journal.json + meta/*.json snapshot 6. Verify against a fresh DB before merging (see "Verification" below) ``` If you find yourself hand-writing a `.sql` file under `backend/src/db/migrations/` from scratch, stop and ask whether the change can be expressed in `schema.ts` instead. Hand-authored migrations are valid in special cases (data backfills, raw SQL Drizzle can't generate), but they are off the golden path and need extra care — see "Hand-authored migrations" below. ## The invariant that bit us: journal