👁 Image
Hyperbee.Migrations 3.1.0

Hyperbee.Migrations

👁 Build status
👁 NuGet
👁 .NET

A versioned, journaled migration framework for .NET that supports relational and NoSQL databases through a single, consistent API.

Documentation: https://stillpoint-software.github.io/hyperbee.migrations/

Why

Database schema and data evolve over the life of an application. Hyperbee.Migrations gives you a structured, version-controlled way to evolve them across every environment -- local, test, staging, production -- with the same discipline you bring to source code. Migrations live in your repo as C# classes (or as embedded resource files), are discovered by reflection at runtime, and execute exactly once per environment.

What's new in v3.0

v3.0 adds migration squashing across all five providers, plus the tooling and discovery surface that supports it:

• Migration squashing. Collapse a long run of historical migrations [N..M] into a single equivalent squash migration. Mature environments auto-mark the squash via the Replaces graph (no re-run); fresh installs run the squash body. Squashes are up-only and carry a content checksum + Kind/Replaces ledger metadata.
• The hyperbee-migrations CLI. Generates squash artifacts against an ephemeral, topology-matched container, runs a verification round, and emits the squash body + sidecar metadata + summary. Also hosts the recover from-mid-range verb for the documented mid-range recovery path. The CLI references zero provider packages -- it discovers providers through the migration assembly's reference closure.
• Five .Squash provider packages. Hyperbee.Migrations.Providers.<P>.Squash (Postgres, Aerospike, MongoDB, OpenSearch, Couchbase) each implement the shared ISquashProvider contract (provider-specific snapshot capture + canonicalization + verification). Install the .Squash package alongside the provider package to enable hyperbee-migrations squash --provider <p> for that store.
• IMigrationHost discovery. A migration project exposes exactly one IMigrationHost that builds a configured service provider for an arbitrary connection. The CLI, the recovery verb, and the runner all consume the same host through a single reflection scan -- the v1 Postgres-only static-method convention is gone.

Upgrading from v2: existing v2 migrations continue to work unchanged; squash is additive. See the and the squashing migrations guide.

Supported providers

Targets .NET 8, 9, and 10. Each provider package is shipped independently on NuGet.

Install

dotnet add package Hyperbee.Migrations.Providers.Postgres

Or whichever provider matches your store. The core Hyperbee.Migrations library is referenced transitively.

Quick start

// Program.cs
using Hyperbee.Migrations.Providers.Postgres;

var builder = WebApplication.CreateBuilder( args );

// Register the Npgsql data source the migration runner reads from.
builder.Services.AddNpgsqlDataSource( builder.Configuration.GetConnectionString( "Migrations" ) );

builder.Services.AddPostgresMigrations( opts =>
{
 opts.SchemaName = "migration"; // ledger schema (default: "migration")
 // LockingEnabled defaults to true in v3.0 (production-safe). Set false
 // explicitly only for dev/test fixtures that intentionally race.
} );

var app = builder.Build();

using ( var scope = app.Services.CreateScope() )
{
 // Single-provider host: resolve the typed runner. Resolving the base
 // MigrationRunner also works in single-provider hosts, but the typed
 // runner is the documented entry point and the only one that works in
 // multi-provider hosts (a multi-provider host throws on
 // GetRequiredService<MigrationRunner>() to prevent silently routing to
 // the wrong provider).
 var runner = scope.ServiceProvider.GetRequiredService<PostgresMigrationRunner>();
 await runner.RunAsync( app.Lifetime.ApplicationStopping );
}

app.Run();

Multi-provider hosts. When you call more than one Add{Provider}Migrations on the same service collection (e.g. one app applies Postgres + MongoDB migrations), GetRequiredService<MigrationRunner>() throws to prevent silently routing to the wrong provider. Resolve the typed runner directly: PostgresMigrationRunner, MongoDBMigrationRunner, CouchbaseMigrationRunner, OpenSearchMigrationRunner, AerospikeMigrationRunner. See multi-provider hosts for the full pattern.

A migration is a class:

using Hyperbee.Migrations;

[Migration( 20260101_001 )]
public class CreateUsersTable( PostgresResourceRunner<CreateUsersTable> runner ) : Migration
{
 public override Task UpAsync( CancellationToken ct = default )
 => runner.AllSqlFromAsync( ct );
}

The companion resource file Resources/20260101_001_CreateUsersTable.sql ships in the assembly via <EmbeddedResource>.

For detailed walk-throughs by provider, see the documentation site:

• Concepts
• Getting Started
• PostgreSQL | Aerospike | Couchbase | MongoDB | OpenSearch

Multi-provider hosts

A single application can register migrations for more than one provider:

builder.Services
 .AddPostgresMigrations( opts => { /* ... */ } )
 .AddMongoDBMigrations( opts => { /* ... */ } );

// Resolve typed runners; the base MigrationRunner resolution throws in
// multi-provider hosts to prevent silent shadowing.
var pg = sp.GetRequiredService<PostgresMigrationRunner>();
var mg = sp.GetRequiredService<MongoDBMigrationRunner>();

See Multi-Provider Hosts for the full pattern, failure-isolation samples, and the expand/contract recipe for cross-store changes.

Project layout

Documentation

Building from source

Requires .NET 8, 9, and 10 SDKs (the solution multi-targets all three for compatibility testing).

git clone https://github.com/Stillpoint-Software/hyperbee.migrations.git
cd hyperbee.migrations
dotnet build Hyperbee.Migrations.slnx -c Release
dotnet test Hyperbee.Migrations.slnx -c Release

Integration tests use Testcontainers and require a Docker engine. They are gated behind #if INTEGRATIONS; enable with -p:EnableIntegrationTests=true.

Acknowledgments

The framework API draws on prior art in the .NET migration space:

• Fluent Migrator
• Raven Migrations
• DbUp
• Cronos -- cron expression support
• Couchbase .NET Client -- Couchbase connectivity and DI extensions
• Parlot -- statement parsers across all providers

Contributing

See for the build/test/PR flow. We use a trunk-based GitHub flow; please open an issue to discuss substantial changes before sending a PR.

License

Released under the .