db-migrate

Files (4)

• SKILL.md
• evals.json · evals/
• trigger-eval.json · evals/
• framework-commands.md · references/

SKILL.md (first lines)

# 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](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

```bash
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](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

From mgiovani/cc-arsenal, MIT.

More from mgiovani/cc-arsenal