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í importarapp.core.dbno exigeDATABASE_URL.dispose_engine()los cierra en ellifespan. - El engine fija
search_pathconDATABASE_SCHEMAS(entrecomillados) enserver_settings: el SQL sin calificar resuelve contra los esquemas del servicio y nunca contrapublic. pool_pre_ping=True,pool_sizeymax_overflowdesde la configuración;NullPoolsólo enlocal(ADR 0003).- Sesiones con
expire_on_commit=Falseyautoflush=False. obtener_sesionda una sesión por request sin empresa; sólo la usan rutas sin identidad, como/ready. Las rutas de negocio usanSesionEmpresa(ADR 0008).NAMING_CONVENTIONen 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 enpublicsin avisar. - Nombres de constraints por defecto — PostgreSQL los genera distintos en
cada base y las migraciones de
downgradeno los encuentran.
Consecuencias¶
- Alembic no reutiliza este engine: con
search_pathla reflexión omite el esquema de las FK (ADR 0005). expire_on_commit=Falsedeja los atributos accesibles tras elcommit, pero no refleja lo que la base calcule después: el repository hacerefreshcuando 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.