Fun facts

A few things that stand out about this codebase.

The first commit is from 2008

The initial commit lands on 2008-12-01. ClickHouse predates Spark, Snowflake, Iceberg, and most of the modern OLAP ecosystem. The directory was called dbms/ for its first dozen years and was renamed to src/ only on 2020-04-03 — the first commit on src/ literally has the message dbms/ → src/.

The name has nothing to do with HTTP clicks

The "click" in ClickHouse is a Yandex.Metrica clickstream — page hits, ad impressions, web events. The original use case was to power the analytics behind Yandex's web tracking. The DBMS could chew through trillions of click events for any user query, hence the name.

A single binary that is many binaries

clickhouse is a multi-call executable. The dispatch table is in programs/main.cpp and routes to server, client, local, keeper, keeper-client, compressor, format, obfuscator, disks, git-import, static-files-disk-uploader, static-files-disk-uploader, extract-from-config, benchmark, su, install, start, stop, restart, status, zookeeper-dump-tree, and a handful more. Symlinking clickhouse-client simply runs the same binary with the client mode selected by argv[0].

The same file blocks dlopen outright:

extern "C"
{
    void * dlopen(const char *, int) { return nullptr; }
    ...
}

The comment is candid: "We absolutely discourage the ancient technique of loading 3rd-party uncontrolled dangerous libraries into the process address space, because it is insane."

Keeper is a database that talks ZooKeeper

clickhouse-keeper (src/Coordination/) is a Raft state machine that speaks the ZooKeeper wire protocol. You can swap in Keeper for an existing ZooKeeper ensemble without changing application clients. It uses NuRaft for consensus, RocksDB for the log, and an in-memory KV store as the state machine.

Some files are very long

src/Storages/StorageReplicatedMergeTree.cpp is over 520 KB. src/Interpreters/Context.cpp is over 310 KB. src/Storages/MergeTree/KeyCondition.cpp is over 220 KB. These are not generated; they have been hand-edited over many years. They are also surprisingly readable — comments and helper functions keep them navigable.

ClickHouse vendors everything

There are ~256 submodules under contrib/. The project re-vendors Boost, Poco, Arrow, Parquet, RocksDB, OpenSSL, gRPC, protobuf, LZ4, ZSTD, Avro, Iceberg, Delta-Kernel, Hive-related libs, usearch, SimSIMD, cppkafka, librdkafka, …. The build system in cmake/ and the per-library *-cmake/ directories under contrib/ exists largely so this army of dependencies can be statically linked into one executable.

A static dlopen panic in the comments

/// We absolutely discourage the ancient technique of loading 3rd-party uncontrolled dangerous libraries into the process address space, because it is insane.

That is the actual comment that lives next to the dlopen override.

"ASan, not ASAN"

AGENTS.md is unusually opinionated. Among other things, it asks contributors to:

• Use Allman braces (CI enforces it).
• Never use sleep in C++ to fix race conditions ("this is stupid and not acceptable").
• Say "exception" rather than "crash" because logical errors don't crash the release build.
• Write ASan, not ASAN ("there are two words: Address Sanitizer").
• Refer to a function as f, not f(), when you mean the function itself rather than its application.

Settings, settings, settings

The runtime has well over 1500 settings. They are registered through X-macros in src/Core/Settings.cpp, and a tracker (AGENTS.md again) demands an entry in the changelog whenever one is added or renamed. There is a system table for every group: system.settings, system.server_settings, system.merge_tree_settings, system.user_settings, plus hidden ones for testing.

A built-in dashboard

programs/server/dashboard.html, play.html, binary.html, merges.html, and jemalloc.html are static assets compiled into the server. Hit http://server:8123/dashboard and you get a real-time SQL-driven dashboard for system metrics. The server also embeds play.html, an in-browser SQL playground.

A Clojure jepsen suite

tests/jepsen.clickhouse/ is a Clojure project that runs Aphyr-style jepsen tests against clickhouse-keeper and replicated tables. It is one of the few corners of the repo that is not C++/Python.

Custom build tools

utils/c++expr is a wrapper that compiles a one-line expression against the ClickHouse build to print the size, alignment, or cost of any internal type. utils/auto-bisect/ automates git bisect on test failures. utils/changelog/ regenerates the giant CHANGELOG.md from PR labels. .claude/tools/ ships JS and Python helpers for fetching CI reports and analyzing assembly. The project leans heavily on its own tooling, much of which is documented in Tooling.

Approximately 300,000 commits

master is just shy of 230,000 commits in this checkout (the rest live on long-lived branches). Few open-source projects have this much density. A typical day still sees dozens of merges.