MongoDBMigrations 1.1.0

Additional Details

All versions 1.*.* are deprecated and no longer supported. Please use version 2.0.0 and higher. They contain brand new fluent API, lots of improvements. Migrations are from elder versions 100% compatible with the latest version. So don't afraid to upgrade.

There is a newer version of this package available.
See the version list below for details.
dotnet add package MongoDBMigrations --version 1.1.0
NuGet\Install-Package MongoDBMigrations -Version 1.1.0
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="MongoDBMigrations" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add MongoDBMigrations --version 1.1.0
#r "nuget: MongoDBMigrations, 1.1.0"
#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.
// Install MongoDBMigrations as a Cake Addin
#addin nuget:?package=MongoDBMigrations&version=1.1.0

// Install MongoDBMigrations as a Cake Tool
#tool nuget:?package=MongoDBMigrations&version=1.1.0

MongoDBMigrations

NuGet

MongoDBMigrations using the official MongoDB C# Driver to migrate your documents in database No more downtime for schema-migrations. Just write small and simple migrations.

We need migrations when:
1. Rename collections
2. Rename keys
3. Manipulate data types
4. Index creation
5. Removing collections / data

New Features!

  • Added: MongoDB document schema uniformity validation
  • Added: Async impl for runner and database locator
  • See more...

Next Feature/Todo

  • Diff calculation
  • Auto generated migrations
  • Migration as part of CI

Installation

MongoDBMigrations tested with .NET Core 2.0+
https://www.nuget.org/packages/MongoDBMigrations/

PM> Install-Package MongoDBMigrations -Version 1.1.0

How to use

Create a migration by impelmeting the interface IMigration. Best practice for the version is to use Semantic Versioning but ultimately it is up to you. You could simply use the patch version to count the number of migrations. If there is a duplicate for a specific type an exception is thrown on initialization. This is the simple migration template. Method Up used for migrate your database forward and Down to rollback thus these methods must do the opposite things. Please keep it in mind.

//Create migration
public class MyTestMigration : IMigration
{
    public Verstion Version => new Version(1,1,0);
    public string Name => "Some descrioption about this migration.";
    public void Up(IMongoDatabase database)
    {
        // ...
    }
    
    public void Down(IMongoDatabase database)
    {
        // ...
    }
}

Use next code for initialize MigrationRunner and start migration.

var options = new MigrationRunnerOptions
{
    ConnectionString = CONNECTION_STRING,
    DatabaseName = DATABASE,
    IsSchemeValidationActive = true, // Use true for engage schema validation, otherwise false
    MigrationProjectLocation = @"<some_path_here>" //also needs for schema validation, it's absolute path for *.csproj file with migration classes
};
//Create instance of runner
var runner = new MigrationRunner(options);
//Find and set assembly with our migrations. If you don't call this method, runner try to find migrations in assembly from which the call is made
runner.Locator.LookInAssemblyOfType<MyTestMigration>();
//Start migration to version 1.1.0 when you don't need result
runner.UpdateTo(new Version(1,1,0));

//Start migration to version 1.0.0 and getting result of each migration between current and target versions
var result = runner.UpdateTo(new Version(1,0,0));

You also can get progress of migration process, just subscribe to MigrationApplied event

runner.MigrationApplied += Handle;
var result = runner.UpdateTo(new Version(1, 1, 0));
runner.MigrationApplied -= Handle;

where Handle is:

private void Handle(object sender, MigrationResult result)
{
    //Result handling
    Debug.WriteLine(result.Message);
}

If you wanna use database document schema validation, please subscribe on event Confirm in runner. Inside of handler you can display some message and ask confirmation in following way:

private void ConfirmHandler(object sender, ConfirmationEventArgs eventArgs)
{
    Console.WriteLine("Documents in db are inconsistent.");
    // Some code for handling confirmation
    eventArgs.Continue = true; //True if you still want to continue (it can brake you data), otherwise false. 
}

In case if handler does not found and validation has failed - migration process will cancel automatically.

If you not test your migration yet, mark it by IgnoreMigration attribute, and runner will skip it.

You can't check if database is outdated by calling runner.Status.IsNotLatestVersion(newestVersion)) or runner.Status.ThrowIfNotLatestVersion(newestVersion). The last one throw DatabaseOutdatedExcetion when database is outdated.

Tips

  1. Use {migrationVerstion}_{migrationName}.cs pattern of you migration classes.
  2. Save you migrations in non-production assamblies and use method LookInAssemblyOfType<T>() of MigratiotionLocator for find them.
  3. Keep migrations as simple as possible
  4. Do not couple migrations to your domain types, they will be brittle to change, and the point of a migration is to update the data representation when your model changes.
  5. Stick to the mongo BsonDocument interface or use javascript based mongo commands for migrations, much like with SQL, the mongo javascript API is less likely to change which might break migrations
  6. Add an application startup check that the database is at the correct version (I plan to implement helpers in feature releases)
  7. Write tests of your migrations, TDD them from existing data scenarios to new forms. Use IgnoreMigrationattribute while WIP.
  8. Automate the deployment of migrations (I plan to implement helpers in feature releases)

License

MongoDbMigrations is licensed under MIT. Refer to license.txt for more information.
Free Software, Hell Yeah!

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. 
.NET Core netcoreapp2.1 is compatible.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on MongoDBMigrations:

Package Downloads
PiBox.Plugins.Persistence.MongoDb

PiBox is a `service hosting framework` that allows `.net devs` to `decorate their services with behaviours or functionality (think of plugins) while only using minimal configuration`.

POKA.Utils.Infrastructure.MongoDb

Package Description

FappCommon.Mongo4Test

Declare set of class to easily use MongoDb (ussing Mongo2Go) for testing purpose

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.2.0 409,854 2/1/2022
2.1.0 309,458 11/20/2020
2.0.0 121,797 3/22/2020
1.1.2 52,029 10/4/2019
1.1.1 2,184 9/20/2019
1.1.0 7,527 11/21/2018
1.0.1 2,446 8/16/2018
1.0.0 2,215 8/9/2018