Db:migrate

---

name: "db:migrate" description: "Run database migrations against the target environment. Use when applying schema changes, running pending migrations, or checking migration status. Do NOT use for seed data insertion or database backups." argument-hint: " [--status] [--rollback ]" user-invocable: true

Database Migration Runner

Apply pending database migrations to a target environment (dev, staging, production) using Alembic.

Procedure

Step 1: Determine Target Environment

Read the environment argument. Valid values: dev, staging, production.

If production is specified, require confirmation via AskUserQuestion before proceeding:

"You are about to run migrations against PRODUCTION. This cannot be undone automatically. Continue?"

Step 2: Check Migration Status

alembic --config config/${env}.ini current
alembic --config config/${env}.ini heads

If --status flag is set, display current revision and pending migrations, then stop.

Step 3: Run Pending Migrations

alembic --config config/${env}.ini upgrade head

Report the number of migrations applied and the new current revision.

Step 4: Verify Schema

Run the schema validation script:

python scripts/verify_schema.py --env ${env}

Report any discrepancies between the expected schema and the actual database state.

If --rollback <N> is specified, roll back N migrations instead of applying:

alembic --config config/${env}.ini downgrade -${N}