0057. Dos pools de base de datos: tenant con RLS y panel con BYPASSRLS¶
Estado: Aceptado Fecha: 2026-10-29 Autor: Duval Alcivar Módulo(s) afectado(s): app/core/config.py, app/core/db.py, app/api/deps.py, app/domains/empresas/admin_router.py, app/main.py, tests/
Contexto¶
El ADR 0046 dejó un solo rol de base sujeto a la RLS y una sola sesión por
request. Eso funciona para el tenant, pero el panel administrativo necesita lo
contrario: ver todas las empresas, con el empresa_id como filtro de
consulta y no como restricción. Hoy se resuelve fijando
app.current_empresa_id empresa por empresa —en query o en el cuerpo, ruta por
ruta—, así que cada endpoint administrativo arrastra condiciones extra y una
consulta cross-empresa se vuelve una pasada por empresa.
Decisión¶
- Dos engines y dos pools, no un engine con dos roles:
DATABASE_URL→ rol con RLS y sinBYPASSRLS. Es el de siempre.ADMIN_DATABASE_URL→ rol conBYPASSRLS. Es el del panel.build_admin_enginereplica el perfil del engine normal (mismosearch_path, mismo pool) y falla al construirse si la variable no está.get_dbentrega el pool del tenant;get_db_admin, el del panel. Son dependencias distintas (SesionEmpresaySesionAdmin). Una ruta no puede quedarse con la sesión equivocada por un cambio de rol: son objetos separados desde el import.- La separación es por router, no por dominio.
router.pyconserva lo que corre con la empresa del token y la RLS activa;admin_router.py—uno por dominio— expone el CRUD administrativo. Models, repository, service y schemas se escriben una sola vez y no saben quién los llama. - El panel no fija
app.current_empresa_id. ConBYPASSRLSno hace falta. El filtro por empresa, cuando el endpoint lo recibe, va explícito en el repository (RelEmpresaAplicacion.empresa_id == empresa_id). El tenant sigue sin escribir ese filtro: la RLS es su protección. - Reemplaza un punto concreto del ADR 0046: allí se descartó un rol con
BYPASSRLS«para el rol del servicio», porque habría dejado la RLS sin filtrar en el camino de todos los requests. Con dos roles ese argumento no aplica: el engine del tenant conserva la RLS y el privilegiado sólo lo usa el panel. El resto del ADR 0046 sigue vigente. router.pyes de lectura;router_admin.pyescribe. Cada dominio expone el GET enrouter.pyy todo el POST/PUT/DELETE enrouter_admin.py. Hay dos excepciones, y son las tablas con RLS que el tenant administra sobre su propia empresa:cat_feriadosycat_bancos. El tenant también conservaPOST/DELETEderel_empresa_aplicacion—habilitar aplicaciones de su empresa— porque la RLS lo acota igual.- La lectura también se separa. La lectura pública de los catálogos globales
y la navegación de la empresa es del tenant y solo acepta el token normal; el
panel lee los mismos recursos desde
/api/v1/<dominio>/admin/...con su pool. Muere el guard mixto del ADR 0052 en catálogos: ninguna ruta normal debe estar condicionada a root. Las rutas.../existe/{id}quedan en el router de tenant porque las consumen los adaptadores de otros servicios, no el panel. - La plantilla base de navegación es del panel.
GET /api/v1/navegacion/plantillase mudó a/api/v1/navegacion/admin/plantilla: el frontend de empresa no consulta la plantilla, la estructura viva la administra el panel y la materialización del alta de empresa sigue enplantilla.py(ADR 0034). Si en el futuro la app de empresa la necesita, se agrega como lectura de ese dominio. sucursalesrepite el patrón y muereget_db_por_scope. El router tenant queda con el listado de su empresa (RLS) y el CRUD vive enapi/v1/sucursales/adminconget_db_admin, montado antes que el router tenant para que el literal/adminno caiga en/{sucursal_id}. El helper que elegía el pool según el token se retira con la limpieza dedeps.py.- La autenticación no entra en esa regla:
login,refreshylogoutson POST por protocolo, no escritura de dominio, y viven en el router público.
Alternativas descartadas¶
- Un solo rol con
BYPASSRLSpara todo el servicio — el aislamiento entre empresas quedaría sólo en la aplicación, justo en el camino de los requests de tenant. Es lo que el ADR 0046 descartó y sigue descartado. - Un solo rol con RLS y el admin rotando contexto por empresa — es el estado anterior: condiciones extra en cada endpoint y una consulta cross-empresa por cada empresa del catálogo.
- Separar el panel en otro servicio — duplicaría los seis dominios, los contratos y el despliegue para un cambio que se resuelve con dos pools.
- Función
SECURITY DEFINERcomo vía de escape — mueve el privilegio a la base sin separar superficies y deja el mismo problema de autorización.
Consecuencias¶
- Hay que crear el rol y darle privilegios explícitos.
BYPASSRLSno concede permisos, sólo saltea las políticas:
CREATE ROLE identidad_admin LOGIN PASSWORD '<secreto>' BYPASSRLS;
GRANT USAGE ON SCHEMA identidad TO identidad_admin;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA identidad TO identidad_admin;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA identidad TO identidad_admin;
ALTER DEFAULT PRIVILEGES IN SCHEMA identidad
GRANT ALL ON TABLES TO identidad_admin;
ALTER DEFAULT PRIVILEGES IN SCHEMA identidad
GRANT USAGE, SELECT ON SEQUENCES TO identidad_admin;
Las secuencias hacen falta porque las tablas usan columnas identity: sin
USAGE el INSERT falla aunque la tabla esté concedida.
- El panel cambia de ruta: el CRUD de empresas pasa de /api/v1/empresas/... a
/api/v1/empresas/admin/.... El frontend administrativo debe actualizarse.
- Riesgo nuevo y central: el aislamiento del panel depende de qué dependencia
usa cada ruta. Una ruta administrativa montada sobre get_db con token
admin falla con 401 (el token admin no lleva empresa_id), así que el error
se ve; una ruta de tenant sobre get_db_admin sería una fuga silenciosa y no
tiene red de base. La revisión de ese import es parte del contrato de cada
endpoint nuevo.
- El rol del panel no debe ser superusuario: BYPASSRLS alcanza y acota el
daño a las políticas, no a la administración entera del cluster.
- Los tests del panel overridean get_db_admin, así que corren sin
ADMIN_DATABASE_URL; la construcción del engine se prueba aparte
(tests/unit/core/test_db.py).