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 WHERE devolve só as linhas do cliente atual.
  • Ligar não basta: ENABLE ROW LEVEL SECURITY não vale para o dono da tabela. Use também FORCE ROW LEVEL SECURITY e conecte a aplicação com um usuário que não seja dono, nem superusuário, nem tenha BYPASSRLS.
  • Leitura e escrita: a política precisa de USING (o que se vê) e WITH 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 FORCE ou 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

ModeloIsolamentoCusto e operação
Um banco por clienteMáximo: cada cliente tem seu próprio bancoCaro e trabalhoso: migrations, backups e conexões multiplicados pelo número de clientes
Um schema por clienteBom, mas depende do search_path certo em cada conexãoFica pesado com centenas ou milhares de schemas
Tabelas compartilhadas com coluna tenant_idDepende de quem aplica o filtroSimples 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 para SELECT, UPDATE e DELETE. As outras simplesmente não aparecem.
  • WITH CHECK: define quais linhas podem ser gravadas por INSERT e UPDATE. 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:

QuemEscapa do RLS?Como resolver
Dono da tabelaSim, por padrãoALTER TABLE ... FORCE ROW LEVEL SECURITY
SuperusuárioSempre, mesmo com FORCENunca conecte a aplicação como superusuário
Usuário com BYPASSRLSSempre, mesmo com FORCECrie 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 true quando 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. Prefira UNIQUE (tenant_id, email).
  • Views rodam com as permissões do dono. Uma view criada pelo app_owner pode ignorar o RLS das tabelas por baixo. No PostgreSQL 15 ou mais novo, crie as views com WITH (security_invoker = true).
  • Funções SECURITY DEFINER também rodam como o dono. Use só quando for inevitável e filtre por app.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.
  • TRUNCATE não passa pelo RLS. Não conceda TRUNCATE ao app_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_dump usa row_security = off, que faz a consulta dar erro em vez de devolver dados filtrados pela metade. Rode o backup com um usuário que tenha BYPASSRLS e 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 BYPASSRLS e não é dono das tabelas.
  • Todas as tabelas com dados de cliente têm ENABLE e FORCE ROW LEVEL SECURITY.
  • Toda política tem USING e WITH 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 usam security_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.