0056. Entorno exclusivo de Alembic: .env.migrations¶
Estado: Aceptado Fecha: 2026-10-29 Autor: Duval Alcivar Módulo(s) afectado(s): alembic/env.py, alembic.ini, app/core/config.py, README.md, tests/
Contexto¶
Hasta ahora Alembic y la aplicación compartían get_settings(), que lee .env.
El archivo .env es el del runtime y su usuario de base tiene límites de
conexión y no debería poder ejecutar DDL. Las migraciones necesitan lo
contrario: un usuario con permisos para crear esquemas, tablas, índices y
políticas RLS. Cada alembic upgrade head con el usuario de runtime choca
contra esos límites o, peor, obliga a ampliarlos.
Decisión¶
- Alembic lee exclusivamente
.env.migrations, nunca.env. La ruta se resuelve desdealembic/env.py(raíz del repositorio), no desde elcwd, así quealembiclanzado desde cualquier directorio lee el mismo archivo. get_settings(env_file=...)acepta la ruta del archivo de entorno. Sin argumentos se comporta como antes (.env); con una ruta,pydantic-settingsreemplaza suenv_filepor esa ruta. La caché delru_cachequeda por archivo, de modo que pedir uno explícito no contamina la app.- Si
.env.migrationsno existe,env.pyfalla con unRuntimeErrorque dice qué archivo crear y para qué. No hay fallback a.env: un fallback silencioso volvería a conectar las migraciones con el usuario de runtime. .env.migrationsno se versiona: está en.gitignore, igual que.env.
Alternativas descartadas¶
- Variable de entorno
ENV_FILEconmodel_config.env_filedinámico — obliga a setear el entorno antes de importarapp.core.config, y cualquier import indirecto (por ejemploapp.registry) puede llegar primero. Depender del orden de imports es frágil. - Leer el archivo directamente en
env.pycon otro parser — duplica la validación deSettings(driver asíncrono, esquemas obligatorios) y podría aceptar valores que la aplicación rechaza. - Dejar
.envy pedirle al usuario de runtime permisos de DDL — amplía permisos de un usuario de aplicación sólo para migrar, que es exactamente lo que se quiere evitar. - Duplicar la URL en
alembic.ini— ya descartado en el ADR 0003: pone credenciales en un archivo versionado y separa la fuente de la conexión.
Consecuencias¶
- Las migraciones corren con el usuario de migraciones y la aplicación con el suyo, contra la misma base y los mismos esquemas.
- Quien clone el repositorio debe crear
.env.migrationsantes dealembic upgrade head; si falta, el error lo dice explícitamente. - Costo: dos archivos de entorno que pueden divergir en
DATABASE_SCHEMAS. El esquema sigue saliendo deDATABASE_SCHEMAS, así que ambos deben declararlo igual. - Las variables reales del proceso (
DATABASE_URLexportada en el shell) siguen teniendo prioridad sobre el archivo, porque es el orden depydantic-settings(entorno > dotenv). Es deliberado: permite sobrescribir en CI sin tocar archivos.