SimpleMongoMigrations 1.0.5

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.

How to use

new MigrationEngine(
    "mongodb://localhost:27017", // connection string
    "TestDB", // database name
    Assembly.GetAssembly(typeof(_001_AddDefaultData)) // assembly to scan for migrations
).Run();

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

See demos for .NET 6 and .NET Framework 4.7.2.

using MongoDB.Driver;
using SimpleMongoMigrations.Abstractions;
using SimpleMongoMigrations.Attributes;
using SimpleMongoMigrations.ConsoleAppNet6.Models;

namespace SimpleMongoMigrations.Tests.Migrations
{
    [Version("0.0.3")] // You can also use numbers for versions, such as 1, 2, 3, etc.
    [Name("Adds a unique index by name")] // Optional text description
    [Ignore] // Ignore this migration, for instance, if it causes issues
    public class _003_AddIndexByName : IMigration
    {
        public void Up(IMongoDatabase database)
        {
            database.GetCollection<City>(nameof(City)).Indexes.CreateOne(new CreateIndexModel<City>(
                Builders<City>.IndexKeys.Ascending(x => x.Name),
                new CreateIndexOptions
                {
                    Unique = true
                }));
        }
    }
}

Note that the IMigration interface does not include a Down method. This means you cannot roll back migrations or downgrade your database.

Migration history

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")
}

Transactions

Transactions are not supported at the moment. However, support for transactions is planned for a future release.

License

SimpleMongoMigrations is licensed under the MIT License.