Aller au contenu
Logo Aurabase
aurabase

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.

Référence6 min de lectureNiveau débutantRévisé le 15 avr. 2026

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émaPropriétaireUsage
project_{uuid}vousTables, 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}_authaura-authUtilisateurs, sessions et MFA. Ne pas modifier.
project_{uuid}_storageaura-storageBuckets, objets et policies de storage
project_{uuid}_platformplateformeFunctions, 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 de uuid_generate_v4(). Préférez uuid à bigint generated always as identity quand 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, jamais timestamp nu
  • FKs suffixées _id : author_id, tenant_id
  • Booléens préfixés is_ ou has_
  • Pas de colonne project_id — le schéma est déjà l'isolant
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()
);
Attention

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 anon
  • auth.role() — text · anon / authenticated / service_role
  • auth.tenant() — uuid du tenant courant (RBAC multi-tenant)
  • auth.has_role(name) — boolean · true si le user a ce rôle applicatif
  • auth.email() — text · email du user, lu depuis le JWT
  • auth.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.

namingsql
-- ✓ 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> ou uq_<table>_<colonnes> (unique)
  • Toujours indexer : les FKs, les colonnes de filter/order_by fréquents, les where des policies RLS
  • Ne pas indexer : colonnes booléennes à forte cardinalité low (utiliser partial index), tables < 1000 lignes
  • pgvector : using hnsw pour > 100k vecteurs, ivfflat sinon

Pour aller plus loin#