Raw SQL migrations and contexts for ClickHouse referencing ClickHouse.Client

• 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
  • Provides all the features of the ClickHouse.Client package
  • Fully async contract
• Testing toolkit: seamlessly integrate unit testing into your ClickHouse.Facades components using the dedicated ClickHouse.Facades.Testing package. Test ClickHouse contexts and facades effectively, mock facades or specific database requests, and monitor interactions with the ClickHouse database using the provided testing tools.
• Comprehensive documentation presented in repository Wiki.

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

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.

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.