Repository navigation
Running in CI
Run migrations from your pipeline, gate pull requests and deployments on them, and build once to deploy everywhere.
Install the tool as a local tool so CI uses the version in
.config/dotnet-tools.json:
jobs:
migrate:
runs-on: ubuntu-latest
environment: production
# Every command that connects needs these, validate included.
env:
PROD_MONGODB_URL: ${{ secrets.PROD_MONGODB_URL }}
BASTION_SSH_KEY: ${{ secrets.BASTION_SSH_KEY }} # if prod has a tunnel
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
with: { global-json-file: global.json }
- run: dotnet tool restore
- run: dotnet tool run migrate-mongo validate --env prod
- run: dotnet tool run migrate-mongo up --env prod-
environment: productionscopes the secrets and can require an approval. See Environments and Secrets. -
validatechecks nothing was edited, removed or added out of order before anything runs. -
upexits non-zero on any failure, failing the job. See Exit Codes.
- run: dotnet tool run migrate-mongo validate --env stagingvalidate fails with exit code 4 if someone edited an applied
migration, removed one, or added one older than the newest applied one. A read-only database user is enough for it.
plan exits with 2 when there's something to apply, so a pipeline can decide
whether a deployment step (or an approval) is needed:
status=0
migrate-mongo plan --env prod || status=$?
case $status in
0) echo "Nothing to deploy" ;;
2) migrate-mongo up --env prod ;;
*) exit 1 ;;
esacCapture the exit code with ||: CI shells usually run with set -e, which would stop the script as soon as plan
exits with 2.
status --check exits with 2 in the same cases, and suits a scheduled check for indexes changed by hand. Add
up --dry-run to see exactly what would run.
Build a bundle in the build job and run it on deploy agents that don't have .NET:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-dotnet@v6
with: { global-json-file: global.json }
- run: dotnet tool restore
- run: dotnet tool run migrate-mongo bundle -r linux-x64 -o out
- uses: actions/upload-artifact@v7
with: { name: migrations, path: out/ }
deploy:
needs: build
runs-on: [self-hosted, production]
steps:
- uses: actions/download-artifact@v8
with: { name: migrations }
- run: chmod +x MyApp.Migrations && ./MyApp.Migrations up --env prod
env: { PROD_MONGODB_URL: ${{ secrets.PROD_MONGODB_URL }} }The same bundle runs against staging and production, so what you tested is what you deploy.
--json writes one JSON object per line instead of text, ending with a result line carrying the exit code. Use it to
annotate a build or post a summary. See Commands.
Nothing is GitHub-specific: install the .NET SDK, dotnet tool restore, set the connection variables, and run the
same commands. Or use the Docker images, or a bundle where there's no .NET. For a Bitbucket Pipelines
example, see AWS IAM Authentication.
When many instances run migrations at once (e.g. at startup) or overlap with a pipeline run, the lock ensures only one applies them; the others wait and then find nothing to do. 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