Repository navigation
Environments and Secrets
One migrate-mongo.yaml describes every environment (local, staging, production), and secrets come from environment
variables, so the file can be committed.
Top-level settings are the defaults. Each entry under environments is merged over them, so it only needs what's
different:
project: src/MyApp.Migrations
mongodb:
url: ${MONGODB_URL:-mongodb://localhost:27017/?directConnection=true}
databaseName: myapp
indexes:
onRebuild: allow
environments:
staging:
mongodb:
url: ${STAGING_MONGODB_URL}
prod:
mongodb:
url: ${PROD_MONGODB_URL}
indexes:
onRebuild: fail # never drop an index in production without --allow-rebuild
tunnel:
host: bastion.example.com
user: deploy
privateKey: ${BASTION_SSH_KEY}
hostKeyFingerprint: SHA256:x9Yb...Select one with --env (or -e):
migrate-mongo status # top-level settings, e.g. a local database
migrate-mongo plan --env staging
migrate-mongo up --env prod
- Any setting can be overridden per environment. An empty environment changes nothing.
- Unknown settings are errors in every environment, not just the selected one, so a typo in
prodis caught when you run againststaging. - The environment's name is recorded with each run, and is available to migrations as
context.Run.Environment.
Any value can reference an environment variable with ${NAME}, or ${NAME:-default} for a fallback. A variable that
isn't set, or is empty, is an error unless it has a default, so a missing secret fails fast instead of connecting
somewhere unexpected.
Keep secrets out of the file:
-
Connection strings (they usually contain a password):
mongodb.url: ${PROD_MONGODB_URL}. -
SSH keys and passwords for tunnels:
privateKey: ${BASTION_SSH_KEY}. - Or avoid passwords altogether with AWS IAM authentication.
migrate-mongo passes its environment to your migrations project (and bundles read it directly), so
set the variables wherever you run the command.
Use deployment environments to scope secrets and add approvals:
jobs:
migrate:
runs-on: ubuntu-latest
environment: production
env:
PROD_MONGODB_URL: ${{ secrets.PROD_MONGODB_URL }}
BASTION_SSH_KEY: ${{ secrets.BASTION_SSH_KEY }}
steps:
# ...
- run: dotnet tool run migrate-mongo up --env prodEvery command that connects needs the variables, validate included. See Running in CI.
Export them in your shell, or keep the top-level settings pointing at a local database (as above) so plain
migrate-mongo up needs no secrets at all.
The tool needs a user that can read and write the database being migrated, including the
state collections. Collection definitions also need to create, modify and drop
collections and indexes. A read-only user is enough for validate, e.g. as a pull request gate.
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