alembic-patterns

Alembic Patterns

Alembic migration patterns with automatic handling of problematic types.

Triggers

Use this skill when the user:

• Creates an Alembic migration
• Gets errors during migration
• Works with enum, array, nullable changes

Main principle: Automatic fixing

Alembic does not always correctly generate downgrade. The plugin automatically:

• Adds enum deletion in downgrade
• Warns about nullable changes without data migration
• Checks the order of FK operations

Enum types

More details: ${CLAUDE_PLUGIN_ROOT}/skills/alembic-patterns/references/enum-handling.md

Creating table with enum

status_type = sa.Enum("pending", "active", "inactive", name="status_type")

def upgrade() -> None:
    op.create_table(
        "orders",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("status", status_type, nullable=False),
        sa.PrimaryKeyConstraint("id"),
    )

def downgrade() -> None:
    op.drop_table("orders")
    status_type.drop(op.get_bind(), checkfirst=False)  # IMPORTANT!

Adding column with enum

def upgrade() -> None:
    status_type = sa.Enum("pending", "active", name="status_type")
    status_type.create(op.get_bind(), checkfirst=True)
    op.add_column("orders", sa.Column("status", status_type))

def downgrade() -> None:
    op.drop_column("orders", "status")
    # Delete only if enum is not used elsewhere
    # sa.Enum(name="status_type").drop(op.get_bind(), checkfirst=True)

Nullable changes

# Changing NULL -> NOT NULL
def upgrade() -> None:
    # First update data
    op.execute("UPDATE users SET name = 'Unknown' WHERE name IS NULL")
    # Then change constraint
    op.alter_column("users", "name", nullable=False)

def downgrade() -> None:
    op.alter_column("users", "name", nullable=True)

Foreign Keys

# Correct order in downgrade
def downgrade() -> None:
    # First delete FK
    op.drop_constraint("fk_orders_user_id", "orders", type_="foreignkey")
    # Then table
    op.drop_table("users")