mongodb-migrations

What it is and what it does

mongodb-migrations is a command-line and programmatic tool for versioning and applying schema changes to MongoDB databases. It works by reading timestamped Python migration files from a migrations folder, each containing a Migration class with upgrade and downgrade methods, and tracking which migrations have been applied via a metastore collection in MongoDB itself.

The tool is designed for teams that need to evolve their MongoDB schema over time without losing data. It supports both CLI execution (via the `mongodb-migrate` command) and direct Python API calls through MigrationManager, allowing you to integrate migrations into deployment pipelines. Configuration is handled via config.ini or command-line arguments, supporting both direct host/port/database settings and MongoDB connection URLs with optional authentication.

Use it for:

• Apply coordinated schema changes across a MongoDB database as your application evolves, tracking which migrations have run.
• Downgrade to a previous migration state by running downgrade methods when a deployment needs to be rolled back.
• Migrate to a specific point in time using --to_datetime to upgrade or downgrade only to a particular migration timestamp.
• Integrate migrations into CI/CD pipelines by calling MigrationManager programmatically instead of using the CLI.
• Manage multiple MongoDB instances with the same migration set by configuring different databases in config.ini or command-line arguments.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Manages schema migrations for MongoDB databases by running timestamped Python migration files that define upgrade and downgrade operations against your data.

Yes, if you need MongoDB schema versioning and can accept a dormant project. The tool is stable for its core use case (running timestamped migrations), has no known vulnerabilities, and low install friction. However, the 823-day maintenance gap and GPLv3 copyleft license mean you should verify compatibility with your MongoDB and Python versions before adopting, and confirm that GPLv3 licensing aligns with your project's legal requirements.

Install

mongodb-migrations on PyPI

pip install mongodb-migrations

uv add mongodb-migrations

poetry add mongodb-migrations

Installing mongodb-migrations

Before you install

Low friction install with only pymongo and configparser as runtime dependencies. Project is dormant (last commit 2024-08-05, no release for 823 days), so expect no active maintenance or bug fixes going forward.

License in practice

GPLv3 copyleft license means any code that uses this package must also be released under GPLv3 or a compatible license; proprietary projects cannot incorporate it without legal risk.

Quickstart

pip install mongodb-migrations

# Create migrations/20160320145400_description.py with a Migration class extending BaseMigration
# Implement upgrade() method

from mongodb_migrations.migration_manager import MigrationManager
manager = MigrationManager()
manager.config.config_file = "config.ini"
manager.config._from_ini()
manager.run()

Requires a config.ini file with MongoDB connection details (host/port/database or url) and a migrations folder with timestamped migration files.

Verify before relying

• Whether the dormant status and 823-day gap since last release pose compatibility risks with current MongoDB or Python versions.
• Whether GPLv3 copyleft applies to migration scripts themselves or only to the tool's source code.

Package facts

Evidence: mongodb_migrations-1.3.1-py3-none-any.whl

Tags

More Python Modules packages