https://github.com/jordandchappell/csharp.mongo.migration
Simple script based MongoDB database migrations written and run using .NET in C#
https://github.com/jordandchappell/csharp.mongo.migration
csharp database-migrations dotnet library migration migration-tool migrations mongodb mongodb-database open-source
Last synced: 9 months ago
JSON representation
Simple script based MongoDB database migrations written and run using .NET in C#
- Host: GitHub
- URL: https://github.com/jordandchappell/csharp.mongo.migration
- Owner: JordanDChappell
- License: mit
- Created: 2024-04-01T07:28:15.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-07T09:42:24.000Z (9 months ago)
- Last Synced: 2025-10-07T11:40:42.507Z (9 months ago)
- Topics: csharp, database-migrations, dotnet, library, migration, migration-tool, migrations, mongodb, mongodb-database, open-source
- Language: C#
- Homepage:
- Size: 108 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CSharp Mongo Migrations
Simple script based MongoDB database migrations written and run in .NET.
`CSharp.Mongo.Migration` uses the [C# MongoDB Driver](https://www.mongodb.com/docs/drivers/csharp/current/) to update documents in script based single use migrations (rather than on-the-fly).
See the [Wiki](https://github.com/JordanDChappell/CSharp.Mongo.Migration/wiki) for more information.
## Status
## Usage
### Installation
Nuget: https://www.nuget.org/packages/CSharp.Mongo.Migration
Install using the Visual Studio package manager or the dotnet CLI:
```
dotnet add package CSharp.Mongo.Migration
```
### Running Migrations
1. Create an instance of the `MigrationRunner` class
```csharp
MigrationRunner runner = new("yourDatabaseConnectionString");
```
2. Register an `IMigrationLocator` and run the migrations
```csharp
await runner
.RegisterLocator(new AssemblyMigrationLocator("Assembly.With.Your.Migrations.dll"))
.RunAsync();
```
### Writing Migrations
A migration script should implement the `IMigration` or `IAsyncMigration` interface. The following properties / methods will need to be defined:
- `string Name`
- `string Version`
- `void Up(IMongoDatabase)` / `Task UpAsync(IMongoDatabase database)`
- `void Down(IMongoDatabase)` / `Task DownAsync(IMongoDatabase database)`
An optional `bool Skip()` method can be defined that can be used to conditionally skip a migration.
`Up` / `UpAsync` will be run when the `MigrationRunner.RunAsync` method is called.
`Down` / `DownAsync` will be called when the `MigrationRunner.RevertAsync(string)` method is called, if you don't expect to revert a migration, simply have this method throw an exception.
#### Explicit Order
If a migration requires or depends on another migration script, the `IOrderedMigration` interface can be used and it's `DependsOn` property implemented to provide version dependencies between migrations. Migrations need to implement one of the `IMigration` or `IAsyncMigration` interfaces along with the `IOrderedMigration` interface to be loaded and run.
#### Ignoring Migrations
If a migration is no longer required, you can remove the class from your application, or use the `[IgnoreMigration]` attribute on that class.
For example:
```
[IgnoreMigration]
public class MyMigration1 : IMigration { }
```
### Restoring Migrations
To revert or restore a migration run the `RevertAsync("version")` function on an instance of the `MigrationRunner` class
```csharp
MigrationRunner runner = new("youDatabaseConnectionString");
await runner
.RegisterLocator(new AssemblyMigrationLocator("Assembly.With.Migration.Version.dll"))
.RevertAsync("version");
```
### Migration Documents
When a migration has been applied a new document will be created in the target database in a collection named `_migrations` by default. These documents are used to track which migrations have been applied and when they were applied.
**Note:** to override the default collection name, use a constructor that includes the `migrationCollectionName` parameter, or set the public `MigrationRunner.MigrationCollectionName` property.
### Logging
This library provides support for logging using [Microsoft.Extensions.Logging](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line).
The `MigrationRunner` class writes information level logs that help to understand which migrations have been located and when they have successfully completed. In order to configure logging use the `RegisterLogger` function.
## Why Create Another Library?
There are a number of other libraries for MongoDB designed to be used in C#. This library was written out of necessity to be used in a large development team with fairly sizeable database instances. There are some use cases that this library caters to that others do not:
* Allow migrations to run out of order
* Provide a version identifier that is not a number or using SemVer
* Encourage `async` migration scripts
Using other libraries we found that migration versions could clash when using number or SemVer based identifiers, our team uses GitFlow to achieve the development throughput and organisation that we require and often larger feature branches would clash when selecting version numbers.
## Dependencies
This library uses the following packages:
- [C# MongoDB Driver](https://www.mongodb.com/docs/drivers/csharp/current/)
### Development Dependencies
We use the following libraries for testing / development purposes:
- [AutoMoqCore](https://www.nuget.org/packages/AutoMoqCore/)
- [DefaultDocumentation](https://github.com/Doraku/DefaultDocumentation)
- [EphemeralMongo7](https://www.nuget.org/packages/EphemeralMongo7)
- [xunit](https://www.nuget.org/packages/xunit)