ClickHouse Configuration Guide

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