Ко-локация и Citus: инвариант, делающий шардирование пригодным к использованию

Команда мигрирует на Citus и рада, что запросы для отдельных клиентов так же быстры, как раньше. Потом они добавляют новую таблицу без колонки tenant_id, и новый join-запрос занимает 500 мс вместо 5 мс. Ревью схемы выявляет причину: одна таблица не была ко-локирована.

Архитектура Citus

Citus — расширение Postgres, превращающее кластер экземпляров Postgres в одну логическую шардированную базу данных:

• Координатор: один узел, хранящий метаданные кластера (карта шардов, информация о распределении таблиц), разбирающий запросы, планирующий распределённое выполнение и возвращающий результаты клиенту.
• Воркеры: N узлов, хранящих фактические данные (шарды). Воркеры выполняют Postgres-запросы локально и возвращают результаты координатору.
• Клиент: подключается к координатору как к обычному Postgres. Изменения драйвера не требуются.

Клиент → Координатор (держит метаданные, планирует, маршрутизирует)
              ↓               ↓               ↓
          Воркер 0        Воркер 1        Воркер 2
        (шарды 0-10)   (шарды 11-21)  (шарды 22-31)

Три типа таблиц

-- Распределить таблицы в рамках клиента по tenant_id
SELECT create_distributed_table('users',       'tenant_id');
SELECT create_distributed_table('projects',    'tenant_id', colocate_with => 'users');
SELECT create_distributed_table('tasks',       'tenant_id', colocate_with => 'users');
SELECT create_distributed_table('comments',    'tenant_id', colocate_with => 'users');
SELECT create_distributed_table('attachments', 'tenant_id', colocate_with => 'users');

-- Реплицировать небольшие lookup-таблицы на каждый воркер
SELECT create_reference_table('plans');
SELECT create_reference_table('feature_flags');
SELECT create_reference_table('countries');

-- Таблица tenants остаётся локальной на координаторе (control plane)

Ко-локация: центральный инвариант

Ко-локация означает, что таблицы, распределённые по одному ключу, имеют соответствующие шарды на одном физическом воркере. Если orders и payments обе распределены по tenant_id, то все заказы клиента 42 и все его платежи живут на воркере 1.

Запрос, соединяющий orders и payments с фильтром по tenant_id = 42:

• С ко-локацией: планировщик отправляет join на воркер 1, который выполняет его как обычный Postgres join — одна машина, полное использование индексов, однозначные миллисекунды.
• Без ко-локации (например, payments распределена по payment_id): координатор должен собрать частичные результаты со всех воркеров и объединить их. P99 задержка = самый медленный воркер. Каждый воркер участвует. В 10–100× медленнее.

Ко-локация — не оптимизация производительности — это проектный контракт, благодаря которому шардированная система ведёт себя как единственный Postgres для 99% случаев.

Кросс-шард запросы и их смягчение

Запросы без фильтра по ключу шарда расходятся на все шарды. Примеры:

• «Список всех пользователей с email, заканчивающимся на @enterprise.com» (нет tenant_id)
• «Подсчёт всех заказов за сегодня по всем клиентам» (кросс-клиентская аналитика)
• «Найти пользователя по email для входа» (email, не tenant_id)

Для OLTP:

1. Переработать API: почти все OLTP-запросы должны нести tenant_id. Lookup при входе по email требует отдельного индекса или небольшого lookup-сервиса, разрешающего email → tenant_id сначала.
2. CDC в OLAP: кросс-клиентская аналитика должна выполняться на отдельном аналитическом хранилище (ClickHouse, BigQuery), пополняемом через Change Data Capture. Никогда не запускайте глобальные агрегаты на OLTP-кластере.
3. Rate-limit fan-out endpoints: для редких легитимных кросс-шард операций — rate-limit и документируйте их стоимость.

Опытная метрика: кросс-шард запросы должны составлять <1–2% OLTP-трафика. Выше этого — схема ушла от ко-локации и требует ревью.