0003. Migraciones de base de datos con Alembic¶
Estado: Aceptado Fecha: 2026-09-25 Autor: Duval Alcivar Módulo(s) afectado(s): alembic/, alembic.ini, app/registry.py, pyproject.toml, docs/
Contexto¶
El esquema identidad todavía no existe y el servicio necesita una única forma
de evolucionar: los cambios de tablas deben aplicarse igual en cada entorno, en
orden y con rollback. El ADR 0002 ya fijó que alembic/ guarda env.py y una
migración versionada por cambio, pero no dijo cómo se conecta Alembic a la base
de datos, de dónde sale la metadata ni dónde vive la tabla de versiones.
Dos restricciones del proyecto condicionan la respuesta: ninguna tabla del
servicio vive en public (el esquema es el dominio, ADR 0004 transversal), y la
cadena de conexión es asíncrona (asyncpg) y viene de get_settings(), nunca
de un archivo versionado.
Decisión¶
- Alembic es la única forma en que el esquema
identidadevoluciona: una migración versionada por cambio, enalembic/versions/, aplicadas en orden. Ninguna tabla se crea fuera de una migración. - La tabla de versiones
alembic_versionvive dentro del esquemaidentidad, no enpublic: ninguna tabla del servicio vive enpublic. - Alembic reutiliza el engine de la aplicación (
build_engine), así que se conecta con el mismosearch_pathque el servicio. La URL no se duplica enalembic.ini: sale deget_settings()enenv.py.target_metadataproviene deapp.registry, por lo que un dominio nuevo debe agregar el import de susmodelsahí para aparecer en--autogenerate. - El esquema
identidadse crea con unCREATE SCHEMA IF NOT EXISTSidempotente antes de migrar, porque la tabla de versiones no puede vivir en un esquema que todavía no existe. El nombre sale deDATABASE_SCHEMAS. autogenerateproduce un borrador que siempre se revisa: no crea esquemas y no sabe nada de RLS, así que la política RLS se escribe a mano en la misma migración que crea su tabla (ADR 0012 transversal).include_schemas=Trueacotado coninclude_name.include_schemashace falta para que--autogeneratevea tablas fuera depublic, pero por sí solo compara todos los esquemas de la base: en una base compartida proponeDROPde las tablas de otros servicios.env.pypasa uninclude_nameque sólo admite el esquema por defecto de la conexión (que, por elsearch_path, es el primer esquema del servicio) más los demás esquemas deDATABASE_SCHEMAS, y que además excluye la tablaalembic_version.- El id y el nombre de cada migración se generan solos.
env.pyregistraprocess_revision_directives: si no se pasó--rev-id, calculaYYYYMMDD_NNNcon_siguiente_revision_id()(fecha en UTC y correlativo del día sobreversions/) y lo fija como id y como nombre. Nadie escribe la fecha ni el correlativo a mano. revision_environment = trueenalembic.ini. Alembic, por defecto, no ejecutaenv.pyen unalembic revisionsin--autogenerate; esta opción lo fuerza para que el hook del id y el nombre corra también en ese caso.- Cada migración se formatea al escribirse. El cuerpo de
--autogeneratelo renderiza Alembic con comillas simples y líneas largas.alembic.inideclarapost_write_hooksy Alembic ejecutaruff formatsobre el archivo recién creado, así que la migración nace con el estilo del repo. pyproject.tomlexceptúaalembic/versions/*.pydeE501,F401eI001. Son archivos generados, con imports inyectados por la plantilla y literales SQL que el formateador no puede partir.
Alternativas descartadas¶
Base.metadata.create_all()— sólo crea lo que falta en una base vacía: no deja historial, no generaALTERcuando una tabla cambia, no permite rollback y no puede agregar las políticas RLS. El esquema quedaría distinto entre una base nueva y una migrada.- Poner
alembic_versionenpublic— rompe la regla de que ninguna tabla del servicio vive enpublicy deja una tabla del servicio fuera de su esquema dueño. - Construir un engine propio dentro de
env.py— duplicaría la conexión y correría con unsearch_pathdistinto al de la aplicación, el peor lugar para que aparezca una diferencia. - Migrar a mano o con un script suelto — sin orden ni historial versionado, cada entorno queda en un estado distinto y no hay forma de revertir.
- Borrar a mano las tablas ajenas del borrador — cada
--autogeneratetraeríaDROPde otros servicios y dependería de que la persona los borre bien; se reemplaza por el filtroinclude_nameenenv.py. - Formatear la migración a mano (
ruff formatdespués de generarla) — un paso que se olvida y deja el gate en rojo; se reemplaza porpost_write_hooks.
Consecuencias¶
- Cualquier entorno se lleva al estado deseado con
alembic upgrade head, y cada cambio es reversible conalembic downgrade. - La conexión y la metadata tienen una sola fuente: si el
search_patho los modelos cambian, Alembic los ve sin configuración extra. - Costo: un dominio nuevo que olvide su import en
app/registry.pyno aparece en--autogeneratey hay que revisar el borrador para detectarlo. - Costo:
alembic.inise escribe sólo en ASCII porque Alembic lo lee con la codificación del locale del sistema (cp1252 en Windows). revision_environment = trueimplica que cualquieralembic revision(con o sin--autogenerate) necesita la base levantada, porque Alembic ejecutaenv.pyy éste abre una conexión. Es el precio del id y el nombre automáticos.pyproject.tomlexceptúaalembic/versions/*.pydeE501,F401eI001: el resto de las reglas sigue aplicando y, comopost_write_hooksformatea el archivo, la migración nace con el lint limpio.
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.