{"id":21933103,"url":"https://github.com/kotlerman/kot.mongodb.migrations","last_synced_at":"2025-08-01T06:07:48.468Z","repository":{"id":64575577,"uuid":"460620678","full_name":"kotlerman/Kot.MongoDB.Migrations","owner":"kotlerman","description":"MongoDB migrations library for .NET","archived":false,"fork":false,"pushed_at":"2024-10-27T17:43:42.000Z","size":174,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T12:38:57.721Z","etag":null,"topics":["csharp","csharp-code","dotnet","migrations","mongodb","mongodb-driver","nuget","transactions"],"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/kotlerman.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":"2022-02-17T21:54:14.000Z","updated_at":"2024-10-27T19:23:26.000Z","dependencies_parsed_at":"2024-10-26T19:13:31.695Z","dependency_job_id":"37ffcc0f-bb77-46af-b843-bf7d45c97ee6","html_url":"https://github.com/kotlerman/Kot.MongoDB.Migrations","commit_stats":{"total_commits":107,"total_committers":2,"mean_commits":53.5,"dds":0.009345794392523366,"last_synced_commit":"04ae002d9ff5140349e02b7ccaa90dafb6892d05"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlerman%2FKot.MongoDB.Migrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlerman%2FKot.MongoDB.Migrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlerman%2FKot.MongoDB.Migrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlerman%2FKot.MongoDB.Migrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kotlerman","download_url":"https://codeload.github.com/kotlerman/Kot.MongoDB.Migrations/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249800050,"owners_count":21326996,"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":["csharp","csharp-code","dotnet","migrations","mongodb","mongodb-driver","nuget","transactions"],"created_at":"2024-11-29T00:07:46.644Z","updated_at":"2025-04-19T20:57:18.104Z","avatar_url":"https://github.com/kotlerman.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build](https://github.com/kotlerman/Kot.MongoDB.Migrations/actions/workflows/build.yml/badge.svg)](https://github.com/kotlerman/Kot.MongoDB.Migrations/actions/workflows/build.yml)\n[![Coverage Status](https://coveralls.io/repos/github/kotlerman/Kot.MongoDB.Migrations/badge.svg?branch=main)](https://coveralls.io/github/kotlerman/Kot.MongoDB.Migrations?branch=main)\n[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/kotlerman/Kot.MongoDB.Migrations/blob/main/LICENSE)\n\n# Kot.MongoDB.Migrations\nThis package enables you to create and run MongoDb migrations. Simple and clean, with minimal dependencies. Supports wrapping migrations in a transaction. To use with DI containers, see [Kot.MongoDB.Migrations.DI](#kotmongodbmigrationsdi) below.\n\n## Installation\nRun the following command in the NuGet Package Manager Console:\n```powershell\nPM\u003e Install-Package Kot.MongoDB.Migrations\n```\n\n## Usage\n### Creating migration classes\nCreate classes that describe your migrations. Each class must implement *IMongoMigration*. You can also derive from the *MongoMigration* class that provides a simple implementation.\n```csharp\nclass MyMigration : MongoMigration\n{\n    public MyMigration() : this(\"1.0.0\") { }\n\n    public override async Task UpAsync(IMongoDatabase db, IClientSessionHandle session, CancellationToken ct)\n    {\n        ...\n    }\n\n    public override async Task DownAsync(IMongoDatabase db, IClientSessionHandle session, CancellationToken ct)\n    {\n        ...\n    }\n}\n```\n\n### Configuring migrator\nCreate an instance of *IMigrator* using *MigratorBuilder* (you can also create it manually, if you need). Provide a connection string or an instance of *IMongoClient* and *MigrationOptions*, then choose where to load migrations from.\n```csharp\nvar options = new MigrationOptions(\"myDb\");\nvar migrator = MigratorBuilder.FromConnectionString(\"mongodb://localhost:27017\", options)\n    .LoadMigrationsFromCurrentDomain()\n    .WithLogger(...) // Use this to pass ILoggerFactory if you want logs\n    .Build();\n```\nCurrently migrations can be loaded with the following methods:\n- **LoadMigrationsFromCurrentDomain()** - load from current domain\n- **LoadMigrationsFromExecutingAssembly()** - load from executing assembly\n- **LoadMigrationsFromAssembly(Assembly assembly)** - load from a specified *assembly*\n- **LoadMigrationsFromNamespace(string @namespace)** - load from a specified *@namespace* (scans all assemblies of current domain)\n- **LoadMigrations(IEnumerable\u003cIMongoMigration\u003e migrations)** - load from a specified *migrations* collection\n\n\n### Running migrations\nTo apply migrations, add the following code. This will check which migrations were applied before and determine which migrations should be applied now. You can also pass a target version as an argument in case you want to migrate (up/down) to a specific version.\n```csharp\nMigrationResult result = await migrator.MigrateAsync();\n```\n\n### Transactions\nWith the help of transactions you can ensure that a database stays in a consistent state when migration process fails. Make sure you know what can and what cannot be done with a database when using transactions (see official [docs](https://www.mongodb.com/docs/upcoming/core/transactions/)).\nTo specify how to wrap migrations in transactions, set *TransactionScope* property of *MigrationOptions*. There are 3 options:\n- **None** - transactions are not used (this is the default value)\n- **SingleMigration** - each migration is wrapped in a separate transaction\n- **AllMigrations** - all migrations a wrapped in a single transaction\n\nExample:\n```csharp\nvar options = new MigrationOptions(\"myDb\")\n{\n    TransactionScope = TransactionScope.SingleMigration\n};\n```\n\nWhen one of the last two options is used, an instance of *IClientSessionHandle* is passed to the *UpAsync* and *UpAsync* methods of migrations. You should pass it to all DB operations like this:\n```csharp\npublic override async Task UpAsync(IMongoDatabase db, IClientSessionHandle session, CancellationToken cancellationToken)\n{\n    IMongoCollection\u003cTestDoc\u003e collection = db.GetCollection\u003cTestDoc\u003e(\"my_docs_collection\");\n    var doc = new TestDoc { SomeData = \"Some data\" };\n    await collection.InsertOneAsync(session, doc, null, cancellationToken);\n}\n```\n\nYou can further configure transactions behavior by setting *ClientSessionOptions* property of *MigrationOptions*:\n```csharp\nvar options = new MigrationOptions(\"myDb\")\n{\n    TransactionScope = TransactionScope.SingleMigration,\n    ClientSessionOptions = new ClientSessionOptions\n    {\n        DefaultTransactionOptions = new TransactionOptions(maxCommitTime: TimeSpan.FromMinutes(1))\n    }\n};\n```\n\n### Parallel runs\nYou might face situations with several parallel migration runs. E.g., if you migrate your DB on web app startup and there are several instances of the app. You can specify what to do in such cases by setting *ParallelRunsBehavior* property of *MigrationOptions*. There are 2 options:\n- **Cancel** - silently cancel current run (this is the default value)\n- **Throw** - throw an exception\n\nExample:\n```csharp\nvar options = new MigrationOptions(\"myDb\")\n{\n    ParallelRunsBehavior = ParallelRunsBehavior.Throw\n}\n```\n\n# Kot.MongoDB.Migrations.DI\nThis package enables you to use [Kot.MongoDB.Migrations](#kotmongodbmigrations) package with DI container. \n\n## Installation\nRun the following command in the NuGet Package Manager Console:\n```powershell\nPM\u003e Install-Package Kot.MongoDB.Migrations.DI\n```\n\n## Usage\nUse extension method to register migration services. By default, migrations are loaded from current domain. You can configure this with different overloads of the extension method. It is also possible to pass an instance of *IMongoClient* instead of connection string or to not pass anything (in this case an instance of *IMongoClient* will be resolved from container).\n```csharp\nvar options = new MigrationOptions(\"myDb\");\nservices.AddMongoMigrations(\"mongodb://localhost:27017\", options, config =\u003e config.LoadMigrationsFromCurrentDomain());\n```\nThen resolve an instance of *IMigrator* and use as described [above](#running-migrations).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkotlerman%2Fkot.mongodb.migrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkotlerman%2Fkot.mongodb.migrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkotlerman%2Fkot.mongodb.migrations/lists"}