Repository navigation
How It Works
How migrate-mongo, your migrations project and your app fit together, and why upgrading one doesn't break the others.
┌──────────────────────────────┐ build (your SDK) ┌─────────────────────────────────────────┐
│ migrate-mongo (the tool) │ ──────────────────────▶ │ Your migrations project (console app) │
│ Native AOT, no .NET needed │ │ ├─ Kevsoft.MigrateMongo.Runner │
│ • config, --env, secrets │ spawn + handshake │ ├─ Kevsoft.MigrateMongo (engine) │
│ • init / create │ ──────────────────────▶ │ ├─ MongoDB.Driver (your version) │
│ • build, bundles │ JSON events (stdout) │ └─ Migrations/*.cs, Collections/*.cs │
│ • SSH tunnels │ ◀────────────────────── │ │
│ • output, exit codes │ └─────────────────────────────────────────┘
└──────────────────────────────┘ ▲ same engine, state and lock
┌──────┴──────────────────────────────────┐
│ Your app: Kevsoft.MigrateMongo.Hosting │
└─────────────────────────────────────────┘
-
The tool is a launcher. It reads
migrate-mongo.yaml, builds your migrations project, opens any SSH tunnel, runs the project and renders what it reports. It never loads your code or the MongoDB driver. -
Your migrations project is a small console app that calls
MigrateMongoRunner.RunAsync(args). It contains the engine, your migrations and collection definitions, and theMongoDB.Driverversion you chose. This is the only process that talks to MongoDB. - Your app can run the same engine at startup with Hosting. It uses the same state collections and lock, so the CLI and app instances coordinate safely.
- The tool finds
migrate-mongo.yaml, applies--envand resolves${VARIABLES}. - It builds the project from
project:with your .NET SDK (the one yourglobal.jsonpins), unless you pass--no-buildor a pre-built--runnersuch as a bundle. -
Handshake. It runs the project with
--mm-handshake. The project replies with the protocol versions it speaks and its library, driver and runtime versions, printed as theRunner:line. The tool picks the highest protocol version both understand. - It runs the project again with the command and the resolved settings on standard input, so connection strings and keys aren't on its command line.
- The project takes the lock, does the work, and streams events (
migrationStarted,lockWaiting,result, ...) as JSON lines. The tool renders them, or passes them through with--json, and exits with the result's exit code.
Running the project directly (dotnet run -- up) or a bundle skips the tool: the project reads the config itself and
writes the output.
Because the tool only starts processes and exchanges JSON, nothing is loaded across the boundary:
- The tool doesn't need .NET. It's compiled with Native AOT. The .NET SDK is only needed to build your project.
-
You choose the driver. Your project references
MongoDB.Driver3.9 or later. Upgrading it doesn't need a new tool. -
The tool and the libraries version independently. The protocol is versioned. If the tool is too old for the
runner, it stops with exit code
5and tells you to update it, rather than failing with a confusing error.
A source generator in Kevsoft.MigrateMongo.Abstractions finds [Migration], [ManagedCollection] and
[ManagedView] classes at compile time and writes the code that creates them (resolving constructor dependencies from
the service provider). That means:
- mistakes are build errors, not runtime surprises;
- nothing is discovered by reflection at runtime;
- a migration's checksum is computed from its source at build time. See Safety.
Kevsoft.MigrateMongo ·
NuGet ·
Releases ·
Issues ·
Found a mistake? These pages live in
wiki/ on main; pull requests welcome.
Get started
Migrations
- Writing Migrations
- Transactions
- Recording Results
- Dependency Injection
- Custom Templates
- Adopting an Existing Database
Collections
- Managing Collections
- Indexes
- Search Indexes
- Collection Options
- Validators
- Views
- Undeclared Collections
Deploying
Connecting
Reference
Concepts