ClickHouse Configuration Guide¶

Comprehensive configuration reference for HeliosDB's ClickHouse protocol support.

Connection Configuration¶

Native Protocol (TCP Port 9000)¶

from clickhouse_driver import Client

# Basic connection
client = Client(
    host='localhost',
    port=9000,
    user='default',
    password='',
    database='default'
)

# With compression and SSL
client = Client(
    host='clickhouse.example.com',
    port=9000,
    user='analytics_user',
    password='secure_password',
    database='analytics',
    compression='lz4',
    ssl_verify=True,
    ssl_check_hostname=True
)

Connection String Format¶

clickhouse://username:password@host:9000/database?compression=lz4

Connection Parameters¶

Parameter	Type	Default	Description
`host`	string	localhost	Server hostname
`port`	int	9000	Native protocol port
`user`	string	default	Username
`password`	string	None	Password
`database`	string	default	Database name
`compression`	string	None	Compression type (lz4, lz4hc, zstd)
`ssl_verify`	bool	False	Verify SSL certificate
`ssl_check_hostname`	bool	False	Check SSL hostname

HTTP Protocol (Port 8123)¶

cURL Examples¶

# Simple query
curl 'http://localhost:8123/?query=SELECT%20count()%20FROM%20events'

# With authentication
curl -u analytics:password 'http://localhost:8123/?query=SELECT%20count()%20FROM%20events'

# With compression
curl -H 'Accept-Encoding: gzip' \
  'http://localhost:8123/?query=SELECT%20*%20FROM%20events%20LIMIT%2010'

Python HTTP Client¶

import requests

def query_clickhouse(sql):
    response = requests.get(
        'http://localhost:8123/',
        params={'query': sql},
        auth=('analytics', 'password')
    )
    return response.text

result = query_clickhouse('SELECT count() FROM events')

Compression Settings¶

Available Compression Types¶

Type	Speed	Ratio	Use Case
lz4	450 MB/s	2-3x	Real-time (default)
lz4hc	200 MB/s	3-5x	Balanced
zstd	140 MB/s	5-15x	Storage savings
none	600 MB/s	1x	Maximum speed

Configuring Compression¶

from clickhouse_driver import CompressionSettings

client = Client(
    host='localhost',
    compression=CompressionSettings(
        type='lz4'
    )
)

Query Settings¶

Performance Settings¶

client = Client(
    host='localhost',
    settings={
        # Execution timeouts
        'max_query_execution_time': 60,
        'timeout_before_checking_execution_speed': 10,

        # Memory management
        'max_memory_usage': 5000000000,  # 5GB
        'max_memory_usage_for_user': 10000000000,  # 10GB
        'memory_tracker_fault_probability': 0,

        # GROUP BY optimization
        'max_rows_to_group_by': 100000000,
        'group_by_two_level_threshold': 100000,
        'group_by_overflow_mode': 'break',

        # JOIN optimization
        'max_rows_in_join': 1000000,
        'join_overflow_mode': 'throw',

        # Distributed queries
        'distributed_aggregation_memory_efficient': 1,

        # Other
        'use_uncompressed_cache': 1,
        'max_insert_threads': 4
    }
)

Setting Reference¶

Setting	Type	Default	Description
`max_query_execution_time`	int	0	Max query time (seconds)
`max_memory_usage`	int	0	Max memory per query
`max_rows_to_group_by`	int	0	Max rows in GROUP BY
`group_by_overflow_mode`	string	throw	Overflow handling
`max_rows_in_join`	int	0	Max rows in JOIN

TLS/SSL Configuration¶

Basic TLS¶

client = Client(
    host='clickhouse.example.com',
    port=9440,  # TLS port
    user='default',
    password='password',
    ssl_verify=True,
    ssl_certfile='/path/to/client.crt',
    ssl_keyfile='/path/to/client.key',
    ca_certs='/path/to/ca.crt'
)

TLS Parameters¶

Parameter	Type	Default	Description
`ssl_verify`	bool	False	Verify certificate
`ssl_check_hostname`	bool	False	Check hostname
`ssl_certfile`	string	None	Client certificate
`ssl_keyfile`	string	None	Client key
`ca_certs`	string	None	CA certificate

Connection Pooling¶

Go Client Pooling¶

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"localhost:9000"},
    Auth: clickhouse.Auth{
        Database: "default",
        Username: "default",
        Password: "",
    },
    MaxOpenConns: 5,
    MaxIdleConns: 5,
    ConnMaxLifetime: time.Hour,
})

Python Client¶

# Configure connection pool size
client = Client(
    host='localhost',
    settings={
        'max_connections': 50,
        'connection_timeout': 30
    }
)

Table Configuration¶

MergeTree Settings¶

CREATE TABLE events (
  timestamp DateTime,
  event_type String,
  user_id UInt32,
  value Float32
) ENGINE = MergeTree()
ORDER BY (timestamp, user_id)
PRIMARY KEY (timestamp)
PARTITION BY toYYYYMM(timestamp)
SETTINGS
  index_granularity = 8192,
  min_compress_block_size = 65536,
  max_compress_block_size = 1048576;

TTL Configuration¶

-- Auto-delete after 90 days
CREATE TABLE events (
  timestamp DateTime,
  event_type String,
  value Float32
) ENGINE = MergeTree()
ORDER BY timestamp
PARTITION BY toYYYYMM(timestamp)
TTL timestamp + INTERVAL 90 DAY;

-- Tiered storage
CREATE TABLE analytics (
  timestamp DateTime,
  event_type String,
  value Float32
) ENGINE = MergeTree()
ORDER BY timestamp
TTL (
    timestamp + INTERVAL 30 DAY TO DISK 'hot',
    timestamp + INTERVAL 365 DAY TO DISK 'cold'
);

HeliosDB-Specific Settings¶

Server Configuration¶

# heliosdb.toml
[clickhouse]
enabled = true
tcp_port = 9000
http_port = 8123
bind = "0.0.0.0"
max_connections = 10000

[clickhouse.auth]
password = "your_secure_password"
users_config = "/etc/heliosdb/clickhouse_users.xml"

[clickhouse.compression]
default = "lz4"
level = 3

[clickhouse.limits]
max_memory_usage = 10737418240  # 10GB
max_query_execution_time = 300

Environment Variables¶

Variable	Description
`HELIOSDB_CLICKHOUSE_TCP_PORT`	Native protocol port
`HELIOSDB_CLICKHOUSE_HTTP_PORT`	HTTP protocol port
`HELIOSDB_CLICKHOUSE_PASSWORD`	Authentication password
`HELIOSDB_CLICKHOUSE_MAX_MEMORY`	Max memory usage

Cluster Configuration¶

Distributed Tables¶

-- Local table on each node
CREATE TABLE events_local (
  timestamp DateTime,
  event_type String,
  value Float32
) ENGINE = MergeTree()
ORDER BY timestamp;

-- Distributed table
CREATE TABLE events_distributed AS events_local
ENGINE = Distributed(
    cluster_name,
    'default',
    'events_local'
);

Cluster Configuration (XML)¶

<remote_servers>
  <cluster_name>
    <shard>
      <replica>
        <host>clickhouse-1</host>
        <port>9000</port>
      </replica>
    </shard>
    <shard>
      <replica>
        <host>clickhouse-2</host>
        <port>9000</port>
      </replica>
    </shard>
  </cluster_name>
</remote_servers>

Related: README.md | COMPATIBILITY.md | EXAMPLES.md

Last Updated: December 2025