migration-plan

Overview

Migration planning pipeline: discovery → impact analysis → dependency mapping → phase design → rollback strategy → output plan. Produces a comprehensive MIGRATION-PLAN.md document.

Required References

Before starting, read references/backend/migration-safety.md for safety patterns and rollback strategies.

Step 1: Discovery

1. Current state:
   • Identify the database system (Postgres, MySQL, SQLite, MongoDB)
   • Identify the ORM/migration tool (Prisma, Alembic, Knex, TypeORM, raw SQL)
   • List existing migrations and their status
   • Read current schema definition
2. Target state:
   • Understand the desired end state from the user's description
   • Identify all affected tables, columns, indexes, and constraints
3. Environment:
   • Check for multi-environment setup (dev, staging, prod)
   • Check for read replicas or multi-region
   • Check for concurrent access patterns

Step 2: Impact Analysis

1. Schema changes:
   • New tables/columns to add
   • Columns to modify (type, nullability, default)
   • Columns/tables to remove
   • Index changes
   • Constraint changes
2. Code changes:
   • ORM models that need updating
   • Queries that reference changed columns
   • API endpoints that expose changed fields
   • Validation schemas that need updating
3. Data changes:
   • Rows that need backfilling
   • Data transformations required
   • Estimated row counts for affected tables

Step 3: Dependency Mapping

1. Database dependencies:
   • FK relationships to/from changed tables
   • Views or materialized views that reference changed columns
   • Stored procedures or triggers affected
   • Indexes that need rebuilding
2. Code dependencies:
   • Files that import/use changed models
   • Tests that reference changed schema
   • Seed data that needs updating
3. Service dependencies:
   • Other services that read/write to affected tables
   • Message queue consumers that depend on schema
   • Cron jobs or background workers affected