mongo-migrator 1.0.0rc1

Simple MongoDB migrations tool.

Mongo Migrator

Mongo Migrator is a simple tool to manage MongoDB migrations. It allows you to create, run, and rollback migrations in a MongoDB database.

Features

• Easily create migration files with a predefined template.
• Apply migrations to the database.
• Revert migrations quickly.
• Validate and ensure no bifurcations in migration history.
• Keep a clear version history of migrations.

Installation

To install Mongo-Migrator, you can use PyPI:

pip install mongo-migrator

Configuration

Mongo-Migrator uses a configuration file named mongo-migrator.config to connect to your MongoDB instance and manage migrations. Here is an example of a configuration file:

[database]
host = localhost
port = 27017
name = your_database
user = your_user
password = your_password

[migrations]
directory = migrations
collection = version_history

Configuration breakdown

• database: MongoDB connection details.
  • host: MongoDB host address.
  • port: MongoDB port number.
  • name: The database name where migrations will be applied.
  • user: (Optional) The username for database authentication.
  • password: (Optional) The password for database authentication.
• migrations: Migration settings.
  • directory: Directory where migration files are stored.
  • collection: Name of the collection that stores migration version information.

Usage

Mongo-Migrator provides several commands to manage your migrations. These can be executed from the command line.

Initialize the package

To initialize the package, run the following command:

mongo_migrator init

This command initializes the migration system by reading the configuration file, creating the migrations directory, and setting up the version collection in the specified MongoDB database.

Create a new migration

To create a new migration, run the following command:

mongo-migrator create --title "Added new field"

This command generates a new migration file with a timestamp and the provided title. The new migration file will be placed in the migrations directory.

Apply migrations

mongo-migrator upgrade

This command applies all pending migrations in the correct order. You can also specify a version to upgrade to. The argument <version> indicates the last version which will be applied.

mongo-migrator upgrade --version <version>

Rollback migrations

mongo-migrator downgrade

This command rolls back the last migration that was applied. You can also specify a version to downgrade to. The argument <version> indicates the version in which the database will be rolled back. Downgrade in migration <version> will not be applied.

mongo-migrator downgrade --version <version>

View history

mongo-migrator history

This command displays the migration history, showing the version number and the migration message.

Other commands

• mongo-migrator --help: Display the help message.
• mongo-migrator --version: Display the package version.

Test environment

This repository comes with a folder test-project which can be run to test the mongo-migrator package. It also contains example-project, which is the same small project as test-project already initialized and with some migrations made.

The following dependencies are required to run the example project:

• Docker
• Docker Compose
• Python 3.8 or higher
• pipenv

Setup of the test environment

1. First of all, go to the test-project folder and activate the environment:

cd test-project
export PIPENV_VENV_IN_PROJECT=1 # Optional, but recommended
pipenv shell
pipenv install

2. Use the docker-compose.yml file to start a MongoDB instance:

docker-compose up -d

3. Run the setup script

python3 setup-test-db.py

The script will create a database called test-db and a collection called test-collection with some sample data.

4. Now the environment is ready to be tested.

Contributing

By the time, contributions are not being accepted. However, issues will be reviewed and answered.

License

This project is licensed under the MIT License - see the LICENSE file for details.