Skip to content

clickhouse-server.md

Latest commit

 

History

History
109 lines (83 loc) · 4.07 KB

clickhouse-server.md

File metadata and controls

109 lines (83 loc) · 4.07 KB
Raw

ClickHouse Server Platform

clickhouse-server is the BenchBox platform for benchmarking self-hosted ClickHouse instances - Docker containers, bare-metal servers, and clusters - via the native TCP binary protocol (clickhouse-driver).

Installation

uv add benchbox --extra clickhouse-server
uv add benchbox --extra clickhouse

The two extras are equivalent.

Quick Start

docker run -d --name clickhouse-server \
  -p 9000:9000 -p 8123:8123 \
  clickhouse/clickhouse-server

benchbox run --platform clickhouse-server --benchmark tpch --scale 0.01

The docker run command starts a local ClickHouse server with Docker, and the benchbox run command runs a TPC-H benchmark against it.

Connection Options

Option Default Description
host localhost ClickHouse server hostname
port 9000 Native TCP protocol port
username default Authentication username
password `` Authentication password
secure false Enable TLS 
benchbox run --platform clickhouse-server --benchmark tpch \
  --platform-option host=my-clickhouse.example.com \
  --platform-option port=9000 \
  --platform-option username=default \
  --platform-option password=secret \
  --platform-option secure=false

Performance Options

These carry BenchBox defaults rather than ClickHouse's own, and are set as session settings on each connection.

Option Default Description
max_memory_usage 8GB Per-query memory limit
max_threads 8 Query parallelism (clickhouse-local defaults to 4)
max_execution_time 300 Per-query timeout in seconds
insert_block_size 65536 Rows per native streaming insert block
send_receive_timeout 300 Driver socket timeout in seconds
compression false Disabled by default (clickhouse-cityhash compatibility on Python 3.13+)

insert_block_size rejects 1000 and any non-positive value.

clickhouse-cloud sets max_memory_usage and max_threads to 0 so the managed service handles sizing.

Container memory limits

max_memory_usage is a per-query limit. It does not track any memory limit set on a containerized ClickHouse server. When you run the server in a container, size the two together and leave the container headroom above the per-query limit for background MergeTree merges and caches.

Tuned Runs

--tuning tuned applies a curated template for TPC-H, SSB and TPC-DS: MergeTree sort keys, plus monthly partitions on the TPC-H LINEITEM and ORDERS tables. The same templates serve the local, server and cloud platforms (examples/tunings/clickhouse/, packaged with BenchBox). For other benchmarks there is no curated template, so --tuning tuned resolves to the fallback. ClickHouse's "OLAP session pack" session settings apply to tuned runs either way.

benchbox run --platform clickhouse-server --benchmark tpch --tuning tuned

The templates disable every constraint, so a table the template sorts has no PRIMARY KEY clause and its sort key is the index. A table the template does not tune keeps the schema's primary key and derives its ORDER BY from it. If you supply a template that enables primary_keys, its columns must be a prefix of the tuned sort key, or the run fails before any table is created.

OPTIMIZE TABLE ... FINAL is off by default. To run it on each table after it loads, set --platform-option optimize_after_load=true. It runs on tuned runs only. Its time is reported as phases.post_load_maintenance and is not counted in data-loading time.

Comparison with Other ClickHouse Platforms

clickhouse-local clickhouse-server clickhouse-cloud
Infrastructure None (in-process) Docker / dedicated Managed service
Driver chdb clickhouse-driver clickhouse-connect
Network None TCP 9000 HTTPS 8443
Credentials Not required Optional Required
Windows Not supported Supported Supported

See clickhouse-migration.md for migration from legacy clickhouse:server selectors.