Hyperbee.Migrations.Providers.OpenSearch.Aws 3.0.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Hyperbee.Migrations.Providers.OpenSearch.Aws --version 3.0.0
                    


                    

                
NuGet\Install-Package Hyperbee.Migrations.Providers.OpenSearch.Aws -Version 3.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Hyperbee.Migrations.Providers.OpenSearch.Aws" Version="3.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Hyperbee.Migrations.Providers.OpenSearch.Aws" Version="3.0.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Hyperbee.Migrations.Providers.OpenSearch.Aws" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Hyperbee.Migrations.Providers.OpenSearch.Aws --version 3.0.0
                    


                    

                
#r "nuget: Hyperbee.Migrations.Providers.OpenSearch.Aws, 3.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Hyperbee.Migrations.Providers.OpenSearch.Aws@3.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Hyperbee.Migrations.Providers.OpenSearch.Aws&version=3.0.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Hyperbee.Migrations.Providers.OpenSearch.Aws&version=3.0.0
                    


                            Install as a Cake Tool

Hyperbee.Migrations

Build status License: MIT 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 v2 → v3 upgrade guide and the squashing migrations guide.

Supported providers

Provider Package Statement format Locking
Aerospike Hyperbee.Migrations.Providers.Aerospike AQL-like CREATE_ONLY record + TTL
Couchbase Hyperbee.Migrations.Providers.Couchbase N1QL Couchbase.Extensions.Locks
MongoDB Hyperbee.Migrations.Providers.MongoDB shell-like document conditional write
OpenSearch Hyperbee.Migrations.Providers.OpenSearch OpenSearch DSL op_type=create + realtime GET
PostgreSQL Hyperbee.Migrations.Providers.Postgres raw .sql files session-level advisory lock

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:

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

Path Contents
src/Hyperbee.Migrations/ Core: runner, options, record-store contract, conventions, resource helpers
src/Hyperbee.Migrations.Providers.*/ Per-provider implementations
runners/Hyperbee.MigrationRunner.*/ Per-provider standalone runner executables (Docker-ready)
runners/samples/ Working samples per provider
docs/site/ Jekyll documentation source (just-the-docs)
docs/decisions/ Architecture Decision Records
tests/ Unit + Testcontainers integration tests

Documentation
Concepts & guides https://stillpoint-software.github.io/hyperbee.migrations/
Operator guides docs/guides/
Changelog CHANGELOG.md

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:

Contributing

See CONTRIBUTING.md 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 MIT License.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 0 5/17/2026
2.2.0 84 5/4/2026

https://github.com/Stillpoint-Software/hyperbee.migrations/releases/latest