Easy Migration Executor

Execute database and code migrations with validation, rollback support, and progress tracking.

When to Use This Command

Run this command when you need to:

• Run pending database migrations with pre-flight validation and automatic backup
• Execute code migrations (API version upgrades, dependency updates) with step-by-step verification
• Perform data migrations between storage systems with integrity checks

Consider alternatives when:

• You need to write a new migration file rather than execute existing ones
• Your ORM's built-in migration command handles everything you need

Quick Start

Configuration

Copy
name: easy-migration-executor
type: command
category: documentation

Example Invocation

Copy
claude command:run easy-migration-executor --type database --env staging

Example Output

Migration Target: staging database
Current Version: migration_042_add_user_roles
Pending Migrations: 3

Pre-flight Checks:
  [OK] Database connection verified
  [OK] Backup created: backup-staging-20260315-104500.sql
  [OK] Disk space sufficient (18GB available)
  [OK] No active transactions blocking DDL

Executing Migrations:
  [1/3] 043_create_permissions_table...applied (0.8s)
  [2/3] 044_add_role_permissions_fk...applied (0.3s)
  [3/3] 045_seed_default_roles...applied (1.2s)

Post-Migration Validation:
  [OK] Schema matches expected state
  [OK] Foreign key constraints valid
  [OK] Seed data verified (5 default roles)
  [OK] Application health check passes

Migration complete. 3/3 migrations applied successfully.
Rollback command: claude command:run easy-migration-executor --rollback 042

Core Concepts

Migration Execution Overview

Aspect	Details
Database Migrations	DDL and DML changes with version tracking and ordering
Code Migrations	API upgrades, import path changes, deprecated code replacement
Data Migrations	Moving data between schemas, tables, or storage backends
Backup Strategy	Automatic snapshot before any migration execution
Rollback Support	Reverse migrations with data preservation when possible

Migration Workflow

  Pending Migrations
        |
        v
  +-------------------+
  | Pre-flight Checks |---> Connection, backup, locks
  +-------------------+
        |
        v
  +-------------------+
  | Create Backup     |---> Database snapshot
  +-------------------+
        |
        v
  +-------------------+
  | Execute Sequenced |---> One migration at a time
  +-------------------+
        |
        v
  +-------------------+
  | Validate Each     |---> Schema check after each step
  +-------------------+
        |
        v
  +-------------------+
  | Post-flight Check |---> Full integrity validation
  +-------------------+

Configuration

Parameter	Type	Default	Description
type	string	database	Migration type: database, code, data
env	string	development	Target environment: development, staging, production
rollback	string	none	Roll back to a specific migration version
dry_run	boolean	false	Show what would be executed without applying changes
batch_size	integer	1000	Row batch size for data migrations to limit memory usage

Best Practices

1. Always Back Up Before Migrating - Even in development, take a snapshot before running migrations. A failed migration mid-execution can leave the database in an inconsistent state that is difficult to recover manually.

2. Run Migrations One at a Time in Production - Execute each migration individually and validate before proceeding to the next. If migration 2 of 5 fails, you want to know exactly which change caused the issue.

3. Test Migrations Against Production-Size Data - A migration that runs in 2 seconds on a development database with 100 rows may lock a production table with 10 million rows for 30 minutes. Test with realistic data volumes.

4. Make Migrations Idempotent - Write migrations so they can be safely re-run without error. Use IF NOT EXISTS for table creation and check for column existence before adding columns.

5. Keep Rollback Scripts Current - Every forward migration should have a corresponding rollback script. Test rollback scripts with the same rigor as forward migrations to ensure they actually work when needed.

Common Issues

1. Migration Blocked by Active Locks - Long-running queries hold locks that prevent DDL changes. Check for active transactions before migrating and schedule migrations during low-traffic windows for production databases.

2. Migration Succeeds But Application Fails - The new schema is incompatible with the running application code. Deploy application code that supports both old and new schemas before running the migration.

3. Rollback Loses Data - A migration that adds a column and populates it with computed data cannot be rolled back without losing that data. For destructive rollbacks, flag the data loss clearly and require explicit confirmation.