Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mikeamputer/clickhouse.facades
Raw SQL migrations and contexts for ClickHouse
https://github.com/mikeamputer/clickhouse.facades
clickhouse context csharp dotnet migrations testing
Last synced: 5 days ago
JSON representation
Raw SQL migrations and contexts for ClickHouse
- Host: GitHub
- URL: https://github.com/mikeamputer/clickhouse.facades
- Owner: MikeAmputer
- License: mit
- Created: 2023-10-12T11:40:18.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-05-19T02:11:19.000Z (6 months ago)
- Last Synced: 2024-05-19T05:42:23.179Z (6 months ago)
- Topics: clickhouse, context, csharp, dotnet, migrations, testing
- Language: C#
- Homepage:
- Size: 137 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ClickHouse.Facades
Raw SQL migrations and contexts for [ClickHouse](https://github.com/ClickHouse/ClickHouse) referencing [ClickHouse.Client](https://github.com/DarkWanderer/ClickHouse.Client). Production tested.
[](https://www.nuget.org/packages/ClickHouse.Facades/)
[](https://github.com/MikeAmputer/ClickHouse.Facades/blob/master/LICENSE)
## Key Features
- **Migrations:** allows you to perform raw SQL migrations on your ClickHouse database.
- Rollback support
- Fully async contract
- [Migration template](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/src/ClickHouse.Facades.Templates) 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](https://github.com/DapperLib/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](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/src/ClickHouse.Facades.Testing) package.
- Facades mocking
- Specific requests mocking and tracking
- **Comprehensive documentation** presented in [repository Wiki](https://github.com/MikeAmputer/ClickHouse.Facades/wiki).
## Migrations Usage
Implement `IClickHouseMigrationInstructions` and `IClickHouseMigrationsLocator`
([example](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/examples/Example.Simple/Migrations/Settings))
and register them as DI services
```csharp
services.AddClickHouseMigrations();
```
You can request `IClickHouseMigrator` service or use `IServiceProviderExtensions` to manage migrations
```csharp
await serviceProvider.ClickHouseMigrateAsync();
```
### Add Migrations
Add `ClickHouseMigration` inheritor with `ClickHouseMigration` attribute
```csharp
[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`, `ClickHouseContextFactory`, `ClickHouseFacade`
([example](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/examples/Example.Simple/Context))
and register them as DI services
```csharp
services.AddClickHouseContext(builder => builder
.AddFacade()
.AddFacade());
```
Request `IClickHouseContextFactory` service to create context
```csharp
await using var context = await contextFactory.CreateContextAsync();
var ordersFacade = context.GetFacade();
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](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/examples) provided in the repository.