Configure Query Head Pooling

Use these procedures to enable query head pooling and set up its components. For an overview of how the feature works, see Query head pools.

To set up query head pooling in a basic configuration:

Create at least one additional query head pool.
Enable http_proxy and clickprox.
Enable the query_head_pooling_enabled tunable.
Configure routing rules.
If using database rules, update client applications to pass the database parameter.

Enable query head pooling⚓︎

Query head pooling is disabled by default. These tunables control it:

query_head_pooling_enabled: Enables query head pooling. Disabled by default.
http_proxy.enabled: Enables the HTTP proxy for HTTP connection routing. Required to route HTTP traffic through the HTTP proxy.
query_head_native_routing_enabled: Routes native TCP connections through ClickProx. Enabled by default.
all_clickhouse_http_via_chproxy_enabled: Routes all HTTP connections, including default pool traffic, through the HTTP proxy. When disabled, default pool HTTP traffic goes directly to the query head. Disabled by default.

To support both HTTP and native TCP clients:

Enable Full Query Head Routing
spec:
  http_proxy:
    enabled: true
  clickprox:
    enabled: true
  query_head_pooling_enabled: true
  query_head_native_routing_enabled: true

Configure ClickProx⚓︎

Configure ClickProx with the clickprox tunable:

ClickProx Configuration
spec:
  clickprox:
    enabled: true
    port: 9000
    metrics_port: 9090
    drain_timeout: 30

Field	Description
`enabled`	Enable or disable ClickProx
`port`	Port for incoming native TCP connections
`metrics_port`	Port for Prometheus metrics
`drain_timeout`	Seconds to wait for in-flight connections before shutting down

Create query head pools⚓︎

Create query head pools by adding a pool definition to hydrolixcluster.yaml.

Set the service field to query-head:

Query Head Pool
spec:
  pools:
    analytics-query-head:
      name: analytics-query-head
      service: query-head
      cpu: 4
      memory: 16Gi
      replicas: 2

Configure routing rules⚓︎

Routing rules in the HydrolixCluster spec direct connections to a pool based on the database or username parameter the client supplies. Each routing rule can also set a priority (lower number is higher priority) and a default_query_peer to specify which query-peer pool the query head uses by default. The query-head pool is always the default pool. Routing rules can select either the default or any other existing query head pool.

Route by database⚓︎

Route by Database
spec:
  pools:
    analytics-query-head:
      name: analytics-query-head
      service: query-head
      routing:
        database: hydro.logs
        priority: 10
        default_query_peer: analytics-query-peer

Route by username⚓︎

Route by Username
spec:
  pools:
    analytics-query-head:
      name: analytics-query-head
      service: query-head
      routing:
        username: analyst
        priority: 10
        default_query_peer: analytics-query-peer