SimpleMongoMigrations 1.0.16

dotnet add package SimpleMongoMigrations --version 1.0.16
                    
NuGet\Install-Package SimpleMongoMigrations -Version 1.0.16
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SimpleMongoMigrations" Version="1.0.16" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="SimpleMongoMigrations" Version="1.0.16" />
                    
Directory.Packages.props
<PackageReference Include="SimpleMongoMigrations" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add SimpleMongoMigrations --version 1.0.16
                    
#r "nuget: SimpleMongoMigrations, 1.0.16"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#addin nuget:?package=SimpleMongoMigrations&version=1.0.16
                    
Install SimpleMongoMigrations as a Cake Addin
#tool nuget:?package=SimpleMongoMigrations&version=1.0.16
                    
Install SimpleMongoMigrations as a Cake Tool

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 a Down 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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