ClickHouse.Facades 2.9.1

ClickHouse.Facades

.NET package for managing ClickHouse migrations and organizing raw SQL through structured database contexts. Makes it easy to separate concerns across features, services, or tables. Built on ClickHouse.Client and tested in production.

Key Features

• Migrations: allows you to perform raw SQL migrations on your ClickHouse database.
  • Rollback support
  • Supports file-based migrations
    • Customizable migration file name parser
    • Customizable file content parser
  • Supports code-defined (inline) migrations using C# classes
  • Conditional migrations based on ClickHouse server version
  • Migration template for .NET CLI
• Contexts: provides a way to work with ClickHouse contexts, allowing you to organize your database operations in a structured manner.
  • Context-specific migrations, allowing separate migration management for distinct packages or components
  • Parametrized queries (anonymous type parameters supported)
  • Query cancellation by termination on ClickHouse side
  • Transactions support (keeper is required)
  • Retryable contexts
  • Dapper compatibility (reader deserialization)
  • Provides all the features of the ClickHouse.Client package
  • Fully async contract
• Testing toolkit: provides tools for unit testing components of ClickHouse.Facades with the dedicated ClickHouse.Facades.Testing package.
  • Facades mocking
  • Specific requests mocking and tracking
• Comprehensive documentation presented in repository Wiki.

Migrations Usage

Implement IClickHouseMigrationInstructions and IClickHouseMigrationsLocator (example) and register them as DI services

services.AddClickHouseMigrations<ClickHouseMigrationInstructions, ClickHouseMigrationsLocator>();

You can request IClickHouseMigrator service or use IServiceProviderExtensions to manage migrations

await serviceProvider.ClickHouseMigrateAsync();

Add Migrations

Add ClickHouseMigration inheritor with ClickHouseMigration attribute

[ClickHouseMigration(202310240941, "ExampleMigration")]
public class ExampleMigration : ClickHouseMigration
{
    protected override void Up(ClickHouseMigrationBuilder migrationBuilder)
    {
        // migrationBuilder.AddRawSqlStatement("create table if not exists ...")
    }

    protected override void Down(ClickHouseMigrationBuilder migrationBuilder)
    {
        // migrationBuilder.AddRawSqlStatement("drop table if exists ...")
    }
}

The index of ClickHouseMigrationAttribute is used to order migrations. It's best to always use idempotent statements (for example with if [not] exists) since migration may fail.

Context Usage

Implement the following class inheritors: ClickHouseContext<TContext>, ClickHouseContextFactory<TContext>, ClickHouseFacade<TContext> (example) and register them as DI services

services.AddClickHouseContext<ExampleContext, ExampleContextFactory>(builder => builder
    .AddFacade<UsersFacade>()
    .AddFacade<OrdersFacade>());

Request IClickHouseContextFactory<TContext> service to create context

await using var context = await contextFactory.CreateContextAsync();

var ordersFacade = context.GetFacade<OrdersFacade>();

await ordersFacade.GetOrders();

You can create as many contexts as you need with any number of facades. Facades are built via DI and are stateful within context lifetime.

Examples

For a deeper understanding and practical use cases of how to implement migrations and facades, please refer to the examples folder provided in the repository.