Chproxy is an HTTP proxy and load balancer for ClickHouse. It provides the following features:
- May proxy requests to multiple distinct
ClickHouseclusters depending on the input user. For instance, requests from
appserveruser may go to
stats-rawcluster, while requests from
reportserveruser may go to
- May map input users to per-cluster users. This prevents from exposing real usernames and passwords used in
ClickHouseclusters. Additionally this allows mapping multiple distinct input users to a single
- May accept incoming requests via HTTP and HTTPS.
- May limit HTTP and HTTPS access by IP/IP-mask lists.
- May limit per-user access by IP/IP-mask lists.
- May limit per-user query duration. Timed out or canceled queries are forcibly killed via KILL QUERY.
- May limit per-user requests rate.
- May limit per-user number of concurrent requests.
- All the limits may be independently set for each input user and for each per-cluster user.
- May delay request execution until it fits per-user limits.
- Per-user response caching may be configured.
- Response caches have built-in protection against thundering herd problem aka
dogpile effect. More information can be found in Thundering herd.
- Evenly spreads requests among replicas and nodes using
- Monitors node health and prevents from sending requests to unhealthy nodes.
- Supports automatic HTTPS certificate issuing and renewal via Let’s Encrypt.
- May proxy requests to each configured cluster via either HTTP or HTTPS.
- Prepends User-Agent request header with remote/local address and in/out usernames before proxying it to
ClickHouse, so this info may be queried from system.query_log.http_user_agent.
- Exposes various useful metrics in Prometheus text format.
- Configuration may be updated without restart - just send
- Easy to manage and run - just pass config file path to a single
- Easy to configure:
server: http: listen_addr: ":9090" allowed_networks: ["127.0.0.0/24"] users: - name: "default" to_cluster: "default" to_user: "default" # by default each cluster has `default` user which can be overridden by section `users` clusters: - name: "default" nodes: ["127.0.0.1:8123"]