Welcome to Hyperbee Migrations
Hyperbee Migrations is a database migration framework for .NET. It gives your team a structured, version-controlled way to evolve database schemas and data across every environment – from local dev boxes to production clusters. Instead of maintaining loose SQL scripts, you describe changes in C# classes or embedded resource files that are discovered, ordered, and executed automatically.
Key Features
- Supports Aerospike, Couchbase, MongoDB, OpenSearch, and PostgreSQL
- Code migrations with full dependency injection
- Resource migrations with embedded SQL, N1QL, AQL, MongoDB commands, and OpenSearch DDL
- Document seeding from JSON files
- Distributed locking to prevent concurrent migrations
- Profile-based environment scoping
- Cron-based lifecycle control
- Migration journaling and record tracking
- Standalone runners with Docker support
A Quick Example
A migration is a simple class decorated with a version attribute:
[Migration(1)]
public class CreatePeopleCollection : Migration
{
public override async Task UpAsync(CancellationToken cancellationToken = default)
{
// apply the change
}
public override async Task DownAsync(CancellationToken cancellationToken = default)
{
// optionally reverse the change
}
}
Migrations are discovered by reflection, executed in version order, and journaled so they only run once.
Documentation Guide
| Page | What You Will Find |
|---|---|
| Concepts | Core concepts: migration types, versioning, idempotency, profiles, locking |
| Getting Started | Step-by-step setup for each provider |
| Code Migrations | Writing C# code migrations with dependency injection |
| Continuous Migrations | Long-running, scheduled, and repeating migrations |
| Resource Migrations | Declarative migrations with embedded resource files |
| Runners | Standalone runners, CLI reference, Docker |
| Multi-Provider Hosts | Composing two or more providers in a single application |
| Aerospike | Aerospike provider reference |
| Couchbase | Couchbase provider reference |
| MongoDB | MongoDB provider reference |
| OpenSearch | OpenSearch provider reference |
| OpenSearch FAQ - Template Propagation | Detailed FAQ on OpenSearch index-template behavior |
| PostgreSQL | PostgreSQL provider reference |
| Squashing Migrations | Compact long migration histories into a single fast-applying migration |
| Troubleshooting | Common errors, recovery flows, frequently asked questions |
| Supported Versions | .NET TFMs and provider-server versions |
| Advanced Topics | Custom providers, retry strategies, locking internals |
Installation
Install the provider package that matches your database:
dotnet add package Hyperbee.Migrations.Providers.Aerospike
dotnet add package Hyperbee.Migrations.Providers.Couchbase
dotnet add package Hyperbee.Migrations.Providers.MongoDB
dotnet add package Hyperbee.Migrations.Providers.OpenSearch
dotnet add package Hyperbee.Migrations.Providers.Postgres
The core library is referenced transitively by every provider package; install it directly only if you are writing a custom record store:
dotnet add package Hyperbee.Migrations
Credits
The Hyperbee Migrations API is heavily influenced by Fluent Migrator, Raven Migrations, and DbUp. Special thanks to:
- Cronos – cron expression support
- Couchbase .NET Client – Couchbase connectivity and DI extensions
- Raven Migrations – migration pattern inspiration
Contributing
We welcome contributions! See the repo-local CONTRIBUTING guide for the development setup, coding conventions, and the provider-author DI checklist.