clickhouse-server

The long-running database server. The entry point is programs/server/Server.cpp, a ~195 KB file that wires together every subsystem.

Purpose

clickhouse-server is the production ClickHouse process. It listens on the configured ports (HTTP, native TCP, MySQL, Postgres, gRPC, ArrowFlight, interserver HTTP, …), loads users and grants from users.xml/RBAC, attaches every database from disk, and starts the background pools that drive merges, mutations, fetches, moves, and TTL.

Source layout

Path	Purpose
programs/server/Server.cpp	Entry point: argv parsing, config load, listener wiring, graceful shutdown.
programs/server/Server.h	Declarations.
programs/server/MetricsTransmitter.cpp	Optional Graphite/StatsD push of system.metrics and system.events.
programs/server/clickhouse-server.cpp	Tiny entry shim.
programs/server/config.xml	The default server configuration (~98 KB).
programs/server/users.xml	The default user/profile configuration.
programs/server/config.d/, users.d/	Drop-in directories for overrides.
programs/server/dashboard.html, play.html, binary.html, merges.html, jemalloc.html	Static dashboards baked into the binary.
programs/server/fuzzers/	libFuzzer harnesses that exercise the server.

Startup sequence

graph TD
    Main[main.cpp dispatcher] --> ServerEntry[Server::main]
    ServerEntry --> Config[ConfigReloader<br/>config.xml + config.d/]
    Config --> Logger[Logger init<br/>src/Loggers]
    Logger --> Mem[MemoryTracker, jemalloc]
    Mem --> Context[Context::createGlobal<br/>src/Interpreters]
    Context --> Disks[Disks + ObjectStorages]
    Context --> Coord[ZooKeeper / Keeper client]
    Context --> Access[Access control loader<br/>src/Access]
    Access --> Loaders[ExternalDictionariesLoader<br/>UserDefinedSQLObjects]
    Loaders --> Databases[Database loader<br/>loadMetadata.cpp]
    Databases --> Listeners[HTTPHandler<br/>TCPHandler<br/>MySQL/Postgres/gRPC/ArrowFlight<br/>InterserverIO HTTP]
    Listeners --> Background[Background pools<br/>BackgroundSchedulePool, MergesPool, FetchesPool]
    Background --> Ready[Ready to serve]

The actual flow inside Server.cpp:

1. Parse the command line. Resolve --config-file (/etc/clickhouse-server/config.xml by default).
2. Set up the logger, memory tracker, jemalloc tuning, and signal handlers (via BaseDaemon from src/Daemon/).
3. Run global initializers: phdr_cache, OpenSSL, time-zone DB.
4. Create the global Context (src/Interpreters/Context.cpp). Most subsystems attach to it.
5. Create disks and object-storage caches.
6. Connect to ZooKeeper / clickhouse-keeper (if configured) for replicated tables and DDL.
7. Load access control: users, roles, grants, quotas, row policies, settings profiles.
8. Load named collections, dictionaries, user-defined SQL objects.
9. Walk metadata/<database>/ and recreate every table in memory by re-running their CREATE TABLE statements (loadMetadata.cpp).
10. Start interserver communication and the background pools.
11. Bind listeners for every enabled protocol.
12. Enter the main loop until SIGTERM/SIGINT. On shutdown, gracefully drain in-flight queries, flush logs, detach databases.

Listeners and protocols

Server.cpp instantiates handlers from src/Server/. Each handler is paired with a protocol class:

Protocol	Handler	Default port
HTTP / HTTPS	HTTPHandler	8123 / 8443
Native TCP / TLS	TCPHandler	9000 / 9440
Interserver HTTP	InterserverIOHTTPHandler	9009
MySQL wire	MySQLHandler	9004
PostgreSQL wire	PostgreSQLHandler	9005
gRPC	GRPCServer	9100
ArrowFlight	ArrowFlight*	9006
Prometheus exposition	PrometheusMetricsWriter	9363
Replicas Status (HTTP)	ReplicasStatusHandler	8123 (path)

See API → HTTP interface and API → Native TCP.

Configuration

programs/server/config.xml is the documented schema. It includes config.d/ overrides. Key sections:

• <logger>, <openSSL>, <keep_alive_timeout>.
• <remote_servers> — clusters for Distributed tables.
• <zookeeper> / <keeper_server> — coordination backend.
• <storage_configuration> — disks, volumes, storage policies.
• <merge_tree> / <merge_tree_setting> — engine defaults.
• <users_config> / <user_directories> — RBAC backends.
• <dictionaries_config> — external dictionary configs.
• <query_log>, <part_log>, <text_log>, <metric_log>, <asynchronous_metric_log> — system tables.
• <async_metrics>, <background_pool_size>.

YAML is also accepted (config.yaml.example is the canonical sample). See Reference → configuration.

Background pools

The server runs several thread pools:

• BackgroundSchedulePool — long-lived periodic tasks (replication queue, fetches, cleanup).
• BackgroundMergesAndMutationsPool / BackgroundMovesPool / BackgroundFetchesPool — MergeTree work.
• BackgroundCommonPool — generic catch-all.
• Per-task pools for distributed inserts, dictionary loads, etc.

The pool sizes are configurable in config.xml and queryable via system.metrics.

Static-asset dashboards

The server embeds:

• dashboard.html — real-time SQL-driven dashboard (/dashboard).
• play.html — in-browser SQL playground (/play).
• binary.html — symbol info for the running binary.
• merges.html — visualizer for the merge backlog.
• jemalloc.html — jemalloc heap profile viewer.

They are static SPAs that talk to the server's own HTTP API.

Graceful shutdown

Server.cpp installs handlers for SIGINT/SIGTERM. On shutdown it:

1. Stops accepting new connections.
2. Cancels any running queries cooperatively.
3. Flushes all system.*_log tables.
4. Drains background pools.
5. Detaches each database (DatabaseAtomic style atomic detach).
6. Releases ZooKeeper sessions cleanly.
7. Joins remaining threads and exits.

A hard shutdown leaves the process in a recoverable state because every persistent state is on disk in immutable parts plus a Keeper-coordinated replication log.

Entry points for modification

• To add a new server-side option, edit src/Core/ServerSettings.cpp.
• To add a new wire protocol, add a handler class under src/Server/ and register it in Server.cpp next to the existing listeners.
• To change startup ordering, edit Server::main in programs/server/Server.cpp.

Related pages

• Architecture
• Server protocols
• Configuration reference
• Coordination