Saltar a contenido

0004. Base de datos: engine asíncrono perezoso y search_path del servicio

Estado: Aceptado Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): app/core/db.py, app/main.py

Contexto

La base del CRM aloja los esquemas de varios servicios, y ninguna tabla de este servicio vive en public (ADR 0004 transversal). El servicio usa SQLAlchemy 2 asíncrono con asyncpg (ADR 0001). Falta fijar cómo se crea el engine, cómo resuelve el SQL sin calificar y cómo se nombran constraints e índices.

Decisión

  • Engine y fábrica de sesiones perezosos (get_engine, get_session_factory): se crean en el primer uso, así importar app.core.db no exige DATABASE_URL. dispose_engine() los cierra en el lifespan.
  • El engine fija search_path con DATABASE_SCHEMAS (entrecomillados) en server_settings: el SQL sin calificar resuelve contra los esquemas del servicio y nunca contra public.
  • pool_pre_ping=True, pool_size y max_overflow desde la configuración; NullPool sólo en local (ADR 0003).
  • Sesiones con expire_on_commit=False y autoflush=False.
  • obtener_sesion da una sesión por request sin empresa; sólo la usan rutas sin identidad, como /ready. Las rutas de negocio usan SesionEmpresa (ADR 0008).
  • NAMING_CONVENTION en la metadata: pk_, fk_, uq_, ck_, ix_.

Alternativas descartadas

  • Engine creado al importar — cualquier import (tests, Alembic) exigiría una base configurada.
  • Calificar todo con el esquema y no fijar search_path — un SQL sin calificar caería en public sin avisar.
  • Nombres de constraints por defecto — PostgreSQL los genera distintos en cada base y las migraciones de downgrade no los encuentran.

Consecuencias

  • Alembic no reutiliza este engine: con search_path la reflexión omite el esquema de las FK (ADR 0005).
  • expire_on_commit=False deja los atributos accesibles tras el commit, pero no refleja lo que la base calcule después: el repository hace refresh cuando lo necesite.

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.