ClickHouse.Facades

Raw SQL migrations and contexts for ClickHouse referencing ClickHouse.Client

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.
  • Per context migrations, allowing separate migration management for distinct packages or components
  • Parametrized queries (anonyomous type parameters supported)
  • Query cancellation by termination on ClickHouse side
  • 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.

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 = contextFactory.CreateContext();

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.

Documentation

Documentation will be presented in repository Wiki (WIP)