Conventions
Naming des schémas, colonnes, policies RLS, helpers auth, index. Des conventions stables et documentées pour que votre équipe ait une seule façon de nommer les choses.
Un préfixe par domaine#
Chaque projet reçoit quatre sous-schémas préfixés project_{uuid}. Vos tables métier vont dans le schéma principal ; ne créez jamais d'objets dans les schémas système.
| Schéma | Propriétaire | Usage |
|---|---|---|
project_{uuid} | vous | Tables, vues et fonctions métier. C'est le schéma où atterrit votre SQL non qualifié (create table posts …) ; il ne s'appelle public que dans le SQL exporté par aura db backup download et schema/dump, qui sont portables. |
project_{uuid}_auth | aura-auth | Utilisateurs, sessions et MFA. Ne pas modifier. |
project_{uuid}_storage | aura-storage | Buckets, objets et policies de storage |
project_{uuid}_platform | plateforme | Functions, jobs, cron et secrets |
snake_case, pluriel, id uuid#
- Tables au pluriel :
posts,comments,invoices - Colonnes en
snake_case:created_at,user_id,last_seen_at - Clés primaires
id uuid primary key default gen_random_uuid()— pas deuuid_generate_v4(). Préférezuuidàbigint generated always as identityquand les identifiants sont exposés aux clients (non devinables, pas de problème de précision 2^53 en JavaScript) ; une colonne identity fonctionne aussi, et les sauvegardes et restaurations la gèrent. - Timestamps
timestamptz, jamaistimestampnu - FKs suffixées
_id:author_id,tenant_id - Booléens préfixés
is_ouhas_ - Pas de colonne
project_id— le schéma est déjà l'isolant
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()
);
Ne jamais ajouter de colonne project_id. L'isolation est déjà garantie par le schéma. Une colonne tenant multiplierait les index et fragiliserait la sécurité.
Trois fonctions injectées dans chaque session#
Le gateway ouvre les connexions Postgres avec request.jwt.claims renseigné. Les trois helpers ci-dessous lisent ces claims et sont utilisables partout dans vos policies.
auth.uid()— uuid de l'utilisateur courant, NULL si anonauth.role()— text · anon / authenticated / service_roleauth.tenant()— uuid du tenant courant (RBAC multi-tenant)auth.has_role(name)— boolean · true si le user a ce rôle applicatifauth.email()— text · email du user, lu depuis le JWTauth.claim(key)— jsonb · accès brut à un claim custom
Un nom prédictible, une opération, un rôle#
Convention : <table>_<scope>_<operation>. Exemple : posts_own_read, orders_admin_delete. Toujours préciser to aura_authenticated ou to aura_anon.
-- ✓ Bon : table_scope_op
create policy "posts_own_read" on posts for select …
create policy "orders_admin_all" on orders for all …
-- ✗ À éviter
create policy "allow_stuff" -- trop vague
create policy "new_policy_42" -- pas descriptif
Naming et quand indexer#
- Nom :
idx_<table>_<colonnes>ouuq_<table>_<colonnes>(unique) - Toujours indexer : les FKs, les colonnes de
filter/order_byfréquents, leswheredes policies RLS - Ne pas indexer : colonnes booléennes à forte cardinalité low (utiliser partial index), tables < 1000 lignes
- pgvector :
using hnswpour > 100k vecteurs,ivfflatsinon