> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'Закрытая предварительная версия в ClickHouse Cloud'}
        </div>;
};

<PrivatePreviewBadge />

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

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

<Warning>
  **Требуется HTTP-интерфейс**

  Маршрутизация с учетом реплик применяется на уровне прокси через [интерфейс HTTP/HTTPS](/docs/ru/concepts/features/interfaces/http). ClickHouse Cloud переводит маршрутизацию с учетом реплик с `session_id` на заголовок `X-ClickHouse-Replica-Tag`. На вкладках ниже описаны оба метода на время этого перехода.

  Маршрутизация с учетом реплик **в настоящее время недоступна через собственный протокол** (собственный порт, например драйвер [clickhouse-go](/docs/ru/integrations/language-clients/go/index), работающий в режиме собственного протокола по умолчанию). Клиентам собственного протокола необходимо перейти на HTTP и передавать значение маршрутизации в каждом запросе.
</Warning>

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

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

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

Откройте [тикет в службу поддержки](https://clickhouse.com/support/program) и попросите включить HTTP-маршрутизацию запросов к репликам с закреплением сеанса. Укажите ID вашего сервиса и причину, по которой она вам нужна (временные таблицы, состояние сеанса, повторное использование кэша или согласованность чтения после записи). Перед миграцией существующего сервиса попросите службу поддержки подтвердить, что для него включена маршрутизация на основе заголовков. Продолжайте использовать `session_id`, пока не получите подтверждение; `X-ClickHouse-Replica-Tag` не обеспечит липкую маршрутизацию, пока развертывание не дойдет до вашего сервиса. Перезапуск не требуется.

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

<Tabs>
  <Tab title="X-ClickHouse-Replica-Tag (предпочтительный)">
    Чтобы закрепить рабочую нагрузку за репликой, передавайте заголовок `X-ClickHouse-Replica-Tag` через [HTTPS-интерфейс](/docs/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`](/docs/ru/integrations/language-clients/go/configuration#connection-settings).

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

    ### Согласованность чтения после записи

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

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

    ### Проверьте, к какой реплике вы подключены

    Снова выполните пример `SELECT hostName()` с тем же значением `X-ClickHouse-Replica-Tag`. Пока число реплик не изменится, вы должны получить то же имя хоста. Другое значение заголовка может соответствовать другой реплике.
  </Tab>

  <Tab title="session_id (legacy)">
    <Warning>
      `X-ClickHouse-Replica-Tag` заменяет `session_id` для маршрутизации с учетом реплик. Продолжайте использовать `session_id`, пока служба поддержки не подтвердит, что для вашего сервиса включена маршрутизация по заголовкам.
    </Warning>

    **Параллельные запросы завершаются ошибкой `SESSION_IS_LOCKED`**

    * Поскольку `session_id` создает HTTP-сеанс ClickHouse, в одном сеансе одновременно может выполняться только один запрос.
    * После включения маршрутизации по заголовкам для вашего сервиса рабочие нагрузки, которым нужна только привязка к реплике, могут перейти на `X-ClickHouse-Replica-Tag`. Параллельные запросы могут использовать один и тот же тег реплики.
    * Если вам требуется состояние HTTP-сеанса ClickHouse, выполняйте последовательно запросы с общим `session_id`.

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

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

    Указывайте параметр запроса `session_id` в каждом запросе:

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

    Для clickhouse-go (v2) установите `Protocol: clickhouse.HTTP` и передайте `session_id` как [настройку](/docs/ru/integrations/language-clients/go/database-sql-api#sessions). Драйвер отправит его как параметр URL-запроса.

    ### Согласованность чтения после записи с `session_id`

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

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

    ### Проверка реплики, на которую направляет `session_id`

    Снова выполните пример `SELECT hostName()` с тем же `session_id`. Пока количество реплик не изменится, вы должны получить то же имя хоста. Другой `session_id` может быть сопоставлен с другой репликой.
  </Tab>
</Tabs>

<div id="subdomain-based-routing-deprecated">
  ## Устаревшая маршрутизация на основе поддоменов
</div>

Маршрутизация на основе поддоменов больше не включается для новых сервисов. Если вы уже используете sticky-поддомены, обратитесь в [поддержку](https://clickhouse.com/support/program), чтобы перейти на [метод с HTTP-заголовком](#http-based-routing).

<Accordion title="Как работает устаревшая маршрутизация на основе поддоменов">
  Ранее включение маршрутизации с учетом реплик позволяло использовать подстановочный поддомен для имени хоста сервиса. Для сервиса с именем хоста `abcxyz123.us-west-2.aws.clickhouse.cloud` любое имя хоста, соответствующее шаблону `*.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud` (например, `aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud`), Envoy по хешу направлял на одну и ту же реплику. Исходное имя хоста по-прежнему использовало балансировку нагрузки `LEAST_CONNECTION` — алгоритм маршрутизации по умолчанию.
</Accordion>

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

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

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

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

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

<div id="replica-aware-routing-does-not-work-out-of-the-box-with-private-link">
  ### Private Link и устаревший метод с поддоменом
</div>

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

Устаревший метод с поддоменом так не работает: нужно добавить DNS для шаблона хоста `*.sticky.*`, а неправильная настройка может привести к неравномерному распределению нагрузки между репликами.

<div id="replica-aware-routing-requires-http">
  ### Для маршрутизации с учетом реплик требуется HTTP-протокол
</div>

Липкая маршрутизация использует HTTP-заголовок или параметр запроса в зависимости от метода маршрутизации, доступного для вашего сервиса. Собственный бинарный протокол не передает ни одного из этих значений, по которым HTTP-прокси мог бы вычислить хеш, поэтому маршрутизация с учетом реплик недоступна через собственный протокол. Чтобы использовать эту возможность, клиентам собственного протокола необходимо перенести соответствующую рабочую нагрузку на HTTP-интерфейс.

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

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

* Убедитесь, что используете метод маршрутизации, доступный для вашего сервиса: заголовок `X-ClickHouse-Replica-Tag` или устаревший URL-параметр запроса `session_id`.
* Убедитесь, что во всех запросах используется точно одно и то же значение маршрутизации.
* Немного подождите после включения. Изменения могут вступить в силу менее чем за минуту.
* Проверьте, не изменилось ли недавно количество реплик: после масштабирования ожидается переназначение. Используйте `SELECT hostName()`, чтобы определить новое соответствие.