leo-claude-mktplace/plugins/saas-db-migrate/commands/db-migrate-plan.md

name, description, agent

name	description	agent
db-migrate plan	Show execution plan with rollback strategy	migration-planner

/db-migrate plan - Migration Execution Plan

Skills to Load

• skills/rollback-patterns.md
• skills/migration-safety.md
• skills/visual-header.md

Visual Output

Display header: DB-MIGRATE - Plan

Usage

/db-migrate plan [--target=<migration>] [--include-rollback]

Arguments:

• --target: Plan up to specific migration (default: all pending)
• --include-rollback: Show rollback plan alongside forward plan

Prerequisites

Run /db-migrate setup first. Pending migrations must exist.

Process

1. Determine Current State

Query the migration history to find:

• Latest applied migration
• All pending (unapplied) migrations in order
• Any out-of-order migrations (applied but not contiguous)

2. Build Forward Plan

For each pending migration, document:

• Migration identifier and description
• SQL operations that will execute (summarized)
• Estimated lock duration for ALTER operations
• Dependencies on previous migrations
• Expected outcome (tables/columns affected)

3. Build Rollback Plan (if --include-rollback)

For each migration in reverse order, document:

• Rollback/downgrade operations
• Data recovery strategy (if destructive operations present)
• Point-of-no-return warnings (migrations that cannot be fully rolled back)
• Recommended backup steps before applying

4. Risk Assessment

Evaluate the complete plan:

• Total number of operations
• Presence of destructive operations (DROP, ALTER TYPE)
• Estimated total lock time
• Data migration volume (if data changes included)
• Recommended maintenance window duration

5. Present Plan

Display ordered execution plan with risk indicators.

Output Format

+----------------------------------------------------------------------+
|  DB-MIGRATE - Plan                                                   |
+----------------------------------------------------------------------+

Current State: migration_005_add_user_roles (applied)
Pending: 3 migrations

FORWARD PLAN

Step 1: migration_006_add_orders_table
  Operations:
    [+] CREATE TABLE orders (5 columns)
    [+] CREATE INDEX ix_orders_user_id
    [+] ADD FOREIGN KEY orders.user_id -> users.id
  Lock Impact: None (new table)
  Risk: LOW

Step 2: migration_007_add_order_items
  Operations:
    [+] CREATE TABLE order_items (4 columns)
    [+] CREATE INDEX ix_order_items_order_id
  Lock Impact: None (new table)
  Risk: LOW

Step 3: migration_008_add_status_to_orders
  Operations:
    [~] ADD COLUMN orders.status VARCHAR(20) DEFAULT 'pending'
    [~] ADD CHECK CONSTRAINT valid_status
  Lock Impact: ~2s (instant ADD COLUMN with DEFAULT in PostgreSQL 11+)
  Risk: LOW

ROLLBACK PLAN

Step 3 (reverse): Undo migration_008
  [~] DROP CONSTRAINT valid_status
  [~] DROP COLUMN orders.status
  Reversible: YES

Step 2 (reverse): Undo migration_007
  [-] DROP TABLE order_items
  Reversible: YES (but data is lost)

Step 1 (reverse): Undo migration_006
  [-] DROP TABLE orders
  Reversible: YES (but data is lost)

RISK SUMMARY
  Total Operations: 9
  Destructive:      0
  Lock Time:        ~2 seconds
  Risk Level:       LOW
  Maintenance Window: Not required

RECOMMENDATION: Safe to apply without maintenance window.

Important Notes

• The plan is informational; it does not apply any migrations
• Lock time estimates are approximate and depend on table size
• Always back up the database before applying destructive migrations
• Out-of-order migrations are flagged as warnings