Implementation:ClickHouse ClickHouse Nfpm Client Package

Knowledge Sources	ClickHouse
Domains	Packaging
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for generating the clickhouse-client DEB and RPM packages provided by the nfpm external packaging tool and its YAML configuration.

Description

The clickhouse-client package provides the ClickHouse command-line tools as symlinks to the main clickhouse binary. This implements the multi-call binary pattern, where a single executable serves as multiple distinct tools based on the name used to invoke it (argv[0] dispatch).

The package includes 12 tool entry points: clickhouse-benchmark, clickhouse-compressor, clickhouse-format, clickhouse-client, clickhouse-local, ch, chc, chl, clickhouse-obfuscator, clickhouse-chdig, and chdig. Each is a symlink or wrapper that points to the main binary installed by the clickhouse-common-static package.

The package also includes a client configuration file at /etc/clickhouse-client/config.xml marked as config|noreplace to preserve operator customizations across upgrades.

It declares replaces and conflicts with the legacy clickhouse-compressor package, since that tool's functionality is now integrated into the unified binary.

Usage

Use this package configuration when building the ClickHouse client tools package for distribution. The nfpm tool should be invoked from the packages/ directory after staging all symlinks and the client configuration file in the root/ subdirectory.

Code Reference

Source Location

Repository: ClickHouse
File: packages/clickhouse-client.yaml (lines 1--72)

Signature

name: "clickhouse-client"
arch: "${DEB_ARCH}"
platform: "linux"
version: "${CLICKHOUSE_VERSION_STRING}"
vendor: "ClickHouse Inc."
homepage: "https://clickhouse.com"
license: "Apache"
section: "database"
priority: "optional"
maintainer: "ClickHouse Dev Team <packages+linux@clickhouse.com>"

replaces:
- clickhouse-compressor
conflicts:
- clickhouse-compressor

overrides:
  deb:
    depends:
    - clickhouse-common-static (= ${CLICKHOUSE_VERSION_STRING})
  rpm:
    depends:
    - clickhouse-common-static = ${CLICKHOUSE_VERSION_STRING}

contents:
- src: root/etc/clickhouse-client/config.xml
  dst: /etc/clickhouse-client/config.xml
  type: config|noreplace
- src: root/usr/bin/clickhouse-benchmark
  dst: /usr/bin/clickhouse-benchmark
- src: root/usr/bin/clickhouse-compressor
  dst: /usr/bin/clickhouse-compressor
- src: root/usr/bin/clickhouse-format
  dst: /usr/bin/clickhouse-format
- src: root/usr/bin/clickhouse-client
  dst: /usr/bin/clickhouse-client
- src: root/usr/bin/clickhouse-local
  dst: /usr/bin/clickhouse-local
- src: root/usr/bin/ch
  dst: /usr/bin/ch
- src: root/usr/bin/chc
  dst: /usr/bin/chc
- src: root/usr/bin/chl
  dst: /usr/bin/chl
- src: root/usr/bin/clickhouse-obfuscator
  dst: /usr/bin/clickhouse-obfuscator
- src: root/usr/bin/clickhouse-chdig
  dst: /usr/bin/clickhouse-chdig
- src: root/usr/bin/chdig
  dst: /usr/bin/chdig

API

# Generate DEB package:
nfpm package -p deb -f clickhouse-client.yaml

# Generate RPM package:
nfpm package -p rpm -f clickhouse-client.yaml

I/O Contract

Inputs

Name	Type	Required	Description
`root/etc/clickhouse-client/config.xml`	XML config file	Yes	Default client configuration file
`root/usr/bin/clickhouse-benchmark`	Symlink	Yes	Symlink to `clickhouse` for benchmarking tool
`root/usr/bin/clickhouse-compressor`	Symlink	Yes	Symlink to `clickhouse` for compression tool
`root/usr/bin/clickhouse-format`	Symlink	Yes	Symlink to `clickhouse` for SQL formatter
`root/usr/bin/clickhouse-client`	Symlink	Yes	Symlink to `clickhouse` for interactive SQL client
`root/usr/bin/clickhouse-local`	Symlink	Yes	Symlink to `clickhouse` for local analytics engine
`root/usr/bin/ch`	Symlink	Yes	Short alias symlink to `clickhouse`
`root/usr/bin/chc`	Symlink	Yes	Short alias for `clickhouse-client`
`root/usr/bin/chl`	Symlink	Yes	Short alias for `clickhouse-local`
`root/usr/bin/clickhouse-obfuscator`	Symlink	Yes	Symlink to `clickhouse` for data obfuscation tool
`root/usr/bin/clickhouse-chdig`	Symlink	Yes	Symlink to `clickhouse` for diagnostics tool
`root/usr/bin/chdig`	Symlink	Yes	Short alias for `clickhouse-chdig`
`${CLICKHOUSE_VERSION_STRING}`	Environment variable	Yes	Version string for the package
`${DEB_ARCH}`	Environment variable	Yes	Target architecture

Outputs

Name	Type	Description
`clickhouse-client_${VERSION}_${ARCH}.deb`	Debian package	DEB package containing client tools, symlinks, and configuration
`clickhouse-client-${VERSION}.${ARCH}.rpm`	RPM package	RPM package with equivalent contents

Installed File Layout

The package installs the following files on the target system:

/etc/clickhouse-client/config.xml          # Client config (noreplace)
/usr/bin/clickhouse-benchmark              # Benchmarking tool
/usr/bin/clickhouse-compressor             # Compression utility
/usr/bin/clickhouse-format                 # SQL formatter
/usr/bin/clickhouse-client                 # Interactive SQL client
/usr/bin/clickhouse-local                  # Local analytics engine
/usr/bin/ch                                # Short alias
/usr/bin/chc                               # Short alias for client
/usr/bin/chl                               # Short alias for local
/usr/bin/clickhouse-obfuscator             # Data obfuscation
/usr/bin/clickhouse-chdig                  # Diagnostics tool
/usr/bin/chdig                             # Short alias for chdig
/usr/share/doc/clickhouse-client/AUTHORS
/usr/share/doc/clickhouse-client/CHANGELOG.md
/usr/share/doc/clickhouse-client/LICENSE
/usr/share/doc/clickhouse-client/README.md

Symlink Dispatch Table

The following table shows how each tool name maps to the behavior selected by the ClickHouse binary:

Symlink Name	Tool Behavior
`clickhouse-client`	Interactive SQL client for connecting to ClickHouse servers
`clickhouse-local`	Standalone analytical engine for processing local files
`clickhouse-benchmark`	Load testing and query benchmarking tool
`clickhouse-format`	SQL formatting and pretty-printing
`clickhouse-compressor`	Data compression/decompression using ClickHouse codecs
`clickhouse-obfuscator`	Data obfuscation for creating anonymized datasets
`clickhouse-chdig` / `chdig`	ClickHouse diagnostics
`ch`	Alias for ClickHouse main entry
`chc`	Alias for `clickhouse-client`
`chl`	Alias for `clickhouse-local`

Usage Examples

# Set required environment variables:
export CLICKHOUSE_VERSION_STRING="24.3.1.1"
export DEB_ARCH="amd64"

# Stage symlinks in the root directory:
mkdir -p packages/root/usr/bin
mkdir -p packages/root/etc/clickhouse-client
for tool in clickhouse-benchmark clickhouse-compressor clickhouse-format \
            clickhouse-client clickhouse-local ch chc chl \
            clickhouse-obfuscator clickhouse-chdig chdig; do
    ln -sf clickhouse "packages/root/usr/bin/$tool"
done

# Generate the DEB package:
cd packages
nfpm package -p deb -f clickhouse-client.yaml

Related Pages

Implements Principle

Principle:ClickHouse_ClickHouse_Client_Package_Configuration

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment