Skip to content

MongoMig

Alembic-style schema evolution and migrations for MongoDB.

Change your models, see exactly what changed, generate a migration, review its impact, and run it safely. Built for Python services (FastAPI, Flask, workers) on PyMongo or Beanie.

pip install mongomig            # add [beanie] for Beanie support

Python 3.11+ · MongoDB 6.0+ (tested on 6.0, 7.0 and 8.0)

The workflow

$ mongomig diff                                     # what changed in your models (offline)
$ mongomig revision --autogenerate -m "evolve users" # generate the migration
$ mongomig plan                                     # impact and risk against real data
$ mongomig upgrade                                  # batched, locked, resumable
$ mongomig drift --check                            # does stored data still match? (scheduled)

What you get

  • Autogenerate from your models. Plain Pydantic (@collection) or Beanie documents, with no extra declarations. MongoMig generates backfills with your defaults, renames, indexes and $jsonSchema validators. Risky changes become commented TODO(review) blocks, and data is never deleted automatically.
  • Deterministic diffs. Models are compared with a committed schema snapshot, so the result is the same on every machine and in CI.
  • See the impact first. plan and --dry-run estimate the documents touched and spot collection scans, unique indexes that would fail on duplicates, and validator rejections.
  • Production-grade execution. A distributed lock, batched operations with progress, and checkpoints so a failed migration resumes where it stopped. Also transactions, checksums, confirmation before destructive migrations, and restorable backups.
  • Catch drift. mongomig drift compares your models with the data actually stored.
  • Keep history manageable. mongomig squash replaces old revisions with one, and existing databases adopt it automatically.

Where to go next
New here Getting started
"How do I…?" (step by step, with real output) Recipes
Know Alembic, or using hand-written scripts? Coming from Alembic or scripts
How it thinks Concepts
Writing migrations by hand Writing migrations
From model changes to migrations Autogenerate
Running it in production Production guide
Look something up CLI · Python API · Troubleshooting

Example projects: FastAPI + Pydantic · FastAPI + Beanie