ClickHouse C – ネイティブバイナリプロトコルを使用してClickHouseと対話する

clickhouse-c ヘッダーオンリーCクライアントで、ClickHouse Native wire format、つまりTCP上のネイティブプロトコルでネイティブフォーマットブロックを伝送します。1つのコアヘッダーに加え、TCP、圧縮、コーデック、I/Oバックエンド用のオプションのフォローアップヘッダーがあります。PostgreSQL拡張機能（pallocアリーナ、longjmp）に組み込むために設計されていますが、PG固有のコードはありません。clickhouse.hのみを含めると、呼び出し元が供給するchc_ioを介した純粋なブロックデコーダーが得られ、TCP、圧縮、libc以外のリンクタイム依存関係なしで、clickhouse-localのFORMAT Nativeをパイプから読み取るのに使用できます。 クイックスタート TCPや圧縮なしでClickHouseローカルクエリをデコードします。/* 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) { /* `clickhouse local --format Native -q "..."` を起動し、パイプ経由でその標準出力を読み取ります。詳細な配線については、examples/minimal_decode.c を参照してください。*/ int fd = /* 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: BlockInfoなし、カスタムシリアライゼーションなし */ /* ストリーム全体で1つの永続的なリーダー: chc_block_read は、ブロック境界を越えて読み取られたバイトを次のブロックのためにバッファリングします。*/ 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. 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. Integration clickhouse-cは、フラットなヘッダーセットとして配布されます。各ヘッダーには宣言と実装の両方が含まれており、センチネルマクロで保護されています。コンシューマーごとに正確に1つの翻訳単位が実装マクロを定義し、ヘッダーを含みます。それ以外のすべては宣言のみを含みます。/* consumer/src/clickhouse.c — ライブラリをリンクする唯一のTU */ #define CHC_IMPLEMENTATION #include "clickhouse.h" #include "clickhouse-posix-io.h" /* …使用する機能のために clickhouse-client.h, clickhouse-compression.h をここに含める */ 他のTUは公開宣言のみを含みます: #include "clickhouse.h" #include "clickhouse-posix-io.h" /* ここにCHC_IMPLEMENTATION はない */ stdlib の malloc/realloc/free ヘルパーは、clickhouse.h を含める前に #define CHC_PROVIDE_STDLIB_ALLOC の背後で利用可能です。実際のPostgreSQL拡張機能内でのpalloc/repalloc/pfree配線については、pg_clickhouse または pg_stat_ch を参照してください。 ヘッダー ヘッダー 目的 リンク clickhouse.h コア: 型、エラー、chc_alloc、chc_io、型名パーサー、ブロックリーダー＆ライター — clickhouse-client.h TCPパケットループ: Hello / Query / Data / EOS / Exception / Progress / Pong — clickhouse-async.h Iolessクライアント: 呼び出し元によるバイト送信で駆動される同じパケットループ、ソケットなし — clickhouse-compression.h 圧縮フレームレイアウト、CityHash128、chc_codecディスパッチ、LZ4 & ZSTDアダプター（CHC_NO_LZ4 / CHC_NO_ZSTDでオプトアウト） -llz4 -lzstd clickhouse-posix-io.h EINTRループとキャンセルフック付きのブロッキングread(2)/write(2)上のchc_io — clickhouse-openssl.h SSL_read/SSL_write上のchc_io -lssl -lcrypto 各フォローアップヘッダーは独立しています。ビルドに必要なものを選択してください。clickhouse-client.hはClickHouse 23.3以降をサポートしています。ヘッダーごとの参照はdoc/にあり、インライン宣言とコメントはヘッダー自体にあります。例はexamples/にあります。 テスト test.sh を使用してテストを実行します: ./test.sh エラーでヘッダーが見つからない、またはリンカエラーが発生した場合は、適切なディレクトリを指すようにCFLAGSとLDFLAGSを使用してください。例: Homebrewを使用: CFLAGS=-I/opt/homebrew/include LDFLAGS=-L/opt/homebrew/lib ./test.sh スクリプトはtestで個々のテストを実行します。個々のテストを実行するには、それらのベース名（末尾の.cなし）を引数として渡します: ./test.sh test_cancel test_block_decode test_client_tcp PATHからclickhouseサーバーを起動します。代わりに実行中のサーバーに対してテストするには、CHC_TEST_PORTを設定します。例: 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 は、そのようなサーバーをプロキシして、test/ch23_3_sparse.bin のような再生フィクスチャを記録します。 非目標 HTTPプロトコル — libcurlを直接ラップします。DNS、エンドポイントラウンドロビン、コネクションプーリング、リトライ/バックオフ。SSL/TLSコンテキストライフサイクル。chc_ioコールバック;呼び出し元がOpenSSLを駆動します。スレッディング。各chc_clientは設計上シングルスレッドです。ライブラリ内の非同期I/O。ブロッキングクライアントはchc_io.readを同期的に呼び出します（コールバックは内部で何でも行う可能性があります — epoll、io_uring、WaitLatchOrSocket）。イベントループで呼び出し元によるバイト送信で駆動される、I/Oを全く行わないiolessクライアントについては、clickhouse-async.hを参照してください。v1でのVariant / Dynamic / JSON / AggregateFunctionデコーディング。アップストリームのワイヤーフォーマットは25.x / 26.xでまだ変動しています。