CH.Native 1.1.1

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, QueryAsync<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.QueryAsync<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.QueryAsync<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

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

// Dapper
var users = await connection.QueryAsync<User>("SELECT * FROM users");

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).

Query Latency

Large Result Sets

Bulk Insert

Memory Efficiency (1M rows)

Enable lazy string materialization via connection string (StringMaterialization=Lazy) or builder (.WithStringMaterialization(StringMaterialization.Lazy)). Lazy mode defers UTF-8 string decoding until values are accessed, reducing memory by ~68% for streaming reads. Best for ExecuteReaderAsync / QueryAsync workloads; typed queries (QueryAsync<T>) always use eager decoding.

Apple M5, .NET 10.0, ClickHouse 25.3 — run benchmarks with dotnet run --project benchmarks/CH.Native.Benchmarks -c Release

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.