Loading post…
ClickhouseAnnouncement
Replica-aware routing public beta
Summary
ClickHouse’s replica-aware routing is now in Public Beta for Enterprise customers, addressing cases where temporary tables and named sessions become invisible after a request reaches another replica. The feature routes requests to a consistent replica using an X-ClickHouse-Replica-Tag or a native TLS SNI override, supporting session-scoped access and read-after-write consistency. Over HTTP, Envoy reads the header and uses consistent hashing; native connections decouple the SNI used for routing from the hostname validated against the certificate. Stickiness is best-effort and can change after upgrades, restarts, or scaling, so temporary objects and session settings may need recreation. The feature is available through service settings for Enterprise plans on standard ClickHouse Cloud and BYOC.
Context
Temporary tables and named sessions exist only on the replica where they were created. Load balancing can send a later query to another replica, while replication lag can temporarily hide a write there; replica-aware routing keeps related requests on one replica.
Approach / What changed
HTTP clients provide a shared value in X-ClickHouse-Replica-Tag, which Envoy uses for consistent hashing. Native clients provide a shared --tls-sni-override value; the connection validates the certificate against --host while Envoy hashes the overridden SNI for routing. The implementation uses an L7 Envoy proxy rather than session_id, because ClickHouse permits only one query at a time within a session.
Takeaways
Use the same X-ClickHouse-Replica-Tag or native SNI override for related requests to route them to the same replica.
Replica-aware routing can support temporary tables, named sessions, read-after-write checks, and schema changes that have not yet synced across replicas.
Routing is best-effort rather than guaranteed: upgrades, restarts, or scaling can move a key, requiring temporary objects and session settings to be recreated.
FAQ
How does HTTP replica-aware routing keep a read on the same replica as a write?
The write and read use the same X-ClickHouse-Replica-Tag header. Envoy uses that value for consistent hashing, so both requests route to the same replica and the read can see the write before other replicas catch up.
What is different about native connections?
Native clients use --tls-sni-override as the routing value while --host remains the hostname validated against the certificate. This lets Envoy hash the SNI without requiring a certificate for every routing key.
What can break replica stickiness?
Stickiness is best-effort, so upgrades, restarts, and scaling in or out can move a routing key to another replica. Temporary tables and session settings then need to be recreated; SELECT hostName() can show which replica served a request.
Source and freshness
- Source
- clickhouse.com
- Published
- Added to Yomu
Summaries are generated from the original by a language model. Check the original before relying on it.
Keep reading
Related reading
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
The best engineering reads, once a week
One useful email. Unsubscribe anytime.