{"id":19961014,"url":"https://github.com/mikeamputer/clickhouse.facades","last_synced_at":"2026-03-08T21:25:20.145Z","repository":{"id":199896014,"uuid":"704025662","full_name":"MikeAmputer/ClickHouse.Facades","owner":"MikeAmputer","description":"Raw SQL migrations and contexts for ClickHouse","archived":false,"fork":false,"pushed_at":"2024-05-19T02:11:19.000Z","size":140,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-05-19T05:42:23.179Z","etag":null,"topics":["clickhouse","context","csharp","dotnet","migrations","testing"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MikeAmputer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-12T11:40:18.000Z","updated_at":"2024-05-29T06:57:55.423Z","dependencies_parsed_at":"2023-10-13T08:17:41.410Z","dependency_job_id":"26dfb45e-6c77-4fa3-9cc1-80fa49a2452b","html_url":"https://github.com/MikeAmputer/ClickHouse.Facades","commit_stats":null,"previous_names":["mikeamputer/clickhouse.facades"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeAmputer%2FClickHouse.Facades","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeAmputer%2FClickHouse.Facades/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeAmputer%2FClickHouse.Facades/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeAmputer%2FClickHouse.Facades/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MikeAmputer","download_url":"https://codeload.github.com/MikeAmputer/ClickHouse.Facades/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224374797,"owners_count":17300691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","context","csharp","dotnet","migrations","testing"],"created_at":"2024-11-13T02:06:07.945Z","updated_at":"2026-03-08T21:25:20.131Z","avatar_url":"https://github.com/MikeAmputer.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ClickHouse.Facades\n[![Latest version](https://img.shields.io/nuget/v/ClickHouse.Facades)](https://www.nuget.org/packages/ClickHouse.Facades/)\n[![License](https://img.shields.io/github/license/MikeAmputer/ClickHouse.Facades)](https://github.com/MikeAmputer/ClickHouse.Facades/blob/master/LICENSE)\n[![Wiki](https://img.shields.io/badge/wiki-docs-lightgrey?logo=github)](https://github.com/MikeAmputer/ClickHouse.Facades/wiki)\n\nZero-ORM .NET package for managing [ClickHouse](https://github.com/ClickHouse/ClickHouse) migrations and organizing raw SQL through structured database contexts.\nMakes it easy to separate concerns across features, services, or tables.\nBuilt on [ClickHouse.Driver](https://github.com/ClickHouse/clickhouse-cs) ([ClickHouse.Client](https://github.com/DarkWanderer/ClickHouse.Client) for version `\u003c 3.0.0`) and tested in production.\n\n[Does OLAP need an ORM?](https://clickhou.se/3Jy2uF8)\n\n\u003e [!NOTE]\n\u003e This is an unofficial package and is not affiliated with or endorsed by ClickHouse Inc.\n\u003e \n\u003e \"ClickHouse\" is a registered trademark of ClickHouse Inc. — [clickhouse.com](https://clickhouse.com/)\n\n## Key Features\n- **Migrations:** allows you to perform raw SQL migrations on your ClickHouse database.\n  - Rollback support\n  - Supports file-based migrations\n    - Customizable migration file name parser\n    - Customizable file content parser\n  - Supports code-defined (inline) migrations using C# classes\n  - Conditional migrations based on ClickHouse server version\n  - [Migration template](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/src/ClickHouse.Facades.Templates) for .NET CLI\n- **Contexts:** provides a way to work with ClickHouse contexts, allowing you to organize your database operations in a structured manner.\n  - Context-specific migrations, allowing separate migration management for distinct packages or components\n  - Parametrized queries (anonymous type parameters supported)\n  - Query cancellation by termination on ClickHouse side\n  - Transactions support (keeper is required)\n  - Retryable contexts\n  - [Dapper](https://github.com/DapperLib/Dapper) compatibility (reader deserialization)\n  - Provides all the features of the ClickHouse.Driver/ClickHouse.Client package\n  - Fully async contract\n- **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.\n  - Facades mocking\n  - Specific requests mocking and tracking\n- **Comprehensive documentation** presented in [repository Wiki](https://github.com/MikeAmputer/ClickHouse.Facades/wiki).\n\n## Migrations Usage\nImplement `IClickHouseMigrationInstructions` and `IClickHouseMigrationsLocator`\n([example](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/examples/Example.Simple/Migrations/Settings))\nand register them as DI services\n```csharp\nservices.AddClickHouseMigrations\u003cClickHouseMigrationInstructions, ClickHouseMigrationsLocator\u003e();\n```\nYou can request `IClickHouseMigrator` service or use `IServiceProviderExtensions` to manage migrations\n```csharp\nawait serviceProvider.ClickHouseMigrateAsync();\n```\n\n### Add Migrations\nAdd `ClickHouseMigration` inheritor with `ClickHouseMigration` attribute\n```csharp\n[ClickHouseMigration(202310240941, \"ExampleMigration\")]\npublic class ExampleMigration : ClickHouseMigration\n{\n    protected override void Up(ClickHouseMigrationBuilder migrationBuilder)\n    {\n        // migrationBuilder.AddRawSqlStatement(\"create table if not exists ...\")\n    }\n\n    protected override void Down(ClickHouseMigrationBuilder migrationBuilder)\n    {\n        // migrationBuilder.AddRawSqlStatement(\"drop table if exists ...\")\n    }\n}\n```\nThe 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.\n\n## Context Usage\nImplement the following class inheritors: `ClickHouseContext\u003cTContext\u003e`, `ClickHouseContextFactory\u003cTContext\u003e`, `ClickHouseFacade\u003cTContext\u003e`\n([example](https://github.com/MikeAmputer/ClickHouse.Facades/tree/master/examples/Example.Simple/Context))\nand register them as DI services\n```csharp\nservices.AddClickHouseContext\u003cExampleContext, ExampleContextFactory\u003e(builder =\u003e builder\n    .AddFacade\u003cUsersFacade\u003e()\n    .AddFacade\u003cOrdersFacade\u003e());\n```\nRequest `IClickHouseContextFactory\u003cTContext\u003e` service to create context\n```csharp\nawait using var context = await contextFactory.CreateContextAsync();\n\nvar ordersFacade = context.GetFacade\u003cOrdersFacade\u003e();\n\nawait ordersFacade.GetOrders();\n```\nYou can create as many contexts as you need with any number of facades. Facades are built via DI and are stateful within context lifetime.\n\n\u003e [!NOTE]\n\u003e You can perform migrations on your ClickHouse database without the necessity of implementing contexts.\n\n## Examples\n\nFor 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. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeamputer%2Fclickhouse.facades","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeamputer%2Fclickhouse.facades","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeamputer%2Fclickhouse.facades/lists"}