Principle:ClickHouse ClickHouse Client Package Configuration
| Knowledge Sources | |
|---|---|
| Domains | Packaging, Distribution |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Client package configuration is the practice of distributing multiple command-line tools from a single binary through symlink-based dispatch, packaged with appropriate configuration files and dependency declarations.
Description
ClickHouse compiles into a single monolithic binary that contains all functionality: server, client, local analytics engine, benchmarking tool, data obfuscator, format converter, and more. Rather than shipping separate binaries for each tool, the client package creates symbolic links that point to the main clickhouse binary. When invoked through a symlink, the binary inspects argv[0] (the name it was called with) to determine which tool's behavior to execute.
The client package bundles the following tools via symlinks:
clickhouse-client: Interactive SQL client for connecting to ClickHouse servers.clickhouse-local: Standalone analytical engine for processing local files without a server.clickhouse-benchmark: Load testing and benchmarking tool for ClickHouse queries.clickhouse-format: SQL formatting and pretty-printing utility.clickhouse-compressor: Data compression/decompression using ClickHouse codecs.clickhouse-obfuscator: Data obfuscation tool for creating anonymized datasets.clickhouse-chdig/chdig: ClickHouse diagnostics tool.ch: Short alias forclickhouse-localor the main binary.chc: Short alias forclickhouse-client.chl: Short alias forclickhouse-local.
This approach offers disk space savings, atomic updates (upgrading the single binary updates all tools simultaneously), and simplified distribution.
Usage
Client package configuration should be applied when:
- Building the
clickhouse-clientDEB or RPM package for distribution. - Deploying ClickHouse command-line tools on developer workstations or analytics servers.
- Adding a new CLI tool to the ClickHouse distribution (by adding a new symlink entry to the package YAML).
- Understanding tool invocation and how a single binary dispatches to different behaviors.
Theoretical Basis
Symlink-Based Multi-Call Binary Pattern
The multi-call binary pattern, popularized by BusyBox in the embedded Linux world, uses a single executable to provide the functionality of many distinct programs. The dispatch mechanism works as follows:
- The binary is installed at a canonical path (e.g.,
/usr/bin/clickhouse). - Symbolic links are created pointing to the binary, each named after a specific tool (e.g.,
/usr/bin/clickhouse-client -> clickhouse). - When the operating system executes a symlink, it resolves to the actual binary but passes the symlink name as
argv[0]. - The binary's
mainfunction inspectsargv[0]and dispatches to the appropriate tool implementation.
This pattern has several advantages for a project like ClickHouse:
- Single compilation unit: All tools share the same codebase and are always at the same version.
- Shared libraries: Common code (parsers, formatters, compression codecs) is linked once rather than duplicated across multiple binaries.
- Atomic updates: Upgrading the base
clickhousebinary automatically upgrades all tools. - Disk efficiency: Symlinks consume negligible disk space compared to full binary copies.
Short Aliases
In addition to the full-name symlinks, the client package provides abbreviated aliases (ch, chc, chl) for frequently used tools. These follow the Unix tradition of short command names for interactive use while retaining the longer names for scripts and documentation clarity.
Dependency and Conflict Management
The client package declares:
- Dependency on
clickhouse-common-staticat the exact same version, ensuring the base binary is installed. - Replaces and conflicts with
clickhouse-compressor, because the compressor functionality was historically a separate package that is now integrated into the client package.
This conflict resolution ensures clean upgrades from older ClickHouse versions where the compressor was distributed independently.
Configuration Files
The client package includes a default configuration file at /etc/clickhouse-client/config.xml marked as config|noreplace. This file controls client-side settings such as default output format, connection timeouts, and server endpoints. The noreplace flag ensures operator customizations survive package upgrades.