Saltar a contenido

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 identidad evoluciona: una migración versionada por cambio, en alembic/versions/, aplicadas en orden. Ninguna tabla se crea fuera de una migración.
  • La tabla de versiones alembic_version vive dentro del esquema identidad, no en public: ninguna tabla del servicio vive en public.
  • Alembic reutiliza el engine de la aplicación (build_engine), así que se conecta con el mismo search_path que el servicio. La URL no se duplica en alembic.ini: sale de get_settings() en env.py. target_metadata proviene de app.registry, por lo que un dominio nuevo debe agregar el import de sus models ahí para aparecer en --autogenerate.
  • El esquema identidad se crea con un CREATE SCHEMA IF NOT EXISTS idempotente antes de migrar, porque la tabla de versiones no puede vivir en un esquema que todavía no existe. El nombre sale de DATABASE_SCHEMAS.
  • autogenerate produce 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=True acotado con include_name. include_schemas hace falta para que --autogenerate vea tablas fuera de public, pero por sí solo compara todos los esquemas de la base: en una base compartida propone DROP de las tablas de otros servicios. env.py pasa un include_name que sólo admite el esquema por defecto de la conexión (que, por el search_path, es el primer esquema del servicio) más los demás esquemas de DATABASE_SCHEMAS, y que además excluye la tabla alembic_version.
  • El id y el nombre de cada migración se generan solos. env.py registra process_revision_directives: si no se pasó --rev-id, calcula YYYYMMDD_NNN con _siguiente_revision_id() (fecha en UTC y correlativo del día sobre versions/) y lo fija como id y como nombre. Nadie escribe la fecha ni el correlativo a mano.
  • revision_environment = true en alembic.ini. Alembic, por defecto, no ejecuta env.py en un alembic revision sin --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 --autogenerate lo renderiza Alembic con comillas simples y líneas largas. alembic.ini declara post_write_hooks y Alembic ejecuta ruff format sobre el archivo recién creado, así que la migración nace con el estilo del repo.
  • pyproject.toml exceptúa alembic/versions/*.py de E501, F401 e I001. 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 genera ALTER cuando 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_version en public — rompe la regla de que ninguna tabla del servicio vive en public y 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 un search_path distinto 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 --autogenerate traería DROP de otros servicios y dependería de que la persona los borre bien; se reemplaza por el filtro include_name en env.py.
  • Formatear la migración a mano (ruff format después de generarla) — un paso que se olvida y deja el gate en rojo; se reemplaza por post_write_hooks.

Consecuencias

  • Cualquier entorno se lleva al estado deseado con alembic upgrade head, y cada cambio es reversible con alembic downgrade.
  • La conexión y la metadata tienen una sola fuente: si el search_path o los modelos cambian, Alembic los ve sin configuración extra.
  • Costo: un dominio nuevo que olvide su import en app/registry.py no aparece en --autogenerate y hay que revisar el borrador para detectarlo.
  • Costo: alembic.ini se escribe sólo en ASCII porque Alembic lo lee con la codificación del locale del sistema (cp1252 en Windows).
  • revision_environment = true implica que cualquier alembic revision (con o sin --autogenerate) necesita la base levantada, porque Alembic ejecuta env.py y éste abre una conexión. Es el precio del id y el nombre automáticos.
  • pyproject.toml exceptúa alembic/versions/*.py de E501, F401 e I001: el resto de las reglas sigue aplicando y, como post_write_hooks formatea 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.