Todo SaaS dice que es multi-tenant. En la práctica, en buena parte de ellos, el aislamiento entre clientes depende de una sola cosa: que el desarrollador se acuerde de escribir WHERE tenant_id = ? en cada consulta, cada endpoint, cada reporte y cada job en segundo plano. Basta un olvido, una ruta nueva hecha con prisa o un filtro que vino del cliente en vez de la sesión, y los datos de una empresa aparecen en la pantalla de otra.
Multi-tenant de verdad es cuando el aislamiento no depende de que nadie se acuerde. En este post vas a ver cómo hacerlo en PostgreSQL con Row-Level Security (RLS) forzada en todas las tablas, cómo pasar el cliente actual a la base sin que se filtre entre conexiones del pool y, sobre todo, cómo tener un test automatizado propio que rompe el build si alguna tabla queda sin protección.
Resumen para quien tiene prisa
- La idea: la base de datos, y no la aplicación, decide qué filas puede ver y escribir cada cliente. Una consulta sin
WHEREdevuelve solo las filas del cliente actual. - Activar no basta:
ENABLE ROW LEVEL SECURITYno aplica al dueño de la tabla. Usa tambiénFORCE ROW LEVEL SECURITYy conecta la aplicación con un usuario que no sea dueño, ni superusuario, ni tengaBYPASSRLS. - Lectura y escritura: la política necesita
USING(lo que se ve) yWITH CHECK(lo que se escribe); si no, se pueden insertar filas en nombre de otro cliente. - Contexto por transacción: define el cliente con
set_config('app.tenant_id', ..., true)dentro de una transacción. Así no queda pegado a la conexión cuando vuelve al pool. - Test propio: un test lee el catálogo de Postgres y falla si alguna tabla está sin RLS, sin
FORCEo sin política. Otro crea dos clientes e intenta leer, modificar y borrar los datos del vecino.
Las tres formas de aislar clientes
| Modelo | Aislamiento | Costo y operación |
|---|---|---|
| Una base por cliente | Máximo: cada cliente tiene su propia base | Caro y laborioso: migraciones, backups y conexiones multiplicados por la cantidad de clientes |
| Un schema por cliente | Bueno, pero depende del search_path correcto en cada conexión | Se vuelve pesado con cientos o miles de schemas |
Tablas compartidas con columna tenant_id | Depende de quién aplique el filtro | Simple y barato, una sola migración para todos |
La tercera opción es la más común, porque escala bien y es fácil de operar. El problema es que, sin RLS, el aislamiento vive en el código de la aplicación. Con RLS pasa a vivir en la base, y las tablas compartidas ganan un aislamiento parecido al de los otros modelos sin su costo.
Cómo funciona Row-Level Security
RLS es un recurso de PostgreSQL (desde la versión 9.5) que agrega un filtro obligatorio a cada tabla. Una vez activado, toda lectura y toda escritura deben estar permitidas por una política. Si no hay ninguna política, nadie ve ni modifica nada: por defecto se niega.
Cada política tiene dos partes:
USING: define qué filas existentes son visibles paraSELECT,UPDATEyDELETE. Las demás simplemente no aparecen.WITH CHECK: define qué filas pueden escribirse conINSERTyUPDATE. Si la fila nueva no pasa, el comando falla con error.
Si omites el WITH CHECK, Postgres reutiliza la expresión del USING. Aun así, conviene escribir las dos de forma explícita: queda claro para quien lee y evita sorpresas cuando alguien cambie solo una.
Por qué “forzada”: quién se escapa del RLS
Este es el punto que más tumba implementaciones. Según la documentación de PostgreSQL, tres tipos de usuario no son filtrados por el RLS:
| Quién | ¿Se escapa del RLS? | Cómo resolverlo |
|---|---|---|
| Dueño de la tabla | Sí, por defecto | ALTER TABLE ... FORCE ROW LEVEL SECURITY |
| Superusuario | Siempre, incluso con FORCE | Nunca conectes la aplicación como superusuario |
Usuario con BYPASSRLS | Siempre, incluso con FORCE | Crea el usuario de la aplicación con NOBYPASSRLS |
Es muy común que la aplicación se conecte con el mismo usuario que corrió las migraciones y, por lo tanto, es dueño de las tablas. En ese escenario activas el RLS, creas las políticas, todo parece correcto, y el filtro simplemente no se aplica. El FORCE cierra esa puerta. Separar el usuario de la aplicación del de las migraciones cierra las demás.
Paso a paso
1. Dos usuarios: uno para migraciones y otro para la aplicación
-- dueño de las tablas: lo usan solo las migraciones
CREATE ROLE app_owner NOLOGIN;
-- lo usa la aplicación: sin superusuario y sin BYPASSRLS
CREATE ROLE app_user LOGIN NOSUPERUSER NOBYPASSRLS;
CREATE SCHEMA app AUTHORIZATION app_owner;
GRANT USAGE ON SCHEMA app TO app_user;
-- todo lo que app_owner cree en el schema nace con permiso para app_user
ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA app
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_user;
La contraseña de app_user va al gestor de secretos, no al repositorio. En servicios gestionados (RDS, Cloud SQL, Azure, Supabase, Neon), el usuario administrador que viene con la base suele tener privilegios especiales. No lo uses en la aplicación.
2. Una función para leer el cliente actual
CREATE FUNCTION app.current_tenant_id() RETURNS uuid
LANGUAGE sql STABLE
AS $
SELECT NULLIF(current_setting('app.tenant_id', true), '')::uuid
$;
Dos detalles importantes. El segundo argumento true hace que current_setting devuelva NULL en vez de error cuando la variable no existe. Y el NULLIF cubre el caso en que la variable ya se usó en la conexión y volvió vacía: sin él, ''::uuid da error. Con NULL, la comparación nunca es verdadera y no aparece ninguna fila. Fallar cerrado es exactamente lo que queremos.
Cuidado con ejemplos de internet que devuelven
truecuando no hay cliente definido, “para facilitar el acceso administrativo”. Eso convierte cualquier olvido en acceso a todos los clientes.
3. La tabla con RLS activado y forzado
CREATE TABLE app.invoices (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id uuid NOT NULL DEFAULT app.current_tenant_id()
REFERENCES app.tenants (id),
total numeric(12,2) NOT NULL,
created_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON app.invoices (tenant_id);
ALTER TABLE app.invoices ENABLE ROW LEVEL SECURITY;
ALTER TABLE app.invoices FORCE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON app.invoices
USING (tenant_id = (SELECT app.current_tenant_id()))
WITH CHECK (tenant_id = (SELECT app.current_tenant_id()));
El DEFAULT app.current_tenant_id() completa el tenant_id solo en los INSERT. El índice en tenant_id evita que el filtro se convierta en un recorrido de toda la tabla. Y envolver la función en (SELECT ...) hace que Postgres la calcule una vez por consulta, y no una vez por fila.
Repite el ENABLE, el FORCE y la política en todas las tablas con datos de clientes. La propia tabla app.tenants también entra, con la política id = (SELECT app.current_tenant_id()), para que un cliente no liste a los demás.
4. Pasar el cliente a la base, por transacción
El cliente actual viene de la sesión autenticada (el token o la cookie validados en el servidor), nunca de un parámetro que manda el navegador. En Node.js con el paquete pg, un helper lo resuelve:
import { Pool, type PoolClient } from 'pg'
export const pool = new Pool({ connectionString: process.env.DATABASE_URL }) // se conecta como app_user
export async function withTenant<T>(tenantId: string, fn: (db: PoolClient) => Promise<T>) {
const db = await pool.connect()
try {
await db.query('BEGIN')
// el "true" del final deja la variable válida solo hasta el fin de esta transacción
await db.query("SELECT set_config('app.tenant_id', $1, true)", [tenantId])
const result = await fn(db)
await db.query('COMMIT')
return result
} catch (err) {
await db.query('ROLLBACK')
throw err
} finally {
db.release()
}
}
// uso: sin WHERE tenant_id, y aun así solo vienen las facturas del cliente de la sesión
const facturas = await withTenant(session.tenantId, db =>
db.query('SELECT id, total FROM app.invoices ORDER BY created_at DESC'))
¿Por qué por transacción? Las conexiones se reutilizan en el pool (y en poolers como PgBouncer en modo transaction). Un SET común queda pegado a la conexión, y la siguiente petición que la tome hereda el cliente anterior. Con set_config(..., true), que equivale a SET LOCAL, el valor desaparece en el COMMIT o el ROLLBACK. set_config tiene otra ventaja: acepta parámetros, así que no hay concatenación de strings en el SQL.
Si usas un ORM (Prisma, Drizzle, TypeORM, Sequelize, Eloquent, Django), la idea es la misma: abrir una transacción, llamar a set_config como primera instrucción y correr las consultas dentro de ella.
Las trampas que el RLS no resuelve solo
- Las restricciones únicas filtran existencia. Las claves únicas y foráneas se verifican ignorando el RLS. Un
UNIQUE (email)global permite que el cliente A descubra, por el error de duplicado, que un email existe en el cliente B. PrefiereUNIQUE (tenant_id, email). - Las vistas corren con los permisos del dueño. Una vista creada por
app_ownerpuede ignorar el RLS de las tablas de abajo. En PostgreSQL 15 o más nuevo, crea las vistas conWITH (security_invoker = true). - Las funciones
SECURITY DEFINERtambién corren como el dueño. Úsalas solo cuando sea inevitable y filtra porapp.current_tenant_id()dentro de ellas. - Las particiones tienen políticas propias. Las políticas de la tabla particionada valen cuando la consulta pasa por ella. Quien accede a una partición directamente se topa con las políticas de la partición. Por eso el test de abajo revisa también las particiones.
TRUNCATEno pasa por el RLS. No le desTRUNCATEaapp_user.- Los jobs y las colas también son peticiones. Workers, crons y consumidores de colas necesitan el mismo
withTenant. Si un job de verdad necesita ver todos los clientes, crea un usuario separado para él, déjalo explícito y limita lo que hace. - Backups:
pg_dumpusarow_security = off, que hace que la consulta dé error en vez de devolver datos filtrados a medias. Corre el backup con un usuario que tengaBYPASSRLSy que no sea el de la aplicación.
El test automatizado que garantiza todo esto
Un RLS configurado a mano una vez no garantiza nada dentro de seis meses. Alguien crea una tabla nueva en una migración y se olvida del FORCE. Alguien cambia el usuario de la conexión para “resolver rápido” un error de permisos. Lo que impide la filtración en esos casos es un test que corre en cada pull request. Tiene tres partes.
1. Cobertura: ninguna tabla sin RLS forzado
Esta consulta lee el catálogo de Postgres y lista toda tabla del schema app (incluidas las particiones) que esté sin RLS, sin FORCE o sin ninguna política. El resultado esperado es vacío.
SELECT c.oid::regclass AS tabla,
c.relrowsecurity AS rls_activado,
c.relforcerowsecurity AS rls_forzado,
EXISTS (SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid) AS tiene_politica
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'app'
AND c.relkind IN ('r', 'p') -- tablas comunes y particionadas (las particiones son 'r')
AND (NOT c.relrowsecurity
OR NOT c.relforcerowsecurity
OR NOT EXISTS (SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid));
Al ser un test sobre el catálogo, atrapa la tabla nueva en el mismo PR en que se creó, sin que nadie tenga que escribir un test específico para ella. Si existe una tabla que de verdad es global (una lista de países, por ejemplo), ponla en otro schema, y no en una lista de excepciones que crece sin que nadie lo note.
2. El usuario de la aplicación no puede escaparse
SELECT rolname, rolsuper, rolbypassrls
FROM pg_roles
WHERE rolname = current_user
AND (rolsuper OR rolbypassrls); -- esperado: vacío
SELECT c.oid::regclass
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'app'
AND pg_has_role(current_user, c.relowner, 'MEMBER'); -- esperado: vacío
Ejecutadas con la misma conexión que usa la aplicación, estas consultas confirman que no es superusuario, no tiene BYPASSRLS y no es dueña (ni miembro del dueño) de ninguna tabla.
3. Comportamiento: el cliente A intenta tocar los datos del cliente B
Aquí el test crea dos clientes con datos e intenta, conectado como app_user, todas las formas de cruzar la frontera. Ejemplo con el runner de tests nativo de Node.js (node:test) y el withTenant de arriba:
import { test, before } from 'node:test'
import assert from 'node:assert/strict'
import { pool, withTenant } from '../src/db'
import { seedTwoTenants } from './seed' // crea A y B con facturas, usando app_owner
let A: string, B: string, facturaDeB: string
before(async () => ({ A, B, facturaDeB } = await seedTwoTenants()))
test('A solo ve sus propias filas', async () => {
const { rows } = await withTenant(A, db => db.query('SELECT tenant_id FROM app.invoices'))
assert.ok(rows.length > 0)
assert.ok(rows.every(r => r.tenant_id === A))
})
test('A no encuentra la factura de B ni por id', async () => {
const { rowCount } = await withTenant(A, db =>
db.query('SELECT 1 FROM app.invoices WHERE id = $1', [facturaDeB]))
assert.equal(rowCount, 0)
})
test('A no modifica ni borra datos de B', async () => {
const upd = await withTenant(A, db =>
db.query('UPDATE app.invoices SET total = 0 WHERE id = $1', [facturaDeB]))
const del = await withTenant(A, db =>
db.query('DELETE FROM app.invoices WHERE id = $1', [facturaDeB]))
assert.equal(upd.rowCount, 0)
assert.equal(del.rowCount, 0)
})
test('A no escribe en nombre de B', async () => {
await assert.rejects(
withTenant(A, db =>
db.query('INSERT INTO app.invoices (tenant_id, total) VALUES ($1, 10)', [B])),
/row-level security/)
})
test('sin cliente definido, no aparece nada', async () => {
const { rowCount } = await pool.query('SELECT 1 FROM app.invoices')
assert.equal(rowCount, 0)
})
Los tests de cobertura y de usuario garantizan que la regla vale para todas las tablas. Los tests de comportamiento garantizan que la regla funciona. Conviene generar los tests de comportamiento en un bucle, a partir de la lista de tablas del catálogo, para que toda tabla nueva reciba automáticamente los mismos intentos de invasión.
Si prefieres testear directo en SQL, la extensión pgTAP tiene funciones como policies_are(), policy_cmd_is() y results_eq(). Solo recuerda que las dos primeras revisan los metadatos de las políticas, no si los datos del vecino están de verdad ocultos. El test de comportamiento sigue siendo necesario.
Corriendo en el CI
# .github/workflows/rls.yml
name: rls
on: [pull_request]
jobs:
aislamiento:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:18
env: { POSTGRES_PASSWORD: postgres }
ports: ['5432:5432']
options: >-
--health-cmd pg_isready --health-interval 5s --health-retries 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 24 }
- run: npm ci
- run: npm run db:migrate # corre como app_owner
- run: npm run test:rls # corre como app_user
Usa en el CI la misma versión principal de Postgres que en producción, y corre las migraciones y los tests con los mismos usuarios de producción. Un test que corre como superusuario siempre pasa, y por eso no prueba nada.
¿Y el rendimiento?
Con el índice en tenant_id y la función dentro de (SELECT ...), la política se convierte, en la práctica, en un filtro más en el plan de la consulta, como el WHERE que escribirías a mano. Compruébalo con EXPLAIN ANALYZE en las consultas más pesadas. En tablas grandes, los índices compuestos que empiezan por tenant_id (por ejemplo, (tenant_id, created_at)) suelen ayudar más que el índice simple.
Mantén también Postgres actualizado. La ronda del 12/11/2026 trajo las versiones 18.7, 17.12, 16.16 y 15.20, y marcó el fin del soporte de PostgreSQL 14.
Checklist
- La aplicación se conecta con un usuario que no es superusuario, no tiene
BYPASSRLSy no es dueño de las tablas. - Todas las tablas con datos de clientes tienen
ENABLEyFORCE ROW LEVEL SECURITY. - Toda política tiene
USINGyWITH CHECK, y falla cerrada cuando no hay cliente definido. - El cliente viene de la sesión autenticada y se define con
set_config(..., true)dentro de una transacción. - Las restricciones únicas incluyen
tenant_id. Las vistas usansecurity_invoker. - Jobs, colas y crons pasan por el mismo helper.
- El CI tiene el test de cobertura del catálogo, el test del usuario y el test de intento de invasión entre clientes, corriendo en cada PR.
Con esto, el WHERE tenant_id que alguien olvide deja de ser una filtración y pasa a ser solo una línea más que no hacía falta. Y la tabla nueva sin protección no llega a producción, porque el build se rompe antes.


