CH.Native 1.1.2-prerelease.33

CH.Native

A high-performance modern .NET client for ClickHouse using the native binary TCP protocol.

Quick Start

dotnet add package CH.Native

await using var connection = new ClickHouseConnection("Host=localhost;Port=9000");
await connection.OpenAsync();

var result = await connection.ExecuteScalarAsync<int>("SELECT 1");
Console.WriteLine(result); // 1

See the Getting Started Guide for more examples, or run samples/CH.Native.Samples.QuickStart for the same flow as a runnable project.

Features

• Native Binary Protocol - Direct TCP communication on port 9000 for optimal performance
• Full Async/Await - All operations are async with streaming support
• ADO.NET Provider - Standard DbConnection implementation with Dapper compatibility
• Bulk Insert - High-performance batched inserts with typed mapping
• Compression - LZ4 (default) and Zstd compression support
• Resilience - Built-in retry policies, circuit breakers, and health checking
• Load Balancing - Multi-server support with round-robin, random, or first-available strategies
• TLS/SSL - Secure connections with certificate validation
• Telemetry - OpenTelemetry-compatible tracing, metrics, and logging
• Type Safety - Full support for all ClickHouse types with .NET mapping

Supported ClickHouse Types

CH.Native supports the full ClickHouse type system across read, write, and bulk-insert paths. See Data Types for the complete CLR-mapping reference.

All types round-trip through both the read path (ExecuteReaderAsync, QueryStreamAsync<T>) and the bulk-insert path (CreateBulkInserter<T>). Nullable(...) wraps any non-composite type. Composites compose freely (e.g. Array(Nullable(LowCardinality(String)))).

Installation

dotnet add package CH.Native

Basic Usage

Execute a Query

await using var connection = new ClickHouseConnection("Host=localhost;Port=9000");
await connection.OpenAsync();

// Scalar query
var count = await connection.ExecuteScalarAsync<long>("SELECT count() FROM users");

// DDL/DML
await connection.ExecuteNonQueryAsync("CREATE TABLE IF NOT EXISTS users (id UInt32, name String) ENGINE = Memory");

Query with Parameters

var users = await connection.QueryStreamAsync<User>(
    "SELECT * FROM users WHERE age > @minAge",
    new { minAge = 18 }
).ToListAsync();

Typed Results

public class User
{
    public uint Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

await foreach (var user in connection.QueryStreamAsync<User>("SELECT * FROM users"))
{
    Console.WriteLine($"{user.Id}: {user.Name}");
}

Bulk Insert

var users = new List<User> { /* ... */ };

await using var inserter = connection.CreateBulkInserter<User>("users");
await inserter.InitAsync();
await inserter.AddRangeAsync(users);
await inserter.CompleteAsync();

ADO.NET / Dapper

// Use CH.Native.Dapper for the fast-path Dapper-shaped API on top of CH.Native.
using CH.Native.Dapper;

await using var connection = new ClickHouseDbConnection("Host=localhost;Port=9000");
await connection.OpenAsync();

// QueryAsync<T> here is CH.Native.Dapper's fast-path extension — routes
// through CH.Native's typed-accessor mapper, no boxing tax.
var users = await connection.QueryAsync<User>("SELECT * FROM users");

For DI scenarios where the connection is typed as IDbConnection, replace using Dapper; with using CH.Native.Dapper; to opt into the fast path automatically. See ADO.NET & Dapper for the full story.

Documentation

Samples

End-to-end runnable console projects under samples/. Each picks a flavour by CLI arg, creates a temp table, runs the demo, and drops the table.

Performance

Three-way comparison against ClickHouse.Driver (HTTP) and Octonica (native TCP). Each row shows time / memory; the best value in each row is bold.

The tables below cover the headline workloads. For the full benchmark matrix — every row-count scaling for reads/inserts, complex queries (GROUP BY / JOIN / WHERE / ORDER BY), compression algorithms (LZ4 / Zstd), connection-establishment latency, and specialised type comparisons (Geo, Variant, JSON) — see docs/performance-comparison.md.

Small queries (latency)

Streaming reads — 1M rows

CH.Native ships an opt-in StringMaterialization=Lazy mode that defers UTF-8 string decode until each field is accessed. The "lazy / default" cells below show both modes; the default mode also benefits from the typed-accessor read path.

Dapper-style API — 1M rows

CH.Native.Dapper provides Dapper-shaped extensions that route through CH.Native's typed-accessor mapper, sidestepping the per-value boxing Dapper's compiled mapper pays. Compared row-for-row against Dapper on top of ClickHouse.Driver:

Bulk insert — 1M rows

Test conditions

• Apple M5, .NET 10.0, ClickHouse 26.5.1 (Docker image clickhouse/clickhouse-server:latest resolved at run time).
• Driver: ClickHouse.Driver 1.2.0 (HTTP); Octonica: Octonica.ClickHouseClient 3.1.8 (native TCP).
• Reproduce with: dotnet run --project benchmarks/CH.Native.Benchmarks -c Release -- large (or dapper, insert, simple).

Requirements

• .NET 8.0, 9.0, or 10.0
• ClickHouse server with native protocol enabled (port 9000)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.