Saltar a contenido

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 sin BYPASSRLS. Es el de siempre.
  • ADMIN_DATABASE_URL → rol con BYPASSRLS. Es el del panel. build_admin_engine replica el perfil del engine normal (mismo search_path, mismo pool) y falla al construirse si la variable no está.
  • get_db entrega el pool del tenant; get_db_admin, el del panel. Son dependencias distintas (SesionEmpresa y SesionAdmin). 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.py conserva 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. Con BYPASSRLS no 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.py es de lectura; router_admin.py escribe. Cada dominio expone el GET en router.py y todo el POST/PUT/DELETE en router_admin.py. Hay dos excepciones, y son las tablas con RLS que el tenant administra sobre su propia empresa: cat_feriados y cat_bancos. El tenant también conserva POST/DELETE de rel_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/plantilla se 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 en plantilla.py (ADR 0034). Si en el futuro la app de empresa la necesita, se agrega como lectura de ese dominio.
  • sucursales repite el patrón y muere get_db_por_scope. El router tenant queda con el listado de su empresa (RLS) y el CRUD vive en api/v1/sucursales/admin con get_db_admin, montado antes que el router tenant para que el literal /admin no caiga en /{sucursal_id}. El helper que elegía el pool según el token se retira con la limpieza de deps.py.
  • La autenticación no entra en esa regla: login, refresh y logout son POST por protocolo, no escritura de dominio, y viven en el router público.

Alternativas descartadas

  • Un solo rol con BYPASSRLS para 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 DEFINER como 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. BYPASSRLS no 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).