database-migration

Database Migration

Overview

Database migrations are high-risk operations that can cause data loss, service outages, and inconsistencies. Rushed migrations fail; systematic migrations succeed.

Core principle: ALWAYS have a tested rollback plan before executing any migration. No migration is too small for planning.

Violating the letter of this process is violating the spirit of database migration safety.

First 5 Minutes Checklist (Emergency Migration)

Use this when urgent schema change needed. Don't think, follow the list.

Minute	Action	Output
0-1	Identify what needs to change and why	change_classified
1-2	Check if change is reversible	rollback_possible or requires_planning
2-3	Estimate rows affected and lock impact	impact_assessed
3-4	Create backup of affected tables	backup_verified
4-5	If >1M rows or DDL lock: STOP, use full process	proceed or escalate

After 5 minutes: Proceed to Phase 2 (Plan) if safe, otherwise follow full process.

The Iron Law

NO MIGRATION WITHOUT A TESTED ROLLBACK PLAN FIRST

If you haven't verified you can undo the change, you cannot execute the migration.

When to Use

Use for ANY database change:

• Schema modifications (ADD/DROP/ALTER)
• Large data transformations
• Index creation or removal
• Foreign key changes
• Data type conversions
• Table splitting or merging

Use this ESPECIALLY when:

• Zero-downtime is required (production systems)
• Table has >1 million rows
• Change affects foreign key relationships
• Multiple tables need coordinated changes
• Rollback must preserve data

Don't skip when:

• "It's just adding a column" (NULL vs NOT NULL matters)
• "We're in a hurry" (rushed migrations cause outages)
• "It's a small table" (today's small table is tomorrow's large table)

When NOT to Use

This skill is for systematic database migrations. Don't use it for:

• Local development only - Experiment freely in dev
• Seed data insertion - Use standard insert scripts
• Query optimization - Use systematic-debugging for investigation
• New greenfield tables - Simple CREATE TABLE is fine