Acuerdos
Denominación de esquemas, columnas, políticas RLS, ayudantes de autenticación, índices. Convenciones estables y documentadas para que su equipo tenga una forma de nombrar las cosas.
Un prefijo por dominio#
Cada proyecto recibe cuatro subesquemas con el prefijo project_{uuid}. Sus tablas de negocios entran en el esquema principal; Nunca cree objetos en esquemas del sistema.
| esquema | propietario | uso |
|---|---|---|
project_{uuid} | tu | Tablas, vistas y funciones empresariales. Este es el esquema en el que aterriza su SQL no calificado (create table posts …); se llama public solo en el SQL que exportas con aura db backup download y schema/dump, que son portátiles. |
project_{uuid}_auth | aura-auth | Usuarios, sesiones y MFA. No modificar. |
project_{uuid}_storage | aura-storage | Depósitos, objetos y políticas de almacenamiento. |
project_{uuid}_platform | plataforma | Funciones, trabajos, cron y secretos |
caso_serpiente, plural, identificación uuid#
- Plural tablas:
posts,comments,invoices - Columnas en
snake_case:created_at,user_id,last_seen_at - Claves primarias
id uuid primary key default gen_random_uuid()— nouuid_generate_v4(). Prefierauuidsobrebigint generated always as identitycuando los identificadores estén expuestos a los clientes (no se puede adivinar, no hay problema de precisión 2^53 en JavaScript); una columna de identidad también funciona, y las copias de seguridad y restauraciones se encargan de ella. - Marcas de tiempo
timestamptz, nuncatimestampdesnudo - FK con el sufijo
_id:author_id,tenant_id - Booleanos con el prefijo
is_ohas_ - Sin columna
project_id— el esquema ya es el aislador
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 agregue una columna project_id. El aislamiento ya proviene del esquema y dicha columna agregaría índices sin agregar seguridad.
Tres funciones inyectadas en cada sesión.#
La puerta de enlace abre Postgres conexiones con request.jwt.claims especificado. Los tres ayudantes a continuación leen estos reclamos y pueden usarse en cualquier parte de sus pólizas.
auth.uid()— uuid del usuario actual, NULL si es anónimoauth.role()— texto · anon / autenticado / service_roleauth.tenant()— uuid del inquilino actual (RBAC multiinquilino)auth.has_role(name)— booleano · verdadero si el usuario tiene este rol de aplicaciónauth.email()— texto · correo electrónico del usuario, leído desde JWTauth.claim(key)— jsonb · acceso sin formato a un reclamo personalizado
Un nombre predecible, una operación, un rol#
Convención: <table>_<scope>_<operation>. Ejemplo: posts_own_read, orders_admin_delete. Especifique siempre to aura_authenticated o to aura_anon.
-- ✓ Bueno: 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" -- demasiado vago
create policy "new_policy_42" -- no descriptivo
Denominación y cuándo indexar#
- Nombre:
idx_<table>_<colonnes>ouq_<table>_<colonnes>(único) - Siempre indexe: FK, columnas frecuentes
filter/order_by,wherede políticas RLS - No indexar: columnas booleanas con cardinalidad alta baja (use índice parcial), tablas < 1000 filas
- pgvector:
using hnswpara> 100k vectores,ivfflaten caso contrario