Instruction file imported from zamax14/Copilot-Tools (.github/instructions/alembic.instructions.md). Copyright stays with the author.

Alembic Guidelines

Reglas

• Siempre crear migraciones reversibles (implementar upgrade() y downgrade())
• Probar el downgrade() antes de hacer merge
• Nunca borrar columnas en la misma release que el código que las usa
• Una migración por cambio lógico — no mezclar cambios no relacionados
• Revisar el SQL generado con alembic upgrade head --sql antes de aplicar

Naming

Usar mensajes descriptivos al crear revisiones:

alembic revision --autogenerate -m "add_email_index_to_users"
alembic revision --autogenerate -m "create_orders_table"
alembic revision --autogenerate -m "add_status_column_to_orders"

Estructura

alembic/
├── env.py
├── versions/
│   ├── 001_create_users_table.py
│   └── 002_add_email_index_to_users.py
└── alembic.ini

Patterns

Agregar columna nullable primero

def upgrade() -> None:
    op.add_column("users", sa.Column("phone", sa.String(20), nullable=True))

def downgrade() -> None:
    op.drop_column("users", "phone")

Migración de datos

def upgrade() -> None:
    # Primero el cambio de schema
    op.add_column("users", sa.Column("full_name", sa.String(200), nullable=True))

    # Luego la migración de datos
    users = sa.table("users", sa.column("full_name"), sa.column("first_name"), sa.column("last_name"))
    op.execute(users.update().values(full_name=sa.func.concat(users.c.first_name, " ", users.c.last_name)))

Crear índices

def upgrade() -> None:
    op.create_index("ix_users_email", "users", ["email"], unique=True)

def downgrade() -> None:
    op.drop_index("ix_users_email", table_name="users")

Comandos Frecuentes

# Crear migración
alembic revision --autogenerate -m "descripcion_del_cambio"

# Aplicar todas las migraciones pendientes
alembic upgrade head

# Revertir última migración
alembic downgrade -1

# Ver estado actual
alembic current

# Ver historial
alembic history --verbose

# Generar SQL sin aplicar
alembic upgrade head --sql