ClickHouse C – Talk to ClickHouse using its native binary protocol

ClickHouse/clickhouse-c is a minimalist header-only C client implementing the ClickHouse Native wire format over TCP. The library consists of one core header plus optional follow-up headers for TCP, compression, codecs, and I/O backends. It is designed for embedding inside PostgreSQL extensions but contains no PostgreSQL-specific code. Including clickhouse.h alone provides a pure block decoder over caller-supplied chc_io, usable for reading clickhouse-local's FORMAT Native output from a pipe without TCP, compression, or link-time dependencies beyond libc.

The quickstart demonstrates decoding a clickhouse local query without TCP or compression. A runnable end-to-end version is available in examples/minimal_decode.c. The required server setting is output_format_native_encode_types_in_binary_format = 0; without it, the server emits binary type tags and chc_block_read returns CHC_ERR_TYPE.

Integration follows a single-translation-unit model: exactly one translation unit per consumer defines the CHC_IMPLEMENTATION macro and includes headers, while other TUs include only public declarations. A stdlib malloc/realloc/free helper is available behind CHC_PROVIDE_STDLIB_ALLOC. For palloc/repalloc/pfree wiring inside PostgreSQL extensions, see pg_clickhouse or pg_stat_ch.

Headers include clickhouse.h (core), clickhouse-client.h (TCP packet loop), clickhouse-async.h (ioless client), clickhouse-compression.h (compressed frames, LZ4 & ZSTD adapters), clickhouse-posix-io.h (blocking read/write), and clickhouse-openssl.h (SSL support). Each follow-up header is independent. Testing uses test.sh with CFLAGS and LDFLAGS for configuration.

ClickHouse/clickhouse-c عميل C minimalist ينفذ Format Native wire over TCP. تتكون المكتبة من رأس رئيسي واحد بالإضافة إلى رؤوس تالية اختيارية لـ TCP، compression، codecs، و backends I/O. تم تصميمها للدمج داخل تمديدات PostgreSQL ولكنها لا تحتوي على كود PostgreSQL محدد. يتضمن inclusion clickhouse.h وحدهDecoder كتلة نقي على chc_io المقدم من قبل المستدعي، قابل للقراءة إخراج FORMAT Native من clickhouse-local من خلال أنبوب دون TCP، compression، أو تبعيات وقت الربط باستثناء libc.

يُظهر quickstart decoding查询 clickhouse local بدون TCP أو compression. تتوفر نسخة end-to-end قابلة للتشغيل في examples/minimal_decode.c. إعداد الخادم المطلوب هو output_format_native_encode_types_in_binary_format = 0؛ بدونها، يصدر الخادم علامات نوع ثنائية ويعيد chc_block_read CHC_ERR_TYPE.

يتبع التكامل نموذج وحدة ترجمة واحدة: وحدة ترجمة واحدة بالضبط لكل مستهلك تحدد macro CHC_IMPLEMENTATION وتدرج الرؤوس، بينما تشمل TU الأخرى فقط الإعلانات العامة. helper malloc/realloc/free من stdlib متاح خلف CHC_PROVIDE_STDLIB_ALLOC. للـ wiring palloc/repalloc/pfree داخل تمديدات PostgreSQL، راجع pg_clickhouse أو pg_stat_ch.

تتضمن الرؤوس clickhouse.h (النواة)، clickhouse-client.h (حلقة حزم TCP), clickhouse-async.h (عميل بدون i/o), clickhouse-compression.h (إطارات مضغوطة، مُوَسِّعات LZ4 & ZSTD), clickhouse-posix-io.h (قراءة/كتابة كتلية), و clickhouse-openssl.h (دعم SSL). كل رأس لاحق مستقل. الاختبارات تستخدم test.sh مع CFLAGS و LDFLAGS للتكوين.

ClickHouse/clickhouse-c হলো minimalist C ক্লায়েন্ট যা TCP over Native wire format বাস্তবায়ন করে। এই লাইব্রেরি একটি মূল হেডার প্লাস ঐচ্ছিক ফলো-আপ হেডার TCP, compression, codecs, এবং I/O backends জন্য। এটি PostgreSQL extensions-এর মধ্যে এম্বেড করার জন্য ডিজাইন করা गया है কিন্তু इसमें কোনো PostgreSQL-विशिष्ट কোড নেই। clickhouse.h একমাত্র অন্তর্ভুক্ত করলে একটি puro block decoder পেয়ে যা caller-supplied chc_io ব্যবহার করে, TCP ছাড়া, compression ছাড়া, libc এর বাইরে কোনো link-time নির্ভরতা ছাড়া clickhouse-local-এর FORMAT Native output পড়তে সক্ষম।

কwiaক্টের ডেমো clickhouse localuery TCP বা compression ছাড়া ডিকোডিং প্রদর্শন করে। examples/minimal_decode.c এন্ড-টু-এন্ড সংস্করণ উপলব্ধ। প্রয়োজনীয় সার্ভার সেটিং output_format_native_encode_types_in_binary_format = 0; tanpa এটি, সার্ভার বাইনারি টাইপ ট্যাগs উত্পাদন করে এবং chc_block_read CHC_ERR_TYPE ফেরত দেয়।

একই ট্রান্সলেশন-ইউনিট মডেল অনুসরণ করে ইন্টিগ্রেশন: একে একে उपভোগকারী জন্য একক translation unit CHC_IMPLEMENTATION ম্যাক্রো সংজ্ঞায়িত করে এবং হেডার অন্তর্ভুক্ত করে, আর অন্য TU শুধু পাবলিক ঘোষণা অন্তর্ভুক্ত করে। CHC_PROVIDE_STDLIB_ALLOCের পেছনে stdlib malloc/realloc/free helper উপলব্ধ। PostgreSQL extensions-র মধ্যে palloc/repalloc/pfree wiringের জন্য, pg_clickhouse বা pg_stat_ch দেখুন।

হেডার অন্তর্ভুক্ত clickhouse.h (কোর), clickhouse-client.h (TCP প্যাকেট লুপ), clickhouse-async.h (ioless client), clickhouse-compression.h (compressed frames, LZ4 & ZSTD এডাপ্টার), clickhouse-posix-io.h (ব্লকিং read/write), এবং clickhouse-openssl.h (SSL সমর্থন)। প্রতিটি ফলো-আপ হেডার স্বাধীন। test.sh CFLAGS এবং LDFLAGS কনফিগারেশন দিয়ে পরীক্ষা করা হয়েছে।

ClickHouse/clickhouse-c ist ein minimalistischer C-Client, der den Native wire format über TCP implementiert. Die Bibliothek besteht aus einem Core-Header plus optionalen Folgeheadern für TCP, compression, codecs und I/O Backends. Sie ist für die Einbettung in PostgreSQL-Erweiterungen konzipiert, enthält aber keinen PostgreSQL-spezifischen Code. Das Einbinden von clickhouse.h allein bietet einen reinen Block-Decoder für caller-supplied chc_io, verwendbar zum Lesen der FORMAT Native Ausgabe von clickhouse-local aus einem Pipe ohne TCP, compression, oder Link-Time-Abhängigkeiten jenseits von libc.

Das Quickstart-Beispiel demonstriert das Dekodieren einer clickhouse local-Abfrage ohne TCP oder Kompression. Ein ausführbares End-to-End-Beispiel steht in examples/minimal_decode.c zur Verfügung. Die erforderliche Server-Einstellung ist output_format_native_encode_types_in_binary_format = 0; ohne sie emittiert der Server binäre Typ-Tags und chc_block_read gibt CHC_ERR_TYPE zurück.

Die Integration folgt einem Single-Translation-Unit-Modell: genau ein Translation-Einheit pro Consumer definiert das CHC_IMPLEMENTATION-Makro und inkludiert Header, während andere TU nur öffentliche Deklarationen inkludieren. Ein stdlib malloc/realloc/free-Helfer steht hinter CHC_PROVIDE_STDLIB_ALLOC. Für palloc/repalloc/pfree-Verkabelung in PostgreSQL-Erweiterungen siehe pg_clickhouse oder pg_stat_ch.

Header umfassen clickhouse.h (Kern), clickhouse-client.h (TCP-Paket-Loop), clickhouse-async.h (ioless Client), clickhouse-compression.h (komprimierte Frames, LZ4 & ZSTD-Adapter), clickhouse-posix-io.h (blockierender Lesen/Schreiben), und clickhouse-openssl.h (SSL-Support). Jeder folgende Header ist unabhängig. Die Tests verwenden test.sh mit CFLAGS und LDFLAGS für Konfiguration.

ClickHouse/clickhouse-c es un cliente C minimalista que implementa el formato nativo por wire sobre TCP. La biblioteca consta de un encabezado principal más encabezados opcionales posteriores para TCP, compresión, codecs y backends de E/S. Está diseñado para incrustarse dentro de extensiones de PostgreSQL, pero no contiene código específico de PostgreSQL. Incluir clickhouse.h solo proporciona un decodificador de bloques puro sobre chc_io suministrado por el llamador, usable para leer la salida FORMAT Native de clickhouse-local de un pipe sin TCP, compresión o dependencias de enlace más allá de libc.

La demostración rápida muestra decodificando una consulta clickhouse local sin TCP ni compresión. Una versión ejecutable de extremo a extremo está disponible en ejemplos/minimal_decode.c. La configuración del servidor requerida es output_format_native_encode_types_in_binary_format = 0; sin ella, el servidor emite etiquetas de tipo binario y chc_block_read devuelve CHC_ERR_TYPE.

El seguimiento sigue un modelo de unidad de traducción única: exactamente un unidad de traducción por consumidor define el macro CHC_IMPLEMENTATION e incluye encabezados, mientras que otras TU solo incluyen declaraciones públicas. Un helper malloc/realloc/free de stdlib está disponible detrás de CHC_PROVIDE_STDLIB_ALLOC. Para wiring palloc/repalloc/pfree dentro de extensiones de PostgreSQL, ver pg_clickhouse o pg_stat_ch.

Los encabezados incluyen clickhouse.h (núcleo), clickhouse-client.h (bucle de paquetes TCP), clickhouse-async.h (cliente sin i/o), clickhouse-compression.h (marcos comprimidos, adaptadores LZ4 & ZSTD), clickhouse-posix-io.h (lectura/escritura bloqueante), y clickhouse-openssl.h (soporte SSL). Cada encabezado posterior es independiente. Las pruebas usan test.sh con CFLAGS y LDFLAGS para configuración.

ClickHouse/clickhouse-c est un client C minimaliste mettant en œuvre le format natif wire over TCP. La bibliothèque se compose d'un en-tête principal plus des en-têtes suivants optionnels pour TCP, compression, codecs et backends E/S. Elle est conçue pour être intégrée dans des extensions PostgreSQL mais ne contient aucun code spécifique à PostgreSQL. L'inclusion de clickhouse.h seul fournit un décodeur de blocs pur sur chc_io fourni par l'appelant, utilisable pour lire la sortie FORMAT Native de clickhouse-local à partir d'un pipe sans TCP, compression, ou dépendances de liaison au-delà de libc.

La démonstration rapide montre le décodage d'une requête clickhouse local sans TCP ni compression. Une version end-to-end exécutable est disponible dans examples/minimal_decode.c. La configuration serveur requise est output_format_native_encode_types_in_binary_format = 0 ; sans elle, le serveur émet des étiquettes de type binaire et chc_block_read renvoie CHC_ERR_TYPE.

L'intégration suit un modèle d'unité de traduction unique : exactement une unité de traduction par consommateur définit la macro CHC_IMPLEMENTATION et inclut les en-têtes, tandis que les autres TU n'incluent que des déclarations publiques. Un helper malloc/realloc/free de la stdlib est disponible derrière CHC_PROVIDE_STDLIB_ALLOC. Pour le wiring palloc/repalloc/pfree dans les extensions PostgreSQL, voir pg_clickhouse ou pg_stat_ch.

Les en-têtes incluent clickhouse.h (noyau), clickhouse-client.h (boucle de paquets TCP), clickhouse-async.h (client sans i/o), clickhouse-compression.h (cadres compressés, adaptateurs LZ4 & ZSTD), clickhouse-posix-io.h (lecture/écriture bloquante), et clickhouse-openssl.h (support SSL). Chaque en-tête suivant est indépendant. Les tests utilisent test.sh avec CFLAGS et LDFLAGS pour la configuration.

ClickHouse/clickhouse-c एक minimalist C क्लाइंट है जो TCP over Native wire format लागू करता है। पुस्तकालय एक कोर हेडर प्लस वैकल्पिक अनुवर्ती हेडर के लिए बनाया गया है TCP, compression, codecs, और I/O backends। इसे PostgreSQL extensions के भीतर एम्बेड करने के लिए डिज़ाइन किया गया है लेकिन इसमें कोई PostgreSQL-विशिष्ट कोड नहीं है। clickhouse.h शामिल करने से एक शुद्ध block decoder मिलता है जिसे caller-supplied chc_io के साथ उपयोग किया जा सकता है, TCP के बिना, compression के बिना, libc के अलावा कोई link-time निर्भरता के साथ clickhouse-local के FORMAT Native output पढ़ने के लिए।

क्विकस्टार्ट एक clickhouse local query बिना TCP या compression के डिकोडिंग का प्रदर्शन करता है। examples/minimal_decode.c में एंड-टू-एंड संस्करण उपलब्ध है। आवश्यक सर्वर सेटिंग output_format_native_encode_types_in_binary_format = 0 है; बिना इसे, सर्वर बाइनरी प्रकार के टैग उत्सर्जित करता है और chc_block_read CHC_ERR_TYPE लौटाता है।

एकीकरण एकल-ट्रांसलेशन-यूनिट मॉडल का अनुसरण करता है: प्रति उपभोक्ता ठीक एक translation unit CHC_IMPLEMENTATION मैक्रो परिभाषित करता है और हेडर शामिल करता है, जबकि अन्य TU केवल सार्वजनिक घोषणाओं को शामिल करते हैं। CHC_PROVIDE_STDLIB_ALLOC के पीछे एक stdlib malloc/realloc/free helper उपलब्ध है। PostgreSQL extensions के भीतर palloc/repalloc/pfree wiring के लिए, pg_clickhouse या pg_stat_ch देखें।

हेडर में clickhouse.h (कोर), clickhouse-client.h (TCP पैकेट लूप), clickhouse-async.h (ioless client), clickhouse-compression.h (compressed frames, LZ4 & ZSTD एडाप्टर), clickhouse-posix-io.h (ब्लॉकिंग read/write), और clickhouse-openssl.h (SSL समर्थन) शामिल हैं। प्रत्येक अनुवर्ती हेडर स्वतंत्र है। test.sh के साथ CFLAGS और LDFLAGS के लिए configuration के साथ परीक्षण किया गया है।

ClickHouse/clickhouse-c adalah klien C minimalist yang menerapkan Native wire format over TCP. Perpustakaan terdiri dari satu header utama plus header opsional berikutnya untuk TCP, compression, codecs, dan I/O backends. Dirancang untuk dimasukkan ke dalam ekstensi PostgreSQL tetapi tidak berisi kode PostgreSQL-specific. Menginclude clickhouse.h saja menyediakan pure block decoder untuk caller-supplied chc_io, dapat digunakan untuk membaca output FORMAT Native clickhouse-local dari pipa tanpa TCP, compression, atau dependensi link-time di luar libc.

Quickstart menampilkan dekoding query clickhouse local tanpa TCP atau kompresi. Versi end-to-end yang dapat dijalankan tersedia di examples/minimal_decode.c. Pengaturan server yang diperlukan adalah output_format_native_encode_types_in_binary_format = 0; tanpa itu, server mengeluarkan binary type tags dan chc_block_read mengembalikan CHC_ERR_TYPE.

Integrasi mengikuti model satu-unit translasi: satu unit translasi per konsumen mendefinisikan macro CHC_IMPLEMENTATION dan mencakup header, sementara TU lain hanya mencakup deklarasi publik. Helper malloc/realloc/free stdlib di balik CHC_PROVIDE_STDLIB_ALLOC. Untuk wiring palloc/repalloc/pfree di dalam ekstensi PostgreSQL, lihat pg_clickhouse atau pg_stat_ch.

Header mencakup clickhouse.h (inti), clickhouse-client.h (TCP packet loop), clickhouse-async.h (ioless client), clickhouse-compression.h (frame terkompresi, adapter LZ4 & ZSTD), clickhouse-posix-io.h (baca/ulis blok), dan clickhouse-openssl.h (SSL support). Setiap header berikutnya mandiri. Pengujian menggunakan test.sh dengan CFLAGS dan LDFLAGS untuk konfigurasi.

ClickHouse/clickhouse-cはTCP over Native wire formatを実装する最小限のCクライアントです。ライブラリはコアヘッダー1つと、TCP、圧縮、codec、I/Oバックエンド用のオプションのフォローヘッダーで構成されています。PostgreSQL拡張内への埋め込みを目的として設計されていますが、PostgreSQL固有のコードは含まれていません。clickhouse.hだけを含めると、呼び出し元が供給するchc_ioを使用した純粋なブロックデコーダが提供され、TCP、圧縮、libc以外のリンク時依存関係なしにclickhouse-localのFORMAT Native出力をパイプから読み取ることができます。

クイックスタートはTCPや圧縮なしでclickhouse localクエリのデコーディングをデモンストレーションします。examples/minimal_decode.cにエンドツーエンドで動作するバージョンが用意されています。必要なサーバー設定はoutput_format_native_encode_types_in_binary_format = 0です。これを設定しないと、サーバーはバイナリタイプのタグを発し、chc_block_readはCHC_ERR_TYPEを返します。

統合はシングル翻訳単位モデルに従います：消費者1つにつきちょうど1つの翻訳単元でCHC_IMPLEMENTATIONマクロを定義しヘッダーをインクルードし、他のTUはパブリック宣言のみをインクルードします。stdlib malloc/realloc/freeヘルパーはCHC_PROVIDE_STDLIB_ALLOCの背後にあります。PostgreSQL拡張内でのpalloc/repalloc/pfreeのワイヤリングについては、pg_clickhouseまたはpg_stat_chを参照してください。

ヘッダーにはclickhouse.h（コア）、clickhouse-client.h（TCPパケットループ）、clickhouse-async.h（ioless client）、clickhouse-compression.h（圧縮フレーム、LZ4 & ZSTDアダプター）、clickhouse-posix-io.h（ブロッキング読み書き）、およびclickhouse-openssl.h（SSLサポート）が含まれます。各フォローヘッダーは独立しています。test.shでCFLAGSとLDFLAGSの設定でテストされています。

ClickHouse/clickhouse-c é um cliente C minimalista que implementa o formato nativo wire over TCP. A biblioteca consiste em um cabeçalho principal mais cabeçalhos opcionais posteriores para TCP, compression, codecs e backends I/O. Foi projetado para incorporação dentro de extensões PostgreSQL, mas não contém código específico de PostgreSQL. Incluindo clickhouse.h sozinho fornece um decodificador de bloco puro sobre chc_io fornecido pelo chamador, utilizável para ler a saída FORMAT Native de clickhouse-local de um pipe sem TCP, compression, ou dependências de link além de libc.

A demonstração rápida demonstra decodificando uma consulta clickhouse local sem TCP ou compressão. Uma versão end-to-end executável está disponível em examples/minimal_decode.c. A configuração do servidor necessária é output_format_native_encode_types_in_binary_format = 0; sem ela, o servidor emite tags de tipo binário e chc_block_read retorna CHC_ERR_TYPE.

A integração segue um modelo de unidade de tradução única: exatamente um unidade de tradução por consumidor define o macro CHC_IMPLEMENTATION e inclui cabeçalhos, enquanto outras TU incluí apenas declarações públicas. Um helper malloc/realloc/free de stdlib está disponível atrás de CHC_PROVIDE_STDLIB_ALLOC. Para wiring palloc/repalloc/pfree dentro de extensões PostgreSQL, veja pg_clickhouse ou pg_stat_ch.

Os cabeçalhos incluem clickhouse.h (núcleo), clickhouse-client.h (loop de pacotes TCP), clickhouse-async.h (client sem i/o), clickhouse-compression.h (quadros comprimidos, adaptadores LZ4 & ZSTD), clickhouse-posix-io.h (leitura/escrita bloqueante), e clickhouse-openssl.h (suporte SSL). Cada cabeçalho seguinte é independente. Os testes usam test.sh com CFLAGS e LDFLAGS para configuração.

ClickHouse/clickhouse-c — минималистский клиент C, реализующий Native wire format over TCP. Библиотека состоит из одного основного заголовка плюс опциональные последующие заголовки для TCP, compression, codecs и I/O backends. Разработана для встраивания внутри расширений PostgreSQL, но не содержит кода PostgreSQL-специфического. Включение clickhouse.h alone предоставляет чистый декодер блоков для вызывающего chc_io, пригодный для чтения вывода FORMAT Native clickhouse-local из канала без TCP, compression, и зависимостей времени связывания, кроме libc.

Быстрый старт демонстрирует декодирование запроса clickhouse local без TCP или compression. Доступен исполняемый пример end-to-end в examples/minimal_decode.c. Требуемая настройка сервера output_format_native_encode_types_in_binary_format = 0; без неё сервер выдает бинарные типовые метки, и chc_block_read возвращает CHC_ERR_TYPE.

Интеграция следует моделью единичного трансляционного блока: ровно один трансляционный блок на потребителя определяет макрос CHC_IMPLEMENTATION и включает заголовки, а другие TU включают только публичные объявления. Помощь malloc/realloc/free stdlib доступна за CHC_PROVIDE_STDLIB_ALLOC. Для wiring palloc/repalloc/pfree внутри расширений PostgreSQL смотрите pg_clickhouse или pg_stat_ch.

Заголовочные файлы включают clickhouse.h (ядро), clickhouse-client.h (цикл пакетов TCP), clickhouse-async.h (клиент без i/o), clickhouse-compression.h (сжатые кадры, адаптеры LZ4 & ZSTD), clickhouse-posix-io.h (блокирующее чтение/запись), и clickhouse-openssl.h (поддержка SSL). Каждый последующий заголовок независим. Тесты используют test.sh с CFLAGS и LDFLAGS для конфигурации.

ClickHouse/clickhouse-c是一个最小化的头文件C客户端，实现ClickHouse原生wire format over TCP。该库由一个核心头文件加上可选的后续头文件组成，用于TCP、压缩、codec和I/O后端。它旨在嵌入PostgreSQL扩展中，但不包含PostgreSQL特定代码。仅包含clickhouse.h即提供纯块解码器，可用于在调用方提供的chc_io上读取clickhouse-local的FORMAT Native输出，无需TCP、压缩，仅依赖libc。

快速入门演示无TCP或压缩的clickhouse local查询解码。在examples/minimal_decode.c中提供了可运行的端到端版本。所需的服务器设置是output_format_native_encode_types_in_binary_format = 0；没有它，服务器会发出二进制类型标签，chc_block_read返回CHC_ERR_TYPE。

集成遵循单翻译单元模型：每个消费者恰好一个翻译单元定义CHC_IMPLEMENTATION宏并包含头文件，而其他TU仅包含公共声明。由CHC_PROVIDE_STDLIB_ALLOC提供的stdlib malloc/realloc/free辅助函数。关于在PostgreSQL扩展中 wiring palloc/repalloc/pfree，请参阅pg_clickhouse或pg_stat_ch。

头文件包括clickhouse.h（核心），clickhouse-client.h（TCP包循环），clickhouse-async.h（ioless客户端），clickhouse-compression.h（压缩帧，LZ4 & ZSTD适配器），clickhouse-posix-io.h（阻塞读/写），和clickhouse-openssl.h（SSL支持）。每个后续头文件均独立。测试使用带有CFLAGS和LDFLAGS配置的test.sh。