csharp-mongodb-migrations
0.1.3-preview.0.8
See the version list below for details.
dotnet add package csharp-mongodb-migrations --version 0.1.3-preview.0.8
NuGet\Install-Package csharp-mongodb-migrations -Version 0.1.3-preview.0.8
<PackageReference Include="csharp-mongodb-migrations" Version="0.1.3-preview.0.8" />
paket add csharp-mongodb-migrations --version 0.1.3-preview.0.8
#r "nuget: csharp-mongodb-migrations, 0.1.3-preview.0.8"
// Install csharp-mongodb-migrations as a Cake Addin #addin nuget:?package=csharp-mongodb-migrations&version=0.1.3-preview.0.8&prerelease // Install csharp-mongodb-migrations as a Cake Tool #tool nuget:?package=csharp-mongodb-migrations&version=0.1.3-preview.0.8&prerelease
MongoDB Migration
Simple database migrations for MongoDB.Driver
using ASP.NET DI.
Quick start
Install the NuGet package & Implement the database migrations system in your solution using the following steps:
dotnet add package csharp-mongodb-migrations
Inject migrations service
Inject AddMigrations
into your services.
- If migrations are not in the
Assembly.GetEntryAssembly
, then manually specify the assemblies in the parameters ofAddMigrations
. - Call
AddMigrations
after configuring options.
services
.Configure<MyDatabaseSettings>(builder.Configuration.GetSection("Database:MyDatabaseSettings"))
.AddMigrations()
Update settings
Implement IDatabaseMigratable
for your database settings.
- Options must be configured before injecting services.
- A
Database.Alias
must be unique: The name used to identify the database during runtime. - A
Database.Name
must be unique: The name of the actual MongoDB database. - Assign a unique constant value to
DatabaseMigrationSettings.Database.Alias
.
public sealed record MyDatabaseSettings : IOptions<MyDatabaseSettings>, IDatabaseMigratable
{
public required string ConnectionString { get; init; }
public required string DatabaseName { get; init; }
public required string MyCollectionName { get; init; }
MyDatabaseSettings IOptions<MyDatabaseSettings>.Value => this;
public DatabaseMigrationSettings GetMigrationSettings()
{
return new()
{
ConnectionString = ConnectionString,
Database = new("MyDatabase", DatabaseName),
MirgrationStateCollectionName = "DATABASE_MIGRATIONS"
};
}
}
Await migrations
Wait for migrations to complete using IMigrationCompletion
before accessing the database at any point.
WaitAsync
may not ever be called in constructors.WaitAsync
is fast when the migration is completed, or the database is not configured.
sealed class MyRepository(IOptions<MyDatabaseSettings> databaseSettings, IMigrationCompletion migrationCompletion) {
private readonly IMongoCollection<MyModel> _myCollection = new MongoClient(databaseSettings.ConnectionString)
.GetDatabase(databaseSettings.DatabaseName)
.GetCollection<MyModel>(databaseSettings.MyCollectionName);
public async Task<MyModel> GetOrSetAsync(MyModel insertModel, CancellationToken cancellationToken = default) {
_ = await migrationCompletion.WaitAsync(databaseSettings.Value, cancellationToken).ConfigureAwait(false);
// ... do stuff
}
}
Implement migrations
Add IMigration
s between version 0 and 1 and so on.
- The alias used for the
MigrationAttribute
must match the name inIDatabaseMigratable.GetMigrationSettings().Database.Alias
.
[Migration("MyDatabase", 0, 1, Description = "Add composite index to MyCollection")]
public sealed class PoeNinjaAddCompositeIndexMigration(IOptions<MyDatabaseSettings> optionsAccessor) : IMigration
{
public async Task DownAsync(IMongoDatabase database, CancellationToken cancellationToken = default)
{
}
public async Task UpAsync(IMongoDatabase database, CancellationToken cancellationToken = default)
{
}
}
Fixing database versions
A fixed database version ensures that the migration always produces a database of the specified version, even if the initial version was higher than the fixed version.
- Fixing upgrades the database, if the initial version is lower than the fixed version.
- Fixing downgrades the database, if the initial version is higher than the fixed version.
- Fixing the database to a version is especially useful for a procedural feature rollout.
Fix a specific version by setting the long? MigrateToFixedVersion
property in your IDatabaseMigratable
; if the property is null
- by default - a migration to the latest version will occur.
public DatabaseMigrationSettings GetMigrationSettings()
{
return new()
{
ConnectionString = ConnectionString,
Database = new("MyDatabase", DatabaseName),
MirgrationStateCollectionName = "DATABASE_MIGRATIONS",
MigrateToFixedVersion = 42069,
};
}
Migrations without ASP.NET DI
MongoDB Migration extensively uses ASP.NET to prepare the environment required for processing of migrations. Without ASP.NET most features are unavailable, but the core - DatabaseMirationProcessor
- public API; it is accessible to the user.
- Describe your database in the
DatabaseMigrationSettings
record. - Pack all available
IMigration
s into theMigrationExecutionDescriptor
record. - Instantiate
DatabaseMirationProcessor
for your database. - Call
DatabaseMirationProcessor.MigrateToVersionAsync
with the availableMigrationExecutionDescriptor
s.
ToDO
- Allow upgrading the database to the latest version.
- Allow upgrading the database to a specific version.
- Allow downgrading the database to a specific version.
- Add test cases.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. 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 is compatible. 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.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 is compatible. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. 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
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.1)
- MongoDB.Driver (>= 2.22.0)
- System.Collections.Immutable (>= 7.0.0)
-
.NETStandard 2.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.1)
- MongoDB.Driver (>= 2.22.0)
- System.Collections.Immutable (>= 7.0.0)
-
.NETStandard 2.1
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.1)
- MongoDB.Driver (>= 2.22.0)
- System.Collections.Immutable (>= 7.0.0)
-
net6.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.1)
- MongoDB.Driver (>= 2.22.0)
-
net7.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.1)
- MongoDB.Driver (>= 2.22.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.2.0 | 194 | 12/21/2023 |
1.1.1 | 131 | 11/5/2023 |
1.1.0 | 81 | 11/4/2023 |
1.0.0 | 58 | 11/3/2023 |
0.1.4 | 68 | 11/3/2023 |
0.1.3-preview.0.8 | 52 | 11/3/2023 |
0.0.0-preview.0.32 | 39 | 11/3/2023 |
0.0.0-preview.0.28 | 49 | 11/3/2023 |
0.0.0-preview.0.16 | 45 | 11/3/2023 |