Оглавление

• Зачем бизнесу мультиарендность и где тут деньги
• Модели изоляции: отдельная БД, отдельная схема, общий кластер с RLS
• Базовая реализация на PostgreSQL: колонка tenant_id, политики RLS, триггер и роли
  • 1) Схема, служебные функции и роли
  • 2) Таблицы с колонкой tenant_id и индексами
  • 3) Включаем RLS и прописываем политики
  • 4) Как приложение устанавливает текущего арендатора
• Производительность: индексы, планировщик, партиционирование и пул соединений
• Миграции и операционные задачи
  • Онбординг нового арендатора
  • Бэкап и восстановление данных одного арендатора
  • Удаление арендатора (право быть забытым)
  • Перенос «шумного соседа» в отдельную БД/шард
• Безопасность и аудит
• Интеграции и кэш
• Типичные ошибки и грабли
• Минимальный пример сервиса на Node.js
• Бизнес-метрики успеха и экономия
• Чек-лист внедрения

Зачем бизнесу мультиарендность и где тут деньги

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

• Ниже расходы: один кластер, общее железо и лицензии.
• Быстрее доставка фич: одно приложение и единый пайплайн.
• Проще комплаенс: доказуемая изоляция данных между клиентами.
• Предсказуемая эксплуатация: стандартные процедуры масштаба и аварий.

Ключ — убрать риск «перемешивания» данных между клиентами. Эту гарантию в PostgreSQL обеспечивает Row Level Security (RLS) — политики на уровне строк.

Модели изоляции: отдельная БД, отдельная схема, общий кластер с RLS

• Отдельная БД на клиента
  • Плюсы: максимальная изоляция, просто объяснить аудиту.
  • Минусы: дорого, сложно мигрировать и поддерживать сотни БД, неудобные кросс-клиентские отчёты.
• Отдельная схема на клиента
  • Плюсы: лучше, чем отдельные БД по стоимости, заметная изоляция.
  • Минусы: сложные миграции, раздуваются метаданные и планировщик.
• Общая схема + RLS (мы выбираем это)
  • Плюсы: один набор таблиц, простые миграции, эффективные кэши и индексы, сильная изоляция на уровне строк.
  • Минусы: требует дисциплины в политике доступа и индексах.

Базовая реализация на PostgreSQL: колонка tenant_id, политики RLS, триггер и роли

Ниже — минимальный, но полноценный каркас мультиарендности с RLS.

1) Схема, служебные функции и роли

-- Подготовка служебной схемы и функций
CREATE SCHEMA IF NOT EXISTS app;

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

-- Триггер, который проставляет tenant_id при INSERT
CREATE OR REPLACE FUNCTION app.set_tenant() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  IF NEW.tenant_id IS NULL THEN
    NEW.tenant_id := app.current_tenant();
  END IF;
  RETURN NEW;
END;
$$;

-- Роли приложения
CREATE ROLE app_user NOINHERIT LOGIN;
CREATE ROLE app_admin NOINHERIT LOGIN; -- для админских задач без BYPASSRLS

-- Никогда не давайте вашим ролям BYPASSRLS: это обходит RLS!
-- Проверить: SELECT rolbypassrls FROM pg_roles WHERE rolname = 'app_user';

2) Таблицы с колонкой tenant_id и индексами

CREATE EXTENSION IF NOT EXISTS pgcrypto; -- для gen_random_uuid()

CREATE TABLE public.customers (
  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id    uuid NOT NULL,
  name         text NOT NULL,
  created_at   timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE public.invoices (
  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id    uuid NOT NULL,
  customer_id  uuid NOT NULL,
  number       text NOT NULL,     -- номер счёта в рамках арендатора
  amount_cents bigint NOT NULL CHECK (amount_cents >= 0),
  currency     text NOT NULL CHECK (char_length(currency) = 3),
  issued_at    date NOT NULL,
  created_at   timestamptz NOT NULL DEFAULT now(),
  UNIQUE (tenant_id, number),     -- уникальность в пределах арендатора
  FOREIGN KEY (customer_id, tenant_id) REFERENCES public.customers(id, tenant_id)
);

-- Для внешнего ключа добавим составной индекс у customers
CREATE UNIQUE INDEX customers_pk ON public.customers(id, tenant_id);

-- Ключевые индексы по tenant_id для RLS-предикатов
CREATE INDEX customers_tenant_idx ON public.customers(tenant_id);
CREATE INDEX invoices_tenant_idx  ON public.invoices(tenant_id);
CREATE INDEX invoices_tenant_number_idx ON public.invoices(tenant_id, number);

-- Триггеры для авто-проставления tenant_id
CREATE TRIGGER customers_set_tenant
BEFORE INSERT ON public.customers
FOR EACH ROW EXECUTE FUNCTION app.set_tenant();

CREATE TRIGGER invoices_set_tenant
BEFORE INSERT ON public.invoices
FOR EACH ROW EXECUTE FUNCTION app.set_tenant();

Важно: все внешние ключи и уникальные ограничения, которые «логически» зависят от арендатора, делайте составными: включайте tenant_id. Так вы избежите ложной коллизии значений у разных клиентов.

3) Включаем RLS и прописываем политики

ALTER TABLE public.customers ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.invoices  ENABLE ROW LEVEL SECURITY;

-- Базовая политика: видеть и изменять только строки своего арендатора
CREATE POLICY customers_tenant_isolation ON public.customers
  USING (tenant_id = app.current_tenant())
  WITH CHECK (tenant_id = app.current_tenant());

CREATE POLICY invoices_tenant_isolation ON public.invoices
  USING (tenant_id = app.current_tenant())
  WITH CHECK (tenant_id = app.current_tenant());

-- Минимальные привилегии для приложения
GRANT USAGE ON SCHEMA public, app TO app_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON public.customers, public.invoices TO app_user;

RLS добавляет в каждый запрос предикат tenant_id = app.current_tenant(). Планировщик сможет опираться на индексы, если предикат простой и детерминированный (current_setting — STABLE, это хорошо для планов).

4) Как приложение устанавливает текущего арендатора

Приложение обязано установить параметр сессии app.tenant_id на начало транзакции. Если используете пул в режиме «пул транзакций» (например, PgBouncer), делайте SET LOCAL в каждой транзакции.

-- В транзакции приложения
BEGIN;
SET LOCAL app.tenant_id = '8f43f1c9-5b34-4b0a-94c3-5d73a3b63f6d';
-- любой запрос теперь автоматически фильтруется политиками RLS
SELECT * FROM public.invoices ORDER BY issued_at DESC LIMIT 20;
COMMIT;

Никогда не полагайтесь на «дефолтного арендатора»: отсутствие app.tenant_id должно приводить к пустым результатам и ошибкам вставки. Добейтесь этого через NOT NULL на tenant_id и политики RLS.

Производительность: индексы, планировщик, партиционирование и пул соединений

• Индексы. Всегда индексируйте tenant_id и сочетания с часто фильтруемыми полями: (tenant_id, created_at), (tenant_id, number), (tenant_id, status). Это минимизирует накладные расходы RLS.
• Тип функции. Используйте STABLE функции (как app.current_tenant) — они дружат с планировщиком и кешированием планов.
• Партиционирование. Если данных много по времени, используйте партиционирование по дате с включением tenant_id в ключи и индексы. Для очень крупных арендаторов подойдёт хэш‑партиционирование по tenant_id, но это усложняет миграции — взвешивайте.
• Пул соединений. В transaction pooling (PgBouncer) параметр сессии сбрасывается — делайте SET LOCAL в начале каждой транзакции. В session pooling можно использовать SET один раз при получении соединения из пула.
• Лимиты и таймауты. Можно задавать timeouts и квоты на уровне ролей (например, app_user для базового тарифа) — так «шумный сосед» не обвалит всю систему.

Миграции и операционные задачи

Онбординг нового арендатора

• Создайте запись в таблице tenants (если нужна метадата) и сгенерируйте UUID арендатора.
• Привяжите пользователей и домены к tenant_id в своей системе аутентификации.
• Пропишите в конфиге приложения или в JWT клеймо tenant_id, которое вы будете передавать до БД.

CREATE TABLE public.tenants (
  id uuid PRIMARY KEY,
  name text NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

Бэкап и восстановление данных одного арендатора

Есть два надёжных пути:

1. Роль «экспортёра» с включённым RLS и предустановленным tenant_id. pg_dump в этом случае выгрузит только видимые строки.

CREATE ROLE tenant_exporter NOINHERIT LOGIN;
GRANT CONNECT ON DATABASE yourdb TO tenant_exporter;
GRANT USAGE ON SCHEMA public, app TO tenant_exporter;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO tenant_exporter;
ALTER ROLE tenant_exporter SET row_security = on;
ALTER ROLE tenant_exporter SET app.tenant_id = '8f43f1c9-5b34-4b0a-94c3-5d73a3b63f6d';

# Выгрузка только строк арендатора благодаря RLS
pg_dump -h db -U tenant_exporter -d yourdb -Fc -Z6 -f tenant.dump

# Восстановление в «песочницу»
pg_restore -h db -U app_admin -d sandbox -c tenant.dump

2. Точечные дампы через psql и COPY с WHERE:

psql "$DSN" -c "COPY (SELECT * FROM public.invoices WHERE tenant_id = '8f43f1c9-5b34-4b0a-94c3-5d73a3b63f6d') TO STDOUT WITH CSV" > invoices.csv

Первый путь удобнее: меньше ручной работы и не забываете связанные таблицы — RLS сам всё отфильтрует.

Удаление арендатора (право быть забытым)

• Все таблицы должны иметь tenant_id и внешние ключи с ON DELETE CASCADE на корневой сущности арендатора (например, tenants).
• Выполните транзакцию, удаляющую корневую запись, и проверьте счётчики удалённых строк.

ALTER TABLE public.customers ADD CONSTRAINT customers_tenant_fk
  FOREIGN KEY (tenant_id) REFERENCES public.tenants(id) ON DELETE CASCADE;
ALTER TABLE public.invoices ADD CONSTRAINT invoices_tenant_fk
  FOREIGN KEY (tenant_id) REFERENCES public.tenants(id) ON DELETE CASCADE;

BEGIN;
DELETE FROM public.tenants WHERE id = '8f43f1c9-5b34-4b0a-94c3-5d73a3b63f6d';
COMMIT;

Перенос «шумного соседа» в отдельную БД/шард

• Выгрузите арендатора через pg_dump ролью с RLS (см. выше).
• Разверните отдельную БД/шард, восстановите дамп.
• Переключите маршрутизацию запросов этого арендатора на новый DSN в роутинге приложения.
• Для непрерывности используйте логическую репликацию на время переключения.

Безопасность и аудит

• Роли без BYPASSRLS. Это табу для приложенческих ролей. Проверяйте при ревью прав.
• Админские операции. Для кросс‑арендаторских отчётов используйте функции SECURITY DEFINER, в которых явно контролируете, какие таблицы и как читаются. Выполняйте их от роли без BYPASSRLS или с аккуратным SET ROLE.
• Аудит. Логируйте tenant_id в приложении и в БД:

ALTER SYSTEM SET log_line_prefix = '%m [%p] user=%u db=%d app=%a tenant=%v ';
-- Перед запросами: SET application_name и SET LOCAL app.tenant_id

• Тесты против утечек. Покройте pgTAP или простыми SQL‑тестами: под разными tenant_id сделайте выборки и убедитесь, что кросс‑доступ невозможен.

-- Пример идеи теста (упрощённо)
SET LOCAL app.tenant_id = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
SELECT COUNT(*) FROM public.invoices \gset
\echo :count  -- должно быть 0 для чужих данных

Интеграции и кэш

• Кэш и ключи. Всегда включайте tenant_id в ключи Redis/мемкеша: invoice:{tenant}:{number}.
• Очереди и события. Включайте tenant_id в полезную нагрузку и маршрутизацию (routing key). Иначе легко перепутать обработку фоновых задач.
• Хранилища файлов. Директории и префиксы с tenant_id, запреты на листинг чужих пространств.

Типичные ошибки и грабли

• Отсутствие tenant_id в одной из таблиц. Линтер миграций и ревью схемы должны это ловить.
• Политики только WITH CHECK без USING — чтение утечёт. Нужны обе части.
• Материализованные представления без фильтра по tenant_id — кэшируете чужие данные. Либо делайте материализацию на арендатора, либо храните агрегации с tenant_id.
• Секвенсы и «сквозные» id. Порядок значений глобален. Это не проблема само по себе, но никогда не показывайте внутренние id в UI как «количество клиентов в системе» — могут быть догадки о чужой активности. Используйте публичные номера, уникальные в рамках tenant_id.
• PgBouncer в transaction pooling и SET один раз на сессию — потеряете контекст арендатора. Делайте SET LOCAL на каждую транзакцию.

Минимальный пример сервиса на Node.js

Ниже — рабочий пример с node-postgres. Он показывает, как устанавливать tenant_id на транзакцию и не забыть про пул соединений.

// package.json
// {
//   "type": "module",
//   "dependencies": { "pg": "^8.11.3", "express": "^4.19.2" }
// }

import express from 'express';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const app = express();
app.use(express.json());

async function withTenant(tenantId, fn) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    // Важно: SET LOCAL — параметр действует только в пределах транзакции
    await client.query('SET LOCAL app.tenant_id = $1', [tenantId]);
    const result = await fn(client);
    await client.query('COMMIT');
    return result;
  } catch (e) {
    await client.query('ROLLBACK');
    throw e;
  } finally {
    client.release();
  }
}

// Пример ручки: создать счёт и вернуть его
app.post('/api/:tenantId/invoices', async (req, res) => {
  const tenantId = req.params.tenantId;
  const { customer_id, number, amount_cents, currency, issued_at } = req.body;

  try {
    const row = await withTenant(tenantId, async (db) => {
      const ins = await db.query(
        `INSERT INTO public.invoices (customer_id, number, amount_cents, currency, issued_at)
         VALUES ($1, $2, $3, $4, $5)
         RETURNING id, tenant_id, customer_id, number, amount_cents, currency, issued_at, created_at`,
        [customer_id, number, amount_cents, currency, issued_at]
      );
      return ins.rows[0];
    });

    res.status(201).json(row);
  } catch (e) {
    if (e.code === '23505') { // unique_violation
      return res.status(409).json({ error: 'Номер счёта уже существует' });
    }
    console.error(e);
    res.status(500).json({ error: 'Внутренняя ошибка' });
  }
});

// Пример ручки: пагинация по дате в пределах арендатора
app.get('/api/:tenantId/invoices', async (req, res) => {
  const tenantId = req.params.tenantId;
  const { limit = 50, before } = req.query;
  const lim = Math.min(parseInt(limit, 10) || 50, 200);

  try {
    const rows = await withTenant(tenantId, async (db) => {
      if (before) {
        const { rows } = await db.query(
          `SELECT id, tenant_id, customer_id, number, amount_cents, currency, issued_at, created_at
           FROM public.invoices
           WHERE issued_at < $1
           ORDER BY issued_at DESC
           LIMIT $2`,
          [before, lim]
        );
        return rows;
      } else {
        const { rows } = await db.query(
          `SELECT id, tenant_id, customer_id, number, amount_cents, currency, issued_at, created_at
           FROM public.invoices
           ORDER BY issued_at DESC
           LIMIT $1`,
          [lim]
        );
        return rows;
      }
    });

    res.json({ items: rows });
  } catch (e) {
    console.error(e);
    res.status(500).json({ error: 'Внутренняя ошибка' });
  }
});

const port = process.env.PORT || 3000;
app.listen(port, () => console.log(`Listening on ${port}`));

Заметьте: мы никогда не передаём tenant_id в запросах к БД напрямую (кроме SET LOCAL). Политики RLS сами ограничат видимость и изменение строк.

Бизнес-метрики успеха и экономия

• Стоимость владения (TCO): меньше инстансов БД, интерконнектов и бэкапов.
• Скорость вывода фич: одна схема, один набор миграций.
• SLA и прогнозируемость: регулируете нагрузку на уровне ролей и таймаутов, не плодите кластеры «на всякий случай».
• Комплаенс: проверяемая изоляция, аудит действий с tenant_id, процедуры удаления арендатора.

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

• В каждой таблице есть tenant_id и индексы по нему.
• На всех таблицах включён RLS и есть пара USING/WITH CHECK.
• Роли приложения НЕ имеют BYPASSRLS.
• Приложение делает SET LOCAL app.tenant_id в начале каждой транзакции.
• Внешние ключи и уникальные ограничения учитывают tenant_id.
• Кэш, очереди и хранилища файлов включают tenant_id в ключи/пути.
• Есть роль экспортёра с row_security=on и предустановленным app.tenant_id для бэкапов одного арендатора.
• Набор автотестов ловит любые утечки данных между арендаторами.

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