db-migration

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.