Saltar a contenido

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 de alembic.ini; la metadata, de app/registry.py.
  • Las ids son YYYYMMDD_NNN (UTC, correlativas por día), como en los demás servicios. env.py la asigna sola salvo que se pase --rev-id.
  • alembic_version vive en el esquema del servicio, no en public.
  • include_name limita --autogenerate a DATABASE_SCHEMAS: sin el filtro, Alembic propone borrar las tablas de los otros servicios.
  • env.py crea el esquema sólo si falta: PostgreSQL exige CREATE sobre la base incluso con IF NOT EXISTS.
  • env.py usa un engine propio sin search_path y con NullPool.
  • env.py falla si DATABASE_SCHEMAS no incluye el esquema de los modelos (fuerzaventas, ADR 0006).
  • Cada migración generada se formatea con ruff format (post_write_hooks).

Alternativas descartadas

  • alembic_version en public — todos los servicios compartirían la tabla y se pisarían las versiones.
  • Reutilizar build_engine() — con search_path=fuerzaventas, PostgreSQL omite el esquema al reflejar las FK y --autogenerate propone 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 local un administrador debe crear el esquema antes del primer alembic upgrade.
  • Un dominio que no se importe en app/registry.py no 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.