ClickHouse C – Talk to ClickHouse using its native binary protocol

ClickHouse released clickhouse-c, a header-only C client that talks to ClickHouse over its Native binary protocol and Native Format blocks, with no link-time dependencies beyond libc. The library is designed for embedding inside PostgreSQL extensions using palloc arenas and longjmp, and can decode `clickhouse local` output from a pipe without TCP or compression. Users must set `output_format_native_encode_types_in_binary_format = 0` on the server, otherwise `chc_block_read` returns `CHC_ERR_TYPE`.

Header-only C client for the ClickHouse https://clickhouse.com/ Native wire format — the Native Protocol https://clickhouse.com/docs/reference/interfaces/specs/NativeProtocol over TCP carrying Native Format https://clickhouse.com/docs/reference/interfaces/specs/NativeFormat blocks. One core header, plus optional follow-up headers for TCP, compression, codecs, and I/O backends. Designed for embedding inside PostgreSQL extensions palloc arena, longjmp but with no PG-specific code. Including clickhouse.h alone gives a pure block decoder over caller-supplied chc io , usable for reading clickhouse-local 's FORMAT Native from a pipe with no TCP, no compression, no link-time deps beyond libc. Decode a clickhouse local query without TCP or compression. / demo.c — cc -std=c11 -O2 -I. demo.c -o demo / define CHC PROVIDE STDLIB ALLOC define CHC IMPLEMENTATION include "clickhouse.h" include "clickhouse-posix-io.h" include <stdio.h include <unistd.h int main void { / Spawn clickhouse local --format Native -q "..." and read its stdout via a pipe; see examples/minimal decode.c for the full plumbing. / int fd = / read end of pipe from child /; chc alloc al = chc alloc stdlib ; chc posix io state; chc io io; chc posix io init &state, &io, fd, NULL, NULL ; chc block opts opts = {}; / clickhouse-local: no BlockInfo, no custom serialization / / One persistent reader for the whole stream: chc block read keeps bytes read past a block boundary buffered for the next block. / chc err ierr = {}; chc in in; if chc in init &in, &io, &al, opts.read buffer bytes, &ierr = CHC OK { fprintf stderr, "init: %s\n", ierr.msg ; return 1; } for ;; { chc block block = NULL; chc err err = {}; if chc block read &in, &al, &opts, &block, &err = CHC OK { fprintf stderr, "decode: %s\n", err.msg ; return 1; } if block break; for size t r = 0; r < chc block n rows block ; r++ for size t c = 0; c < chc block n columns block ; c++ / dispatch on chc column layout chc block column block, c /; chc block destroy block, &al ; } chc in free &in ; } Runnable end-to-end version: examples/minimal decode.c https://github.com/ClickHouse/clickhouse-c/blob/main/examples/minimal decode.c . Required server setting Query packet for TCP, -- flag for clickhouse local : output format native encode types in binary format = 0 Without it, the server emits binary type tags & chc block read returns CHC ERR TYPE . clickhouse-c is distributed as a flat set of headers: each header contains both declarations & implementation, guarded by a sentinel macro. Exactly one translation unit per consumer defines the implementation macro & includes headers; everyone else includes for declarations only. / consumer/src/clickhouse.c — the one TU that links the library in / define CHC IMPLEMENTATION include "clickhouse.h" include "clickhouse-posix-io.h" / …include clickhouse-client.h, clickhouse-compression.h here for the features you use. / Other TUs include only the public declarations: include "clickhouse.h" include "clickhouse-posix-io.h" / no CHC IMPLEMENTATION here / A stdlib malloc / realloc / free helper is available behind define CHC PROVIDE STDLIB ALLOC before including clickhouse.h . For palloc / repalloc / pfree wiring inside a real PostgreSQL extension, see pg clickhouse https://github.com/ClickHouse/pg clickhouse or pg stat ch https://github.com/ClickHouse/pg stat ch . | Header | Purpose | Links | |---|---|---| | clickhouse.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse.md | Core: types, errors, chc alloc , chc io , type-name parser, block reader & writer | — | | clickhouse-client.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse-client.md | TCP packet loop: Hello / Query / Data / EOS / Exception / Progress / Pong | — | | clickhouse-async.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse-async.md | Ioless client: same packet loop driven by caller byte submission, no socket | — | | clickhouse-compression.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse-compression.md | Compressed-frame layout, CityHash128, chc codec dispatch, LZ4 & ZSTD adapters opt out with CHC NO LZ4 / CHC NO ZSTD | -llz4 -lzstd | | clickhouse-posix-io.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse-posix-io.md | chc io over blocking read 2 / write 2 with EINTR loop & cancel hook | — | | clickhouse-openssl.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse-openssl.md | chc io over SSL read / SSL write | -lssl -lcrypto | Each follow-up header is independent; pick what your build needs. clickhouse-client.h supports ClickHouse 23.3 and newer. Per-header reference in doc/ https://github.com/ClickHouse/clickhouse-c/blob/main/doc ; inline declarations & comments in the headers themselves. Worked examples in examples/ https://github.com/ClickHouse/clickhouse-c/blob/main/examples . Use test.sh https://github.com/ClickHouse/clickhouse-c/blob/main/test.sh to run tests: ./test.sh If errors report missing headers or linker errors, use CFLAGS and LDFLAGS to point to the appropriate directories, e.g., using Homebrew https://brew.sh : CFLAGS=-I/opt/homebrew/include LDFLAGS=-L/opt/homebrew/lib ./test.sh The script runs individual tests in test https://github.com/ClickHouse/clickhouse-c/blob/main/test . To run individual tests, pass their base names without the trailing .c as arguments: ./test.sh test cancel test block decode test client tcp spawns clickhouse server from PATH . Set CHC TEST PORT to test against a running server instead, eg an older release in docker: docker run -d -p 127.0.0.1:19233:9000 clickhouse/clickhouse-server:23.3.22.3 CHC TEST PORT=19233 ./test.sh client tcp tools/capture.py https://github.com/ClickHouse/clickhouse-c/blob/main/tools/capture.py proxies such a server to record replay fixtures like test/ch23 3 sparse.bin https://github.com/ClickHouse/clickhouse-c/blob/main/test/ch23 3 sparse.bin . - HTTP protocol — wrap libcurl directly. - DNS, endpoint round-robin, connection pooling, retry/backoff. - SSL/TLS context lifecycle. chc io callbacks; caller drives OpenSSL. - Threading. Each chc client is single-threaded by design. - Async I/O inside the library. The blocking client calls chc io.read synchronously the callback may do whatever it wants under the hood — epoll, io uring, WaitLatchOrSocket . For an ioless client that performs no I/O at all, driven by caller byte submission in an event loop, see clickhouse-async.h https://github.com/ClickHouse/clickhouse-c/blob/main/doc/clickhouse-async.md . - Variant / Dynamic / JSON / AggregateFunction decoding in v1. The upstream wire format is still shifting in 25.x / 26.x.