---
name: db-migrate
description: "Use when creating, applying, rolling back, or checking the status of database migrations. NOT for shipping the application release that carries the migration (use `deploy`)."
triggers:
  - "database migration"
  - "db migrate"
  - "migration status"
  - "Create migration"
  - "Run migrations"
  - "Rollback migration"
metadata:
  author: "MrCipherSmith"
  version: "1.0.0"
  category: "quality"
  compatible_harnesses: "cursor,codex,zed,opencode,claude"
license: "MIT"
---

# Database Migration

Create, apply, and manage database migrations.

## Arguments

- `/db-migrate create <name>` — create new migration
- `/db-migrate apply` — apply pending migrations
- `/db-migrate status` — show migration status
- `/db-migrate rollback` — rollback last migration

## Workflow

### Step 1: Detect ORM/Migration Tool
Search for: `prisma/schema.prisma`, `ormconfig.*`, `data-source.ts`, `knexfile.*`, `.sequelizerc`, `drizzle.config.ts`, `alembic.ini`, `migrations/` with raw SQL.

### Step 2: Execute Command

**Create:**

| Tool | Command |
|------|---------|
| Prisma | `npx prisma migrate dev --name <name>` |
| TypeORM | `npx typeorm migration:generate -n <name>` |
| Knex | `npx knex migrate:make <name>` |
| Sequelize | `npx sequelize-cli migration:generate --name <name>` |
| Drizzle | `npx drizzle-kit generate:migration --name <name>` |
| Alembic | `alembic revision --autogenerate -m "<name>"` |

**Apply / Status / Rollback** — analogous commands per tool.

### Step 3: If Creating — Help Write Migration
1. Ask what schema changes are needed (or infer from context)
2. For schema-based ORMs — edit schema first, then generate
3. For code-based migrations — generate template and fill in up/down
4. Review generated migration before applying

### Step 4: Apply & Verify
1. Show migration SQL preview if possible
2. Apply migration
3. Verify with status command

## Rules

- ALWAYS show migration content before applying in production
- ALWAYS confirm before rollback operations
- NEVER apply to production without explicit confirmation
- For destructive operations (drop table, remove column), double-warn
- If ORM can't be detected, ask the user

## Red Flags

| Rationalization | Why it is wrong |
|---|---|
| "The ORM autogenerated it, so the SQL must be correct" | Autogenerate routinely emits drop-and-recreate for a change that could have been an in-place alter. The generated file is a draft to read, not an answer to trust |
| "It's only the dev database, no need to show the SQL first" | The same file is what runs against production later. The preview is the one moment the destructive statement can still be caught, and skipping it in dev means nobody ever read it |
| "A rollback is unlikely, so an empty `down` is fine" | An empty `down` is worse than a missing one: the rollback reports success while changing nothing, and the schema silently stays ahead of the code |
| "Two migration tools are configured; I'll use the one I know" | Each tool keeps its own history table. Picking the wrong one writes a migration the project's real tool will never see and cannot roll back. Ask which is authoritative |
| "`prisma migrate dev` is the standard create command, just run it" | On a database with any drift it offers to reset — i.e. drop the data. Know what the create command does to an existing database before pointing it at one |

## Verification

Do not report the migration as done until all of the following hold:

- The status command shows the intended migration in the intended state (applied, or pending for `create`), and no other migration changed state
- The migration file carries both directions (up and down, or the ORM's equivalent) and the down path was read, not assumed
- Any destructive statement (`DROP`, `ALTER … DROP`, `TRUNCATE`, a column removal) was shown to the user and confirmed in this conversation before it ran
- The report names the detected tool, the migration name/id, and the environment the command ran against
- For a production target: an explicit confirmation exists in this conversation, and the SQL preview preceded it