# Mongrations
A database independent migration and seeding tool for python. Compatible with MySQL, PostgreSQL and MongoDB.
## Required
- Python version 3.6 or above
- pip version 20.3 or above
## Getting Started
1 . Generate a migration file
```bash
mongrations create insert-into-members
```
2 . Contents of the generated migration file (*import and class definition are
autogenerated* - **contents of up() and down() methods are user defined**.)
```python
from mongrations import Mongrations, Database
# MongoDB example
class Mongration(Database):
def __init__(self):
super(Database, self).__init__()
def up(self):
collection = self.db['members']
data = {
'accountId': 1,
'username': 'admin',
'email': 'admin@able.digital',
'firstName': 'Site',
'lastName': 'Owner'
}
collection.insert_one(data)
def down(self):
collection = self.db['members']
collection.delete_one({'username': 'admin'})
Mongrations(Mongration)
```
3 . Run migrations
```bash
mongrations migrate
```
## Install
```bash
pip install --upgrade pip
pip install -U mongrations
```
or install locally
```bash
git clone https://github.com/ableinc/mongrations.git
cd mongrations
python -m pip install -r requirements.txt
python -m pip install .
```
## Use
Mongrations comes with a CLI Tool and an import class for a pythonic migration approach. PyMongo, PyMySQL & Psycopg2 are used under
the hood, so follow <a href="https://api.mongodb.com/python/current/tutorial.html#getting-a-collection">PyMongo</a>'s,
<a href="https://github.com/PyMySQL/PyMySQL">PyMySQL</a>'s, or <a href="https://github.com/psycopg/psycopg2">Psycopg2</a>'s documentation
for instructions on how to create your migrations. For the environment variable tool used in this application, follow
<a href='https://github.com/ableinc/pydotenvs'>this repo</a> (its also installed with this package).
Refer to Mongrations <a href="https://mongrations.readthedocs.io/en/latest/">documentation</a> for more information.
**CLI**
```bash
Usage: mongrations [OPTIONS] COMMAND [ARGS]...
Mongrations; a database migration tool for Python 3.6 and above.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
create
down
inspect
migrate
undo
```
**CLI Examples**
```bash
mongrations create [name] # create new migration (w/ name)
mongrations migrate # run migrations
mongrations down # tear down migrations
mongrations undo # undo last migration
```
**Mongrations Class**
```python
from mongrations import MongrationsCli
migrations = MongrationsCli()
migrations.create(directory='migrations', name='file_name')
migrations.migrate()
migrations.down()
migrations.undo()
```
Run example migration in examples/ folder
## Multi-instance
If your API uses multiple databases to write and read data, you can provide multiple database connections. This can be achieved by providing a connection object (```connection_obj```) to the ```Mongrations``` class in your migrations file. For a ```connection_obj``` example, please refer to the ```examples/``` folder. You can also do this by prepending the service name to your environment variables.
Supported service names:
- ```MONGO_```
- ```MYSQL_```
- ```POSTGRES_```
Example .env file:
```properties
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=password
MYSQL_DB_NAME=myapp
MYSQL_PORT=3306
```
**Note:** ```MONGO_``` service name does **NOT** accept ```MONGO_COLLECTION_NAME```. You will need to provide the collection name in your migration file. The synchronous and asynchronous instances of MongoDB use ```admin``` as the ```authSource``` by default. If you do not want to use ```authSource``` please use ```MONGO_AUTH_SOURCE=None```.
## Issues
Please report all issues to repo.
You **MUST** have write access to your file system to use this application.
## Changelog
January 2023 - Version 1.1.4:
- Bugfix: CLI tool will now add service name to environment when using ```--mongrationFile.json```
January 2023 - Version 1.1.3:
- Updated: CLI tool to handle ```--mongrationFile``` for rollback and down command
- psycopg will be downloaded by the library. Installing from source is no longer an option.
January 2023 - Version 1.1.2:
- Bugfix: postgres connection library fix
- Bugfix: Database connection would close prematurely
January 2023 - Version 1.1.1:
- You can now use the ```mongrationFile.json``` file to add database connection variables. You can refer to an example of this file [here](mongrationFile.json)
- You can specify the environment with ```--migrationfile``` (default env is development):
```bash
mongrations migrate --file mongrationFile.json --env development
```
- The CLI tool can generate the ```mongrationFile.json``` file for you. Run this command:
```bash
mongrations file
```
January 2023 - Version 1.1.0:
- Fixed bug with CLI tool where directory argument wasn't being passed properly to the migrate function.
- The CLI tool has new arguments with better helper descriptions
- The database connection class has been updated to provide more enhances connection strings
- The cache system was rebuilt - The way mongrations caches will change in the future
- ```migrations``` directory will not be created until you create your first migration file
- Updated error codes and error messages.
- In the event your PYTHON_PATH is changed and points to a Python version less than 3.6 the CLI tool will prompt you.
January 2023 - Version 1.0.4:
- The cache system will now keep the cache file in the ```migrations/``` directory at root
- psycopg[binary,pool] will now be installed during pip installation (pip 20.3 > is required)
- Removed the default ```pydotenvs``` import from the migration file
- Time (in ms) will be appended to file names instead of UUIDs
- The library wil be getting a rewrite and released under another name. This will be the last major release to the library under this name. Note: bug fixes will still be published.
January 2022 - Version 1.0.4:
- Squashed bugs
- Mongrations can now run on Linux
- Default: stdout error output if error occurs during caching operation
- Removed the psycopg2 install step from setup.py
- Simplified how the database connection strings are initialized
- Inspect will now pretty print JSON structure and provide file system location
- Updated ```examples/``` directory
August 2020:
- Introduced the official version 1.0.0 of Mongrations!
- Rewrote command line tool; much easier and intuiative
- Extracted classes into their own files; reducing clutter
- Added a raw sql function that allows for much more flexibility
- File name rewrites (if you encounter an upgrade error run the option: --no-cache, with pip)
- psycopg2 is now installed optionally (refer to Notes)
- Super fast writing to the system
- Setup.py has been cleaned up. An occasional bug occured when installing
- Added/Updated examples (refer to Github)
Raw data
{
"_id": null,
"home_page": "https://github.com/ableinc/mongrations",
"name": "mongrations",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "migrations,python3,automation,database,json,nosql,python,database tool,automation tool,open source,mongodb,mysql,postgres,sql",
"author": "AbleInc - Jaylen Douglas",
"author_email": "douglas.jaylen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b0/31/4f3a7d35055fbd2e7e662c8000c6b3839cdb50b5a525b95d3193ca6fd217/mongrations-1.1.4.tar.gz",
"platform": null,
"description": "# Mongrations\n\n![alt text](https://img.icons8.com/dusk/64/000000/database.png \"Mongrations Logo\")\nA database independent migration and seeding tool for python. Compatible with MySQL, PostgreSQL and MongoDB.\n\n## Required\n\n - Python version 3.6 or above\n - pip version 20.3 or above\n\n## Getting Started\n\n1 . Generate a migration file\n```bash\nmongrations create insert-into-members\n```\n2 . Contents of the generated migration file (*import and class definition are \nautogenerated* - **contents of up() and down() methods are user defined**.)\n```python\nfrom mongrations import Mongrations, Database\n\n# MongoDB example\nclass Mongration(Database):\n def __init__(self):\n super(Database, self).__init__()\n\n def up(self):\n collection = self.db['members']\n data = {\n 'accountId': 1,\n 'username': 'admin',\n 'email': 'admin@able.digital',\n 'firstName': 'Site',\n 'lastName': 'Owner'\n }\n collection.insert_one(data)\n\n def down(self):\n collection = self.db['members']\n collection.delete_one({'username': 'admin'})\n\n\nMongrations(Mongration)\n```\n3 . Run migrations\n```bash\nmongrations migrate\n```\n\n## Install\n\n```bash\npip install --upgrade pip\npip install -U mongrations\n\n```\nor install locally\n```bash\ngit clone https://github.com/ableinc/mongrations.git\ncd mongrations\npython -m pip install -r requirements.txt\npython -m pip install .\n```\n\n## Use\n\nMongrations comes with a CLI Tool and an import class for a pythonic migration approach. PyMongo, PyMySQL & Psycopg2 are used under\nthe hood, so follow <a href=\"https://api.mongodb.com/python/current/tutorial.html#getting-a-collection\">PyMongo</a>'s,\n<a href=\"https://github.com/PyMySQL/PyMySQL\">PyMySQL</a>'s, or <a href=\"https://github.com/psycopg/psycopg2\">Psycopg2</a>'s documentation \nfor instructions on how to create your migrations. For the environment variable tool used in this application, follow \n<a href='https://github.com/ableinc/pydotenvs'>this repo</a> (its also installed with this package).\n\nRefer to Mongrations <a href=\"https://mongrations.readthedocs.io/en/latest/\">documentation</a> for more information.\n\n**CLI**\n```bash\nUsage: mongrations [OPTIONS] COMMAND [ARGS]...\n\n Mongrations; a database migration tool for Python 3.6 and above.\n\nOptions:\n --version Show the version and exit.\n --help Show this message and exit.\n\nCommands:\n create\n down\n inspect\n migrate\n undo\n```\n**CLI Examples**\n```bash\nmongrations create [name] # create new migration (w/ name)\nmongrations migrate # run migrations\nmongrations down # tear down migrations\nmongrations undo # undo last migration\n```\n\n**Mongrations Class**\n```python\nfrom mongrations import MongrationsCli\n\nmigrations = MongrationsCli()\n\nmigrations.create(directory='migrations', name='file_name')\nmigrations.migrate()\nmigrations.down()\nmigrations.undo()\n```\nRun example migration in examples/ folder\n\n## Multi-instance\n\nIf your API uses multiple databases to write and read data, you can provide multiple database connections. This can be achieved by providing a connection object (```connection_obj```) to the ```Mongrations``` class in your migrations file. For a ```connection_obj``` example, please refer to the ```examples/``` folder. You can also do this by prepending the service name to your environment variables.\n\nSupported service names:\n\n - ```MONGO_```\n - ```MYSQL_```\n - ```POSTGRES_```\n\nExample .env file:\n\n```properties\nMYSQL_HOST=localhost\nMYSQL_USER=root\nMYSQL_PASSWORD=password\nMYSQL_DB_NAME=myapp\nMYSQL_PORT=3306\n```\n\n**Note:** ```MONGO_``` service name does **NOT** accept ```MONGO_COLLECTION_NAME```. You will need to provide the collection name in your migration file. The synchronous and asynchronous instances of MongoDB use ```admin``` as the ```authSource``` by default. If you do not want to use ```authSource``` please use ```MONGO_AUTH_SOURCE=None```.\n\n## Issues\n\nPlease report all issues to repo.\n\nYou **MUST** have write access to your file system to use this application.\n\n## Changelog\n\nJanuary 2023 - Version 1.1.4:\n\n - Bugfix: CLI tool will now add service name to environment when using ```--mongrationFile.json```\n\nJanuary 2023 - Version 1.1.3:\n\n - Updated: CLI tool to handle ```--mongrationFile``` for rollback and down command\n - psycopg will be downloaded by the library. Installing from source is no longer an option.\n\nJanuary 2023 - Version 1.1.2:\n\n - Bugfix: postgres connection library fix\n - Bugfix: Database connection would close prematurely\n\nJanuary 2023 - Version 1.1.1:\n - You can now use the ```mongrationFile.json``` file to add database connection variables. You can refer to an example of this file [here](mongrationFile.json)\n - You can specify the environment with ```--migrationfile``` (default env is development):\n ```bash\n mongrations migrate --file mongrationFile.json --env development\n ```\n - The CLI tool can generate the ```mongrationFile.json``` file for you. Run this command:\n ```bash\n mongrations file\n ```\n\nJanuary 2023 - Version 1.1.0:\n - Fixed bug with CLI tool where directory argument wasn't being passed properly to the migrate function. \n - The CLI tool has new arguments with better helper descriptions\n - The database connection class has been updated to provide more enhances connection strings\n - The cache system was rebuilt - The way mongrations caches will change in the future\n - ```migrations``` directory will not be created until you create your first migration file\n - Updated error codes and error messages.\n - In the event your PYTHON_PATH is changed and points to a Python version less than 3.6 the CLI tool will prompt you.\n\nJanuary 2023 - Version 1.0.4:\n - The cache system will now keep the cache file in the ```migrations/``` directory at root\n - psycopg[binary,pool] will now be installed during pip installation (pip 20.3 > is required)\n - Removed the default ```pydotenvs``` import from the migration file\n - Time (in ms) will be appended to file names instead of UUIDs\n - The library wil be getting a rewrite and released under another name. This will be the last major release to the library under this name. Note: bug fixes will still be published.\n\nJanuary 2022 - Version 1.0.4:\n - Squashed bugs\n - Mongrations can now run on Linux\n - Default: stdout error output if error occurs during caching operation\n - Removed the psycopg2 install step from setup.py\n - Simplified how the database connection strings are initialized\n - Inspect will now pretty print JSON structure and provide file system location\n - Updated ```examples/``` directory\n\nAugust 2020:\n - Introduced the official version 1.0.0 of Mongrations!\n - Rewrote command line tool; much easier and intuiative\n - Extracted classes into their own files; reducing clutter\n - Added a raw sql function that allows for much more flexibility\n - File name rewrites (if you encounter an upgrade error run the option: --no-cache, with pip)\n - psycopg2 is now installed optionally (refer to Notes)\n - Super fast writing to the system\n - Setup.py has been cleaned up. An occasional bug occured when installing\n - Added/Updated examples (refer to Github)\n",
"bugtrack_url": null,
"license": "",
"summary": "Mongrations; a database independent migration and seeding tool for python.",
"version": "1.1.4",
"split_keywords": [
"migrations",
"python3",
"automation",
"database",
"json",
"nosql",
"python",
"database tool",
"automation tool",
"open source",
"mongodb",
"mysql",
"postgres",
"sql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b0314f3a7d35055fbd2e7e662c8000c6b3839cdb50b5a525b95d3193ca6fd217",
"md5": "3b5a0079ce3cdcf5298d9d473faeee8e",
"sha256": "a6a9783ee0b32040531651b409627d064e6e4923a29b2390c74a3f132af8e213"
},
"downloads": -1,
"filename": "mongrations-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "3b5a0079ce3cdcf5298d9d473faeee8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20943,
"upload_time": "2023-01-11T02:14:36",
"upload_time_iso_8601": "2023-01-11T02:14:36.275754Z",
"url": "https://files.pythonhosted.org/packages/b0/31/4f3a7d35055fbd2e7e662c8000c6b3839cdb50b5a525b95d3193ca6fd217/mongrations-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-11 02:14:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ableinc",
"github_project": "mongrations",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Click",
"specs": []
},
{
"name": "motor",
"specs": []
},
{
"name": "pydotenvs",
"specs": []
},
{
"name": "pymongo",
"specs": []
},
{
"name": "PyMySQL",
"specs": []
},
{
"name": "requests",
"specs": []
}
],
"lcname": "mongrations"
}
JSON
