ClickHouse C: Thư viện C chỉ chứa header để giao tiếp với ClickHouse qua giao thức nhị phân gốc

ClickHouse, hệ quản trị cơ sở dữ liệu phân tích cột (column-oriented) phổ biến, vừa ra mắt clickhouse-c — một thư viện C chỉ chứa header cho phép giao tiếp với máy chủ ClickHouse thông qua giao thức nhị phân gốc (Native Protocol).

Điểm đáng chú ý là thư viện này được thiết kế để nhúng trực tiếp vào các extension PostgreSQL, nhưng hoàn toàn không chứa mã đặc thù cho PostgreSQL.

Native Protocol là gì và tại sao nó quan trọng?

Native Protocol là giao thức nhị phân chạy trên TCP, vận chuyển các khối dữ liệu ở Native Format. So với HTTP, giao thức này có hiệu suất cao hơn đáng kể nhờ giảm thiểu overhead của quá trình tuần tự hóa và truyền tải.

clickhouse-c cung cấp một header lõi duy nhất, kèm theo các header bổ sung tùy chọn cho TCP, nén dữ liệu, codec và các backend vào/ra (I/O).

Chỉ cần include clickhouse.h là bạn đã có một bộ giải mã khối thuần túy, hoạt động trên chc_io do người gọi cung cấp — có thể dùng để đọc FORMAT Native từ pipe của clickhouse-local mà không cần TCP, không cần nén, và không cần phụ thuộc liên kết nào ngoài libc.

Cách sử dụng cơ bản

Ví dụ tối giản dưới đây giải mã một truy vấn từ clickhouse-local mà không cần TCP hay nén:

/* 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"

Một điểm quan trọng cần lưu ý: máy chủ phải được cấu hình với tham số:

• Query packet cho TCP: output_format_native_encode_types_in_binary_format = 0
• clickhouse local: dùng cờ tương ứng

Nếu không có cấu hình này, máy chủ sẽ xuất các thẻ kiểu nhị phân (binary type tags) và hàm chc_block_read sẽ trả về lỗi CHC_ERR_TYPE.

Kiến trúc phân phối dạng header

clickhouse-c được phân phối dưới dạng một tập hợp phẳng các header. Mỗi header chứa cả phần khai báo lẫn phần triển khai, được bảo vệ bằng macro sentinel.

Nguyên tắc sử dụng:

• Đúng một đơn vị biên dịch (translation unit) trong mỗi ứng dụng định nghĩa macro triển khai và include các header.
• Các đơn vị biên dịch khác chỉ include để lấy phần khai báo.

Cách này giúp tránh lỗi liên kết trùng lặp (multiple definition) khi nhiều file nguồn cùng sử dụng thư viện.

Danh sách các header

Dưới đây là các header chính và chức năng tương ứng:

• clickhouse.h — Lõi: kiểu dữ liệu, xử lý lỗi, chc_alloc, chc_io, bộ phân tích tên kiểu, trình đọc và ghi khối.
• clickhouse-client.h — Vòng lặp gói tin TCP: Hello / Query / Data / EOS / Exception / Progress / Pong.
• clickhouse-async.h — Client không I/O: cùng vòng lặp gói tin nhưng do người gọi nạp byte, không dùng socket.
• clickhouse-compression.h — Bố cục khung nén, CityHash128, điều phối codec, bộ chuyển đổi LZ4 và ZSTD.
• clickhouse-posix-io.h — chc_io trên read(2)/write(2) dạng chặn, có vòng lặp xử lý EINTR và hook hủy.
• clickhouse-openssl.h — chc_io trên SSL_read/SSL_write.

Mỗi header bổ sung đều độc lập, bạn chỉ cần chọn những gì dự án của mình cần. Đáng chú ý, clickhouse-client.h hỗ trợ ClickHouse 23.3 trở lên.

Kiểm thử

Thư viện đi kèm script test.sh để chạy kiểm thử:

./test.sh

Nếu gặp lỗi thiếu header hoặc lỗi liên kết, có thể trỏ đến thư mục phù hợp qua CFLAGS và LDFLAGS. Ví dụ với Homebrew:

CFLAGS=-I/opt/homebrew/include LDFLAGS=-L/opt/homebrew/lib ./test.sh

Bạn cũng có thể chạy từng bài kiểm thử riêng lẻ bằng cách truyền tên cơ sở (không có phần mở rộng .c) làm tham số.

Những gì thư viện KHÔNG làm

Đội ngũ phát triển đã nêu rõ các non-goals (mục tiêu không hướng tới) để đặt kỳ vọng đúng đắn:

• Giao thức HTTP — hãy dùng trực tiếp libcurl.
• DNS, xoay vòng endpoint, gộp kết nối (connection pooling), retry/backoff.
• Vòng đời ngữ cảnh SSL/TLS — chc_io chỉ cung cấp callback, người gọi tự điều khiển OpenSSL.
• Đa luồng — mỗi chc_client được thiết kế đơn luồng.
• I/O bất đồng bộ bên trong thư viện — client dạng chặn gọi chc_io.read đồng bộ, nhưng callback có thể làm bất cứ điều gì bên dưới như epoll, io_uring hay WaitLatchOrSocket.

Ngoài ra, việc giải mã các kiểu Variant / Dynamic / JSON / AggregateFunction chưa được hỗ trợ trong phiên bản v1, bởi định dạng wire gốc vẫn đang thay đổi trong các phiên bản 25.x và 26.x.

Ý nghĩa với cộng đồng lập trình viên

Với các nhà phát triển đang xây dựng extension PostgreSQL hoặc các công cụ phân tích dữ liệu hiệu suất cao, clickhouse-c mở ra một lựa chọn nhẹ nhàng và hiệu quả để tích hợp trực tiếp với ClickHouse mà không cần qua lớp HTTP trung gian.

Việc thư viện chỉ phụ thuộc vào libc và hỗ trợ nhúng vào môi trường có sẵn arena cấp phát (như palloc của PostgreSQL) cho thấy đây là sản phẩm được thiết kế kỹ lưỡng cho các tình huống tích hợp thực tế, chứ không chỉ đơn thuần là một client đa dụng.

Dự án được phát hành trên GitHub tại địa chỉ github.com/ClickHouse/clickhouse-c, với tài liệu tham chiếu chi tiết cho từng header trong thư mục doc/ và các ví dụ hoàn chỉnh trong thư mục examples/.