| name | db-migration |
| description | Database schema changes, migrations, seed data, rollback plans, and data safety. Trigger on /db-migration, or when changing schema, writing migrations, seeding data, or planning rollbacks. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob, Bash, Edit |
Database Migration
Handle schema changes safely. Database mistakes are expensive to reverse.
Workflow
1. Understand the change
- What is the current schema? Read the schema file or last migration.
- What needs to change? New table, column, index, constraint, type change?
- Is this additive (new column) or breaking (rename, delete, type change)?
- Does it require a data backfill or transformation?
2. Design the migration
- Use the project's migration tool (Drizzle, Prisma, Knex, raw SQL, etc.).
- Write both
up and down (rollback) migrations.
- For breaking changes: is there a zero-downtime path? (add → migrate → drop)
- For data migrations: test on a copy of production data first.
3. Safety checks
- Additive changes — new columns should be nullable or have defaults.
- Destructive changes — never drop a column/table without confirming no references.
- Index changes — adding indexes locks tables on some databases. Know the impact.
- Type changes — ensure existing data is compatible (cast or backfill first).
4. Test
- Run migrations on a local/dev database first.
- Verify both
up and down work correctly.
- Run seed scripts after migration.
- Run tests that touch the changed schema.
5. Rollback plan
- Know how to revert before you apply.
- If the migration is irreversible (e.g., data loss), warn explicitly.
Rules
- Always write a rollback migration.
- Never run destructive migrations without review.
- Never migrate production data without explicit confirmation.
- Test on a copy of production data for backfill migrations.
Experience Log
This skill learns from experience. Mechanism:
- Read
.claude/experience/'"$s"'.md at skill start to benefit from past lessons.
- Write to
.claude/experience/'"$s"'.md after use if you learned something new.
- Format:
YYYY-MM-DD: <lesson> — one line per entry.
- Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.
