Implementation:ClickHouse ClickHouse Clickhouse Server Start
| Knowledge Sources | |
|---|---|
| Domains | Testing |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Concrete tool for starting a ClickHouse server from a local development build, provided by the clickhouse multicall binary.
Description
The clickhouse binary is a single executable that dispatches to multiple sub-programs based on its first positional argument. When invoked with the server sub-command, execution flows through the main function at programs/main.cpp:L330, which iterates the clickhouse_applications dispatch table (lines 157-206). The entry "server" at line 166 maps to mainEntryClickHouseServer, which initializes the server, loads the configuration file, binds to the configured network ports, and enters the main event loop.
The --config-file flag tells the server where to find its XML configuration. The default repository configuration at programs/server/config.xml sets the native TCP protocol port to 9000 and the HTTP interface port to 8123. Once the server is running, it accepts queries from any compatible client.
The dispatch logic works as follows:
- The
mainfunction (line 330) builds an argument vector and sets a default handler (printHelpOnError). - It iterates
clickhouse_applicationscallingisClickhouseAppfor each entry to match the sub-command. - On match, it stores the corresponding function pointer and breaks.
- The matched function is called at line 403:
main_func(argc, argv).
Usage
Use this command whenever you need a running ClickHouse server for local testing. It must be started before invoking the clickhouse-test runner. The server runs in the foreground by default, so it is typically started in a separate terminal session or backgrounded.
Code Reference
Source Location
- Repository: ClickHouse
- File:
programs/main.cpp - Dispatch table: Lines 157-206 (
clickhouse_applicationsarray) - Server entry: Line 166 (
"server"maps tomainEntryClickHouseServer) - Main function: Lines 330-410 (argument parsing and dispatch)
Signature
./build/programs/clickhouse server --config-file ./programs/server/config.xml
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
server |
Positional sub-command | Yes | Selects the server entry point from the clickhouse_applications dispatch table
|
--config-file |
File path (string) | No (defaults to ./config.xml or /etc/clickhouse-server/config.xml) |
Path to the server XML configuration file. For local testing use ./programs/server/config.xml
|
Compiled clickhouse binary |
Executable file | Yes | The result of building the ClickHouse source tree (typically at ./build/programs/clickhouse)
|
| Server config files | XML files | Yes | programs/server/config.xml and referenced includes such as users.xml
|
Outputs
| Name | Type | Description |
|---|---|---|
| Running server process | OS process | A ClickHouse server process listening on configured ports |
| TCP port 9000 | Network listener | Native protocol endpoint used by clickhouse-client and the test runner
|
| HTTP port 8123 | Network listener | HTTP interface endpoint for REST-style queries |
| Server log | File / stdout | Diagnostic output controlled by the <logger> section of config.xml
|
Usage Examples
Start the server from a build directory:
# Start ClickHouse server using the repository config
./build/programs/clickhouse server --config-file ./programs/server/config.xml
Verify the server is responding:
# Use the client to execute a trivial query
./build/programs/clickhouse client -q "SELECT 1"
If the client returns 1, the server is ready to accept test workloads.
Start the server in the background:
./build/programs/clickhouse server --config-file ./programs/server/config.xml &