Saltar a contenido

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 desde alembic/env.py (raíz del repositorio), no desde el cwd, así que alembic lanzado 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-settings reemplaza su env_file por esa ruta. La caché de lru_cache queda por archivo, de modo que pedir uno explícito no contamina la app.
  • Si .env.migrations no existe, env.py falla con un RuntimeError que 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.migrations no se versiona: está en .gitignore, igual que .env.

Alternativas descartadas

  • Variable de entorno ENV_FILE con model_config.env_file dinámico — obliga a setear el entorno antes de importar app.core.config, y cualquier import indirecto (por ejemplo app.registry) puede llegar primero. Depender del orden de imports es frágil.
  • Leer el archivo directamente en env.py con otro parser — duplica la validación de Settings (driver asíncrono, esquemas obligatorios) y podría aceptar valores que la aplicación rechaza.
  • Dejar .env y 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.migrations antes de alembic 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 de DATABASE_SCHEMAS, así que ambos deben declararlo igual.
  • Las variables reales del proceso (DATABASE_URL exportada en el shell) siguen teniendo prioridad sobre el archivo, porque es el orden de pydantic-settings (entorno > dotenv). Es deliberado: permite sobrescribir en CI sin tocar archivos.