Chproxy

Chproxy is an open-source HTTP proxy and load balancer purpose-built for ClickHouse^®. A community-driven project, it provides robust traffic management and security features for ClickHouse^® clusters.

Chproxy is a reliable and high-performance solution which ensures secure and efficient access to production-grade ClickHouse^® clusters.

Routing and load balancing

• Proxying queries to different ClickHouse^® clusters based on the incoming user.
• Balancing query load across replicas and nodes using the least loaded + round robin strategy.
• Node health monitoring to prevent routing queries to unhealthly nodes.

User management and security

• Mapping incoming users to cluster users to prevent the exposure of real usernames and passwords.
• Mapping multiple incoming users to a single ClickHouse^® user.
• Restricted HTTP and HTTPS access based on IP address or IP mask lists.
• Restricted access for individual users based on IP address or IP mask lists.

Resource and performance control

• Limits on query duration per user with forced termination via KILL QUERY.
• Limits on query rates per user.
• Limits on the number of concurrent queries per user.
• Enforcing query execution delays until user limits are satisfied.
• Independent configuration of all limits for each incoming user and cluster user.

Caching and optimization

• Granular configuration of response caching for each individual user.
• Native thundering herd mitigation for response caches.

Connection security

• Support for incoming queries over HTTP and HTTPS.
• Automatic issuance and renewal of HTTPS certificates via Let’s Encrypt^®.
• Proxying queries to each configured cluster over HTTP or HTTPS.

Monitoring and management

• Exporting performance metrics in Prometheus format.
• Adding user and IP data to the User-Agent header for querying from system.query_log.http_user_agent.
• Configuration updates without a restart via the SIGHUP signal.
• Streamlined launch and management by providing the configuration file path to a single chproxy binary.

1. Create a cloud network and a subnet to host the virtual machine (VM).

2. Create a security group for the VM named vm-proxy in your new cloud network and configure the rules as follows:

   Traffic direction	Description	Port range	Protocol	Source / Destination	CIDR blocks
   Ingress	ClickHouse	8123	TCP	CIDR	0.0.0.0/0
   Ingress	HTTP	8080	TCP	CIDR	0.0.0.0/0
   Ingress	SSH	22	TCP	CIDR	0.0.0.0/0
   Egress	Any Egress	0-65535	Any	CIDR	0.0.0.0/0

3. Create a security group for the VM named vm-test in the same network and configure the rules as follows:

   Traffic direction	Description	Port range	Protocol	Source / Destination	CIDR blocks
   Ingress	ClickHouse	8123	TCP	CIDR	0.0.0.0/0
   Ingress	HTTP	80	TCP	CIDR	0.0.0.0/0
   Ingress	SSH	22	TCP	CIDR	0.0.0.0/0
   Egress	Any Egress	0-65535	Any	CIDR	0.0.0.0/0

4. Get an SSH key pair for connection to the VM.

5. Create and configure a VM to test the application:

   1. When creating the VM, specify the following:

      1. Under Boot disk image on the Marketplace tab, select an Ubuntu or Debian image, e.g., Ubuntu 24.04.
      2. Under Network settings, specify the earlier created cloud network, subnet, and security group for vm-test.
      3. Under Access, specify the username and public SSH key for connection to the VM.
      4. Under General information, specify the VM name: vm-test.

   2. Learn the public IP address of vm-test.

   3. Connect to vm-test over SSH. Use the username you set when creating the VM and the private SSH key you created earlier.

   4. Install ClickHouse Server, ClickHouse Client, and ClickHouse Keeper as detailed in Install ClickHouse on Debian/Ubuntu.

   5. Add the following to /etc/clickhouse-server/config.xml right after the <clickhouse> line:

          <listen_host>0.0.0.0</listen_host>
      

      The 0.0.0.0 address is not recommended in production environments.

   6. Add a rule allowing incoming connections to port 8123:

      sudo iptables -I INPUT -p tcp --dport 8123 -j ACCEPT
      sudo apt-get update && sudo apt-get install -y netfilter-persistent
      sudo netfilter-persistent save
      

   7. Restart ClickHouse Server:

      sudo systemctl restart clickhouse-server
      

6. Install and configure the application:

   1. In the Marketplace, find Chproxy and click Create VM:

      1. Under Network settings, specify the earlier created cloud network, subnet, and security group for vm-proxy.

      2. Under Access, specify the username and public SSH key for connection to the VM.

      3. Under General information, specify the VM name: vm-proxy.

      4. Complete setting up your VM and click Create VM.

         Wait for the VM to be created and the application to be installed: this may take up to 10 minutes.

   2. Learn the public IP address of vm-proxy.

   3. Connect to vm-proxy over SSH. Use the username you set when creating the VM and the private SSH key you created earlier.

   4. Replace the /etc/chproxy/chproxy.yml file contents with the following:

      hack_me_please: true
      
      server:
        http:
            listen_addr: ":8123"
      
      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: ["<VM_public_IP_address>:8123"]
      

      In the nodes field, specify vm-test's public IP address.

      We recommend using hack_me_please: false in the production environment.

   5. Add a rule allowing incoming connections to port 8123:

      sudo iptables -I INPUT -p tcp --dport 8123 -j ACCEPT
      sudo apt-get update && sudo apt-get install -y netfilter-persistent
      sudo netfilter-persistent save
      

   6. Restart Chproxy and check its status:

      sudo systemctl restart chproxy
      sudo systemctl status chproxy
      

      Result:

      ● chproxy.service - Chproxy
          Loaded: loaded (/etc/systemd/system/chproxy.service; enabled; preset: enabled)
          Active: active (running) since Thu 2026-03-05 23:10:11 UTC; 7s ago
            Docs: https://www.chproxy.org/
      ...
      Mar 05 23:10:11 vm-proxy chproxy[1046]: INFO: 2026/03/05 23:10:11 main.go:190: Serving http on ":8123"
      

7. Test your connection:

   1. Connect to vm-test over SSH.

   2. Run the command below specifying the vm-proxy public IP address:

      curl "http://<VM_public_IP_address>:8123/?query=SELECT%201"
      

      Result:

      1
      

      If the command is successful, your ClickHouse^® on vm-test is connected to Chproxy on vm-proxy.

• Load balancing across multiple ClickHouse^® clusters.
• Restricted user access to specific clusters based on IP addresses.
• Response caching to improve query performance.
• Health monitoring of ClickHouse^® nodes and automatic traffic failover.
• Controlling query rates and execution times for individual users.
• Automatic issuance and renewal of HTTPS certificates via Let’s Encrypt^®.
• Masking actual ClickHouse^® credentials from client applications.

Yandex Cloud technical support is available 24/7. The types of requests you can submit and the relevant response times depend on your pricing plan. You can switch to the paid support plan in the management console. You can learn more about the technical support terms and conditions here.