---
id: mongodb-migrations
version: "1.3.1"
license: GPLv3
license_treatment: copyleft
maintenance: dormant
---

# mongodb-migrations — A database migration tool for MongoDB

License: copyleft · Maintenance: dormant · Downloads: 107.8K/mo

## 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 above — 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

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

- License: GPLv3 (copyleft)
- Python support: unspecified
- Install friction: low
- Maintenance: dormant
- Downloads: 107.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mongodb schema migration, database migration tool, mongodb data migration, nosql migration framework, mongodb version control, database schema evolution, mongodb upgrade downgrade, schema-migration, mongodb, devops

[View on SkillFed](https://skillfed.io/packages/mongodb-migrations) · [View on PyPI](https://pypi.org/project/mongodb-migrations/)