db-migrate

DB Migrate

Create, check the status of, and validate database migrations across any framework. Auto-detects the migration tool from project marker files and drives its native CLI: this skill never invents a migration command.

Ground rules

• Detect before acting. Scan for marker files (Phase 1) before running anything.
• Never invent commands. Only run commands from the detection table in references/framework-commands.md or found in the project's own docs/scripts.
• Flag destructive operations and never auto-fix them. DROP TABLE, DROP COLUMN, TRUNCATE, DELETE FROM get a warning and require the user's explicit go-ahead: this skill reports, it does not silently rewrite or apply a migration containing one.
• Report only what a command actually produced. File paths, migration names, and status output in the final summary must come from ls/cat/the framework CLI's own output, never guessed or reconstructed from memory.

Workflow

Phase 1: Detect framework

ls alembic.ini prisma/schema.prisma knexfile.* flyway.conf flyway.toml \
   db/migrate/ manage.py atlas.hcl typeorm.config.* ormconfig.* \
   liquibase.properties 2>/dev/null

Also check package.json (knex, db-migrate, sequelize, typeorm), pyproject.toml/requirements.txt (alembic, sqlalchemy), and Gemfile (activerecord) for framework dependencies when no marker file is conclusive.

If multiple frameworks are detected (e.g. a monorepo with both a Python and a Node service), ask the user which one they mean. If none is detected, ask the user to name it: don't guess a command for a framework you can't confirm.

Full detection table and per-framework commands: references/framework-commands.md, load it once the framework is identified, before running any create/status/rollback command.

Phase 2: Parse the request

Determine the operation from $ARGUMENTS or the user's phrasing:

• create (default if unspecified): make a new migration file
• status: show pending vs. applied migrations
• validate: check rollback coverage, naming convention, index coverage, destructive ops

If --name <name> is given, use it. Otherwise ask for a short, descriptive name before creating the file: don't invent one. --dry-run shows what would be created/run without executing it.

Phase 3: Execute

Production guard. Before running any command that connects to a database (status, autogenerate/schema-diff create, shadow-database commands like prisma migrate dev, or anything that applies or rolls back), check where it points: the environment name (APP_ENV, RAILS_ENV, NODE_ENV, DJANGO_SETTINGS_MODULE), the DATABASE_URL or framework config host, and the target named in --env/profile flags. If any of it looks like production (prod, production, a non-local managed-cloud host), stop and ask the user to confirm before running. Commands that only write a file offline need no check.

create

1. Check naming conventions in existing migrations (Glob migrations/, db/migrate/) and match the project's pattern.
2. Run the framework-native create command from the reference table (use --autogenerate / schema-diff mode where the framework supports it, e.g. Alembic, Prisma).
3. Read the generated file back and show it to the user: don't just report that a command succeeded.
4. Run the validate checks below on the new file, then fix what is fixable in place: add a missing down/reverse, add a CREATE INDEX for an unindexed foreign key, rename a file that breaks the naming pattern. Re-validate after each fix. Stop after 3 rounds, or sooner once clean, and report what still fails.
5. Never auto-fix destructive operations or mixed data + schema changes: report them for the user's decision.
6. Remind the user to review the final diff.

status

Run the framework's status command and show applied migrations (with timestamps), pending migrations, and the current schema version, copied from that command's real output.

validate

Also runs automatically on a new file at the end of create. Check the target migration file(s) for:

1. Rollback exists: every up/forward change has a matching down/reverse (warn if missing).
2. Naming convention: matches the pattern already used in the migrations directory.
3. Foreign-key indexes: grep -iE "REFERENCES|foreign_key|FK_" and confirm a corresponding CREATE INDEX exists.
4. Destructive operations: grep -iE "DROP TABLE|DROP COLUMN|TRUNCATE|DELETE FROM", flag every hit by line.
5. Mixed data + schema changes: warn if one file both alters structure and mutates rows, since these usually deploy and roll back better as two files.

Phase 4: Report

Summarize using only what Phases 1–3 actually produced:

• File path(s) touched
• Migration name and timestamp
• Warnings found (destructive ops with line numbers, missing rollback, missing index): omit the section entirely if there were none, don't write "no issues found" as a guess
• Next step commands (apply / rollback), taken verbatim from the detection table for the detected framework

Notes

• Review auto-generated migrations before applying: autogenerate can include unintended changes (e.g. Alembic missing custom types).
• Prefer transactional DDL where the database supports it, for atomicity. MySQL auto-commits DDL: flag this to the user when detected instead of assuming a transaction wraps it.

Worked examples

1. Create, framework auto-detected (Alembic)

$ ls alembic.ini → found
Framework: Alembic
$ alembic revision --autogenerate -m "add_users_email_index"
  Generating migrations/versions/a1b2c3_add_users_email_index.py ... done

Created: migrations/versions/a1b2c3_add_users_email_index.py
  upgrade(): op.create_index('ix_users_email', 'users', ['email'])
  downgrade(): op.drop_index('ix_users_email', table_name='users')

Validated (round 1 of 3): rollback present, no destructive ops, no foreign keys.
Next: `alembic upgrade head` to apply, `alembic downgrade -1` to roll back.

2. Status check (Prisma)

$ npx prisma migrate status
3 migrations found, 1 pending: 20260710120000_add_orders_table

Applied: 20260601090000_init, 20260615140000_add_users_table
Pending: 20260710120000_add_orders_table
Next: `npx prisma migrate deploy` to apply the pending migration.

3. Validate, destructive op found (Knex)

$ grep -iE "DROP TABLE|DROP COLUMN|TRUNCATE|DELETE FROM" migrations/20260716_cleanup.js
12: knex.schema.dropTable('legacy_sessions')

WARNING: destructive operation at line 12 (dropTable).
Rollback (down()) is present but only recreates an empty table — dropped data is not recoverable from this migration alone.
This needs your explicit confirmation before it's treated as ready to apply.

4. No framework detected

$ ls alembic.ini prisma/schema.prisma knexfile.* ... → none found
$ grep -l "knex\|sequelize\|typeorm" package.json → no match

I couldn't detect a migration framework from marker files or dependencies.
Which one are you using, or is this a brand-new project without one yet?

5. Two frameworks detected in a monorepo

$ ls alembic.ini → found (api/)
$ ls prisma/schema.prisma → found (web/)

Both api/alembic.ini (Alembic) and web/prisma/schema.prisma (Prisma) are present.
Which service's migration do you want — api (Alembic) or web (Prisma)?