endpoin/MIGRATIONS.md

Guía de Migraciones con Alembic

Este proyecto usa Alembic para manejar las migraciones de base de datos.

📋 Comandos Útiles

Dentro del contenedor Docker

# Acceder al contenedor
docker exec -it control_mve_api bash

# Crear una nueva migración automáticamente
alembic revision --autogenerate -m "descripción del cambio"

# Aplicar migraciones pendientes
alembic upgrade head

# Revertir última migración
alembic downgrade -1

# Ver historial de migraciones
alembic history

# Ver estado actual
alembic current

Desde el host (sin entrar al contenedor)

# Crear nueva migración
docker exec -it control_mve_api alembic revision --autogenerate -m "descripción"

# Aplicar migraciones
docker exec -it control_mve_api alembic upgrade head

# Ver historial
docker exec -it control_mve_api alembic history

🚀 Flujo de Trabajo

1. Modificar modelos

Edita tus modelos en app/models/:

# Ejemplo: agregar un nuevo campo
class Cliente(Base):
    __tablename__ = "clientes"
    # ... campos existentes ...
    nuevo_campo = Column(String(100))

2. Generar migración automática

docker exec -it control_mve_api alembic revision --autogenerate -m "agregar campo nuevo_campo a clientes"

Esto creará un archivo en alembic/versions/ con los cambios detectados.

3. Revisar la migración generada

IMPORTANTE: Siempre revisa el archivo generado antes de aplicarlo.

# Ver el archivo más reciente
ls -lt alembic/versions/ | head -n 2

4. Aplicar la migración

docker exec -it control_mve_api alembic upgrade head

5. Verificar que se aplicó

docker exec -it control_mve_api alembic current

🔄 Migración Inicial

La migración inicial ya se ejecuta automáticamente cuando levantas los contenedores gracias al script migrate.sh.

Si necesitas recrear la migración inicial:

# Eliminar migraciones existentes
rm alembic/versions/*.py

# Crear migración inicial
docker exec -it control_mve_api alembic revision --autogenerate -m "migración inicial"

# Aplicarla
docker exec -it control_mve_api alembic upgrade head

📝 Ejemplos Comunes

Agregar un nuevo modelo

1. Crear archivo en app/models/nueva_entidad.py
2. Importarlo en app/models/__init__.py
3. Generar migración: alembic revision --autogenerate -m "agregar modelo NuevaEntidad"
4. Revisar y aplicar: alembic upgrade head

Modificar un campo existente

1. Editar el modelo
2. Generar migración: alembic revision --autogenerate -m "modificar campo X"
3. Revisar migración - Alembic no siempre detecta todos los cambios
4. Aplicar: alembic upgrade head

Crear migración manual

Si necesitas hacer cambios que Alembic no detecta automáticamente:

docker exec -it control_timbres_api alembic revision -m "mi cambio manual"

Luego edita el archivo generado en alembic/versions/:

def upgrade() -> None:
    op.execute("UPDATE clientes SET estado = 'activo' WHERE estado IS NULL")

def downgrade() -> None:
    pass

⚠️ Buenas Prácticas

1. Siempre revisa las migraciones autogeneradas antes de aplicarlas
2. Prueba en desarrollo antes de aplicar en producción
3. Haz backup de la base de datos antes de migraciones importantes
4. Escribe downgrades funcionales para poder revertir cambios
5. Commits pequeños - una migración por cambio lógico
6. Nombres descriptivos para las migraciones

🔧 Troubleshooting

La migración no detecta mis cambios

• Verifica que importaste el modelo en app/models/__init__.py
• Asegúrate de que alembic/env.py importa todos los modelos
• Reinicia el contenedor: docker-compose restart api

Error: "Target database is not up to date"

# Ver qué migraciones faltan
docker exec -it control_mve_api alembic current
docker exec -it control_mve_api alembic history

# Aplicar pendientes
docker exec -it control_mve_api alembic upgrade head

Quiero empezar de cero

# CUIDADO: Esto borra todos los datos
docker-compose down -v
docker-compose up -d

📚 Recursos

• Documentación oficial de Alembic
• Tutorial de Alembic