# Mroll migration tool
`mroll` has been designed to aid MonetDB users with managing database migrations.
The functionality covers both roll forward and backward migration functionality.
Although you can deploy `mroll` from any point in time onwards, it is advised to use it
from day one, i.e. the creation of the database.
`mroll` has been used internally to manage the continuous integration workflow of MonetDB.
## Install
Install mroll from PyPi
```
$ pip install mroll
```
## Synopsis
The command synopsis summarizes the functionality.
```
$ mroll --help
Usage: commands.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
Options:
--help Show this message and exit.
Commands:
config Set up mroll configuration under $HOME/.config/mroll
history Shows applied revisions.
init Creates mroll_revisions tbl.
revision Creates new revision from a template.
rollback Downgrades to previous revision by default.
setup Set up work directory.
show Shows revisions information.
upgrade Applies all revisions not yet applied in work dir.
version Shows current version
```
Each command may come with some options, explained by the `--help` addition.
For example, the location of the migration directory can be specified when you install mroll
with an option `--path` option to specify location. For an example, `--path "/tmp/migration"` location.
To update/set `mroll` configuration use the `config` command.
For example to update configuration setting for working directory path run.
```
mroll config -p <workdir_path>
```
## Usage
To illustrate the functionality we walk you through the steps to get a MonetDB database, called
*demo*, created and managed. We assume you have downloaded `mroll` (see below) and are all set to give it a try.
#### Setup
`mroll` needs a working directory for each database you want to manage. There is no restriction on
its location, but you could keep the migration scripts in your application
folder, e.g. `.../app/migrations`. From the `.../app` directory issue the command:
```
$ mroll setup
ok
```
A subdirectory `migrations` is being created to manage migrations versions.
#### Configuration
`mroll` needs information on the database whereabouts and credentials to initiate the migration steps.
Make sure you have already created and released the demo database using the `monetdb` tools.
Then complete the file `migrations/mroll.ini` to something like:
```
[db]
db_name=demo
user=monetdb
password=monetdb
port=50000
[mroll]
rev_history_tbl_name = mroll_revisions
```
The final step for managing the migrations is
```
$ mroll init
```
#### Define the first revision
The empty database will be populated with a database schema.
For this we define a revision. Revision names are generated
```
$ mroll revision -m "Initialize the database"
ok
$ mroll show all_revisions
<Revision id=fe00de6bfa19 description=Initialize the database>
```
A new revison file was added under `/tmp/migrations/versions`.
Open it and add the SQL commands under `-- migration:upgrade` and `-- migration:downgrade` sections.
```
vi tmp/migrations/versions/<rev_file>
-- identifiers used by mroll
-- id=fe00de6bfa19
-- description=create tbl foo
-- ts=2020-05-08T14:19:46.839773
-- migration:upgrade
create table foo (a string, b string);
alter table foo add constraint foo_pk primary key (a);
-- migration:downgrade
drop table foo;
```
Then run "upgrade" command.
```
$ mroll upgrade
Done
```
Inspect what has being applied with "history" command
```
$ mroll history
<Revision id=fe00de6bfa19 description=create tbl foo>
```
For revisions overview use `mroll show [all|pending|applied]`, `mroll applied` is equivalent to
`mroll history`.
```
$mroll show applied
<Revision id=fe00de6bfa19 description=create tbl foo>
```
To revert last applied revision run the `rollback` command. That will run the sql under `migration:downgrade`
section.
```
$ mroll rollback
Rolling back id=fe00de6bfa19 description=create tbl foo ...
Done
```
## Development
### Developer notes
`mroll` is developed using [Poetry](https://python-poetry.org/), for dependency management and
packaging.
### Installation for development
In order to install `mroll` do the following:
```
pip3 install --user poetry
PYTHON_BIN_PATH="$(python3 -m site --user-base)/bin"
export PATH="$PATH:$PYTHON_BIN_PATH"
git clone git@github.com:MonetDBSolutions/mroll.git
cd mroll
poetry install
poetry run mroll/commands.py --help
```
Install project dependencies with
```
poetry install
```
This will create virtual environment and install dependencies from the `poetry.lock` file. Any of the above
commands then can be run with poetry
```
poetry run mroll/commands.py <command>
```
## Testing
Run all unit tests
```
make test
```
Raw data
{
"_id": null,
"home_page": "https://github.com/MonetDBSolutions/mroll",
"name": "mroll",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "migration,monetdb,mroll",
"author": "svetlin",
"author_email": "svetlin.stalinov@monetdbsolutions.com",
"download_url": "https://files.pythonhosted.org/packages/de/fb/77e6666897deb20ac4ceaf398e5962895574ed1768aa597cbf2da2c8c2b1/mroll-0.4.0.tar.gz",
"platform": null,
"description": "\n\n# Mroll migration tool\n`mroll` has been designed to aid MonetDB users with managing database migrations.\nThe functionality covers both roll forward and backward migration functionality.\nAlthough you can deploy `mroll` from any point in time onwards, it is advised to use it\nfrom day one, i.e. the creation of the database.\n`mroll` has been used internally to manage the continuous integration workflow of MonetDB.\n\n## Install\n\nInstall mroll from PyPi\n\n```\n$ pip install mroll\n```\n\n## Synopsis\nThe command synopsis summarizes the functionality.\n\n```\n$ mroll --help\nUsage: commands.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n config Set up mroll configuration under $HOME/.config/mroll\n history Shows applied revisions.\n init Creates mroll_revisions tbl.\n revision Creates new revision from a template.\n rollback Downgrades to previous revision by default.\n setup Set up work directory.\n show Shows revisions information.\n upgrade Applies all revisions not yet applied in work dir.\n version Shows current version\n```\n\nEach command may come with some options, explained by the `--help` addition.\nFor example, the location of the migration directory can be specified when you install mroll\nwith an option `--path` option to specify location. For an example, `--path \"/tmp/migration\"` location.\n\nTo update/set `mroll` configuration use the `config` command.\nFor example to update configuration setting for working directory path run.\n```\nmroll config -p <workdir_path>\n```\n\n## Usage\nTo illustrate the functionality we walk you through the steps to get a MonetDB database, called\n*demo*, created and managed. We assume you have downloaded `mroll` (see below) and are all set to give it a try.\n\n#### Setup \n`mroll` needs a working directory for each database you want to manage. There is no restriction on\nits location, but you could keep the migration scripts in your application \nfolder, e.g. `.../app/migrations`. From the `.../app` directory issue the command:\n\n```\n$ mroll setup\nok\n```\nA subdirectory `migrations` is being created to manage migrations versions.\n\n#### Configuration\n`mroll` needs information on the database whereabouts and credentials to initiate the migration steps.\nMake sure you have already created and released the demo database using the `monetdb` tools.\nThen complete the file `migrations/mroll.ini` to something like:\n```\n[db]\ndb_name=demo\nuser=monetdb\npassword=monetdb\nport=50000\n\n[mroll]\nrev_history_tbl_name = mroll_revisions\n```\nThe final step for managing the migrations is\n```\n$ mroll init\n```\n#### Define the first revision\nThe empty database will be populated with a database schema.\nFor this we define a revision. Revision names are generated\n\n```\n$ mroll revision -m \"Initialize the database\"\nok\n$ mroll show all_revisions\n<Revision id=fe00de6bfa19 description=Initialize the database>\n```\nA new revison file was added under `/tmp/migrations/versions`. \nOpen it and add the SQL commands under `-- migration:upgrade` and `-- migration:downgrade` sections.\n\n```\nvi tmp/migrations/versions/<rev_file>\n-- identifiers used by mroll\n-- id=fe00de6bfa19\n-- description=create tbl foo\n-- ts=2020-05-08T14:19:46.839773\n-- migration:upgrade\n\tcreate table foo (a string, b string);\n\talter table foo add constraint foo_pk primary key (a);\n-- migration:downgrade\n\tdrop table foo;\n```\nThen run \"upgrade\" command.\n\n```\n$ mroll upgrade\nDone\n```\n\nInspect what has being applied with \"history\" command\n```\n$ mroll history\n<Revision id=fe00de6bfa19 description=create tbl foo>\n```\nFor revisions overview use `mroll show [all|pending|applied]`, `mroll applied` is equivalent to \n`mroll history`.\n```\n$mroll show applied\n<Revision id=fe00de6bfa19 description=create tbl foo>\n```\n\nTo revert last applied revision run the `rollback` command. That will run the sql under `migration:downgrade`\nsection.\n```\n$ mroll rollback \nRolling back id=fe00de6bfa19 description=create tbl foo ...\nDone\n```\n\n## Development\n### Developer notes\n\n`mroll` is developed using [Poetry](https://python-poetry.org/), for dependency management and\npackaging.\n\n### Installation for development\nIn order to install `mroll` do the following:\n\n```\n pip3 install --user poetry\n PYTHON_BIN_PATH=\"$(python3 -m site --user-base)/bin\"\n export PATH=\"$PATH:$PYTHON_BIN_PATH\"\n\n git clone git@github.com:MonetDBSolutions/mroll.git\n cd mroll\n poetry install\n poetry run mroll/commands.py --help\n```\nInstall project dependencies with\n\n```\npoetry install\n```\nThis will create virtual environment and install dependencies from the `poetry.lock` file. Any of the above \ncommands then can be run with poetry\n\n```\npoetry run mroll/commands.py <command>\n```\n## Testing\nRun all unit tests\n```\nmake test\n```\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "monetdb migration tool",
"version": "0.4.0",
"split_keywords": [
"migration",
"monetdb",
"mroll"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "34b2f5b7430a941550e3cb27d95fb01e",
"sha256": "908b4f221daaab050b366fe151fc4e684e8972472203418d5d0490d396469b1e"
},
"downloads": -1,
"filename": "mroll-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34b2f5b7430a941550e3cb27d95fb01e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 18250,
"upload_time": "2022-12-01T13:57:53",
"upload_time_iso_8601": "2022-12-01T13:57:53.261863Z",
"url": "https://files.pythonhosted.org/packages/f8/e4/563595d2f54487bb81f6dd417b48542cf3e1ee714069bcdd733c97539a60/mroll-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "bc6651bfb6e6ca76b1dcf0dcedff86f0",
"sha256": "68c52eb4b8ab47a827a943b8f67778a431ca029150663bbe7bfce59e67d0ec9f"
},
"downloads": -1,
"filename": "mroll-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "bc6651bfb6e6ca76b1dcf0dcedff86f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 17287,
"upload_time": "2022-12-01T13:57:54",
"upload_time_iso_8601": "2022-12-01T13:57:54.922563Z",
"url": "https://files.pythonhosted.org/packages/de/fb/77e6666897deb20ac4ceaf398e5962895574ed1768aa597cbf2da2c8c2b1/mroll-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-01 13:57:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "MonetDBSolutions",
"github_project": "mroll",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mroll"
}
JSON
