clickhouse-rs

clickhouse-rs (crate name clickhouse) is the official pure-Rust client for ClickHouse, the column-oriented analytical database. It maps rows to native Rust structs via serde, communicates over HTTP using the RowBinaryWithNamesAndTypes wire format by default, and validates struct field names and types against the live ClickHouse schema so mismatches surface as clear errors instead of silent corruption.

Beyond basic select/insert, the crate provides an Inserter for infinite buffered inserts with byte/row/time thresholds, LZ4/LZ4HC/ZSTD compression, TLS via rustls or native-tls, mock testing utilities, and optional integrations with uuid, time, chrono, and OpenTelemetry context propagation. It is maintained directly by ClickHouse Inc. and is the de facto standard driver for talking to ClickHouse from async Rust services built on Tokio and Hyper.

What You Get

• Typed select/fetch API that deserializes rows into serde-derived structs, with placeholder binding (?, ?fields) for parameterized queries
• An Inserter for infinite/buffered inserts with configurable byte, row, and time-based flush thresholds
• RowBinaryWithNamesAndTypes wire format by default, giving schema-validated errors instead of opaque NotEnoughData failures
• Built-in compression (LZ4, LZ4HC, ZSTD) and pluggable TLS (native-tls or rustls, including custom root stores)
• Mock server utilities (test-util feature) for unit-testing query and insert logic without a live ClickHouse instance
• Optional uuid, time, chrono, and OpenTelemetry-context feature flags for common data types and distributed tracing

Common Use Cases

• Streaming analytics events or logs from a Tokio-based Rust service into ClickHouse in real time
• Building infinite background inserters that batch rows by size, count, or time window before flushing
• Running parameterized analytical queries from a Rust backend and mapping results directly to domain structs
• Writing integration tests against ClickHouse behavior using the crate’s mock client instead of a live server

Under The Hood

Architecture - The crate centers on a Client that issues HTTP requests to a ClickHouse server via hyper/hyper-util, serializing bound query parameters and streaming RowBinaryWithNamesAndTypes-encoded responses through a rowbinary decoder into caller-defined structs; the Inserter (src/inserter.rs) wraps insert.rs to batch rows and flush on byte/row/time thresholds, while cursors/ handles the async streaming decode loop and sql/ builds parameterized query text. Tech Stack - Built on Tokio and Hyper 1.x for async HTTP, serde/serde_json for row (de)serialization, bytes for zero-copy buffers, optional rustls/native-tls for TLS and lz4_flex/zstd for compression, with a small internal workspace of clickhouse-macros (the #[derive(Row)] proc-macro) and clickhouse-types for schema type modeling. Code Quality - The repo has an extensive tests/it/ integration suite covering compression, TLS, nested types, cursors, mocks, and edge cases like Int256/bfloat16, plus tests/ui compile-fail tests for the derive macro, clippy.toml/rustfmt.toml lint configs, and CI with codecov coverage tracking — a mature, well-tested codebase for a 48-contributor project. API Design - The client API favors ergonomic builder chaining (Client::default().with_url(..).with_user(..)) and query placeholders (?, ?fields) resolved against struct fields, with schema validation surfacing mismatches as descriptive errors by default rather than opaque binary decode failures, at a small, well-documented performance cost that can be opted out of.