Todo SaaS diz que é multi-tenant. Na prática, em boa parte deles, o isolamento entre clientes depende de uma única coisa: o desenvolvedor lembrar de escrever WHERE tenant_id = ? em cada consulta, em cada endpoint, em cada relatório e em cada job em segundo plano. Basta um esquecimento, uma rota nova feita com pressa ou um filtro que veio do cliente em vez da sessão, e os dados de uma empresa aparecem na tela de outra.
Multi-tenant de verdade é quando o isolamento não depende de ninguém lembrar. Neste post, você vai ver como fazer isso no PostgreSQL com Row-Level Security (RLS) forçada em todas as tabelas, como passar o cliente atual para o banco sem vazar entre conexões do pool e, principalmente, como ter um teste automatizado próprio que quebra o build se alguma tabela ficar sem proteção.
Resumo para quem tem pressa
- A ideia: o banco, e não a aplicação, decide quais linhas cada cliente pode ver e gravar. Uma consulta sem
WHEREdevolve só as linhas do cliente atual. - Ligar não basta:
ENABLE ROW LEVEL SECURITYnão vale para o dono da tabela. Use tambémFORCE ROW LEVEL SECURITYe conecte a aplicação com um usuário que não seja dono, nem superusuário, nem tenhaBYPASSRLS. - Leitura e escrita: a política precisa de
USING(o que se vê) eWITH CHECK(o que se grava), senão dá para inserir linhas em nome de outro cliente. - Contexto por transação: defina o cliente com
set_config('app.tenant_id', ..., true)dentro de uma transação. Assim ele não sobra na conexão quando ela volta para o pool. - Teste próprio: um teste lê o catálogo do Postgres e falha se qualquer tabela estiver sem RLS, sem
FORCEou sem política. Outro teste cria dois clientes e tenta ler, alterar e apagar os dados do vizinho.
Os três jeitos de isolar clientes
| Modelo | Isolamento | Custo e operação |
|---|---|---|
| Um banco por cliente | Máximo: cada cliente tem seu próprio banco | Caro e trabalhoso: migrations, backups e conexões multiplicados pelo número de clientes |
| Um schema por cliente | Bom, mas depende do search_path certo em cada conexão | Fica pesado com centenas ou milhares de schemas |
Tabelas compartilhadas com coluna tenant_id | Depende de quem aplica o filtro | Simples e barato, uma migration só para todos |
A terceira opção é a mais comum, porque escala bem e é fácil de operar. O problema é que, sem RLS, o isolamento mora no código da aplicação. Com RLS, ele passa a morar no banco, e as tabelas compartilhadas ganham um isolamento parecido com o dos outros modelos sem o custo deles.
Como o Row-Level Security funciona
RLS é um recurso do PostgreSQL (desde a versão 9.5) que adiciona um filtro obrigatório a cada tabela. Depois que você liga o RLS, toda leitura e toda escrita precisam ser permitidas por uma política. Se não houver nenhuma política, ninguém vê nem altera nada: o padrão é negar.
Cada política tem duas partes:
USING: define quais linhas existentes ficam visíveis paraSELECT,UPDATEeDELETE. As outras simplesmente não aparecem.WITH CHECK: define quais linhas podem ser gravadas porINSERTeUPDATE. Se a linha nova não passar, o comando falha com erro.
Se você omitir o WITH CHECK, o Postgres reaproveita a expressão do USING. Mesmo assim, vale escrever as duas de forma explícita: fica claro para quem lê e evita surpresas quando alguém mexer só em uma delas.
Por que “forçada”: quem escapa do RLS
Este é o ponto que mais derruba implementações. Segundo a documentação do PostgreSQL, três tipos de usuário não são filtrados pelo RLS:
| Quem | Escapa do RLS? | Como resolver |
|---|---|---|
| Dono da tabela | Sim, por padrão | ALTER TABLE ... FORCE ROW LEVEL SECURITY |
| Superusuário | Sempre, mesmo com FORCE | Nunca conecte a aplicação como superusuário |
Usuário com BYPASSRLS | Sempre, mesmo com FORCE | Crie o usuário da aplicação com NOBYPASSRLS |
É muito comum a aplicação conectar com o mesmo usuário que rodou as migrations e, portanto, é dono das tabelas. Nesse cenário, você liga o RLS, cria as políticas, tudo parece certo, e o filtro simplesmente não é aplicado. O FORCE fecha essa porta. Separar o usuário da aplicação do usuário das migrations fecha as outras.
Passo a passo
1. Dois usuários: um para migrations, outro para a aplicação
-- dono das tabelas: usado só pelas migrations
CREATE ROLE app_owner NOLOGIN;
-- usado pela aplicação: sem superusuário e sem BYPASSRLS
CREATE ROLE app_user LOGIN NOSUPERUSER NOBYPASSRLS;
CREATE SCHEMA app AUTHORIZATION app_owner;
GRANT USAGE ON SCHEMA app TO app_user;
-- tudo o que o app_owner criar no schema já nasce liberado para o app_user
ALTER DEFAULT PRIVILEGES FOR ROLE app_owner IN SCHEMA app
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_user;
A senha do app_user vai para o gerenciador de segredos, não para o repositório. Em serviços gerenciados (RDS, Cloud SQL, Azure, Supabase, Neon), o usuário administrador que vem com o banco costuma ter privilégios especiais. Não use ele na aplicação.
2. Uma função para ler o cliente atual
CREATE FUNCTION app.current_tenant_id() RETURNS uuid
LANGUAGE sql STABLE
AS $
SELECT NULLIF(current_setting('app.tenant_id', true), '')::uuid
$;
Dois detalhes importantes. O segundo argumento true faz o current_setting devolver NULL em vez de erro quando a variável não existe. E o NULLIF trata o caso em que a variável já foi usada na conexão e voltou vazia: sem ele, ''::uuid dá erro. Com NULL, a comparação nunca é verdadeira e nenhuma linha aparece. Falhar fechado é exatamente o que queremos.
Cuidado com exemplos da internet que retornam
truequando o cliente não foi definido, “para facilitar o acesso administrativo”. Isso transforma qualquer esquecimento em acesso a todos os clientes.
3. A tabela com RLS ligado e forçado
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()));
O DEFAULT app.current_tenant_id() preenche o tenant_id sozinho nos INSERTs. O índice em tenant_id evita que o filtro vire uma varredura da tabela inteira. E envolver a função em (SELECT ...) faz o Postgres calculá-la uma vez por consulta, e não uma vez por linha.
Repita o ENABLE, o FORCE e a política em todas as tabelas com dados de cliente. A própria tabela app.tenants também entra, com a política id = (SELECT app.current_tenant_id()), para um cliente não listar os outros.
4. Passar o cliente para o banco, por transação
O cliente atual vem da sessão autenticada (o token ou o cookie validado no servidor), nunca de um parâmetro que o navegador manda. Em Node.js com o pacote pg, um helper resolve:
import { Pool, type PoolClient } from 'pg'
export const pool = new Pool({ connectionString: process.env.DATABASE_URL }) // 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')
// o "true" no fim deixa a variável valendo só até o fim desta transação
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: sem WHERE tenant_id, e ainda assim só vêm as faturas do cliente da sessão
const faturas = await withTenant(session.tenantId, db =>
db.query('SELECT id, total FROM app.invoices ORDER BY created_at DESC'))
Por que por transação? Conexões são reaproveitadas pelo pool (e por poolers como o PgBouncer em modo transaction). Um SET comum fica grudado na conexão, e a próxima requisição que pegar essa conexão herda o cliente anterior. Com set_config(..., true), que equivale a SET LOCAL, o valor some no COMMIT ou no ROLLBACK. O set_config tem outra vantagem: aceita parâmetro, então não há concatenação de string no SQL.
Se você usa ORM (Prisma, Drizzle, TypeORM, Sequelize, Eloquent, Django), a ideia é a mesma: abrir uma transação, chamar set_config como primeira instrução e rodar as consultas dentro dela.
As pegadinhas que o RLS não resolve sozinho
- Restrições únicas vazam existência. Chaves únicas e estrangeiras são verificadas ignorando o RLS. Um
UNIQUE (email)global deixa o cliente A descobrir, pelo erro de duplicidade, que um e-mail existe no cliente B. PrefiraUNIQUE (tenant_id, email). - Views rodam com as permissões do dono. Uma view criada pelo
app_ownerpode ignorar o RLS das tabelas por baixo. No PostgreSQL 15 ou mais novo, crie as views comWITH (security_invoker = true). - Funções
SECURITY DEFINERtambém rodam como o dono. Use só quando for inevitável e filtre porapp.current_tenant_id()dentro delas. - Partições têm políticas próprias. As políticas da tabela particionada valem quando a consulta passa por ela. Quem acessa uma partição diretamente esbarra nas políticas da partição. Por isso o teste abaixo verifica partições também.
TRUNCATEnão passa pelo RLS. Não concedaTRUNCATEaoapp_user.- Jobs e filas também são requisições. Workers, crons e consumidores de fila precisam do mesmo
withTenant. Se um job precisa ver todos os clientes, crie um usuário separado para ele, deixe isso explícito e limite o que ele faz. - Backups: o
pg_dumpusarow_security = off, que faz a consulta dar erro em vez de devolver dados filtrados pela metade. Rode o backup com um usuário que tenhaBYPASSRLSe que não seja o da aplicação.
O teste automatizado que garante tudo isso
RLS configurado à mão uma vez não é garantia de nada daqui a seis meses. Alguém cria uma tabela nova numa migration e esquece do FORCE. Alguém troca o usuário da conexão para “resolver rápido” um erro de permissão. O que impede o vazamento nesses casos é um teste que roda em todo pull request. Ele tem três partes.
1. Cobertura: nenhuma tabela sem RLS forçado
Esta consulta lê o catálogo do Postgres e lista toda tabela do schema app (incluindo partições) que esteja sem RLS, sem FORCE ou sem nenhuma política. O resultado esperado é vazio.
SELECT c.oid::regclass AS tabela,
c.relrowsecurity AS rls_ligado,
c.relforcerowsecurity AS rls_forcado,
EXISTS (SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid) AS tem_politica
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'app'
AND c.relkind IN ('r', 'p') -- tabelas comuns e particionadas (partições são 'r')
AND (NOT c.relrowsecurity
OR NOT c.relforcerowsecurity
OR NOT EXISTS (SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid));
Por ser um teste sobre o catálogo, ele pega a tabela nova no mesmo PR em que ela foi criada, sem ninguém precisar escrever um teste específico para ela. Se existir uma tabela que de fato é global (uma lista de países, por exemplo), coloque ela em outro schema, e não numa lista de exceções que cresce sem ninguém ver.
2. O usuário da aplicação não pode escapar
SELECT rolname, rolsuper, rolbypassrls
FROM pg_roles
WHERE rolname = current_user
AND (rolsuper OR rolbypassrls); -- esperado: vazio
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: vazio
Rodadas com a mesma conexão que a aplicação usa, essas consultas confirmam que ela não é superusuário, não tem BYPASSRLS e não é dona (nem membro do dono) de nenhuma tabela.
3. Comportamento: o cliente A tenta mexer nos dados do cliente B
Aqui o teste cria dois clientes com dados e tenta, conectado como app_user, todas as formas de atravessar a fronteira. Exemplo com o executor de testes nativo do Node.js (node:test) e o withTenant acima:
import { test, before } from 'node:test'
import assert from 'node:assert/strict'
import { pool, withTenant } from '../src/db'
import { seedTwoTenants } from './seed' // cria A e B com faturas, usando o app_owner
let A: string, B: string, faturaDoB: string
before(async () => ({ A, B, faturaDoB } = await seedTwoTenants()))
test('A só enxerga as próprias linhas', 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 não acha a fatura do B nem pelo id', async () => {
const { rowCount } = await withTenant(A, db =>
db.query('SELECT 1 FROM app.invoices WHERE id = $1', [faturaDoB]))
assert.equal(rowCount, 0)
})
test('A não altera nem apaga dados do B', async () => {
const upd = await withTenant(A, db =>
db.query('UPDATE app.invoices SET total = 0 WHERE id = $1', [faturaDoB]))
const del = await withTenant(A, db =>
db.query('DELETE FROM app.invoices WHERE id = $1', [faturaDoB]))
assert.equal(upd.rowCount, 0)
assert.equal(del.rowCount, 0)
})
test('A não grava em nome do 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('sem cliente definido, não aparece nada', async () => {
const { rowCount } = await pool.query('SELECT 1 FROM app.invoices')
assert.equal(rowCount, 0)
})
Os testes de cobertura e de usuário garantem que a regra vale para todas as tabelas. Os testes de comportamento garantem que a regra funciona. Vale gerar os testes de comportamento em laço, a partir da lista de tabelas do catálogo, para que toda tabela nova ganhe as mesmas tentativas de invasão automaticamente.
Se você prefere testar direto em SQL, a extensão pgTAP tem funções como policies_are(), policy_cmd_is() e results_eq(). Lembre só que as duas primeiras conferem os metadados das políticas, não se os dados do vizinho estão de fato escondidos. O teste de comportamento continua necessário.
Rodando no CI
# .github/workflows/rls.yml
name: rls
on: [pull_request]
jobs:
isolamento:
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 # roda como app_owner
- run: npm run test:rls # roda como app_user
Use no CI a mesma versão principal do Postgres da produção, e rode as migrations e os testes com os mesmos usuários da produção. Um teste que roda como superusuário passa sempre, e por isso não prova nada.
E o desempenho?
Com o índice em tenant_id e a função dentro de (SELECT ...), a política vira, na prática, um filtro a mais no plano da consulta, como o WHERE que você escreveria à mão. Confira com EXPLAIN ANALYZE nas consultas mais pesadas. Em tabelas grandes, índices compostos que começam por tenant_id (por exemplo, (tenant_id, created_at)) costumam ajudar mais do que o índice simples.
Mantenha também o Postgres atualizado. A rodada de 12/11/2026 trouxe as versões 18.7, 17.12, 16.16 e 15.20, e marcou o fim do suporte do PostgreSQL 14.
Checklist
- A aplicação conecta com um usuário que não é superusuário, não tem
BYPASSRLSe não é dono das tabelas. - Todas as tabelas com dados de cliente têm
ENABLEeFORCE ROW LEVEL SECURITY. - Toda política tem
USINGeWITH CHECK, e falha fechada quando o cliente não foi definido. - O cliente vem da sessão autenticada e é definido com
set_config(..., true)dentro de uma transação. - Restrições únicas incluem
tenant_id. Views usamsecurity_invoker. - Jobs, filas e crons passam pelo mesmo helper.
- O CI tem o teste de cobertura do catálogo, o teste do usuário e o teste de tentativa de invasão entre clientes, rodando em todo PR.
Com isso, o WHERE tenant_id que alguém esquecer deixa de ser um vazamento e passa a ser só uma linha a mais que não fazia falta. E a tabela nova sem proteção não chega em produção, porque o build quebra antes.


