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.
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.
| Esquema | Proprietário | Usar |
|---|---|---|
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}_auth | aura-auth | Usuários, sessões e MFA. Não modifique. |
project_{uuid}_storage | aura-storage | Buckets, objetos e políticas de armazenamento |
project_{uuid}_platform | plataforma | Funçõ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ãouuid_generate_v4(). Prefirauuidabigint generated always as identityquando 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, nuncatimestampnu - FKs com sufixo
_id:author_id,tenant_id - Booleanos prefixados
is_ouhas_ - Sem coluna
project_id— o esquema já é o isolador
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()
);
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 anonauth.role()— texto · anon / autenticado / service_roleauth.tenant()— uuid do locatário atual (RBAC multilocatário)auth.has_role(name)— booleano · verdadeiro se o usuário tiver esta função de aplicativoauth.email()— texto · e-mail do usuário, lido em JWTauth.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.
-- ✓ 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>ouuq_<table>_<colonnes>(único) - Sempre indexa: FKs, colunas
filter/order_byfrequentes,wherede políticas RLS - Não indexa: Colunas booleanas com alta cardinalidade baixa (usar índice parcial), tabelas < 1000 linhas
- pgvector:
using hnswpara > 100k vetores,ivfflatcaso contrário