RavenMigrations 3.0.0

Raven Migrations

Quick Start

    PM > Install-Package RavenDB.Migrations

Introduction

Raven Migrations is a migration framework for RavenDB to help with common tasks you might have to do over time to your database. The framework API is heavily influenced by Fluent Migrator.

Philosophy

We believe any changes to your domain should be visible in your code and reflected as such. Changing things "on the fly", can lead to issues, where as migrations can be tested and throughly vetted before being exposed into your production environment. With RavenDB testing migrations is super simple since RavenDB supports in memory databases (our test suite is in memory).

This is important, once a migration is in your production environment, NEVER EVER modify it in your code. Treat a migration like a historical record of changes.

Concepts

Every migration has several elements you need to be aware of. Additionally, there are over arching concepts that will help you structure your project to take advantage of this library.

A Migration

A migration looks like the following:

// #1 - specify the migration number
[Migration(1)]                 
public class First_Migration : Migration // #2 inherit from Migration
{
    // #3 Do the migration
    public override void Up()
    {
        using (var session = DocumentStore.OpenSession())
        {
            session.Store(new TestDocument 
            { 
                Id = "TestDocuments/1",
                Name = "Khalid Abuhakmeh" 
            });
            session.SaveChanges();
        }
    }
    // #4 optional: undo the migration
    public override void Down()
    {
        using (var session = DocumentStore.OpenSession())
        {
            session.Delete("TestDocuments/1");
            session.SaveChanges();
        }
    }
}

To run the migrations, you can use Microsoft's Dependency Injection:

public void ConfigureServices(IServiceCollection services)
{
    // Add the MigrationRunner into the dependency injection container.
    services.AddRavenDbMigrations();

    // ...
   
    // Get the migration runner and execute pending migrations.
    var migrationRunner = services.BuildServiceProvider().GetRequiredService<MigrationRunner>();
    migrationRunner.Run();
}

Not using ASP.NET Core? You can create the runner manually:

// Skip dependency injection and run the migrations.

// Create migration options, using all Migration objects found in the current assembly.
var options = new MigrationOptions();
options.Assemblies.Add(Assembly.GetExecutingAssembly());

// Create a new migration runner. docStore is your RavenDB IDocumentStore. Logger is an ILogger<MigrationRunner>.
var migrationRunner = new MigrationRunner(docStore, options, logger);
migrationRunner.Run();

Full documentation and sample project available on the GitHub repo.