ClickHouse.Facades 2.5.9

ClickHouse.Facades

Raw SQL migrations and contexts for ClickHouse referencing ClickHouse.Client. Production tested.

Key Features

• Migrations: allows you to perform raw SQL migrations on your ClickHouse database.
  • Rollback support
  • Fully async contract
  • 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.

[!NOTE] You can perform migrations on your ClickHouse database without the necessity of implementing contexts.

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.