# ADR-0002. PostgreSQL, роли БД и изоляция тенантов через RLS

- Статус: принято
- Дата: 2026-09-30

## Контекст

Платформа обслуживает тысячи мерчантов (тенантов) в одной инсталляции. Схема или база на тенанта
плохо масштабируется дальше нескольких сотен арендаторов. Межтенантная утечка — событие,
после которого SaaS-бизнес может не восстановиться, поэтому одной фильтрации в приложении мало.

## Решение

- Единственное OLTP-хранилище — PostgreSQL 17. Модель пула: общая схема, колонка `tenant_id`
  во всех таблицах тенанта.
- Изоляция в два слоя:
  1. Приложение: глобальный scope и автоматическое заполнение `tenant_id` (трейт `BelongsToTenant`).
  2. База: Row-Level Security с `FORCE ROW LEVEL SECURITY` на каждой таблице тенанта.
- Роли БД:

  | Роль | Назначение | RLS |
  |---|---|---|
  | `owner` | владелец схемы, выполняет миграции | член `loyal_rls_system`, видит всё |
  | `app` | HTTP-запросы и задачи тенанта | член `loyal_rls_tenant`, видит только текущий тенант |
  | `system` | межтенантные системные процессы (outbox relay, планировщики, сверка) | член `loyal_rls_system`, видит всё |

  Политики создаются для групповых ролей `loyal_rls_tenant` и `loyal_rls_system` (`CREATE POLICY … TO`),
  поэтому предикат роли приложения остаётся простым (`tenant_id = rls_current_tenant()`)
  и использует индексы. Логины окружения (`loyal_app` и т. п.) получают членство в групповых ролях.
- Контекст тенанта передаётся в БД сессионной настройкой `app.tenant_id`
  (`set_config('app.tenant_id', …, false)`). Она выставляется в начале каждого HTTP-запроса и задачи
  очереди и сбрасывается в конце; пустое значение означает «нет тенанта» — ноль строк.
- Пулер соединений в режиме transaction pooling не используется: сессионные настройки в нём
  перетекают между клиентами. Octane держит постоянные соединения на воркер; при необходимости
  используется пулер в режиме session.
- Все уникальные индексы таблиц тенанта начинаются с `tenant_id` (проверки уникальности идут в обход RLS).
  Внешние ключи внутри тенанта — составные `(tenant_id, id)`, чтобы строка не могла сослаться на чужой тенант.
- Приложение подключается ролью `app`; соединение `pgsql_system` используют только явно разрешённые
  классы (проверяется архитектурным тестом).

## Последствия

- Ошибка в коде приложения (забытый scope, `withoutGlobalScopes`) не приводит к утечке: БД вернёт ноль строк.
- Каждая миграция таблицы тенанта обязана включить RLS хелпером; архитектурный тест проверяет, что у всех
  таблиц с `tenant_id` включён RLS.
- Отчёты «по всем тенантам» строятся только системными процессами.
- В управляемых облаках нужны права на создание ролей; при их отсутствии группы создаёт администратор облака.

## Дополнение (этап 6a)

- Системное соединение `pgsql_system` используют только проверенные файлы: архитектурный тест
  `tests/Architecture/SystemConnectionTest.php` перечисляет их с назначением, новый файл не проходит, пока его не
  добавят туда сознательно.
- Узкие функции SECURITY DEFINER для поиска до выбора тенанта: `api_key_candidates`, `merchant_key_candidates`,
  `staff_tenant_memberships` (ADR-0013), `device_pairing_candidates` и `terminal_device_candidates` (ADR-0016),
  `member_session_candidates` (ADR-0018). Каждая создаётся после `drop function if exists`, принадлежит владельцу
  схемы, `revoke all … from public`, право выполнения — только у групп runtime-ролей.
- Остаточный риск: по умолчанию runtime-группы пишут во все таблицы, включая глобальные таблицы сотрудников
  (ADR-0013). Отдельная роль БД для трафика публичных API без прав на них — пункт 11.4.

## Дополнение (этап 11.4-1)

- Риск выше закрыт ADR-0029: таблицы и функции, нужные только сотрудникам, принадлежат групповой роли
  `loyal_rls_staff`, которую получает логин кабинетов и воркеров. Логин публичного трафика — только член
  `loyal_rls_tenant`, без логинов системной роли и владельца.
