This library is designed to allow a developer to define and apply changes to a MongoDB database based on the current "schema" version of the database. Althought MongoDB is technically "schema-less", you may want to define indexes or pre-populate collections with data at application startup. Additionaly, you may want or need to apply some sort of document migration as your application evolves. This library was designed to handle these scenarios.
Add a reference to the nuget package in your project using one of the methods below.
** NOTE: The nuget packages are not yet created and these installation instructions will not yet work **
Visual Studio Package Manager Console:
Install-Package Stom.MongoDB.SchemaMigrations
dotnet
cli:
dotnet add package Stom.MongoDB.SchemaMigrations
-
Create migration classes derived from
SchemaVersion
and make sure to call the base constructor with the version string of what you want to apply to the database. Then override theApply()
method to perform any actions against the passed inIMongoDatabase
object. The method should returntrue
if successful,false
otherwise.public class Version_0_1_0_migration : SchemaVersion { public Version_0_1_0_migration() : base("0.1.0") { } public async override Task<bool> Apply(IMongoDatabase db) { var index1 = new CreateIndexModel<BsonDocument>(Builders<BsonDocument>.IndexKeys.Ascending("i")); await db.GetCollection<BsonDocument>("MyCollection").Indexes.CreateOneAsync(index1); var index2 = new CreateIndexModel<BsonDocument>(Builders<BsonDocument>.IndexKeys.Ascending("i").Ascending("j")); await db.GetCollection<BsonDocument>("MyCollection2").Indexes.CreateOneAsync(index2); return true; } }
public class Version_0_2_0_migration : SchemaVersion { public Version_0_2_0_migration() : base("0.2.0") { } public override async Task<bool> Apply(IMongoDatabase db) { var index1 = new CreateIndexModel<BsonDocument>(Builders<BsonDocument>.IndexKeys.Ascending("i").Ascending("field1")); await db.GetCollection<BsonDocument>("MyCollection").Indexes.CreateOneAsync(index1); return true; } }
-
Create an instance of
SchemaMigrator
and add your migrations defined in step 1 to theMigrations
collectionIMongoClient mongo = new MongoClient(); IMongoDatabase db = mongo.GetDatabase("SchemaMigrationTest"); var migrator = new SchemaMigrator(db, new SchemaMigratorOptions(), serviceProvider.GetService<ILogger<SchemaMigrator>>()); migrator.Migrations.Add(new Version(0, 1, 0), new Version_0_1_0_migration()); migrator.Migrations.Add(new Version(0, 2, 0), new Version_0_2_0_migration());
-
Call
ApplyAll()
on theSchemaMigrator
instancemigrator.ApplyAll();
The SchemaMigrator
will query the schema collection ("AppliedSchemas" by default but can be changed by setting the CollectionName
property of SchemaMigratorOptions
) to find the highest version applied. It will then loop through its list of migrations and apply only those that have a version newer than the highest version in the designated schema collection in the correct order. The result is of type SchemaMigrationResult
and will contain the following information:
Property | Type | Description |
---|---|---|
StartingVersion |
Version |
The version from which migration is starting. This will be the latest version that exists in the schema table or "0.0.0" if none are found. |
EndingVersion |
Version |
The version up to which the migration completed. |
MigrationsFound |
int |
The number of migrations total that the migrator is aware of. |
MigrationsSkipped |
int |
The number of migrations skipped due to already being applied. |
MigrationsApplied |
int |
The number of migrations that were applied. |
ElapsedMilliseconds |
long |
The number of milliseconds the entire migration process took. |
The schema table will contain a document for each version applied that consists of the following fields:
Field | Type |
---|---|
_id | ObjectId |
version | string |
dateApplied | datetime |