0005. Migraciones con Alembic en el esquema del servicio¶
Estado: Aceptado Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): alembic/, alembic.ini, app/registry.py, pyproject.toml
Contexto¶
El esquema del servicio sólo debe evolucionar con migraciones versionadas,
igual que en identidad y clientes. Pero la base del CRM es compartida: aloja
los esquemas de otros servicios, y fuera de local el rol del servicio no
puede crear esquemas (los crea un administrador).
Decisión¶
- Alembic es la única forma de cambiar el esquema. La URL sale de
Settings, nunca dealembic.ini; la metadata, deapp/registry.py. - Las ids son
YYYYMMDD_NNN(UTC, correlativas por día), como en los demás servicios.env.pyla asigna sola salvo que se pase--rev-id. alembic_versionvive en el esquema del servicio, no enpublic.include_namelimita--autogenerateaDATABASE_SCHEMAS: sin el filtro, Alembic propone borrar las tablas de los otros servicios.env.pycrea el esquema sólo si falta: PostgreSQL exigeCREATEsobre la base incluso conIF NOT EXISTS.env.pyusa un engine propio sinsearch_pathy conNullPool.env.pyfalla siDATABASE_SCHEMASno incluye el esquema de los modelos (fuerzaventas, ADR 0006).- Cada migración generada se formatea con
ruff format(post_write_hooks).
Alternativas descartadas¶
alembic_versionenpublic— todos los servicios compartirían la tabla y se pisarían las versiones.- Reutilizar
build_engine()— consearch_path=fuerzaventas, PostgreSQL omite el esquema al reflejar las FK y--autogeneratepropone borrarlas y recrearlas en cada comparación. - Ids aleatorias de Alembic — no ordenan por fecha y no siguen la convención de la plataforma.
Consecuencias¶
- Fuera de
localun administrador debe crear el esquema antes del primeralembic upgrade. - Un dominio que no se importe en
app/registry.pyno aparece en--autogenerate. - Todavía no hay migraciones: la primera llega con el primer dominio.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.