Ir para o conteúdo
Aura Logo
aurabase

Segurança em nível de linha na produção

Três padrões RLS que cobrem 95% dos casos de uso: propriedade, multilocatário, organização hierárquica. Com pg_prove e testes de depuração.

Guia prático12 min lidoNível avançadoRevisado em 15 de abr. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

O que é RLS#

A segurança em nível de linha é um recurso nativo PostgreSQL que filtra linhas retornadas (ou aceitas) dinamicamente, avaliando uma expressão SQL que pode depender da função atual e das declarações JWT. Aurabase injeta declarações do usuário via request.jwt.claims e expõe auxiliares auth.uid(), auth.role(), auth.tenant(), auth.has_role().

Três coisas que você deve saber antes de escrever uma apólice
  • Nomes de funções. As funções canônicas do banco de dados são aura_anon, aura_authenticated e aura_service_role. Em clusters gerenciados, os aliases de grupo anon, authenticated e service_role também são mapeados para eles (observe que BYPASSRLS permanece estritamente apenas em aura_service_role).
  • RLS está ativado por padrão para tabelas criadas por meio de Aurabase. Qualquer tabela criada com /raw, uma migração, Studio ou API de tabela recebe automaticamente ENABLE e FORCE ROW LEVEL SECURITY (a menos que DISABLE ROW LEVEL SECURITY seja executado explicitamente no mesmo lote DDL): consultas públicas/anônimas retornam [] até que você adicione uma política. Tabelas criadas em uma conexão direta PostgreSQL (psql, Prisma, Drizzle) nunca passam por esse gancho, então elas obtêm não RLS e, em vez disso, sem acesso para as chaves públicas: aura_anon e aura_authenticated não têm privilégios sobre elas até você conceder. Para expor essa tabela ao SDK, habilite RLS primeiro e, em seguida, conceda e adicione uma política: ALTER TABLE posts ENABLE ROW LEVEL SECURITY; GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO aura_authenticated; CREATE POLICY .... Nunca conceda para aura_anon ou aura_authenticated em uma tabela cujo RLS esteja desativado: todo detentor da chave pública, ou todo usuário inscrito, leria (e, com permissões de gravação, modificaria) todas as suas linhas.
  • A chave pública não possui usuário. auth.uid() é NULL para a chave pública e para uma chave service_role; ele retorna um ID apenas para um usuário conectado. Use to aura_authenticated para restringir uma política a usuários conectados.

Propriedade – cada usuário tem suas próprias linhas#

Casos de uso: perfis, notas, postagens onde cada linha pertence a um usuário único via user_id ou author_id.

migrations/posts_rls.sqlsql
alter table posts enable row level security;

create policy "posts_own_read" on posts
  for select to aura_authenticated
  using (auth.uid() = author_id);

create policy "posts_own_write" on posts
  for all to aura_authenticated
  using (auth.uid() = author_id)
  with check (auth.uid() = author_id);
Dica

Combine for all com using + with check para cobrir SELECT/UPDATE/DELETE em uma política. O INSERT usa apenas with check.

Multilocatário — escopo por organização#

Caso de uso: SaaS B2B onde cada usuário pertence a uma organização e vê todos os dados de sua organização. O JWT carrega app_metadata.tenant, que o auxiliar auth.tenant() retorna (NULL quando ausente ou não um UUID, então a política nega).

migrations/tenant_rls.sqlsql
create policy "orders_tenant_scope" on orders
  for all to aura_authenticated
  using (tenant_id = auth.tenant())
  with check (tenant_id = auth.tenant());

-- Índice indispensável para desempenho
create index idx_orders_tenant on orders(tenant_id);

Organização hierárquica – permissões por função#

Caso de uso: SaaS em que as funções em uma organização (administrador, membro, visualizador) têm permissões diferentes. Combinamos auth.tenant() com auth.has_role().

migrations/org_rls.sqlsql
create policy "invoices_read" on invoices
  for select to aura_authenticated
  using (
    tenant_id = auth.tenant()
    and (auth.has_role('admin') or auth.has_role('billing'))
  );

create policy "invoices_write" on invoices
  for all to aura_authenticated
  using (tenant_id = auth.tenant() and auth.has_role('admin'))
  with check (tenant_id = auth.tenant());

pg_prove — uma afirmação por política#

Teste suas políticas — como um usuário real, em CI

As políticas são códigos, então teste-as. aura db raw ... --as authenticated --user <uuid> executa o SQL dentro de PostgreSQL com auth.uid() e auth.role() definidos para esse usuário (adicione --dry-run para reverter as gravações), então a resposta é exatamente o que seu aplicativo verá:

tests/rls.shbash
set -euo pipefail
ALICE=$(aura auth users create --email alice@example.com --password 'Passw0rd!long1' --json | jq -r .id)
BOB=$(aura auth users create --email bob@example.com --password 'Passw0rd!long1' --json | jq -r .id)

aura db raw "insert into posts(author_id, title) values ('$ALICE', 'hello')"
# Bob não deve ver a postagem de Alice
test "$(aura db raw "select count(*) as n from posts" --as authenticated --user "$BOB" --json | jq -r '.[0].n')" = "0"
# Alice deve ver isso
test "$(aura db raw "select count(*) as n from posts" --as authenticated --user "$ALICE" --json | jq -r '.[0].n')" = "1"
# Um visitante não vê nada
test "$(aura db raw "select count(*) as n from posts" --as anon --json | jq -r '.[0].n')" = "0"

Execute-o no CI após aura db push. O simulador RLS do Studio (Banco de dados › uma tabela › simulador RLS) executa a mesma verificação dentro de uma transação PostgreSQL revertida e diz isso ao lado do resultado; pgTAP e pg_prove precisam de uma conexão direta PostgreSQL, que nem toda implantação publica.

Quando a política não faz o que você quer#

  • Resultado vazio? Uma leitura anônima ou conectada de uma tabela com RLS e nenhuma política SELECT correspondente retorna [] com um meta.hint que nomeia a função e a política a serem adicionadas. aura db raw "select * from posts" --as anon mostra o que um visitante vê.
  • RLS desativado? aura db table list marca tabelas com [RLS] e o Advisor avisa sobre tabelas com RLS desabilitadas e tabelas com RLS mas sem política. Desativar RLS (aura db table rls posts off) torna a tabela legível por qualquer pessoa que possua a chave pública.
  • Visualizações. Uma visualização lê com os privilégios do leitor (security_invoker = true é aplicado a cada visualização que você cria), portanto, as políticas de suas tabelas se aplicam.
  • Políticas que somam: múltiplas políticas na mesma tabela + operação + função combinadas em OR. Restringir com AND em uma única política, se necessário
  • Permissões GRANT ausentes: mesmo com uma política, a função deve ter grant select on posts to aura_authenticated
  • Declarações não injetadas: from Postgres, select current_setting('request.jwt.claims', true) — null significa que você está no banco de dados direto, não através do gateway

Para ir mais longe#