Skip to content


Chproxy is an HTTP proxy and load balancer for ClickHouse. It provides the following features:

  • May proxy requests to multiple distinct ClickHouse clusters depending on the input user. For instance, requests from appserver user may go to stats-raw cluster, while requests from reportserver user may go to stats-aggregate cluster.
  • May map input users to per-cluster users. This prevents from exposing real usernames and passwords used in ClickHouse clusters. Additionally this allows mapping multiple distinct input users to a single ClickHouse user.
  • 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 least loaded + round robin technique.
  • 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 SIGHUP signal to chproxy process.
  • Easy to manage and run - just pass config file path to a single chproxy binary.
  • Easy to configure:
listen_addr: ":9090"
allowed_networks: [""]
- name: "default"
to_cluster: "default"
to_user: "default"
# by default each cluster has `default` user which can be overridden by section `users`
- name: "default"
nodes: [""]

Go Report Card

Build Status