mgiovani/ai-arsenal / skills/db-migrate
db-migrate
VerifiedCreates, checks the status of, and validates database migrations by auto-detecting the project's migration framework (Alembic, Prisma, Knex, Django, Rails/ActiveRecord, Flyway, Atlas, TypeORM, Sequelize, SQLx, golang-migrate, Liquibase) from marker files, then driving that framework's own CLI. Use when the user wants to create a new migration, check pending vs. applied migration status, or validate a migration for a missing rollback script, a missing foreign-key index, or a destructive operation like DROP TABLE / TRUNCATE / DELETE FROM. Trigger phrases include "create a migration", "check migration status", "any pending migrations", "validate this migration", "does this migration have a rollback". Not for designing the schema change itself or writing ORM model code (use implement-feature), this skill only manages migration files and framework tooling once the schema change is already decided.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| evals/evals.json | config | 3.9 KB |
| evals/trigger-eval.json | config | 2.1 KB |
| references/framework-commands.md | markdown | 6.7 KB |
references/framework-commands.md
View on GitHub# DB Migrate: Framework Detection & Commands
This reference is loaded when `db-migrate` needs framework-specific commands.
## Contents
- [Detection Table](#detection-table)
- [Rollback Commands](#rollback-commands)
- [Per-Framework Best Practices](#per-framework-best-practices)
- [Alembic (Python)](#alembic-python)
- [Prisma (Node.js)](#prisma-nodejs)
- [Knex (Node.js)](#knex-nodejs)
- [Flyway](#flyway)
- [Rails ActiveRecord](#rails-activerecord)
- [Django](#django)
- [Atlas](#atlas)
- [TypeORM](#typeorm)
- [SQLx (Rust)](#sqlx-rust)
- [Naming Conventions](#naming-conventions)
- [Common Pitfalls](#common-pitfalls)
## Detection Table
| Marker File | Framework | Create Command | Status Command | Apply Command |
|-------------|-----------|---------------|----------------|---------------|
| `alembic.ini` | Alembic (Python) | `alembic revision --autogenerate -m "<name>"` | `alembic current` | `alembic upgrade head` |
| `prisma/schema.prisma` | Prisma (Node.js) | `npx prisma migrate dev --name <name>` | `npx prisma migrate status` | `npx prisma migrate deploy` |
| `knexfile.*` | Knex (Node.js) | `npx knex migrate:make <name>` | `npx knex migrate:status` | `npx knex migrate:latest` |
| `flyway.conf` or `flyway.toml` | Flyway | Create `sql/V{timestamp}__<name>.sql` manually | `flyway info` | `flyway migrate` |
| `db/migrate/` (Ruby) | Rails/ActiveRecord | `rails generate migration <Name>` | `rails db:migrate:status` | `rails db:migrate` |
| `manage.py` + `*/migrations/` | Django | `python manage.py makemigrations [app]` | `python manage.py showmigrations` | `python manage.py migrate` |
| `atlas.hcl` | Atlas | `atlas migrate diff --env local` | `atlas migrate status` | `atlas migrate apply` |
| `typeorm.config.*` or `ormconfig.*` | TypeORM | `npx typeorm migration:generate -n <name>` | `npx typeorm migration:show` | `npx typeorm migration:run` |
| `sequelize-cli` in `package.json` | Sequelize | `npx sequelize-cli migration:generate --name <name>` | `npx sequelize-cli db:migrate:status` | `npx sequelize-cli db:migrate` |
| `Cargo.toml` + `sqlx` dep | SQLx (Rust) | `sqlx migrate add <name>` | `sqlx migrate info` | `sqlx migrate run` |
| `go.mod` + `migrate` dep | golang-migrate | `migrate create -ext sql -dir db/migrations <name>` | `migrate version` | `migrate up` |
| `liquibase.properties` | Liquibase | Create `changelog/<name>.xml` manually | `liquibase status` | `liquibase update` |
## Rollback Commands
| Framework | Rollback Command |
|-----------|-----------------|
| Alembic | `alembic downgrade -1` |
| Prisma | `npx prisma migrate reset` (full) or manual SQL |
| Knex | `npx knex migrate:rollback` |
| Flyway | `flyway undo` (Teams only) or manual SQL |
| Rails | `rails db:rollback` |
| Django | `python manage.py migrate <app> <migration_name>` |
| Atlas | `atlas migrate down` |
| TypeORM | `npx typeorm migration:revert` |
| Sequelize | `npx sequelize-cli db:migrate:undo` |
| SQLx | `sqlx migrate revert` |
## Per-Framework Best Practices
### Alembic (Python)
- Use `--autogenerate` to detect schema changes from SQLAlchemy models
- Always review auto-generated migrations: autogenerate may miss some changes (e.g., custom types)
- Use `alembic revision` (without autogenerate) for data migrations
- Keep `env.py` updated with all model imports for accurate autogenerate
- File naming: `<timestamp>_<slug>.py` (auto-generated)
### Prisma (Node.js)
- `prisma migrate dev` uses a shadow database to detect drift
- `prisma migrate deploy` is for production (no shadow DB needed)
- Do not edit generated SQL files after running dev migration: use `prisma migrate resolve` instead
- For data migrations, use a separate migration with raw SQL via `$executeRaw`
- Reset caution: `prisma migrate reset` drops and re-creates the database
### Knex (Node.js)
- Always write both `up` and `down` functions in migration files
- Use `knex.schema.createTableIfNotExists` for idempotency
- File naming: `<timestamp>_<description>.js`
- Use `knex.raw()` for DDL not covered by the schema builder
### Flyway
- SQL file naming convention: `V{version}__{description}.sql` (double underscore)
- Use `R__` prefix for repeatable migrations (views, stored procedures)
- Commercial Flyway Teams required for undo migrations; open source is forward-only
- Use placeholders `${placeholder}` for environment-specific values
### Rails ActiveRecord
- Never edit existing migrations: create new ones to correct mistakes
- `db/schema.rb` is the source of truth; keep it committed
- Use `change` method when possible (Rails infers rollback); use `up`/`down` for complex migrations
- Data migrations should be separate from schema migrations; consider `data_migrate` gem
### Django
- Run `makemigrations` locally, commit migration files to version control
- Never delete migration files: use `squashmigrations` to consolidate if needed
- Use `RunPython` for data migrations with a `reverse_code` argument for rollback
- Use `--check` flag in CI: `python manage.py migrate --check` to verify no unapplied migrations
### Atlas
- Schema-as-code approach: define target schema in HCL, Atlas generates the migration
- `atlas migrate lint` catches migration issues before applying
- Supports versioned migrations and declarative migrations (pick one per project)
- Integrates with Terraform for infrastructure-as-code workflows
### TypeORM
- Use `synchronize: false` in production: never auto-sync schema
- Keep entity files and migrations in sync
- Use `MigrationInterface` with `up` and `down` methods
- `migration:generate` compares current entities to database, creates diff
### SQLx (Rust)
- Migration files are plain SQL with `-- +migrate Up` / `-- +migrate Down` markers
- Use `sqlx migrate run` in deployment, `sqlx migrate revert` for rollback
- Compile-time query checking requires `sqlx prepare` to generate query metadata
## Naming Conventions
| Style | Example | Used By |
|-------|---------|---------|
| Timestamp + description | `20240315120000_add_user_email.sql` | Flyway, golang-migrate, SQLx |
| Auto-incremented version | `0001_add_user_email.py` | Alembic (default), Django |
| CamelCase description | `AddUserEmail` | Rails, TypeORM |
| Timestamp + CamelCase | `1710504000000-AddUserEmail.ts` | TypeORM default |
## Common Pitfalls
1. Missing DOWN migration: always write rollback scripts, since production incidents require a quick rollback.
2. Non-transactional DDL: some DB engines (MySQL) auto-commit DDL, so wrap it in explicit transactions where supported.
3. Large table migrations: `ALTER TABLE` on large tables can lock, so use `ADD COLUMN ... DEFAULT NULL` then backfill.
4. Index creation: use `CREATE INDEX CONCURRENTLY` (Postgres) to avoid table locks.
5. Enum types: adding enum values is forward-only in some DBs, so plan carefully.
6. Running in CI without a DB: use Docker service containers or test databases in CI pipelines
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |