Getting started¶

Prerequisites¶

• Python 3.13+
• A running MongoDB instance

Install mongrator¶

pip install mongrator

Initialise your project¶

mongrator init

This creates:

• mongrator.toml -- configuration file
• migrations/ -- directory for migration files

Edit mongrator.toml to point at your database:

[mongrator]
uri = "mongodb://localhost:27017"
database = "mydb"
migrations_dir = "migrations"
collection = "mongrator_migrations"

See Configuration for all options including environment variable support.

Create a migration¶

mongrator create add_users_email_index

This generates a timestamped file in the migrations directory, e.g. migrations/20260408_143022_add_users_email_index.py.

Write migration logic¶

Open the generated file and define the up(db) function. Using the ops helpers is the simplest approach:

from mongrator import ops

def up(db):
    return [
        ops.create_index("users", {"email": 1}, unique=True),
    ]

Because ops helpers record their own inverses, rollback works automatically. See Writing migrations for more details.

Apply migrations¶

mongrator up

Check status¶

mongrator status

Roll back¶

mongrator down