migrate:create

Command /migrate:create

Create an Alembic migration with automatic fixing of problematic types.

Principle

Alembic does not always correctly generate downgrade for:

• Enum types — creates in upgrade, but does NOT delete in downgrade
• Array types — problems when changing element type
• JSON/JSONB — nullable changes require data migration

Instructions

Step 1: Create migration

alembic revision --autogenerate -m "{{ message }}"

Step 2: Find the created file

ls -la alembic/versions/*.py | head -1

Step 3: Check and fix migration

Enum types

Problem: Alembic creates enum in upgrade, but does not delete in downgrade.

Auto-fix:

# Find all enums in the file
# Pattern: sa.Enum("value1", "value2", name="enum_name")

If enum is found:

# Add at the beginning of the file
status_type = sa.Enum("pending", "active", "inactive", name="status_type")

def upgrade() -> None:
    # status_type is created automatically when creating the column
    op.create_table(
        "users",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("status", status_type, nullable=False),
        sa.PrimaryKeyConstraint("id"),
    )

def downgrade() -> None:
    op.drop_table("users")
    # IMPORTANT: Delete enum type
    status_type.drop(op.get_bind(), checkfirst=False)

Adding column with enum

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

    op.add_column(
        "users",
        sa.Column("status", status_type, nullable=True),
    )

# downgrade
def downgrade() -> None:
    op.drop_column("users", "status")
    # Enum remains if used in other tables
    # sa.Enum(name="status_type").drop(op.get_bind(), checkfirst=True)

Array types

# When changing array element type
def upgrade() -> None:
    # First delete old column
    op.drop_column("users", "tags")
    # Create with new type
    op.add_column(
        "users",
        sa.Column("tags", sa.ARRAY(sa.String(100)), nullable=True),
    )

def downgrade() -> None:
    op.drop_column("users", "tags")
    op.add_column(
        "users",
        sa.Column("tags", sa.ARRAY(sa.String(50)), nullable=True),
    )