Ir para o conteúdo
Aura Logo
aurabase

Acordos

Nomenclatura de esquemas, colunas, políticas RLS, auxiliares de autenticação, índices. Convenções estáveis ​​e documentadas para que sua equipe tenha uma maneira de nomear as coisas.

Referência6 min lidoNível inicianteRevisado em 15 de abr. de 2026

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

Um prefixo por domínio#

Cada projeto recebe quatro subesquemas prefixados project_{uuid}. Suas tabelas de negócios vão para o esquema principal; nunca crie objetos em esquemas de sistema.

EsquemaProprietárioUsar
project_{uuid}vocêTabelas, visualizações e funções de negócios. Este é o esquema em que seu SQL não qualificado (create table posts …) chega; ele é nomeado public apenas no SQL que você exporta com aura db backup download e schema/dump, que são portáteis.
project_{uuid}_authaura-authUsuários, sessões e MFA. Não modifique.
project_{uuid}_storageaura-storageBuckets, objetos e políticas de armazenamento
project_{uuid}_platformplataformaFunções, jobs, cron e segredos

cobra_case, plural, id uuid#

  • Tabelas plurais: posts, comments, invoices
  • Colunas em snake_case: created_at, user_id, last_seen_at
  • Chaves primárias id uuid primary key default gen_random_uuid() — não uuid_generate_v4(). Prefira uuid a bigint generated always as identity quando os ids forem expostos aos clientes (não é adivinhável, não há problema de precisão de 2 ^ 53 em JavaScript); uma coluna de identidade também funciona, e backups e restaurações cuidam disso.
  • Carimbos de data e hora timestamptz, nunca timestamp nu
  • FKs com sufixo _id: author_id, tenant_id
  • Booleanos prefixados is_ ou has_
  • Sem coluna project_id — o esquema já é o isolador
exemplesql
create table posts (
  id            uuid primary key default gen_random_uuid(),
  author_id     uuid not null references users(id) on delete cascade,
  title         text not null,
  is_published  boolean not null default false,
  created_at    timestamptz not null default now()
);
Atenção

Nunca adicione uma coluna project_id. O isolamento já vem do esquema e tal coluna adicionaria índices sem adicionar segurança.

Três funções injetadas em cada sessão#

O gateway abre conexões Postgres com request.jwt.claims especificado. Os três auxiliares abaixo leem essas afirmações e podem ser usados ​​em qualquer lugar de suas apólices.

  • auth.uid() — uuid do usuário atual, NULL se anon
  • auth.role() — texto · anon / autenticado / service_role
  • auth.tenant() — uuid do locatário atual (RBAC multilocatário)
  • auth.has_role(name) — booleano · verdadeiro se o usuário tiver esta função de aplicativo
  • auth.email() — texto · e-mail do usuário, lido em JWT
  • auth.claim(key) — jsonb · acesso bruto a uma declaração personalizada

Um nome previsível, uma operação, uma função#

Convenção: <table>_<scope>_<operation>. Exemplo: posts_own_read, orders_admin_delete. Sempre especifique to aura_authenticated ou to aura_anon.

namingsql
-- ✓ Bom: table_scope_op
create policy "posts_own_read"   on posts for select …
create policy "orders_admin_all" on orders for all …

-- ✗ Para evitar
create policy "allow_stuff"    -- muito vago
create policy "new_policy_42" -- não descritivo

Nomenclatura e quando indexar#

  • Nome: idx_<table>_<colonnes> ou uq_<table>_<colonnes> (único)
  • Sempre indexa: FKs, colunas filter/order_by frequentes, where de políticas RLS
  • Não indexa: Colunas booleanas com alta cardinalidade baixa (usar índice parcial), tabelas < 1000 linhas
  • pgvector: using hnsw para > 100k vetores, ivfflat caso contrário

Para ir mais longe#