---
title: "ClickHouse Configuration Guide"
---

# ClickHouse Configuration Guide

:::caution[Planned: not in the current release]
ClickHouse protocol support for HeliosDB Full is planned. The current release opens no ClickHouse listener. Reach
the same data over the PostgreSQL listener or `POST /api/v1/query` today. This page
describes the planned interface.
:::

Comprehensive configuration reference for HeliosDB's ClickHouse protocol support.

## Connection Configuration

### Native Protocol (TCP Port 9000)

```python
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

```bash
# 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

```python
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

```python
from clickhouse_driver import CompressionSettings

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

## Query Settings

### Performance Settings

```python
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

```python
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

```go
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

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

## Table Configuration

### MergeTree Settings

```sql
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

```sql
-- 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

```toml
# 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

```sql
-- 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)

```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](https://www.heliosdb.com/docs/full/reference/protocols/clickhouse/readme/) | [COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/clickhouse/compatibility/) | [EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/clickhouse/examples/)