> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Маршрутизация с учетом реплик

> Направляйте связанные запросы на одну и ту же реплику ClickHouse Cloud для временных таблиц, сеансов, повторного использования кэша и согласованности чтения после записи

export const EnterprisePlanFeatureBadge = ({feature = 'Эта возможность', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Возможность тарифа Enterprise
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'доступны' : 'доступна'} в тарифе Enterprise. {support ? `Чтобы включить эту возможность, обратитесь в службу поддержки.` : 'Чтобы перейти на другой тариф, откройте страницу тарифных планов в облачной консоли.'}</p>
            </div>
        </div>;
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Бета</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Возможность в статусе бета</span>
        </a>;
};

<BetaBadge />

<EnterprisePlanFeatureBadge feature="Маршрутизация с учетом реплик" />

Маршрутизация с учетом реплик (также известная как липкие сеансы, липкая маршрутизация или привязка сеанса) направляет связанные запросы на одну и ту же реплику ClickHouse. Используйте ее, если [временные таблицы](/ru/reference/statements/create/table/temporary-table) или [именованное состояние сеанса](/ru/concepts/features/interfaces/http#using-clickhouse-sessions-in-the-http-protocol) должны оставаться доступными между запросами, если связанные запросы должны повторно использовать локальный кэш одной и той же реплики или если требуется [согласованность чтения после записи](#read-after-write-consistency) между записью и последующими операциями чтения.

Она работает по принципу best-effort и не гарантирует изоляцию. Прокси сопоставляет каждое значение маршрутизации с одной репликой. Сопоставление остается стабильным, пока число реплик не изменяется; при масштабировании сервиса значение может быть сопоставлено с другой репликой.

Маршрутизация с учетом реплик доступна через оба интерфейса:

* Через [HTTP/HTTPS](#http-based-routing) с использованием заголовка `X-ClickHouse-Replica-Tag`.
* Через [собственный протокол](#native-protocol-routing) с использованием переопределения TLS Server Name Indication (SNI).

Оба варианта включаются отдельно и используют одно и то же согласованное хеширование на стороне прокси.

<h2 id="prerequisites">
  Предварительные требования
</h2>

* Вашему сервису требуется **2 или более реплики**. В сервисе с одной репликой привязывать попросту не к чему.
* Сервис уровня **Enterprise**.
* Поддерживается в стандартных сервисах ClickHouse Cloud и [BYOC](/ru/products/cloud/guides/infrastructure/deployment-options/byoc/overview)

<h2 id="configuring-replica-aware-routing">
  Настройка маршрутизации с учетом реплик
</h2>

Клиенты уровня Enterprise включают маршрутизацию с учетом реплик на странице настроек сервиса в ClickHouse Cloud console. Откройте свой сервис, перейдите в раздел **Settings** и включите переключатель для нужного интерфейса:

* Один переключатель включает маршрутизацию на основе HTTP по заголовку `X-ClickHouse-Replica-Tag`.
* Отдельный переключатель включает routing по native-протоколу через override SNI.

Можно включить один из них или оба. Перезапуск не требуется, изменения вступают в силу менее чем за минуту.

Переключатели постепенно появляются в планах уровня Enterprise. Если на вашем сервисе их ещё нет, создайте тикет в [поддержку](https://clickhouse.com/support/program), указав ID сервиса, чтобы возможность включили раньше.

<h2 id="http-based-routing">
  Маршрутизация на основе HTTP
</h2>

Чтобы закрепить рабочую нагрузку за репликой, передавайте заголовок `X-ClickHouse-Replica-Tag` через [HTTPS-интерфейс](/ru/concepts/features/interfaces/http). Прокси применяет согласованное хеширование к значению заголовка, поэтому запросы с одинаковым значением направляются к одной и той же реплике, пока число реплик не меняется. Другое значение хешируется независимо и может попасть на ту же или другую реплику, но выбрать, *какой именно* реплике будет соответствовать значение, нельзя.

Используйте существующее имя хоста сервиса. Специальные закреплённые имена хостов или изменения DNS не требуются. Значением заголовка может быть любая строка на ваш выбор, например имя приложения, идентификатор пользователя или метка рабочей нагрузки. Для запросов без заголовка сохраняется обычная балансировка нагрузки.

Указывайте заголовок `X-ClickHouse-Replica-Tag` в каждом запросе:

```bash theme={null}
echo 'SELECT hostName()' | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-
```

Для clickhouse-go (v2) укажите `Protocol: clickhouse.HTTP` и передайте заголовок через [параметр подключения `HttpHeaders`](/ru/integrations/language-clients/go/configuration#connection-settings).

<Info>
  `X-ClickHouse-Replica-Tag` обеспечивает закрепление за репликой без создания HTTP-сеанса ClickHouse. Параллельные запросы могут использовать один и тот же тег, не сталкиваясь с `SESSION_IS_LOCKED`.
</Info>

<h2 id="native-protocol-routing">
  Маршрутизация по собственному протоколу
</h2>

При работе через [собственный протокол](/ru/interfaces/tcp) передавайте значение маршрутизации как имя TLS-сервера в формате `<routing-value>.sticky.<host>`. Подключайтесь к обычному имени хоста вашего сервиса, как обычно. [Клиент ClickHouse](/ru/interfaces/client) принимает значение маршрутизации через параметр `--tls-sni-override`:

```bash theme={null}
clickhouse client \
  --host <host> \
  --secure \
  --tls-sni-override my-workload-1.sticky.<host> \
  --query 'SELECT hostName()'
```

`--host` — это обычное имя хоста вашего сервиса, `--secure` включает TLS, а `--tls-sni-override` передаёт значение маршрутизации. Использование TLS обязательно. Дополнительный сертификат или DNS-запись не требуются.

<h2 id="read-after-write-consistency">
  Согласованность чтения после записи
</h2>

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

Он также помогает после изменения схемы, которое ещё не реплицировалось: повторное использование значения маршрутизации удерживает вставки на реплике, где новая схема уже применена.

По HTTP используйте то же значение заголовка:

```bash theme={null}
# Write, tagged with a routing value
echo "INSERT INTO events VALUES (now(), 'signup')" | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-

# Read it back on the same replica, using the same value
echo 'SELECT count() FROM events' | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-
```

При работе по собственному протоколу используйте то же переопределение SNI:

```bash theme={null}
# Write with a routing value
clickhouse client \
  --host <host> \
  --secure \
  --tls-sni-override my-workload-1.sticky.<host> \
  --query "INSERT INTO events VALUES (now(), 'signup')"

# Read it back on the same replica, using the same value
clickhouse client \
  --host <host> \
  --secure \
  --tls-sni-override my-workload-1.sticky.<host> \
  --query 'SELECT count() FROM events'
```

Для более широких гарантий на всех репликах в ClickHouse Cloud можно также задать [`select_sequential_consistency`](/ru/reference/settings/session-settings#select_sequential_consistency) равным `1`.

<h2 id="check-which-replica">
  Проверьте, к какой реплике вы подключены
</h2>

Снова выполните один из примеров `SELECT hostName()` с тем же значением маршрутизации. Пока число реплик не изменится, вы должны получить то же имя хоста. Другое значение маршрутизации может соответствовать другой реплике.

<h2 id="limitations-of-replica-aware-routing">
  Ограничения маршрутизации с учетом реплик
</h2>

<h3 id="replica-aware-routing-does-not-guarantee-isolation">
  Привязка меняется при изменении числа реплик
</h3>

Масштабирование наружу или внутрь меняет кольцо хеширования маршрутизации. В результате запросы с одинаковым значением маршрутизации могут попасть на другую реплику. Если вы используете временные таблицы или настройки на уровне сеанса, будьте готовы создать их заново после переназначения. Запрос `SELECT hostName()` всегда покажет, на какой реплике вы находитесь.

<h3 id="not-workload-isolation">
  Маршрутизация с учетом реплик не является изоляцией рабочих нагрузок
</h3>

Липкая маршрутизация определяет только то, *какая* реплика обрабатывает запрос. Эта реплика по-прежнему может обслуживать и другой трафик. Для выделенных вычислительных ресурсов используйте [compute-compute separation](/ru/products/cloud/features/infrastructure/warehouses).

<h3 id="private-networking">
  Частное сетевое подключение
</h3>

Маршрутизация как на основе HTTP, так и на основе native-протокола работает с [частным сетевым подключением](/ru/products/cloud/guides/security/connectivity/private-networking) на стандартном имени хоста вашего сервиса. Дополнительные записи DNS не требуются.

<h3 id="native-protocol-routing-requires-tls">
  Маршрутизация по собственному протоколу требует TLS
</h3>

Для маршрутизации по собственному протоколу необходим TLS, поэтому передавайте `--secure`. Для незашифрованного native-соединения сохраняется обычная балансировка нагрузки.

<h2 id="troubleshooting">
  Устранение неполадок
</h2>

**Запросы по-прежнему направляются на разные реплики при одном и том же значении маршрутизации**

* Убедитесь, что переключатель для используемого вами интерфейса включен на странице настроек сервиса. HTTP- и native-методы включаются по отдельности.
* При работе по HTTP убедитесь, что каждый запрос содержит заголовок `X-ClickHouse-Replica-Tag` и что во всех запросах используется точно одно и то же значение.
* При работе по собственному протоколу убедитесь, что задан параметр `--secure`, а `--tls-sni-override` имеет форму `<routing-value>.sticky.<host>`.
* Немного подождите после включения. Изменения могут вступить в силу менее чем за минуту.
* Проверьте, не изменилось ли недавно количество реплик: после масштабирования ожидается переназначение. Используйте `SELECT hostName()`, чтобы определить новое соответствие.

**Ошибки сертификата при работе по собственному протоколу**

* Убедитесь, что в `--host` указано обычное имя хоста вашего сервиса, а значение маршрутизации передается через `--tls-sni-override`, а не через `--host`.