clickhouse-rs

The clickhouse crate is the official Rust client for ClickHouse. Key characteristics include:

• Data Encoding/Decoding: Uses serde for row serialization and deserialization. It supports standard serde attributes like skip_serializing, skip_deserializing, and rename.
• Transport: Uses the RowBinary format over HTTP. (Future plans include Native over TCP).
• Compression: Supports LZ4 compression/decompression.
• Security: Supports TLS via native-tls or rustls-tls.
• Core APIs: Provides methods for selecting rows, inserting data (including client-side batching via inserter), executing DDLs, and watching data.

By default, clickhouse-rs uses the RowBinaryWithNamesAndTypes format, which validates your Rust structs against the ClickHouse schema. This provides clear error messages but adds a small performance penalty.

To maximize performance, you can disable validation using Client::with_validation(false). This switches the client to the RowBinary format.

Warning: When validation is disabled, schema mismatches will result in a generic NotEnoughData error instead of descriptive error messages. It is highly recommended to write smoke tests to ensure your row types match the database schema if you disable validation.

The crate provides utilities to mock the ClickHouse server for testing DDL, SELECT, INSERT, and WATCH queries.

Important: The test-util feature should be enabled only as a dev-dependency in your Cargo.toml to avoid bloating production binaries.

The client is compatible with ClickHouse Cloud and ClickHouse LTS or newer versions.

Legacy Server Support: ClickHouse servers older than v22.6 may incorrectly handle RowBinary in rare cases. To mitigate this, you can use clickhouse version 0.11+ and enable the wa-37420 feature.

<Warning> Do NOT use the wa-37420 feature with newer ClickHouse versions. </Warning>

The Variant data type is supported as a Rust enum.

CRITICAL: Because ClickHouse sorts inner Variant types alphabetically, your Rust enum variants must be defined in the exact same order as the types in the ClickHouse column definition. The names of the variants do not matter, but their order is strictly enforced.

use clickhouse::Row;
use serde::{Serialize, Deserialize};
use time::Date;

// Column: Variant(Array(UInt16), Bool, Date, String, UInt32)
#[derive(Serialize, Deserialize)]
enum MyRowVariant {
    Array(Vec<i16>),      // 1. Array(UInt16)
    Boolean(bool),        // 2. Bool
    #[serde(with = "clickhouse::serde::time::date")]
    Date(time::Date),     // 3. Date
    String(String),       // 4. String
    UInt32(u32),          // 5. UInt32
}

#[derive(Row, Serialize, Deserialize)]
struct MyRow {
    id: u64,
    var: MyRowVariant,
}

To measure the overhead of the clickhouse-rs client itself without network or database latency, you can run benchmarks against a mocked server. The mocked server is a simple HTTP server that returns fixed responses.

Scenarios:

• mocked_select: Measures throughput of Client::query().
• mocked_insert: Measures throughput of Client::insert() and Client::inserter() (note: Client::inserter() requires the inserter feature to be enabled).

Run the benchmarks using:

cargo bench --bench <case>

cargo bench --bench mocked_select

To interact with ClickHouse, initialize a Client using the builder pattern. You should provide the URL (including protocol and port), user, password, and database.

Tip: Reuse or clone Client instances to benefit from the underlying hyper connection pool.

For HTTPS or ClickHouse Cloud connections, ensure you have enabled either the rustls-tls or native-tls cargo features.

use clickhouse::Client;

let client = Client::default()
    // should include both protocol and port
    .with_url("http://localhost:8123")
    .with_user("name")
    .with_password("123")
    .with_database("test");

The crate provides utilities to mock the ClickHouse server, allowing you to test DDL, SELECT, and INSERT queries without a live database.

To use this functionality, you must enable the test-util feature. Warning: This feature is intended for use only in dev-dependencies to avoid bloating production binaries.

[dev-dependencies]
clickhouse = { version = "0.15.1", features = ["test-util"] }

To use the clickhouse crate in your Rust project, add it to your Cargo.toml. For development and testing, you may also want to include the test-util feature.

[dependencies]
clickhouse = "0.14.2"

[dev-dependencies]
clickhouse = { version = "0.14.2", features = ["test-util"] }