MongoDB Migrations

1.3.1 verified Fri May 01 auth: no python maintenance

A database migration tool for MongoDB, providing a simple way to manage and apply schema/data migrations. Current version 1.3.1 is stable but appears to have no recent updates (last release 2018).

pip install mongodb-migrations

Common errors

error pkg_resources.DistributionNotFound: The 'sh' distribution was not found ↓

cause The 'sh' package is a dependency but not installed automatically in all environments.

fix

Run: pip install sh

error AttributeError: module 'pymongo' has no attribute 'MongoClient' ↓

cause Older versions of the library import pymongo incorrectly or require pymongo <4.0.

fix

Install pymongo==3.12.3: pip install pymongo==3.12.3

Warnings

breaking The project is unmaintained since 2018. It may not support newer versions of PyMongo (>=4.0) or MongoDB (>=5.0). Expect breaking changes with asynchronous drivers or modern connection URIs. ↓

fix Consider alternatives like mongodb-migrate, migrate-mongo, or write custom migration scripts.

gotcha The 'down' method is not called automatically on rollback. You must implement 'downgrade' manually if needed. ↓

fix Always implement downgrade methods and use --rollback explicitly.

deprecated The CLI tool 'mongo-migrate' uses Python 2-style string formatting and may fail with Python 3.8+ under certain locale settings. ↓

fix Use Python 3.6-3.7 or pin to older versions of dependencies.

Imports

Connection

wrong

from mongodb_migrations import Connection

correct

from mongodb_migrations.cli import Connection

Connection is in the cli module, not top-level

Migration

from mongodb_migrations.migration import Migration

Quickstart

Initialize migrations, create a sample migration, and run it.

pip install mongodb-migrations
# Create a migration directory
mkdir -p migrations
# Create a migration file
cat > migrations/001_add_index.py << 'EOF'
from mongodb_migrations.migration import Migration

class Migration001(Migration):
    def upgrade(self):
        self.db.users.create_index('email', unique=True)
EOF
# Run CLI (ensure MongoDB is running and credentials are set via env or config)
mongo-migrate run --migrations-dir=./migrations --uri='mongodb://localhost:27017/mydb'