Соглашения
Именование схем, столбцов, политик RLS, помощников аутентификации, индексов. Стабильные, документированные соглашения, позволяющие вашей команде иметь один способ называть вещи.
Один префикс на домен#
Каждый проект получает четыре подсхемы с префиксом project_{uuid}. Ваши бизнес-таблицы входят в основную схему; никогда не создавайте объекты в системных схемах.
| Схема | Владелец | Использовать |
|---|---|---|
project_{uuid} | ты | Таблицы, представления и бизнес-функции. Это схема, в которой находится ваш неквалифицированный SQL (create table posts …); он называется public только в SQL-коде, который вы экспортируете с помощью aura db backup download и schema/dump, которые являются переносимыми. |
project_{uuid}_auth | aura-auth | Пользователи, сеансы и MFA. Не изменяйте. |
project_{uuid}_storage | aura-storage | Корзины, объекты и политики хранения |
project_{uuid}_platform | платформа | Функции, задания, cron и секреты |
Snake_case, множественное число, идентификатор uuid#
- Таблицы во множественном числе:
posts,comments,invoices - Столбцы в
snake_case:created_at,user_id,last_seen_at - Первичные ключи
id uuid primary key default gen_random_uuid()— нетuuid_generate_v4(). Предпочитайтеuuidвместоbigint generated always as identity, когда идентификаторы доступны клиентам (невозможно угадать, в JavaScript нет проблем с точностью 2 ^ 53); столбец идентификаторов тоже работает, и его можно выполнить с помощью резервного копирования и восстановления. - Временные метки
timestamptz, никогдаtimestampголый - FK с суффиксом
_id:author_id,tenant_id - Логические значения с префиксом
is_илиhas_ - Нет столбца
project_id— на схеме уже есть изолятор
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()
);
Никогда не добавляйте столбец project_id. Изоляция уже заложена в схеме, и такой столбец будет добавлять индексы без повышения безопасности.
Три функции, внедряемые в каждый сеанс#
Шлюз открывает соединения Postgres с указанным request.jwt.claims. Три приведенных ниже помощника читают эти претензии и могут быть использованы в любом месте вашего полиса.
auth.uid()— uuid текущего пользователя, NULL, если анонимноauth.role()— текст · анон / аутентифицированный / роль_службыauth.tenant()— uuid текущего клиента (многопользовательский RBAC)auth.has_role(name)— логическое значение · true, если у пользователя есть эта роль приложенияauth.email()— текст · адрес электронной почты пользователя, прочитанный из JWTauth.claim(key)— jsonb · необработанный доступ к пользовательскому утверждению
Предсказуемое имя, операция, роль#
Соглашение: <table>_<scope>_<operation>. Пример: posts_own_read, orders_admin_delete. Всегда указывайте to aura_authenticated или to aura_anon.
-- ✓ Хорошо: table_scope_op
create policy "posts_own_read" on posts for select …
create policy "orders_admin_all" on orders for all …
-- ✗ Чтобы избежать
create policy "allow_stuff" -- слишком расплывчато
create policy "new_policy_42" -- не описательный
Именование и когда индексировать#
- Имя:
idx_<table>_<colonnes>илиuq_<table>_<colonnes>(уникальное) - Всегда индексировать: FK, частые столбцы
filter/order_by,whereполитик RLS - Не индексировать: логические столбцы с высокой кардинальностью и низким значением (используйте частичный индекс), таблицы < 1000 строк
- pgvector:
using hnswдля > 100 тыс. векторов,ivfflatв противном случае