Skip to main content
Skip to main content
Edit this page

Replica-aware routing

Private preview

Replica-aware routing (also known as sticky sessions, sticky routing, or session affinity) increases the chance of cache reuse by consistently routing related requests to the same ClickHouse replica. It is best-effort and does not guarantee isolation.

Protocol support — HTTP/HTTPS only

Replica-aware routing is applied at the proxy layer over the HTTP/HTTPS interface, using the session_id query parameter (see below). It is not available over the native protocol (native port, e.g. the clickhouse-go driver in its default native mode). If you need sticky routing from a native-protocol client, connect that workload over the HTTP interface instead — for clickhouse-go (v2), set Protocol: clickhouse.HTTP on the connection.

HTTP-based routing (session_id)​

To pin a workload to a replica, set the session_id query parameter on the HTTPS interface. The proxy parses the request and uses consistent hashing on the session_id to select a replica, so all requests sharing the same session_id are routed to the same server — until the cluster topology changes.

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

Every request carrying session_id=my-workload-1 lands on the same replica. A different session_id value hashes independently and may land on the same or a different replica — the mapping is consistent, but you do not choose which replica a given value maps to.

Subdomain-based routing (deprecated)​

Deprecated

The subdomain-based mechanism below is deprecated and is no longer enabled on new services. It does not scale (each sticky endpoint requires its own TLS certificate). Use the HTTP-based session_id method instead.

Previously, enabling replica-aware routing allowed a wildcard subdomain on top of the service hostname. For a service with the host name abcxyz123.us-west-2.aws.clickhouse.cloud, any hostname matching *.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud (e.g. aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud) was hashed by Envoy to a consistent replica. The original hostname continued to use LEAST_CONNECTION load balancing, the default routing algorithm.

Limitations of replica-aware routing​

Replica-aware routing doesn't guarantee isolation​

Any disruption to the service — server pod restarts (version upgrade, crash, vertical scaling), or scale out / in — changes the routing hash ring. This causes requests sharing the same session_id to land on a different server pod.

When using the deprecated subdomain method, customers need to manually add a DNS entry to make name resolution work for the new hostname pattern. It is possible that this can cause imbalance in the server load if customers use it incorrectly.

Replica-aware routing requires the HTTP protocol​

Sticky routing is keyed on the session_id query parameter, which only exists on the HTTP/HTTPS interface. The native binary protocol carries no such parameter for the proxy to hash on, so replica-aware routing is not available over the native protocol. Native-protocol clients must move the relevant workload to the HTTP interface to use this feature.

Configuring replica-aware routing​

To enable replica-aware routing, please contact our support team.