clickhouse/clickhouse

Tooling

ClickHouse ships with a substantial collection of build, debug, and analysis helpers. They live in three places: utils/, ci/ (the in-house Praktika runner), and .claude/tools/ (helpers maintained for AI coding agents but useful for humans too).

CMake / ninja

The top-level CMakeLists.txt configures the entire build (≈30 KB).
PreLoad.cmake sets sensible defaults before cmake runs.
Toolchain detection lives in cmake/ — compiler version pins, sanitizer flags, target arches, link-time options.
Per AGENTS.md: don't pass -j to ninja; don't compute nproc. Let ninja decide. Always redirect build output to a log file in the build directory.

`utils/c++expr`

A wrapper around clang++ that compiles a one-line expression against the ClickHouse build and prints the result. Useful for measuring sizes/alignments and for cheap microbenchmarks.

# Size of a Block
.claude/tools/cppexpr.sh -i Core/Block.h 'OUT(sizeof(DB::Block))'

# Size + alignment of a Field
.claude/tools/cppexpr.sh -i Core/Field.h 'OUT(sizeof(DB::Field)) OUT(alignof(DB::Field))'

# Benchmark a snippet
.claude/tools/cppexpr.sh -i Common/Stopwatch.h -b 100000 'Stopwatch sw;'

When asked about the size, layout, or alignment of a ClickHouse data structure, this is the right tool — much more reliable than guessing.

`.claude/tools/analyze-assembly.py`

Disassembles a function from a compiled binary, builds a CFG, computes spill/branch/call density, and reports findings. Use it for hot-path investigations:

python3 .claude/tools/analyze-assembly.py build/programs/clickhouse "insertRangeFrom" --search
python3 .claude/tools/analyze-assembly.py build/programs/clickhouse 0x0dc7c780      # symbol at address
python3 .claude/tools/analyze-assembly.py --before old/clickhouse --after new/clickhouse "func"

Supports llvm-mca micro-architectural analysis (--mca --mcpu=znver3), source-interleaved disassembly (--source), and perf-map weighting.

`.claude/tools/fetch_ci_report.js`

Fetches Praktika CI reports for a PR or a single CI URL without a browser. Per AGENTS.md, this is the preferred way to triage CI failures.

node .claude/tools/fetch_ci_report.js "https://github.com/ClickHouse/ClickHouse/pull/12345"
node .claude/tools/fetch_ci_report.js "<url>" --failed --cidb
node .claude/tools/fetch_ci_report.js "<url>" --download-logs

After downloading logs, the typical follow-up is:

tar -xzf /tmp/ci_logs.tar.gz ci/tmp/pytest_parallel.jsonl
grep "test_name" ci/tmp/pytest_parallel.jsonl | python3 -c "import sys,json; [print(json.loads(l).get('longrepr','')) for l in sys.stdin if 'failed' in l]"

`.claude/tools/fetch_perf_report.py`

Fetches the machine-readable all-query-metrics.tsv from S3 for each performance shard and classifies queries as changed or unstable. Default output shows changed + unstable queries only.

python3 .claude/tools/fetch_perf_report.py "<pr-url>"
python3 .claude/tools/fetch_perf_report.py "<pr-url>" --arch arm
python3 .claude/tools/fetch_perf_report.py "<pr-url>" --summary
python3 .claude/tools/fetch_perf_report.py "<pr-url>" --json

`utils/changelog/`

Regenerates CHANGELOG.md from PR labels and commit messages. Used by release tooling.

`utils/auto-bisect/`

Automates git bisect for failing tests. Given a test name and a known-good/known-bad commit pair, it isolates the offending commit.

`utils/list-versions/`, `utils/list-licenses/`

Generate release.json, licenses.json, and the SBOM-style outputs the release pipeline consumes.

`utils/clickhouse-diagnostics/`

A self-contained diagnostic dumper. Run it on a problem server to collect logs, configs, and system.* snapshots into a single archive for support cases.

`utils/parts-visualizer/`, `utils/trace-visualizer/`, `utils/tests-visualizer/`

Browser-based visualizations powered by ClickHouse query results. Useful when staring at a merge backlog or a query trace.

`utils/keeper-overload/`, `utils/keeper-bench`

Stress and benchmark clickhouse-keeper.

`utils/grpc-client/`

Reference gRPC client. The corresponding server-side code is in src/Server/GRPCServer.cpp.

`tests/clickhouse-test`

The big stateless-test driver. ~250 KB of Python that handles parallelism, isolation, retries, sanitizer-aware skip patterns, and reference-output comparison. The add-test helper uses it to bootstrap new test files.

Praktika CI runner

ci/praktika/ is the in-house workflow framework that drives builds and tests across hundreds of jobs. Workflow definitions live in ci/workflows/, jobs in ci/jobs/, and the docker images in ci/docker/. Per AGENTS.md, the Praktika reports linked from the robot's PR comment are the source of truth — the GitHub Actions tab is secondary.

To run Praktika jobs locally:

python -m ci.praktika run "integration" --test test_some_integration_thing
python -m ci.praktika run "stateless"

The full job catalog is enumerated by ci/praktika/__main__.py.

docker scripts

docker/ hosts the official Docker images for clickhouse-server, clickhouse-client, and clickhouse-keeper. tests/docker_scripts/ hosts test-only images. ci/docker/ hosts the CI runner images.

Static-asset tooling

programs/server/dashboard.html, play.html, binary.html, merges.html, jemalloc.html are baked into the server binary. Editing them is a normal source change; the linked js/ directory is similarly compiled in.