Blog

Row Level Security que deixa a consulta lenta: políticas, funções não leakproof e o índice que deixa de ser usado

Um SaaS de gestão de pedidos com 1.200 clientes guardava tudo numa tabela pedidos de 18 milhões de linhas, e o isolamento entre clientes dependia de cada consulta lembrar do WHERE tenant_id = $1. Depois de um quase vazamento numa rota nova, o time decidiu tirar essa responsabilidade da aplicação e ativar Row Level Security: uma política por tabela, uma função que lê o tenant da transação e pronto. Vinte minutos depois do deploy, a listagem de pedidos saiu de 40 ms para 14 segundos e o pool de conexões esgotou. O EXPLAIN rodado no psql mostrava um Index Scan de 3 ms, porque quem rodou era o dono da tabela, e o dono não passa pela política. Corrigida a função, um segundo problema apareceu dois dias depois: a busca por nome de cliente parou de usar o índice trigram no maior tenant, mesmo com tudo certo na política. Este artigo explica como o PostgreSQL aplica uma política de RLS ao plano, por que a volatilidade da função e o atributo LEAKPROOF dos operadores decidem se um índice ainda pode ser usado, como medir o plano do jeito que a aplicação o recebe e como corrigir sem abrir mão do isolamento.

2026-11-22 / Arquitetura / 13 min

01

A migração para RLS que multiplicou a listagem por 350

O desenho era o recomendado em quase todo guia: a aplicação abre a transação, grava o tenant do usuário com set_config('app.tenant_id', $1, true) e todas as tabelas com tenant_id ganham a política tenant_id = app_tenant_atual(). As consultas foram simplificadas, sem o filtro manual, já que o banco passava a garanti-lo. Em homologação, com 40 mil pedidos, nada mudou de forma perceptível. Em produção, cada listagem passou a ler a tabela inteira.

Seg 09:00  deploy: o filtro tenant_id sai das consultas e passa para uma política de RLS
Seg 09:20  listagem de pedidos: p95 de 40 ms para 14 s; o pool de conexões esgota em 12 minutos
Seg 09:45  EXPLAIN no psql com o usuário das migrações: Index Scan, 3 ms ("não reproduz")
Seg 10:30  rollback do deploy; o filtro manual volta para as consultas
Ter 15:00  EXPLAIN refeito com SET ROLE app_api: Seq Scan com Filter: tenant_id = app_tenant_atual()
Ter 16:10  função passa para STABLE e a política usa (SELECT app_tenant_atual()): listagem em 38 ms
Qua 11:00  novo deploy; busca por nome de cliente no maior tenant: de 60 ms para 1,8 s
Qua 14:30  causa: ILIKE (texticlike) não é leakproof e o índice trigram deixa de ser candidato
Qui 10:00  busca vai para uma função SECURITY DEFINER e o CI passa a conferir planos como app_api

Os dois defeitos têm a mesma raiz: a política não é um WHERE colado na consulta. Ela entra no plano com regras próprias de segurança, e essas regras limitam o que o planejador pode fazer com funções e operadores. Enquanto o filtro estava escrito na consulta, nenhuma dessas regras se aplicava.

02

Como a política entra no plano e por que o EXPLAIN do psql mente

Quando o usuário atual está sujeito a RLS, o PostgreSQL acrescenta a expressão USING de cada política permissiva aplicável (combinadas com OR) como uma qualificação de segurança da tabela. Ela é avaliada antes das condições escritas na consulta, a não ser que a condição da consulta seja segura para rodar antes, ou seja, só use funções marcadas como LEAKPROOF. A ordem existe para impedir que uma função da consulta veja, numa mensagem de erro ou num efeito colateral, o valor de uma linha que a política esconderia.

Três tipos de papel nunca passam por isso: superusuários, papéis com BYPASSRLS e o dono da tabela, a menos que a tabela tenha FORCE ROW LEVEL SECURITY. O usuário das migrações costuma ser o dono, e é com ele que quase todo mundo abre o psql para investigar. Por isso o plano que o plantão via não tinha política nenhuma.

CREATE TABLE pedidos (
  id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  tenant_id  integer     NOT NULL,
  cliente    text        NOT NULL,
  status     text        NOT NULL,
  criado_em  timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX pedidos_tenant_criado_idx ON pedidos (tenant_id, criado_em DESC);
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX pedidos_cliente_trgm_idx ON pedidos USING gin (cliente gin_trgm_ops);

-- Função escrita na migração: plpgsql sem volatilidade declarada é VOLATILE.
CREATE FUNCTION app_tenant_atual() RETURNS integer
LANGUAGE plpgsql AS $
BEGIN
  RETURN current_setting('app.tenant_id')::integer;
END;
$;

CREATE ROLE app_api NOLOGIN;
GRANT SELECT ON pedidos TO app_api;
ALTER TABLE pedidos ENABLE ROW LEVEL SECURITY;
CREATE POLICY isolamento_tenant ON pedidos
  USING (tenant_id = app_tenant_atual());

-- Como dono da tabela (o usuário das migrações), a política nem é aplicada:
EXPLAIN SELECT * FROM pedidos WHERE tenant_id = 42
 ORDER BY criado_em DESC LIMIT 50;
 Limit
   ->  Index Scan using pedidos_tenant_criado_idx on pedidos
         Index Cond: (tenant_id = 42)

-- Como a aplicação enxerga a mesma tabela (a sessão precisa ser membro de app_api):
BEGIN;
SET LOCAL ROLE app_api;
SELECT set_config('app.tenant_id', '42', true);
EXPLAIN SELECT * FROM pedidos ORDER BY criado_em DESC LIMIT 50;
 Limit
   ->  Sort
         Sort Key: criado_em DESC
         ->  Seq Scan on pedidos
               Filter: (tenant_id = app_tenant_atual())
-- A função VOLATILE não pode virar condição de índice: é chamada para cada uma das 18 milhões de linhas.
ROLLBACK;

A regra prática: todo EXPLAIN que investiga uma tabela com RLS precisa rodar dentro de uma transação com SET LOCAL ROLE para o papel da aplicação e com o tenant configurado do mesmo jeito que a aplicação configura. Sem isso, você está analisando outra consulta.

03

A função da política: VOLATILE por padrão e chamada para cada linha

Funções em plpgsql e em SQL que não declaram volatilidade são VOLATILE. Para o planejador, isso significa que o resultado pode mudar a cada chamada, então tenant_id = app_tenant_atual() não pode virar condição de índice: ele não tem um valor fixo para procurar na árvore. Sobra o Seq Scan, com a função executada como filtro em cada uma das 18 milhões de linhas. Funções VOLATILE também são PARALLEL UNSAFE por padrão, e a varredura nem pode ser dividida entre workers.

A correção tem duas partes. A primeira é declarar a função como STABLE, o que é verdade para quem só lê current_setting dentro da transação. A segunda é chamar a função dentro de um SELECT na política. A subconsulta não correlacionada vira um InitPlan: é executada uma vez, antes da varredura, e o resultado entra como parâmetro na condição de índice. Isso também protege contra funções mais caras, como as que consultam uma tabela de sessões, que de outro modo seriam chamadas por linha.

-- STABLE: o valor não muda dentro da consulta, então pode ser usado como condição de índice.
-- Sem a configuração, devolve NULL e a política não deixa passar nenhuma linha.
CREATE OR REPLACE FUNCTION app_tenant_atual() RETURNS integer
LANGUAGE sql STABLE PARALLEL SAFE AS $
  SELECT nullif(current_setting('app.tenant_id', true), '')::integer
$;

-- Envolver a chamada em um SELECT a transforma em InitPlan: executada uma vez por consulta.
ALTER POLICY isolamento_tenant ON pedidos
  USING (tenant_id = (SELECT app_tenant_atual()));

EXPLAIN SELECT * FROM pedidos ORDER BY criado_em DESC LIMIT 50;
 Limit
   InitPlan 1
     ->  Result
   ->  Index Scan using pedidos_tenant_criado_idx on pedidos
         Index Cond: (tenant_id = (InitPlan 1).col1)

-- Política de associação que roda um SubPlan para cada linha da tabela:
CREATE POLICY membros_veem ON notas_fiscais USING (
  EXISTS (SELECT 1 FROM membros m
           WHERE m.tenant_id = notas_fiscais.tenant_id
             AND m.usuario_id = (SELECT app_usuario_atual()))
);

-- Mesma regra avaliada uma vez: a lista de tenants do usuário vira um array.
ALTER POLICY membros_veem ON notas_fiscais USING (
  tenant_id = ANY (ARRAY(
    SELECT m.tenant_id FROM membros m
     WHERE m.usuario_id = (SELECT app_usuario_atual())
  ))
);
--   Index Cond: (tenant_id = ANY ((InitPlan 2).col1))

O mesmo raciocínio vale para políticas de associação, em que o usuário enxerga os tenants dos quais é membro. Um EXISTS correlacionado com a tabela membros é avaliado como SubPlan para cada linha candidata, porque a subconsulta de uma política não é transformada em junção como seria num WHERE comum. Reescrita como tenant_id = ANY (ARRAY(SELECT ...)), a lista de tenants é calculada uma vez e o índice de tenant_id volta a ser usado.

04

Leakproof: por que o ILIKE deixa de usar o índice trigram

Com a função corrigida, a listagem voltou para 38 ms, mas a busca por nome de cliente do maior tenant, com 2,1 milhões de pedidos, foi de 60 ms para 1,8 s. A consulta era a mesma de antes, só sem o filtro de tenant: WHERE cliente ILIKE '%souza%'. O índice GIN com gin_trgm_ops continuava lá. O que mudou é que o operador ILIKE é implementado pela função texticlike, que não é LEAKPROOF. Sob RLS, uma condição da consulta que usa função não leakproof não pode ser avaliada antes da política, e o PostgreSQL também não a usa como condição de índice, porque ler o índice já seria avaliá-la antes. O planejador usa o índice da política, lê os 2,1 milhões de pedidos do tenant e aplica o ILIKE como filtro.

-- Quais operadores de texto podem ser avaliados antes da política?
SELECT o.oprname, o.oprcode, p.proleakproof
  FROM pg_operator o
  JOIN pg_proc p ON p.oid = o.oprcode
 WHERE o.oprleft = 'text'::regtype
   AND o.oprright = 'text'::regtype
   AND o.oprname IN ('=', '~', '~~', '~~*')
 ORDER BY o.oprname;
 oprname |   oprcode   | proleakproof
---------+-------------+--------------
 =       | texteq      | t
 ~       | textregexeq | f
 ~~      | textlike    | f
 ~~*     | texticlike  | f

-- Como a aplicação: a política usa o índice de tenant, mas o ILIKE fica de fora dele.
EXPLAIN SELECT id, cliente, criado_em FROM pedidos
 WHERE cliente ILIKE '%souza%'
 ORDER BY criado_em DESC LIMIT 50;
 Limit
   InitPlan 1
     ->  Result
   ->  Index Scan using pedidos_tenant_criado_idx on pedidos
         Index Cond: (tenant_id = (InitPlan 1).col1)
         Filter: (cliente ~~* '%souza%'::text)
-- O índice trigram não aparece: texticlike não é leakproof e não pode ser condição de índice.

O problema não é exclusivo do ILIKE. Toda função na expressão conta, então lower(email) = $1 perde o índice de expressão em lower(email) mesmo com o = sendo leakproof. A tabela abaixo resume os casos mais comuns; confira na sua versão com a consulta em pg_proc acima, porque a lista de funções leakproof pode mudar entre versões.

Condição na consultaFunçãoLeakproofVira condição de índice sob RLS
tenant_id = 42 (integer)int4eqsimsim
id = '...' (uuid)uuid_eqsimsim
cliente = 'Souza'texteqsimsim
cliente LIKE 'Sou%'textlikenãonão
cliente ILIKE '%souza%'texticlikenãonão
lower(email) = '[email protected]'lowernãonão
dados @> '{"canal":"loja"}'jsonb_containsnãonão
documento @@ to_tsquery(...)ts_match_vqnãonão

Isso explica por que os testes passaram: em tenants pequenos, ler todos os pedidos do tenant e filtrar é rápido. O custo cresce com o tamanho do tenant, e só os maiores clientes, justamente os que mais reclamam, sentem a diferença.

05

Como corrigir sem desligar o isolamento

Para busca textual, a saída mais segura é uma função SECURITY DEFINER pertencente ao dono da tabela. Ela roda com os privilégios do dono, que não passa pela política, e escreve o filtro de tenant explicitamente com a mesma função da política. Sem qualificação de segurança, o planejador volta a combinar o índice trigram com o filtro de tenant. O isolamento continua no banco, só que num lugar revisado e com search_path fixo, que impede outro esquema de sequestrar as funções chamadas. A tabela não pode ter FORCE ROW LEVEL SECURITY, senão o dono também passaria pela política e o ganho desaparece.

-- Busca executada com os privilégios do dono da tabela, que não passa pela política.
CREATE FUNCTION buscar_pedidos_por_cliente(termo text, limite integer DEFAULT 50)
RETURNS SETOF pedidos
LANGUAGE sql STABLE SECURITY DEFINER
SET search_path = pg_catalog, public
AS $
  SELECT p.*
    FROM public.pedidos p
   -- O isolamento continua, mas agora escrito de forma explícita e leakproof.
   WHERE p.tenant_id = (SELECT public.app_tenant_atual())
     -- Escapa % e _ digitados pelo usuário para que virem texto literal no padrão.
     AND p.cliente ILIKE '%' || replace(replace(replace(termo, '\', '\\'), '%', '\%'), '_', '\_') || '%'
   ORDER BY p.criado_em DESC
   LIMIT limite
$;

-- Só a aplicação pode chamar a função.
REVOKE ALL ON FUNCTION buscar_pedidos_por_cliente(text, integer) FROM PUBLIC;
GRANT EXECUTE ON FUNCTION buscar_pedidos_por_cliente(text, integer) TO app_api;

-- SELECT * FROM buscar_pedidos_por_cliente('souza');
--   Bitmap Heap Scan on pedidos p
--     Recheck Cond: (cliente ~~* ...)
--     Filter: (tenant_id = (InitPlan 1).col1)
--     ->  Bitmap Index Scan on pedidos_cliente_trgm_idx

Para o resto, manter o WHERE tenant_id = $1 nas consultas, além da política, é barato e ajuda. A igualdade em integer é leakproof, então pode ser condição de índice, e o planejador conhece o valor do parâmetro no plano customizado. Com o InitPlan da política, ele não sabe qual tenant será lido e estima a seletividade pela média, o que costuma subestimar os tenants grandes. A política continua lá como rede de segurança para a consulta que esquecer o filtro.

O que aparece no EXPLAINCausaCorreção
Seq Scan com Filter: (tenant_id = minha_funcao())Função da política VOLATILE, o padrão sem declaraçãoDeclarar STABLE e chamar como (SELECT minha_funcao())
SubPlan executado para cada linhaEXISTS correlacionado na política de associaçãotenant_id = ANY (ARRAY(SELECT ...)) avaliado como InitPlan
Índice de tenant usado e Filter com ILIKE, LIKE, lower ou @>Função não leakproof na condição da consultaFunção SECURITY DEFINER com filtro explícito de tenant
Rápido no psql e lento na aplicaçãoDono, superusuário ou BYPASSRLS ignoram a políticaEXPLAIN com SET LOCAL ROLE do papel da aplicação
Consulta sem nenhuma linha depois de trocar o poolapp.tenant_id vazio na conexão reaproveitadaset_config(..., true) em cada transação e current_setting(..., true)

Marcar texticlike ou lower como LEAKPROOF com ALTER FUNCTION resolveria o plano, mas exige superusuário, vale para todas as tabelas com RLS do banco e transfere para você a garantia de que a função nunca revela nada sobre os argumentos, nem em mensagens de erro. Na maioria dos serviços gerenciados, nem é possível.

06

Verificar o plano como a aplicação, no CI

O incidente só aconteceu porque ninguém olhava o plano com o papel da aplicação. O script abaixo roda as consultas críticas dentro de transações com SET LOCAL ROLE app_api, o tenant configurado e enable_seqscan desligado. Com seq scan desligado, ele só continua no plano quando não há índice utilizável, então o teste detecta o defeito estrutural mesmo num banco de CI com poucas linhas. Também falha com Index Scan sem Index Cond, que é o que o planejador escolhe para fugir do Seq Scan quando a condição não pode entrar no índice.

// verificar-planos-rls.js
// Roda no CI contra um banco com o esquema de produção: node verificar-planos-rls.js
import pg from 'pg';

const PAPEL_APLICACAO = 'app_api';
const TENANT_DE_TESTE = '42';

// Consultas críticas com valores literais, do jeito que a aplicação as envia.
const CONSULTAS = [
  {
    nome: 'listagem de pedidos',
    sql: 'SELECT id, cliente, status, criado_em FROM pedidos ORDER BY criado_em DESC LIMIT 50',
  },
  {
    nome: 'pedidos abertos',
    sql: "SELECT id FROM pedidos WHERE status = 'aberto' ORDER BY criado_em DESC LIMIT 50",
  },
  {
    nome: 'detalhe do pedido',
    sql: 'SELECT * FROM pedidos WHERE id = 123',
  },
];

// Tabelas em que varrer tudo é sempre um defeito, independente do volume do banco de teste.
const TABELAS_GRANDES = new Set(['pedidos', 'itens_pedido', 'notas_fiscais']);

// Seq Scan, ou Index Scan sem Index Cond (varredura do índice inteiro), numa tabela grande.
const varreTudo = (no) =>
  TABELAS_GRANDES.has(no['Relation Name']) &&
  (no['Node Type'] === 'Seq Scan' ||
    (['Index Scan', 'Index Only Scan'].includes(no['Node Type']) && !no['Index Cond']));

const coletarVarreduras = (no, achados = []) => {
  if (varreTudo(no)) {
    achados.push(`${no['Node Type']} em ${no['Relation Name']} (filtro: ${no.Filter ?? 'nenhum'})`);
  }
  for (const filho of no.Plans ?? []) coletarVarreduras(filho, achados);
  return achados;
};

const client = new pg.Client({ connectionString: process.env.DATABASE_URL });
await client.connect();

let falhas = 0;
try {
  for (const consulta of CONSULTAS) {
    await client.query('BEGIN');
    try {
      await client.query(`SET LOCAL ROLE ${PAPEL_APLICACAO}`);
      await client.query("SELECT set_config('app.tenant_id', $1, true)", [TENANT_DE_TESTE]);
      // Sem Seq Scan barato como opção, só sobra varredura completa quando nenhum índice serve.
      await client.query('SET LOCAL enable_seqscan = off');

      const { rows } = await client.query(`EXPLAIN (FORMAT JSON) ${consulta.sql}`);
      const achados = coletarVarreduras(rows[0]['QUERY PLAN'][0].Plan);

      if (achados.length > 0) {
        falhas += 1;
        console.error(`FALHA ${consulta.nome}: ${achados.join('; ')}`);
      } else {
        console.log(`ok    ${consulta.nome}`);
      }
    } finally {
      await client.query('ROLLBACK');
    }
  }
} finally {
  await client.end();
}

process.exit(falhas > 0 ? 1 : 0);
  1. Liste as funções usadas em políticas e confira provolatile em pg_proc: toda função de política deve ser STABLE ou IMMUTABLE.
  2. Envolva chamadas de função em (SELECT ...) nas expressões USING e WITH CHECK.
  3. Procure nas consultas das tabelas com RLS por LIKE, ILIKE, ~, lower, @> e @@ e decida, caso a caso, entre filtro explícito, função SECURITY DEFINER ou aceitar o filtro.
  4. Rode o script de planos no CI a cada migração que altere políticas, funções ou índices.
  5. Em homologação, ative FORCE ROW LEVEL SECURITY ou use um usuário que não seja dono para que os testes manuais também passem pela política.

FAQ

Perguntas frequentes

Com RLS, ainda preciso escrever WHERE tenant_id = $1 nas consultas?

Não é obrigatório para o isolamento, mas vale a pena. O filtro explícito é leakproof, pode ser condição de índice e dá ao planejador o valor real do tenant, o que melhora a estimativa nos tenants grandes. A política continua sendo a garantia: se uma consulta nova esquecer o filtro, ela ainda não vê dados de outro cliente.

Como usar RLS com PgBouncer em modo transação?

Grave o tenant com set_config('app.tenant_id', $1, true) logo depois do BEGIN, em toda transação. O terceiro argumento true limita o valor à transação, então ele some no COMMIT e não vaza para o próximo cliente que receber a mesma conexão. Nunca use SET de sessão nesse modo. Na função da política, use current_setting('app.tenant_id', true), que devolve NULL ou vazio quando o valor não foi definido, para que a falta de configuração resulte em nenhuma linha em vez de erro ou de dados de outro tenant.

Uma política WITH CHECK também deixa as escritas lentas?

Ela é avaliada sobre cada linha inserida ou atualizada, não sobre a tabela, então não muda o plano de busca das linhas. O custo aparece quando a expressão chama função cara ou consulta outra tabela por linha, como numa carga em lote de 500 mil registros. As mesmas regras valem: função STABLE e chamada dentro de (SELECT ...), para que o valor seja calculado uma vez por comando.

A política entra no plano com regras próprias

Row Level Security não é um WHERE automático. A política é uma qualificação de segurança, avaliada antes das condições da consulta que não são leakproof, e uma função VOLATILE nela transforma cada consulta numa varredura completa. Declarar as funções como STABLE, chamá-las como InitPlan, tratar à parte as buscas com ILIKE, lower ou jsonb e conferir os planos com o papel da aplicação no CI mantém o isolamento no banco sem trocar segurança por um pool esgotado.