{"id":21281744,"url":"https://github.com/prophetlamb/csharp-mongo-migrations","last_synced_at":"2026-04-17T04:33:23.404Z","repository":{"id":205285123,"uuid":"713866505","full_name":"ProphetLamb/csharp-mongo-migrations","owner":"ProphetLamb","description":"Simple database migrations for `MongoDB.Driver` using ASP.NET.","archived":false,"fork":false,"pushed_at":"2025-11-11T14:21:48.000Z","size":268,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-11T15:06:11.701Z","etag":null,"topics":["asp-net-core","csharp","database-migrations","migration","mongodb"],"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/ProphetLamb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-11-03T12:01:28.000Z","updated_at":"2025-11-11T14:21:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"9c4bd81b-5858-45bb-9ac3-837df9e0c8aa","html_url":"https://github.com/ProphetLamb/csharp-mongo-migrations","commit_stats":null,"previous_names":["prophetlamb/csharp-mongo-migrations"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/ProphetLamb/csharp-mongo-migrations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProphetLamb%2Fcsharp-mongo-migrations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProphetLamb%2Fcsharp-mongo-migrations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProphetLamb%2Fcsharp-mongo-migrations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProphetLamb%2Fcsharp-mongo-migrations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ProphetLamb","download_url":"https://codeload.github.com/ProphetLamb/csharp-mongo-migrations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProphetLamb%2Fcsharp-mongo-migrations/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31915256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["asp-net-core","csharp","database-migrations","migration","mongodb"],"created_at":"2024-11-21T10:50:33.577Z","updated_at":"2026-04-17T04:33:23.363Z","avatar_url":"https://github.com/ProphetLamb.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Banner](Images/Banner.png)\n\n# MongoDB Migrations\n\nSimple database migrations for [`MongoDB.Driver`](https://github.com/mongodb/mongo-csharp-driver) using [`ASP.NET`](https://dotnet.microsoft.com/en-us/apps/aspnet) DI.\n\n## Quick start\n\nInstall the [NuGet package](https://www.nuget.org/packages/csharp-mongodb-migrations/) \u0026 Implement the database migrations system in your solution using the following steps:\n\n```bash\ndotnet add package csharp-mongodb-migrations\n```\n\n1.  [Inject migrations service](#inject-migrations-service)\n2.  [Update settings](#update-settings)\n3.  [Await migrations](#await-migrations)\n4.  [Implement migrations](#implement-migrations)\n\n### Inject migrations service\n\nInject `AddMigrations` into your services.\n\n-   If migrations are not in the `Assembly.GetEntryAssembly`, then manually specify the assemblies in the parameters of `AddMigrations`.\n-   Call `AddMigrations` after configuring options.\n\n```csharp\nusing MongoDB.Migration;\n\nservices\n    .Configure\u003cMyDatabaseSettings\u003e(builder.Configuration.GetSection(\"Database:MyDatabaseSettings\"))\n    .AddMigrations()\n```\n\n### Update settings\n\nImplement `IMongoMigratable` for your database settings.\n\n-   Options must be configured before injecting services.\n-   A `Database.Alias` must be unique: The name used to identify the database during runtime.\n-   A `Database.Name` must be unique: The name of the actual MongoDB database.\n-   Assign a unique constant value to `MigrationDescriptor.Database.Alias`.\n\n```csharp\npublic sealed record MyDatabaseSettings : IOptions\u003cMyDatabaseSettings\u003e, IMongoMigratable\n{\n    public required string ConnectionString { get; init; }\n    public required string DatabaseName { get; init; }\n    public required string MyCollectionName { get; init; }\n\n    MyDatabaseSettings IOptions\u003cMyDatabaseSettings\u003e.Value =\u003e this;\n\n    public MongoMigrableDefinition GetMigratableDefinition()\n    {\n        return new()\n        {\n            ConnectionString = ConnectionString,\n            Database = new(\"MyDatabase\", DatabaseName),\n            MirgrationStateCollectionName = \"DATABASE_MIGRATIONS\"\n        };\n    }\n}\n```\n\n### Await migrations\n\nWait for migrations to complete using `IMongoMigrationCompletion` before accessing the database at any point.\n\n-   `WaitAsync` may not ever be called in constructors.\n-   `WaitAsync` is fast when the migration is completed, or the database is not configured.\n\n```csharp\nsealed class MyRepository(IOptions\u003cMyDatabaseSettings\u003e databaseSettings, IMongoMigrationCompletion migrationCompletion) {\n    private readonly IMongoCollection\u003cMyModel\u003e _myCollection = new MongoClient(databaseSettings.ConnectionString)\n        .GetDatabase(databaseSettings.DatabaseName)\n        .GetCollection\u003cMyModel\u003e(databaseSettings.MyCollectionName);\n\n    public async Task\u003cMyModel\u003e GetOrSetAsync(MyModel insertModel, CancellationToken cancellationToken = default) {\n        var migrated = await migrationCompletion.WaitAsync(databaseSettings.Value, cancellationToken).ConfigureAwait(false);\n        // ... do stuff\n    }\n}\n```\n\n### Implement migrations\n\nAdd `IMongoMigration`s between version 0 and 1 and so on.\n\n-   The alias used for the `MongoMigrationAttribute` must match the name in `IMongoMigratable.GetMigrationSettings().Database.Alias`.\n\n```csharp\n[MongoMigration(\"MyDatabase\", 0, 1, Description = \"Add composite index to MyCollection\")]\npublic sealed class MyCollectionAddCompositeIndexMigration(IOptions\u003cMyDatabaseSettings\u003e optionsAccessor) : IMongoMigration\n{\n    public async Task DownAsync(IMongoDatabase database, CancellationToken cancellationToken = default)\n    {\n    }\n\n    public async Task UpAsync(IMongoDatabase database, CancellationToken cancellationToken = default)\n    {\n    }\n}\n```\n\n## Fixing database versions\n\nA fixed database version ensures that the migration always produces a database of the specified version, even if the initial version was higher than the fixed version.\n\n-   Fixing upgrades the database, if the initial version is lower than the fixed version.\n-   Fixing downgrades the database, if the initial version is higher than the fixed version.\n-   Fixing the database to a version is especially useful for a procedural feature rollout.\n\nFix a specific version by setting the `long? MigrateToFixedVersion` property in your `IMongoMigratable`; if the property is `null` - by default - a migration to the latest version will occur.\n\n```csharp\npublic MongoMigrableDefinition GetMigratableDefinition()\n{\n    return new()\n    {\n        ConnectionString = ConnectionString,\n        Database = new(\"MyDatabase\", DatabaseName),\n        MirgrationStateCollectionName = \"DATABASE_MIGRATIONS\",\n        MigrateToFixedVersion = 42069,\n    };\n}\n```\n\n## Migrations without ASP.NET DI\n\nMongoDB Migration extensively uses ASP.NET to prepare the environment required for processing of migrations. Without ASP.NET most features are unavailable, but the core - `DatabaseMirationProcessor` - public API; it is accessible to the user.\n\n1.  Describe your database in the `MongoMigrableDefinition` record.\n2.  Wrap instances of all available `IMongoMigration`s in the `MigrationDescriptor` record.\n3.  Instantiate `DatabaseMirationProcessor` for your database.\n4.  Call `MigrateToVersionAsync` with the available `MigrationDescriptor`s.\n\n## Testing\n\nTests require a local mongodb instance without authentication at port 27017: `mongodb://localhost:27017`.\n\n## Disclaimer\n\n`csharp-mongo-migration` is not affiliated with or endorsed by [MongoDB](https://www.mongodb.com), Inc. MONGODB \u0026 MONGO are registered trademarks of MongoDB, Inc. 2023.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprophetlamb%2Fcsharp-mongo-migrations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprophetlamb%2Fcsharp-mongo-migrations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprophetlamb%2Fcsharp-mongo-migrations/lists"}