Smart Migrate Tool

Detect your project's migration framework and execute database migrations with safety checks, dry-run previews, rollback support, and environment-aware deployment sequencing.

When to Use This Command

Run this command when...

• You need to apply pending database migrations to your development, staging, or production database
• You want a dry-run preview of migration changes before applying them to catch destructive operations
• You need to roll back the most recent migration or revert to a specific migration version
• You want to check migration status showing which migrations have been applied and which are pending
• You are deploying to production and need environment-aware migration execution with safety confirmations

Quick Start

Copy
# .claude/commands/smart-migrate-tool.yaml
name: Smart Migrate Tool
description: Execute database migrations with safety checks and rollback
inputs:
  - name: action
    description: "up, down, status, reset, or dry-run"
    default: "status"

Copy
# Check migration status
claude "smart-migrate-tool status"

# Apply all pending migrations
claude "smart-migrate-tool up"

# Rollback the last migration
claude "smart-migrate-tool down"

# Preview without applying
claude "smart-migrate-tool dry-run"

Output:
  [detect] Framework: Prisma (prisma/schema.prisma)
  [status] Migration status:
    Applied:  20260301_create_users (Mar 1)
    Applied:  20260308_add_teams (Mar 8)
    Pending:  20260315_add_billing
  [apply] Running 20260315_add_billing...
    CREATE TABLE billing_plans (...)
    ALTER TABLE users ADD COLUMN plan_id ...
    CREATE INDEX idx_users_plan_id ...
  [verify] Migration applied successfully.
  Done. 1 migration applied, 0 pending.

Core Concepts

Concept	Description
Framework Detection	Auto-detects Prisma, Sequelize, Knex, Alembic, TypeORM, Django, and other migration frameworks
Safety Checks	Warns about destructive operations (DROP TABLE, DROP COLUMN) and requires confirmation
Dry Run	Previews SQL statements that would execute without modifying the database
Rollback Support	Executes down migrations to revert changes, with cascading rollback for multiple migrations
Environment Awareness	Different confirmation requirements for dev (auto), staging (confirm), and production (double-confirm)

Migration Execution:
  ┌──────────┐    ┌──────────┐    ┌──────────┐
  │  Detect  │───>│  Status  │───>│  Safety  │
  │Framework │    │  Check   │    │  Review  │
  └──────────┘    └──────────┘    └────┬─────┘
                                      │
                          ┌───────────┼───────────┐
                          ▼           ▼           ▼
                     ┌─────────┐ ┌────────┐ ┌─────────┐
                     │ Dry Run │ │ Apply  │ │Rollback │
                     │ Preview │ │  (Up)  │ │ (Down)  │
                     └─────────┘ └────────┘ └─────────┘

Configuration

Parameter	Type	Default	Description
action	string	"status"	Operation: up, down, status, reset, or dry-run
target	string	"latest"	Migrate to a specific version or "latest" for all pending
environment	string	auto-detected	Target environment: dev, staging, or production
force	boolean	false	Skip safety confirmations for destructive operations
steps	integer	1	Number of migrations to roll back (for down action)

Best Practices

1. Always run dry-run first in production -- Preview the exact SQL that will execute before applying. Destructive operations in production are irreversible without backups.
2. Back up the database before migrating -- Take a database snapshot before applying migrations, especially for data migrations that transform existing records.
3. Apply one migration at a time in production -- Use --target <version> to apply migrations individually, verifying each one succeeds before proceeding to the next.
4. Test rollbacks in staging -- Verify that every migration's down method works correctly in staging before relying on it as a production safety net.
5. Never edit applied migrations -- Once a migration has been applied to any shared environment, create a new migration for corrections rather than modifying the existing one.

Common Issues

1. Migration framework not detected -- The tool looks for framework-specific files in standard locations. If your config is in a custom path, set the framework explicitly or create a symlink.
2. Migration state out of sync -- If migrations were applied manually or the tracking table was modified, the status check may be inaccurate. Use the framework's native tools to repair the migration state.
3. Timeout on large data migrations -- Migrations that process millions of rows may exceed default timeouts. Increase the database connection timeout or break the migration into batched operations.