Skip to main content

Curiosus.Migrations

Database migration framework for .NET: raw SQL and C# code migrations, downgrades, long-running data migrations and per-environment policies for PostgreSQL and SQL Server.

Build License NuGet Downloads Coverage Docs

Renamed: formerly Curiosity.Migrations* by SIIS Ltd. Since 5.0.0 the packages are published as Curiosus.Migrations* by curiosus-dev. To migrate, replace Curiosity with Curiosus in package references and code. -- CURIOSITY: directives in SQL scripts keep working.

Why use itโ€‹

Curiosus.Migrations is a database migration framework for .NET (net9.0 and net10.0; stay on 5.x for older runtimes) that gives you precise control over how your database evolves. It keeps raw SQL scripts and C# code migrations in one ordered history, so a schema change and the data migration that goes with it are versioned, applied and rolled back together.

Unlike ORM-specific migration tools, Curiosus.Migrations is database-focused and designed for scenarios where you need fine-grained control over migration execution, especially for large production databases where heavy data migrations must not block a deployment.

๐Ÿ”ง Precise Control

Write raw SQL when you need optimal performance, or use C# code when you need complex logic. You control exactly what runs against your database.

๐Ÿš€ Production-Ready

Long-running migration support and policies that decide what runs in each environment: quick schema changes on deployment, heavy data migrations separately.

๐Ÿ”„ Bidirectional

Downgrade scripts and code migrations roll the database back to a target version when a deployment doesn't go as planned.

๐Ÿ“Š Progressive Migrations

Separate long-running data migrations from quick schema changes to keep your application responsive during upgrades.

๐Ÿงช Testability

Create and initialize test databases with specific migration states for reliable integration testing.

๐Ÿงฉ Extensibility

Customize where migrations come from, how they're logged, and how they're applied to fit your workflow.

Featuresโ€‹

Migration Typesโ€‹

Safety and Controlโ€‹

Extensibilityโ€‹

Quick startโ€‹

Installationโ€‹

# Install core package
dotnet add package Curiosus.Migrations

# Install database provider (PostgreSQL or SQL Server)
dotnet add package Curiosus.Migrations.PostgreSQL
# or
dotnet add package Curiosus.Migrations.SqlServer

Basic Setupโ€‹

Put SQL scripts named by version into a directory: 1.0-create_users.sql, 1.1.up.sql with its 1.1.down.sql, and so on. Then configure and run the engine:

using System.Reflection;
using Curiosus.Migrations;
using Curiosus.Migrations.PostgreSQL;

var builder = new MigrationEngineBuilder();

// UseScriptMigrations() and UseCodeMigrations() return the providers, not the builder: configure them separately
builder.UseScriptMigrations().FromDirectory("./Migrations");
builder.UseCodeMigrations().FromAssembly(Assembly.GetExecutingAssembly());
builder.ConfigureForPostgreSql("Host=localhost;Database=myapp;Username=postgres;Password=secret");
builder.UseUpgradeMigrationPolicy(MigrationPolicy.AllAllowed);

var migrationEngine = builder.Build();
var result = await migrationEngine.UpgradeDatabaseAsync();

if (!result.IsSuccessfully)
{
throw new InvalidOperationException(
$"Migration {result.FailedMigration?.Version} failed: {result.ErrorCode} {result.ErrorMessage}",
result.Exception);
}

Console.WriteLine($"Applied {result.AppliedMigrations.Count} migrations");

The engine creates the database and the migration history table when they are missing. A complete runnable example with script, code and downgrade migrations is in samples/Curiosus.Migrations.Sample.

Get started quickly with the Quick Start Guide or dive into Core Concepts.

Running in productionโ€‹

No concurrency lock yet. The engine doesn't lock the database while it migrates, so two instances starting at the same time can apply the same migration twice or fail on the journal. Until #32 lands, run migrations from one place: a Kubernetes Job or init container, a deployment pipeline step, or the startup of a single replica.

Supported Databasesโ€‹


PostgreSQL

SQL Server

MySQL/MariaDB (#37) and SQLite (#38) are planned for v7, after the engine rework that makes a new database a small dialect (#36). A custom IMigrationConnection can add any other database.

Comparing with Alternativesโ€‹

As of October 2026. โœ… supported, โš ๏ธ partly or with caveats, โŒ not supported, ๐Ÿ’ฐ paid editions only.

Curiosus.MigrationsEF Core MigrationsFluentMigratorDbUpgrateFlywayLiquibase
Migrations written asSQL + C# codeC# generated from the EF model (+ raw SQL)Fluent C# API (+ raw SQL)SQL (+ IScript code)SQLSQL (+ Java)XML/YAML/JSON/SQL changelogs
DatabasesPostgreSQL, SQL ServerAny EF Core relational provider67520+50+
Downgrade / rollbackโœ… Hand-written, freeโœ… Generated Down()โœ… Down(), auto-reversingโŒโŒ๐Ÿ’ฐ Undoโœ… (targeted rollback ๐Ÿ’ฐ)
Long-running vs short-running policiesโœ…โŒโš ๏ธ Tags, profilesโš ๏ธ Script filtersโš ๏ธ Environment scriptsโš ๏ธ Cherry-pick ๐Ÿ’ฐโš ๏ธ Contexts, labels
Dependencies between migrationsโœ…โŒโŒโŒโŒโŒโš ๏ธ Changelog order
C# migrations with DIโœ…โš ๏ธ No DI in migrationsโœ…โš ๏ธ IScriptโŒโŒโŒ
Concurrency lockโŒ #32โœ… Since EF Core 9โŒโŒNot documentedโœ…โœ…
Checksums, drift detectionโŒ #33โš ๏ธ Pending model changes checkโŒโŒโœ…โœ… (drift report ๐Ÿ’ฐ)โœ… (drift ๐Ÿ’ฐ)
Repeatable migrationsโŒ #39โŒโš ๏ธ Maintenance stagesโœ…โœ…โœ…โœ…
CLI, dry-run, SQL previewโŒ #40, #42โœ… dotnet ef, bundles, scriptsโœ… dotnet-fmโš ๏ธ Libraryโœ…โœ…โœ…
LicenseMITMITApache-2.0MITMITApache-2.0 core, paid editionsFSL core, paid editions

The gaps are planned for v7, see the roadmap. Evolve had checksums and locking but has had no stable release since 3.2.0 (June 2023); RoundhousE is superseded by grate.

Choose Curiosus.Migrations when you mix hand-tuned SQL with C# data migrations on PostgreSQL or SQL Server, need heavy backfills kept out of the deployment path, and want free downgrades. Choose something else when your app is EF Core-centric with one schema owner (EF Core Migrations), you target many database engines or want a fluent schema DSL (FluentMigrator), you only need forward-only SQL scripts (DbUp, or grate with hash checks and a CLI), or a DBA-led team needs compliance and drift reports (Flyway, Liquibase).

For a detailed comparison, see The Philosophy Behind Curiosus.Migrations.

Available packagesโ€‹

PackageVersionDownloadsCoverage
Curiosus.MigrationsNuGetNuGetCoverage
Curiosus.Migrations.PostgreSQLNuGetNuGetCoverage
Curiosus.Migrations.SqlServerNuGetNuGetCoverage
Curiosus.Migrations.UtilsNuGetNuGetCoverage

Supportโ€‹

Licenseโ€‹

Curiosus.Migrations is licensed under the MIT License.