Aiursoft.ClickhouseSdk 10.0.13

Aiursoft ClickHouse SDK & Logger Provider

A high-performance, textbook-grade ClickHouse integration suite for .NET applications. It provides an effortless way to interact with ClickHouse using a "DbContext" style pattern and a high-performance logging provider for the standard Microsoft.Extensions.Logging infrastructure.

Key Features

• Automatic Schema Management: Automatically creates databases and tables. Supports schema evolution (automatically adds missing columns).
• High-Performance Bulk Writing: Uses ClickHouseBulkCopy for asynchronous, non-blocking batch uploads.
• Background Log Flushing: Buffered logging with background flushing to ensure zero impact on application performance.
• Clean Configuration: Standard ClickHouse connection strings. Table names are managed through code or configuration.

Project 1: Aiursoft.ClickhouseSdk (Core SDK)

The core SDK provides the base infrastructure for ClickHouse communication.

Installation

dotnet add package Aiursoft.ClickhouseSdk

Basic Usage

1. Define your Entity: Create a class representing your data row.

2. Create your DbContext: Inherit from ClickhouseDbContext and define your sets.

using Aiursoft.ClickhouseSdk;
using Aiursoft.ClickhouseSdk.Abstractions;

public class MyDbContext : ClickhouseDbContext
{
    public ClickhouseSet<MyEntity> MyEntities { get; }

    public MyDbContext(IOptionsMonitor<ClickhouseOptions> options) : base(options)
    {
        // Define the mapping from your entity to ClickHouse row objects
        // You can have multiple sets mapping to different tables in the same database!
        MyEntities = new ClickhouseSet<MyEntity>(GetConnection, "MyTableName", entity => new object[] 
        {
            entity.Id,
            entity.Name,
            entity.CreatedAt
        });
    }

    public override async Task SaveChangesAsync()
    {
        await MyEntities.SaveChangesAsync();
    }
}

3. Register and Configure: In your Program.cs, register your DbContext and bind the configuration.

// 1. Bind configuration (from appsettings.json or environment variables)
builder.Services.Configure<ClickhouseOptions>(options => 
{
    options.ConnectionString = "Host=localhost;Database=MyBusinessDb;User=default;Password=password";
});

// 2. Register your custom DbContext
builder.Services.AddSingleton<MyDbContext>();

4. Initialize the Schema: Call InitClickhouseTableAsync<T> during application startup.

// This will ensure 'MyTableName' exists in the database defined in your connection string.
await host.Services.InitClickhouseTableAsync<MyEntity>("MyTableName", "CreatedAt"); 

Configuration via appsettings.json

Both projects use the same ClickhouseOptions structure. You can define your settings in appsettings.json:

{
  "Clickhouse": {
    "ConnectionString": "Host=localhost;Database=DemoDb;User=default;Password=password",
    "TableName": "AppLogs", 
    "Enabled": true
  }
}

And bind it in your code:

builder.Services.Configure<ClickhouseOptions>(builder.Configuration.GetSection("Clickhouse"));

Project 2: Aiursoft.ClickhouseLoggerProvider (Logging)

A specialized provider that redirects standard ILogger output to ClickHouse.

Installation

dotnet add package Aiursoft.ClickhouseLoggerProvider

Registration

Register the provider in your application builder.

builder.Logging.AddClickhouse(options => 
{
    options.ConnectionString = "Host=localhost;Protocol=http;Port=8123;User=default;Password=password;Database=MyLogs";
    options.TableName = "AppLogs"; // Optional, defaults to "AppLogs"
});

Initialization

Ensure the logging table is initialized at startup.

await host.Services.InitLoggingTableAsync();

How to Contribute

We welcome contributions! Please follow these steps:

1. Fork the repository.
2. Create a feature branch.
3. Ensure all code passes lint.sh and all tests pass.
4. Submit a Pull Request.

License

This project is licensed under the MIT License.