Curiosus.Migrations 6.0.0

Curiosus.Migrations

Core engine of Curiosus.Migrations, a database migration framework for .NET that combines raw SQL scripts and C# code migrations. Install it together with a database provider: PostgreSQL or SQL Server.

Installation

dotnet add package Curiosus.Migrations
dotnet add package Curiosus.Migrations.PostgreSQL # or Curiosus.Migrations.SqlServer

Usage

Put SQL scripts named by version (1.0.sql, 1.1-add_users.sql, 2.0.down.sql) into a directory. Then configure and run the engine:

using Curiosus.Migrations;
using Curiosus.Migrations.PostgreSQL;

var engine = new MigrationEngineBuilder(services)
    .UseScriptMigrations().FromDirectory("./Migrations")
    .UseCodeMigrations().FromAssembly(typeof(Program).Assembly)
    .ConfigureForPostgreSql(connectionString)
    .UseUpgradeMigrationPolicy(MigrationPolicy.ShortRunningAllowed)
    .Build();

var result = await engine.UpgradeDatabaseAsync(cancellationToken);
if (!result.IsSuccessfully)
    throw new InvalidOperationException($"{result.ErrorCode}: {result.ErrorMessage}");

The engine creates the database and the migration history table if they do not exist. To register IMigrationEngine as a singleton, call services.AddMigrations(builder => ...) instead.

A code migration is a class derived from CodeMigration:

public class SeedRolesMigration : CodeMigration
{
    public override MigrationVersion Version => new(1, 2);
    public override string? Comment => "Seed default roles";

    public override Task UpgradeAsync(DbTransaction? transaction = null, CancellationToken cancellationToken = default) =>
        MigrationConnection.ExecuteNonQuerySqlAsync("INSERT INTO roles (name) VALUES ('admin');", null, cancellationToken);
}

Key concepts

• Script migrations come from a directory or from embedded resources. They can be split into batches with --BATCH:. Directives such as --CURIOSUS:TRANSACTION=OFF, --CURIOSUS:LONG-RUNNING=TRUE and --CURIOSUS:DEPENDENCIES=1.0, 1.1 set options for a script. The legacy --CURIOSITY: prefix still works.
• Code migrations are C# classes. They support dependency injection and EF Core.
• Downgrade uses *.down.sql scripts or IDowngradeMigration. Call DowngradeDatabaseAsync with a target version set by SetUpTargetVersion.
• Long-running migrations and policies: the upgrade and downgrade MigrationPolicy values decide which migrations run, so heavy data migrations can run separately from fast schema changes.
• Pre-migrations, variables, transactions, dependencies, journal and custom migration providers.

See also

• Curiosus.Migrations.PostgreSQL: PostgreSQL provider
• Curiosus.Migrations.SqlServer: SQL Server provider
• Curiosus.Migrations.Utils: helpers for batched mass data updates
• Documentation and Quick Start
• Curiosus.Migrations: repository and all packages