CH.Native 0.1.18

CH.Native

A high-performance .NET 8 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.

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

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

Performance

CH.Native uses the native binary protocol (port 9000) instead of HTTP, resulting in lower latency and significantly reduced memory allocations.

Query Performance

Memory Efficiency

Benchmarks run on Apple M5, .NET 8.0, ClickHouse 24.8

Requirements

• .NET 8.0 or later
• 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 MIT License - see the LICENSE file for details.