Оглавление

• Зачем бизнесу RLS и чем она выгоднее отдельных баз
• Базовая модель данных: tenant_id в каждой таблице
• Включаем Row-Level Security и пишем политики
• Как передавать tenant в сессию приложения
• Связи между таблицами и уникальность “внутри арендатора”
• Производительность: индексы, планы, PgBouncer
• Фоновые задачи, миграции и админские обходы
• Миграция действующего продукта на RLS без простоя
• Безопасность и типичные ошибки
• Чек-лист внедрения

Зачем бизнесу RLS и чем она выгоднее отдельных баз

SaaS-продукт со множеством клиентов (арендаторов) рано или поздно сталкивается с выбором: держать раздельные базы на каждого — безопасно, но дорого, или всё сложить в одну базу — дёшево, но страшно. Row-Level Security (RLS) в PostgreSQL позволяет удержать баланс: хранить данные всех арендаторов в одной базе, но технически запретить доступ к «чужим» строкам на уровне СУБД.

Что получает бизнес:

• Экономия инфраструктуры: один кластер вместо десятков, меньше операций, проще бэкапы.
• Быстрое подключение новых клиентов: нет рутинного поднятия баз и миграций на каждый аккаунт.
• Снижение рисков утечек: даже если разработчик забудет фильтр в запросе, RLS не отдаст чужие строки.
• Контроль доступа в одном месте — в базе, а не «по договорённости» между командами и микросервисами.

Базовая модель данных: tenant_id в каждой таблице

Для RLS нужно явное поле, по которому мы делим строки. Обычно это tenant_id (UUID). Важно, чтобы оно присутствовало во всех таблицах с данными арендатора и участвовало в ключах и связях.

-- Для наглядности — аккаунты-арендаторы
CREATE TABLE tenants (
    id          uuid PRIMARY KEY,
    name        text NOT NULL,
    created_at  timestamptz NOT NULL DEFAULT now()
);

-- Базовая бизнес-таблица, например, проекты
CREATE TABLE projects (
    tenant_id   uuid NOT NULL,
    id          bigserial NOT NULL,
    name        text NOT NULL,
    created_at  timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (tenant_id, id),              -- составной ключ: проект уникален внутри арендатора
    FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);

-- Задачи внутри проекта
CREATE TABLE tasks (
    tenant_id   uuid NOT NULL,
    id          bigserial NOT NULL,
    project_id  bigint NOT NULL,
    title       text NOT NULL,
    status      text NOT NULL CHECK (status IN ('new','in_progress','done')),
    created_at  timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (tenant_id, id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id),
    -- Внешний ключ тоже включает tenant_id: это критично для целостности в мультиарендности
    FOREIGN KEY (tenant_id, project_id) REFERENCES projects(tenant_id, id)
);

-- Индексы под типичные выборки
CREATE INDEX idx_projects_tenant_created_at ON projects (tenant_id, created_at DESC);
CREATE INDEX idx_tasks_tenant_project_id ON tasks (tenant_id, project_id);

Ключевая идея: tenant_id входит во все первичные и внешние ключи. Это исключает «скрещивание» записей между арендаторами на уровне ссылочной целостности, а не только в приложении.

Включаем Row-Level Security и пишем политики

Сначала определим безопасную функцию, которая будет получать tenant_id из параметра сессии. Используем настраиваемый параметр app.tenant_id. Он живёт в пределах транзакции/сессии и надёжно читается в SQL.

-- Функция возвращает текущий tenant_id из параметра сессии
CREATE OR REPLACE FUNCTION app.current_tenant()
RETURNS uuid
LANGUAGE sql
STABLE
AS $$
    SELECT current_setting('app.tenant_id', true)::uuid
$$;

Теперь включим RLS и создадим политики для чтения/изменения. Политики используют сравнение tenant_id со значением из функции.

-- Включаем RLS на таблицах
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
ALTER TABLE tasks    ENABLE ROW LEVEL SECURITY;

-- Безопасность по умолчанию: запрещать всё, что не разрешено политиками
ALTER TABLE projects FORCE ROW LEVEL SECURITY;
ALTER TABLE tasks    FORCE ROW LEVEL SECURITY;

-- Политики чтения
CREATE POLICY projects_select ON projects
    FOR SELECT
    USING (tenant_id = app.current_tenant());

CREATE POLICY tasks_select ON tasks
    FOR SELECT
    USING (tenant_id = app.current_tenant());

-- Политики вставки/обновления/удаления
CREATE POLICY projects_write ON projects
    FOR ALL
    TO PUBLIC
    USING (tenant_id = app.current_tenant())
    WITH CHECK (tenant_id = app.current_tenant());

CREATE POLICY tasks_write ON tasks
    FOR ALL
    TO PUBLIC
    USING (tenant_id = app.current_tenant())
    WITH CHECK (tenant_id = app.current_tenant());

USING отвечает за строки, которые видит и может редактировать запрос. WITH CHECK — за строки, которые можно создать или во что можно обновить. В обеих проверках мы требуем совпадение tenant_id.

Как передавать tenant в сессию приложения

Приложение должно устанавливать параметр app.tenant_id на каждую транзакцию. Делайте это через SET LOCAL — тогда значение живёт только до конца транзакции и не протечёт на следующий запрос в пуле соединений.

Пример на Go с pgxpool: в каждом запросе мы открываем транзакцию, выставляем tenant и выполняем работу.

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "os"

    "github.com/jackc/pgx/v5/pgxpool"
)

func main() {
    ctx := context.Background()
    dsn := os.Getenv("DATABASE_URL")
    pool, err := pgxpool.New(ctx, dsn)
    if err != nil { log.Fatal(err) }
    defer pool.Close()

    http.HandleFunc("/projects", func(w http.ResponseWriter, r *http.Request) {
        tenant := r.Header.Get("X-Tenant-ID")
        if tenant == "" { http.Error(w, "missing tenant", http.StatusBadRequest); return }

        tx, err := pool.BeginTx(ctx, pgxpool.TxOptions{})
        if err != nil { http.Error(w, err.Error(), 500); return }
        defer tx.Rollback(ctx)

        if _, err := tx.Exec(ctx, "SET LOCAL app.tenant_id = $1", tenant); err != nil {
            http.Error(w, err.Error(), 500); return
        }

        rows, err := tx.Query(ctx, "SELECT id, name FROM projects ORDER BY created_at DESC LIMIT 10")
        if err != nil { http.Error(w, err.Error(), 500); return }
        defer rows.Close()

        var out string
        for rows.Next() {
            var id int64
            var name string
            if err := rows.Scan(&id, &name); err != nil { http.Error(w, err.Error(), 500); return }
            out += fmt.Sprintf("%d\t%s\n", id, name)
        }

        if err := tx.Commit(ctx); err != nil { http.Error(w, err.Error(), 500); return }
        w.Write([]byte(out))
    })

    log.Println("listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Важно: не используйте SET без LOCAL в пулах соединений (например, PgBouncer в режиме session). Используйте транзакции и SET LOCAL — так безопаснее.

Если у вас Node.js (node-postgres):

const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

async function withTenant(tenantId, fn) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    await client.query('SET LOCAL app.tenant_id = $1', [tenantId]);
    const res = await fn(client);
    await client.query('COMMIT');
    return res;
  } catch (e) {
    await client.query('ROLLBACK');
    throw e;
  } finally {
    client.release();
  }
}

// Пример использования
withTenant('a6a8f3e2-5f7b-4c7d-9f0b-2a1e9e1f1f22', async (client) => {
  const { rows } = await client.query('SELECT count(*) FROM tasks');
  console.log(rows[0]);
});

Связи между таблицами и уникальность “внутри арендатора”

В мультиарендной схеме важно:

• Внешние ключи включают tenant_id. Тогда нельзя связать строку одного арендатора со строкой другого.
• Уникальные ограничения тоже ограничиваются арендатором. Делается составным индексом.

-- Например, хотим уникальные названия проектов внутри арендатора
CREATE UNIQUE INDEX uq_projects_tenant_name ON projects (tenant_id, lower(name));

-- И уникальный внешний идентификатор задачи внутри арендатора
ALTER TABLE tasks ADD COLUMN external_id text;
CREATE UNIQUE INDEX uq_tasks_tenant_external_id ON tasks (tenant_id, lower(external_id));

Если нужен глобально уникальный идентификатор (например, публичный токен), храните его отдельно и не используйте его в связях между таблицами с tenant_id.

Производительность: индексы, планы, PgBouncer

RLS сама по себе почти не «стоит» в плане производительности: оптимизатор учитывает условие RLS как дополнительный фильтр. Узкие места обычно в другом:

• Не забывайте составные индексы, где tenant_id — первый столбец. Тогда фильтрация по арендатору моментально отсечёт лишнее.
• Для сортировок и пагинации добавляйте поле сортировки вторым столбцом индекса: (tenant_id, created_at DESC), (tenant_id, id DESC).
• PgBouncer в режиме transaction подходит хорошо. Главное — не делать SET вне транзакции. Используйте SET LOCAL.
• EXPLAIN ANALYZE покажет, что условие tenant_id применяется так же, как обычный WHERE; на планах это просто дополнительный фильтр.

Пример быстрой выборки последних задач по проекту арендатора:

EXPLAIN ANALYZE
SELECT id, title
FROM tasks
WHERE project_id = 123  -- RLS автоматически добавит tenant_id = app.current_tenant()
ORDER BY id DESC
LIMIT 50;

Если индекс (tenant_id, project_id, id DESC) существует, запрос будет идти по нему без лишних чтений.

Фоновые задачи, миграции и админские обходы

• Фоновые задачи: сохраняйте tenant_id в нагрузке задачи. Рабочий, обрабатывая задачу, начинает транзакцию, делает SET LOCAL и работает в контексте арендатора.
• Админские обходы (агрегации, отчёты по всем арендаторам): используйте роль с правом BYPASSRLS или временно DISABLE RLS внутри строго контролируемой процедуры. Лучше — отдельный read-only пользователь со скриптом и аудиторией.

-- Роль приложения не должна уметь обходить RLS
ALTER ROLE app_user NOBYPASSRLS;

-- Роль администратора может
ALTER ROLE admin_user BYPASSRLS;

Если делаете админскую функцию, не злоупотребляйте SECURITY DEFINER. Если это необходимо, явно вырубайте/включайте RLS внутри функции и убедитесь, что параметры валидируются.

CREATE OR REPLACE FUNCTION admin.recount_all()
RETURNS void
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
BEGIN
  PERFORM set_config('role', 'admin_user', true);
  -- Админские действия, где RLS не мешает
  -- ...
END;
$$;

Миграция действующего продукта на RLS без простоя

Типовой путь из «общей базы без RLS» в «RLS с tenant_id» выглядит так:

1. Добавить колонку tenant_id и заполнить для новых записей

• Добавьте колонку tenant_id NULLABLE.
• Вставки новых строк делайте только через приложение, которое уже знает tenant_id клиента.
• Временно добавьте триггер, проставляющий tenant_id из текущей сессии (или из связанной записи), чтобы не потерять консистентность.

ALTER TABLE projects ADD COLUMN tenant_id uuid;
ALTER TABLE tasks    ADD COLUMN tenant_id uuid;

-- Временный триггер на вставку: для демонстрации — возьмём из сессии
CREATE OR REPLACE FUNCTION app.set_tenant_on_insert()
RETURNS trigger
LANGUAGE plpgsql
AS $$
BEGIN
  IF NEW.tenant_id IS NULL THEN
    NEW.tenant_id := current_setting('app.tenant_id', true)::uuid;
  END IF;
  RETURN NEW;
END;$$;

CREATE TRIGGER trg_projects_tenant BEFORE INSERT ON projects
FOR EACH ROW EXECUTE FUNCTION app.set_tenant_on_insert();

CREATE TRIGGER trg_tasks_tenant BEFORE INSERT ON tasks
FOR EACH ROW EXECUTE FUNCTION app.set_tenant_on_insert();

2. Бекфил данных батчами

• Обновляйте таблицы небольшими порциями по первичному ключу, чтобы не держать долгие блокировки и не забивать WAL.

-- Пример порционного обновления: берём по диапазону id
-- Повторяйте, меняя границы, пока tenant_id не заполнен у всех
UPDATE projects p
SET tenant_id = t.id
FROM tenants t
WHERE p.tenant_id IS NULL
  AND p.owner_tenant_ref = t.legacy_owner_ref  -- используйте ваш способ связки
  AND p.id BETWEEN 100001 AND 120000;

После бекфила сделайте NOT NULL, добавьте составные ключи и индексы CONCURRENTLY.

ALTER TABLE projects ALTER COLUMN tenant_id SET NOT NULL;
ALTER TABLE tasks    ALTER COLUMN tenant_id SET NOT NULL;

-- Перестраиваем ключи и связи без долгих блокировок
ALTER TABLE projects DROP CONSTRAINT projects_pkey;
ALTER TABLE projects ADD PRIMARY KEY USING INDEX 
    (SELECT indexname FROM pg_indexes WHERE tablename='projects' LIMIT 0); -- см. примечание ниже

Примечание: на бою готовьте создание новых индексов заранее через CREATE UNIQUE INDEX CONCURRENTLY, затем переключайте ключи на них в короткую блокировку. Конкретные команды зависят от вашей схемы, поэтому обязательно отрепетируйте на копии базы.

3. Включить RLS в режиме «только наблюдение», затем «жёстко»

• Сначала включите RLS без FORCE и оставьте журнальное логирование. Прогоните тесты и основную нагрузку.
• Когда уверены — добавьте FORCE ROW LEVEL SECURITY и запретите BYPASSRLS для приложенческой роли.

Безопасность и типичные ошибки

• Забытый SET LOCAL: самое опасное место. Помогает middleware, который всегда открывает транзакцию и устанавливает tenant_id до любых запросов.
• Пул соединений: не используйте session pooling с SET (без LOCAL). Только транзакции и SET LOCAL.
• SECURITY DEFINER: функции под повышенными правами легко обходят RLS. Либо не используйте, либо добавьте явные проверки tenant_id внутри функций.
• Политики только на SELECT: не забывайте WITH CHECK для INSERT/UPDATE — иначе можно создать «чужую» строку.
• Суперпользователи и роли с BYPASSRLS видят всё. Приложенческой роли это запрещено.
• Материализованные представления: они обходят RLS при обновлении под ролью запуска. Обновляйте их с нужным tenant или под админом осознанно.
• Представления и безопасность оптимизатора: если пишете общие VIEW для пользователей, добавляйте SECURITY BARRIER при необходимости, чтобы оптимизатор не переупорядочил выражения с потенциально «протекающими» функциями.

CREATE VIEW app.safe_projects WITH (security_barrier=true) AS
SELECT id, name, created_at FROM projects WHERE tenant_id = app.current_tenant();

Чек-лист внедрения

• Во всех «арендных» таблицах есть колонка tenant_id, она в PK и FK.
• Для типовых выборок созданы индексы, начинающиеся с tenant_id.
• Написана функция app.current_tenant() и политики SELECT/INSERT/UPDATE/DELETE.
• Приложение всегда открывает транзакцию и делает SET LOCAL app.tenant_id.
• Роль приложения — NOBYPASSRLS, права ограничены.
• Фоновые задачи передают tenant_id и работают в транзакции с SET LOCAL.
• Миграции и бекфил протестированы на копии боевой БД.
• Мониторинг ошибок и таймаутов включён, есть алерты по отказам политик.

---

Итог: RLS — это простая, но мощная защита на уровне базы. Она дисциплинирует схему, снижает риск утечек из-за человеческого фактора и позволяет экономить на инфраструктуре, не жертвуя скоростью разработки. При грамотной схеме ключей и индексах RLS работает быстро и прозрачно для кода — вы получаете мультиарендный продукт без отдельных баз и лишних серверов.