ClickHouseAmy Chen, Jan Mensch6 min readintermediate
Replica-aware routing public beta
Summary
Replica‑aware routing (public beta) lets ClickHouse Cloud users pin a query stream to a specific replica by sending a custom header (HTTP) or overriding the TLS SNI (native). The proxy (Envoy) hashes the tag and consistently forwards all requests with the same tag to that replica, giving read‑after‑write consistency for temporary tables, session objects, and warm replica caches. Stickiness is bes…
- Send `X-ClickHouse-Replica-Tag` (HTTP) or `--tls-sni-override` (native) to have Envoy hash the value and route all queries with that tag to the same replica.
- Useful for temporary tables, named sessions, cache warm‑up, and read‑after‑write consistency in multi‑replica clusters.
- Implemented as a layer on Istio/Envoy; uses header‑based consistent hashing rather than sub‑domain certificates.
- Stickiness is not a guarantee – upgrades, restarts, or scaling can re‑hash keys, so callers should verify the replica via `select hostname()` if needed.
In ClickHouse clusters, temporary objects and session state live only on the replica where they were created. Without sticky routing, load‑balancers can send follow‑up queries to a different replica, causing “object not found” errors and breaking read‑after‑write semantics. Replica‑aware routing gi…
6/10




