Tello.Mongo.Migration 0.1.0

Tello.Mongo.Migration

A lightweight, production-ready MongoDB migration framework for modern .NET applications.

Features

• Forward & reversible migrations — implement IMongoMigration or IMongoReversibleMigration
• Distributed locking — prevents concurrent migration runs across instances
• Checksum validation — detects when applied migrations have been modified
• Environment & tag filtering — run subsets of migrations per environment or tag
• Dry-run planning — preview pending migrations without executing
• Dependency injection — migrations support constructor injection

Installation

dotnet add package Tello.Mongo.Migration

Quick Start

1. Define a migration

public class CreateUsersIndex : IMongoMigration
{
    public string Id => "202402241200_CreateUsersIndex";
    public string Description => "Create unique index on users.email";

    public async Task UpAsync(IMongoDatabase database, CancellationToken ct)
    {
        var collection = database.GetCollection<BsonDocument>("users");
        var index = new CreateIndexModel<BsonDocument>(
            Builders<BsonDocument>.IndexKeys.Ascending("email"),
            new CreateIndexOptions { Unique = true });

        await collection.Indexes.CreateOneAsync(index, cancellationToken: ct);
    }
}

Migration IDs must match the format yyyyMMddHHmm_Description (12 digits, underscore, name). Migrations are executed in lexicographic order by ID.

2. Register in DI

services.AddMongoMigrations(opts =>
{
    opts.ConnectionString = "mongodb://localhost:27017";
    opts.DatabaseName = "MyDatabase";
    opts.AssembliesToScan = [typeof(CreateUsersIndex).Assembly];
});

Or with an existing IMongoClient:

services.AddMongoMigrations(opts =>
{
    opts.DatabaseName = "MyDatabase";
    opts.AssembliesToScan = [typeof(CreateUsersIndex).Assembly];
}, existingClient);

3. Run migrations

var runner = serviceProvider.GetRequiredService<IMongoMigrationRunner>();
await runner.RunAllAsync();

Reversible Migrations

Implement IMongoReversibleMigration and enable down migrations in options:

public class AddStatusField : IMongoReversibleMigration
{
    public string Id => "202402241300_AddStatusField";
    public string Description => "Add status field to orders";

    public async Task UpAsync(IMongoDatabase database, CancellationToken ct)
    {
        // forward migration
    }

    public async Task DownAsync(IMongoDatabase database, CancellationToken ct)
    {
        // rollback logic
    }
}

services.AddMongoMigrations(opts =>
{
    // ...
    opts.AllowDownMigrations = true;
});

Environment & Tag Filtering

Restrict migrations to specific environments or tag groups:

[MigrationEnvironment("production")]
[MigrationTag("schema")]
[MigrationTag("critical")]
public class ProductionOnlyMigration : IMongoMigration { /* ... */ }

services.AddMongoMigrations(opts =>
{
    // ...
    opts.EnvironmentName = "production";
    opts.TagFilter = ["schema"];
});

• Migrations without [MigrationEnvironment] run in all environments.
• Migrations without [MigrationTag] are excluded when a tag filter is active.

Runner API

IMongoMigrationRunner runner = /* from DI */;

// Execute all pending migrations
await runner.RunAllAsync();

// Execute up to a specific migration
await runner.RunToAsync("202402241300_AddStatusField");

// Dry-run plan (no execution, no lock)
MigrationPlan plan = await runner.GetPlanAsync();

// Validate only (no execution, no lock)
IReadOnlyList<string> warnings = await runner.ValidateAsync();

Configuration

Exceptions