generate-migration

Generate Migration Skill

Generate a complete, reversible Alembic migration for proposed database schema changes. Always requires admin approval before the migration can be applied, as schema changes are irreversible without a rollback procedure.

Quick Start

Use this skill when:

• User requests a new migration (/generate-migration)
• Agent detects a schema change needed for a feature
• User describes a new table, column, or index requirement

Example:

User: "Generate a migration to add a 'priority' column (integer) to the issues table"

AI generates:
- Alembic migration file with upgrade() and downgrade()
- upgrade(): ALTER TABLE issues ADD COLUMN priority INTEGER DEFAULT 0
- downgrade(): ALTER TABLE issues DROP COLUMN priority
- Index if cardinality warrants it

Workflow

1. Gather Schema Context

   • Read note content for schema requirements
   • Use ask_user to clarify ambiguous column types, constraints, or nullability
   • Identify affected tables and existing column names

2. Design Migration

   • Determine migration number by checking existing migrations (ask user for next number)
   • Write upgrade(): forward schema changes using op.add_column, op.create_table, etc.
   • Write downgrade(): exact reversal of every change in upgrade()
   • Add indexes for foreign keys and high-cardinality filter columns

3. Validate Safety

   • All new columns must be nullable or have a server_default (zero-downtime rule)
   • No DROP TABLE or DROP COLUMN in upgrade without explicit user confirmation
   • Destructive operations (DROP, TRUNCATE) require ask_user confirmation before generating

4. Insert to Note

   • Use insert_block to add the migration code block with file path header
   • Use write_to_note to add rollback instructions and deployment steps
   • Mark as pending_approval — admin must review before alembic upgrade head

5. Return Approval-Required Status

   • Return status: pending_approval with required_approval_role: admin
   • Include checklist: backup, staging test, rollback command