Migraciones Alembic

Serconsa usa Alembic para gestionar el esquema de PostgreSQL. La configuración está en backend/alembic.ini.

Configuración

backend/alembic.ini:

[alembic]
script_location = alembic
sqlalchemy.url = postgresql+asyncpg://serconsa:serconsa_secret@postgres:5432/serconsa

El entorno de migración se define en backend/alembic/env.py.

Crear una migración

Con Docker:

docker compose exec -w /app serconsa-backend alembic revision --autogenerate -m "descripcion breve"

Sin Docker (con PYTHONPATH):

cd backend
PYTHONPATH=/app alembic revision --autogenerate -m "descripcion breve"

Esto genera un archivo en backend/alembic/versions/.

Aplicar migraciones

docker exec -w /app serconsa-backend sh -c "PYTHONPATH=/app alembic upgrade head"

O con Docker Compose:

docker compose exec -w /app backend alembic upgrade head

Revertir

Última migración:

docker compose exec -w /app backend alembic downgrade -1

Hasta una revisión concreta:

docker compose exec -w /app backend alembic downgrade abc123

Resolver cabezas múltiples

Si hay dos migraciones que no dependen una de otra:

docker compose exec -w /app backend alembic merge -m "merge descripcion" abc123 def456

Esto crea una migración vacía que depende de ambas cabezas.

Buenas prácticas

1. Una migración por cambio lógico.
2. Revisar siempre el archivo generado antes de commitear.
3. No modificar migraciones ya aplicadas en producción.
4. En entornos compartidos, coordinar la creación de migraciones para evitar cabezas paralelas.
5. Probar upgrade y downgrade antes de subir.

Migraciones de datos

Para migraciones que solo insertan datos (seeds, correcciones), usar op.execute() dentro de upgrade() y, si es reversible, downgrade().

Tabla alembic_version

PostgreSQL mantiene la versión actual en la tabla alembic_version. Nunca modificarla manualmente.

Migraciones en producción

El despliegue de producción debe ejecutar alembic upgrade head antes de levantar el backend. En desarrollo local se hace manualmente.