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.

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 powerful, flexible database migration framework for .NET and .NET Core applications that gives you precise control over how your database evolves. It combines the performance and control of raw SQL with the flexibility of C# code migrations, all wrapped in a robust, enterprise-ready migration system.

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 performance and safety are critical.

🔧 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

Built for enterprise applications with safety features, long-running migration support, and granular policies to control what runs in each environment.

🔄 Bidirectional

First-class support for downgrade migrations enables safe rollbacks when deployments don'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

Script Migrations: Write raw SQL for direct database access
- Batched Execution: Split large scripts into manageable chunks
- Full support for database-specific SQL features and optimizations
Code Migrations: Implement migrations in C# for complex scenarios
- Dependency Injection: Use your application's services in migrations
- Entity Framework Integration: Leverage EF Core when needed
- Implement custom validation, logging, or business logic during migrations

Safety and Control

Policies: Control which migrations run in different environments
Dependencies: Specify explicit requirements between migrations
Downgrade Migrations: Safely roll back changes when needed
Transactions: Configure transaction behavior per migration
Long-running vs Short-running: Separate quick schema changes from data-intensive operations

Extensibility

Migration Providers: Source migrations from files, embedded resources, etc.
Variables: Dynamic value substitution in migrations
Pre-migrations: Run setup scripts before main migrations
Custom Journal: Configure how applied migrations are tracked

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

// Configure the migration engine
var builder = new MigrationEngineBuilder(services)
    .UseScriptMigrations().FromDirectory("./Migrations")  // Add SQL migrations
    .UseCodeMigrations().FromAssembly(Assembly.GetExecutingAssembly())  // Add code migrations
    .ConfigureForPostgreSql("Host=localhost;Database=myapp;Username=postgres;Password=secret")
    .UseUpgradeMigrationPolicy(MigrationPolicy.AllAllowed);

// Build and run the engine
var migrationEngine = builder.Build();
var result = await migrationEngine.UpgradeDatabaseAsync();

// Check results
if (result.IsSuccessfully)
{
    Console.WriteLine($"Successfully migrated");
}

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

Supported Databases

PostgreSQL

SQL Server

Support for additional databases can be added through contributions.

Comparing with Alternatives

Feature	Curiosus.Migrations	EF Core Migrations	FluentMigrator	DbUp
Direct SQL Control	✅ Full	⚠️ Generated	⚠️ Generated	✅ Full
Code Migrations	✅ Native	⚠️ Limited	⚠️ Via API	❌ No
Downgrade Support	✅ First-class	⚠️ Limited	⚠️ Limited	❌ No
Long-running Migrations	✅ Optimized	❌ No	❌ No	❌ No
Migration Policies	✅ Configurable	❌ No	❌ No	❌ No
DI Support	✅ Native	⚠️ Limited	⚠️ Limited	⚠️ Basic
Best For	Enterprise apps, complex migrations, performance-critical systems	Simple CRUD apps with EF Core	Cross-database projects	Simple script runners