SimpleMongoMigrations 1.0.16
dotnet add package SimpleMongoMigrations --version 1.0.16
NuGet\Install-Package SimpleMongoMigrations -Version 1.0.16
<PackageReference Include="SimpleMongoMigrations" Version="1.0.16" />
<PackageVersion Include="SimpleMongoMigrations" Version="1.0.16" />
<PackageReference Include="SimpleMongoMigrations" />
paket add SimpleMongoMigrations --version 1.0.16
#r "nuget: SimpleMongoMigrations, 1.0.16"
#addin nuget:?package=SimpleMongoMigrations&version=1.0.16
#tool nuget:?package=SimpleMongoMigrations&version=1.0.16
SimpleMongoMigrations
SimpleMongoMigrations is a lightweight wrapper around the official MongoDB C# Driver designed to help you manage document migrations in your MongoDB database. It supports standalone MongoDB instances, Azure CosmosDB for MongoDB, and AWS DocumentDB.
This project is inspired by and based on MongoDBMigrations.
Why a new package?
I decided to create a new NuGet package instead of using the original MongoDBMigrations or its forks, such as MongoDBMigrations (RZ version), for several reasons:
- Dependency issues: MongoDBMigrations relies on an outdated
MongoDB.Driver
version (2.14.1), which prevented me from upgrading my solutions. - Lack of support: The original project appears to be unmaintained, with long delays in responding to issues and merging pull requests.
- Learning opportunity: I wanted to gain hands-on experience in managing NuGet packages and setting up GitHub pipelines.
- Missing features: The initial library does not support executing migrations asynchronously.
How to use
See demos for .NET 6 and .NET Framework 4.7.2.
You can also see a real-life usage example in another project.
The migration engine can be set up and configured with a fluent API:
await MigrationEngineBuilder
.Create()
.WithConnectionString("mongodb://localhost:27017") // connection string
.WithDatabase("TestDB") // database name
.WithAssembly(Assembly.GetAssembly(typeof(_1_0_0_AddDefaultData))) // assembly to scan for migrations
.Build()
.RunAsync();
Unlike MongoDBMigrations, the Run
method does not expect a version. All migrations will be executed unless they are marked with the Ignore
attribute.
Simple migration example
You can also find migration samples in the demo and test projects.
The example below creates a new index on the Name
field in the City
collection. Each migration implements either the IMigration
or ITransactionalMigration
interface. Use ITransactionalMigration
only if your environment supports transactions. Standalone MongoDB instances do not support transactions. The only difference between these interfaces is that ITransactionalMigration
provides an UpAsync
method with a session parameter, which should be passed to every database operation to enable rollback in case of failure. If the migration engine detects that your environment doesn't support transactions, the UpAsync
method with a single parameter will be called as a fallback.
using MongoDB.Driver;
using SimpleMongoMigrations.Abstractions;
using SimpleMongoMigrations.Attributes;
using SimpleMongoMigrations.Demo.Models;
namespace SimpleMongoMigrations.Demo.Migrations
{
[Version("1")]
[Name("Adds a unique index by name")]
public class _1_0_0_AddIndexByName : IMigration
{
public Task UpAsync(
IMongoDatabase database,
CancellationToken cancellationToken)
{
return database.GetCollection<City>(nameof(City)).Indexes.CreateOneAsync(
new CreateIndexModel<City>(
Builders<City>.IndexKeys.Ascending(x => x.Name),
new CreateIndexOptions
{
Unique = true
}),
cancellationToken: cancellationToken);
}
}
}
Note: The
IMigration
interface does not include aDown
method. This means you cannot roll back migrations or downgrade your database.
Transactions
Transactions help ensure your database remains in a consistent state if the migration process fails.
To specify how migrations are wrapped in transactions, pass a TransactionScope
value to WithTransactionScope
when configuring the MigrationEngine
. There are three options:
- NoTransaction – Transactions are not used (default).
- PerMigration – Each migration is wrapped in a separate transaction.
- SingleTransaction – All migrations are wrapped in a single transaction.
await MigrationEngineBuilder
.Create()
.WithConnectionString("mongodb://localhost:27017") // connection string
.WithDatabase("TestDB") // database name
.WithAssembly(Assembly.GetAssembly(typeof(_1_0_0_AddIndexByName))) // assembly to scan for migrations
.WithTransactionScope(TransactionScope.SingleTransaction) // Optional, can be omitted if not needed
.Build()
.RunAsync(default);
Use ITransactionalMigration
only if your environment supports transactions in combination with the SingleMigration
or AllMigrations
options. An instance of IClientSessionHandle
is passed to the UpAsync
method of your migrations. You should pass this session to all database operations. If the migration engine detects that your environment doesn't support transactions, the UpAsync
method with a single parameter will be called as a fallback.
[Version("1")]
[Name("Adds a unique index by name")]
public class _1_0_0_AddIndexByName : ITransactionalMigration
{
public Task UpAsync(
IMongoDatabase database,
CancellationToken cancellationToken)
{
return database.GetCollection<City>(nameof(City)).Indexes.CreateOneAsync(
new CreateIndexModel<City>(
Builders<City>.IndexKeys.Ascending(x => x.Name),
new CreateIndexOptions
{
Unique = true
}),
cancellationToken: cancellationToken);
}
public Task UpAsync(
IMongoDatabase database,
IClientSessionHandle session,
CancellationToken cancellationToken)
{
return database.GetCollection<City>(nameof(City)).Indexes.CreateOneAsync(
session,
new CreateIndexModel<City>(
Builders<City>.IndexKeys.Ascending(x => x.Name),
new CreateIndexOptions
{
Unique = true
}),
cancellationToken: cancellationToken);
}
}
Note: Multi-document transactions are supported only on certain MongoDB deployments:
MongoDB Deployment Type | Supports Transactions | Notes |
---|---|---|
Standalone MongoDB | ❌ No | Single-node deployments do not support transactions. |
Replica Set (MongoDB 4.0+) | ✅ Yes | Multi-document transactions supported starting with MongoDB 4.0. |
Sharded Cluster (MongoDB 4.2+) | ✅ Yes | Requires MongoDB 4.2+ and sharded collections. |
MongoDB Atlas Free/Shared (M0/M2/M5) | ✅ Yes | Uses replica sets by default. Transactions are available. |
MongoDB Atlas Dedicated Cluster (M10+) | ✅ Yes | Fully supports transactions. |
Azure Cosmos DB (MongoDB API v4.0+) | ✅ Yes (limited) | Only within the same partition key; no cross-partition support. |
Standalone MongoDB instances do not support multi-document transactions. The migration engine automatically detects whether transactions are supported. If transactions are not supported, the transaction scope specified in WithTransactionScope
will be ignored, and the session
parameter of the UpAsync
method will be null
.
Limitations:
- All operations in a transaction must be on collections within the same database.
- Transactions have duration and size limits (e.g., 60 seconds and 16MB in MongoDB).
- Cosmos DB supports multi-document transactions only within a single partition key value.
Ensure your migration logic is compatible with these limitations and always test transactional migrations in your target environment.
Migration history compatibility
SimpleMongoMigrations maintains migration history in a way that is compatible with MongoDBMigrations. If you are already using MongoDBMigrations, you do not need to make any changes to your database—only minor code adjustments may be required to refactor your migrations.
Below is a sample entry created in the _migrations
collection:
{
"_id" : ObjectId("6828faf9642d86f79f782e4f"),
"n" : "Adds a unique index by name",
"v" : "0.0.3",
"d" : true,
"applied" : ISODate("2025-05-17T21:09:13.355+0000")
}
License
SimpleMongoMigrations is licensed under the MIT License.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
.NET Framework | net472 is compatible. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.7.2
- MongoDB.Driver (>= 3.4.0)
-
.NETStandard 2.1
- MongoDB.Driver (>= 3.4.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.0.16 | 120 | 5/29/2025 |
1.0.15 | 115 | 5/28/2025 |
1.0.14 | 130 | 5/27/2025 |
1.0.13 | 129 | 5/26/2025 |
1.0.12 | 131 | 5/26/2025 |
1.0.11 | 136 | 5/26/2025 |
1.0.10 | 139 | 5/26/2025 |
1.0.9 | 128 | 5/25/2025 |
1.0.8 | 131 | 5/25/2025 |
1.0.7 | 84 | 5/25/2025 |
1.0.6 | 94 | 5/25/2025 |
1.0.5 | 132 | 5/18/2025 |
1.0.4 | 131 | 5/18/2025 |
1.0.3 | 132 | 5/18/2025 |
1.0.2 | 96 | 5/17/2025 |
1.0.1 | 92 | 5/17/2025 |
1.0.0 | 91 | 5/17/2025 |