ClickHouse, native binary protokolü için header-only C istemcisi yayınladı

Kütüphanenin işlevi

ClickHouse, tamamen header olarak dağıtılan bir C istemci kütüphanesi olan clickhouse-c'yi yayınladı; bu kütüphane, veritabanıyla HTTP yerine TCP üzerinden native binary protokolüyle konuşuyor. GitHub'da ClickHouse organizasyonu altında barındırılan proje, Hacker News ana sayfasında da yer buldu. Bildirilen amacı küçük, gömülü kullanım senaryoları ve özellikle PostgreSQL extension'ları ana hedef olarak gösteriliyor.

Çekirdek, tek bir header olan clickhouse.h'den oluşuyor; bu header tip tanımlarını, hata yönetimini, allocator ve I/O arayüzlerini, tip adı ayrıştırıcısını ile block okuyucu ve yazıcıyı içeriyor. Projenin README'sine göre yalnızca bu header, çağıran tarafın sağladığı bir I/O callback'iyle çalışan eksiksiz bir block çözücüsü sunuyor; böylece bir program, bir socket açmadan, sıkıştırmayı etkinleştirmeden veya libc ötesinde herhangi bir şeyle bağlantı kurmadan, pipe üzerinden gelen clickhouse local çıktısını Native formatında ayrıştırabiliyor.

Diğer header'ların her biri tek bir yetenek ekler ve bağımsız olarak dahil edilebilir: clickhouse-client.h, Hello, Query, Data, end-of-stream, Exception, Progress ve Pong paketlerini kapsayan TCP paket döngüsünü uygular ve ClickHouse 23.3 ve sonrasını destekler; clickhouse-compression.h, sıkıştırılmış frame yapısını, CityHash128 checksum'larını ve isteğe bağlı link flag'leri arkasında LZ4 ile ZSTD codec'lerini kapsar; clickhouse-posix-io.h, EINTR yönetimi ve bir iptal (cancellation) kancasıyla blocking okuma ve yazma sağlar; clickhouse-openssl.h ise SSL_read ve SSL_write'ı sarmalar. Ayrı bir header olan clickhouse-async.h, hiç I/O içermeyen aynı paket döngüsünü sunar; byte'ları bir event loop'tan çağıran taraf besler.

PostgreSQL'e gömme için tasarlandı

README'ye göre tasarım, PostgreSQL'in yürütme modelini — palloc üzerinden arena tahsisi ve longjmp tabanlı hata geri sarmayı — göz önünde bulunduruyor ancak hiçbir PostgreSQL'e özgü kod içermiyor. Standart bir malloc tabanlı allocator bir preprocessor define arkasında geliyor ve dokümantasyon, palloc tahsisini gerçek bir extension'a bağlama konusunda referans olarak pg_clickhouse ve pg_stat_ch extension'larını gösteriyor.

Entegrasyon bilinen single-header desenini izliyor: kütüphaneyi kullanan projede tam olarak bir translation unit, header'ları dahil etmeden önce CHC_IMPLEMENTATION tanımlar ve diğer tüm dosyalar bunları yalnızca bildirimler için dahil eder.

Pratikte önemli bir yapılandırma detayı var: output_format_native_encode_types_in_binary_format sunucu ayarı, TCP üzerindeki Query paketinde ya da clickhouse local'a bir flag olarak 0'a ayarlanmalı. Etkin bırakılırsa sunucu binary type tag'leri gönderir ve chc_block_read, CHC_ERR_TYPE ile başarısız olur.

Kapsam, test ve sınırlar

Test paketi test.sh üzerinden çalışıyor. TCP testleri, PATH'ten bir clickhouse server binary'si başlatabiliyor ya da halihazırda çalışan bir örneği CHC_TEST_PORT üzerinden hedefleyebiliyor; dokümantasyon bunu, örneğin Docker'da çalışan eski sürümlerle uyumluluğu denetlemek için kullanmayı öneriyor. Bir capture aracı ayrıca, tekrar oynatma için trafik fixture'ları kaydetmek üzere canlı bir sunucuyu proxy'leyebiliyor.

Hedef olmayanlar (non-goals), özellik listesi kadar bilgilendirici. HTTP desteği yok — öneri libcurl'ü doğrudan sarmalamak — ve DNS çözümleme, endpoint rotasyonu, connection pooling, retry mantığı ya da SSL context yaşam döngüsü yönetimi de yok. Threading de yok: her client nesnesi bilinçli olarak tek iş parçacıklı. Blocking istemci I/O callback'ini senkron olarak çağırır, ancak README, callback'in altta epoll, io_uring veya PostgreSQL'in WaitLatchOrSocket'ını kullanmakta özgür olduğunu belirtir. İlk sürüm ayrıca Variant, Dynamic, JSON ve AggregateFunction kolonları için kod çözme içermiyor, çünkü bu tiplerin wire formatı henüz 25.x ve 26.x sürüm hatlarında değişmeye devam ediyor.

Neden önemli

Çoğu yazılım ClickHouse'a HTTP üzerinden metin veya JSON satır formatlarıyla konuşur; bu, bir tarafta serileştirme, diğer tarafta ayrıştırma ve arada ekstra kopyalar anlamına gelir. Native block protokolünü süreç içinde çözen header-only bir istemci bu yükü ortadan kaldırır ve kritik nokta, ev sahibi programın kendi bellek sistemi üzerinden tahsis yapabilmesidir — bu, yalnızca PostgreSQL içinde çalışan bir kütüphane ile onun içinde doğru davranan bir kütüphane arasındaki farktır. Dar kapsam asıl amaçtır: pooling, threading veya TLS yaşam döngüsü sahiplenilecek bir şey olmadığından kod, bir extension'a ya da başka bir veritabanı aracına vendor edilecek kadar küçük kalıyor. Foreign data wrapper, izleme agent'ı ya da PostgreSQL ile ClickHouse arasında toplu aktarım yolları inşa eden herkes için bu, daha önce ağır istemci kütüphaneleri ya da elle yazılmış protokol kodu gerektiren bir boşluğu kapatıyor.