[](https://pypi.org/project/neo4j-python-migrations/)
# neo4j-python-migrations
> It is a database migration tool for [Neo4j](http://neo4j.com) written in Python
> that allows to apply not only Cypher migrations, but also arbitrary Python-based migrations.
>
> This tool is inspired by [Michael Simons tool for Java](https://github.com/michael-simons/neo4j-migrations)
> and works directly on [neo4j-python-driver](https://github.com/neo4j/neo4j-python-driver).
# Features
- Python migration support makes it possible to do any things in your migration that Python allows you to do.
- Cypher-based migrations support.
- It can be used either via the command line or directly in your code.
- Multi-database support for Neo4j Enterprise Edition users.
- The ability to separate logically independent migration chains within a single database (see the `project` option).
May be useful for Neo4j Community Edition users.
# Installation
From PyPi:
`pip3 install neo4j-python-migrations`
If you want to install it from sources, try this:
```
python3 -m pip install poetry
python3 -m pip install .
python3 -m neo4j_python_migrations
```
# Usage
## Creating migrations
### Naming Convention
Each migration will be a Cypher or Python file following the format `V<sem_ver>__<migration_name>.ext`.
Make sure to follow the naming convention as stated in
[Michael's tool documentation](https://michael-simons.github.io/neo4j-migrations/current/#concepts_naming-conventions)
(except that .py files are allowed).
### Cypher
Just create a Cypher file with your custom script, for example `./migrations/V0001__initial.cypher`:
```
CREATE CONSTRAINT UniqueAuthor IF NOT EXISTS ON (a:AUTHOR) ASSERT a.uuid IS UNIQUE;
CREATE INDEX author_uuid_index IF NOT EXISTS FOR (a:AUTHOR) ON (a.uuid);
```
This script will be executed within a single transaction.
Therefore, if you need both DDL and DML commands, split them into different files.
### Python
Python-based migrations should have a special format, for example `./migrations/V0002__drop_index.py`:
```
from neo4j import Session
# This function must be present
def up(session: Session):
with session.begin_transaction() as tx:
tx.run("DROP INDEX author_uuid_index")
```
## Applying migrations
### CLI
You can apply migrations or verify the status of migrations using the command line interface:
```
Usage: python -m neo4j_python_migrations [OPTIONS] COMMAND [ARGS]...
Options:
--username TEXT The login of the user connecting to the
database. [env var: NEO4J_MIGRATIONS_USER;
default: neo4j]
--password TEXT The password of the user connecting to the
database. [env var: NEO4J_MIGRATIONS_PASS;
required]
--path PATH The path to the directory for scanning
migration files. [env var:
NEO4J_MIGRATIONS_PATH; required]
--port INTEGER Port for connecting to the database [env
var: NEO4J_MIGRATIONS_PORT; default: 7687]
--host TEXT Host for connecting to the database [env
var: NEO4J_MIGRATIONS_HOST; default:
127.0.0.1]
--scheme TEXT Scheme for connecting to the database
[default: neo4j]
--project TEXT The name of the project for separating
logically independent migration chains
within a single database. [env var:
NEO4J_MIGRATIONS_PROJECT]
--schema-database TEXT The database that should be used for storing
information about migrations (Neo4j EE). If
not specified, then the database that should
be migrated is used. [env var:
NEO4J_MIGRATIONS_SCHEMA_DATABASE]
--database TEXT The database that should be migrated (Neo4j
EE) [env var: NEO4J_MIGRATIONS_DATABASE]
--install-completion [bash|zsh|fish|powershell|pwsh]
Install completion for the specified shell.
--show-completion [bash|zsh|fish|powershell|pwsh]
Show completion for the specified shell, to
copy it or customize the installation.
--help Show this message and exit.
Commands:
analyze Analyze migrations, find pending and missed.
migrate Retrieves all pending migrations, verify and applies them.
```
So, to apply migrations, just run the command:
`python3 -m neo4j_python_migrations --username neo4j --password test --path ./migrations migrate`
_Note: it is more secure to store the password in the environment variable NEO4J_MIGRATIONS_PASS._
### Python Code
You can apply migrations directly into your application:
```
from pathlib import Path
from neo4j import GraphDatabase
from neo4j_python_migrations.executor import Executor
with GraphDatabase.driver("neo4j://localhost:7687", auth=("neo4j", "test")) as driver:
executor = Executor(driver, migrations_path=Path("./migrations"))
executor.migrate()
```
Available methods: `migrate`, `analyze`.
# How migrations are tracked
Information about the applied migrations is stored in the database using the schema
described in [Michael's README](https://michael-simons.github.io/neo4j-migrations/current/#concepts_chain).
Supported migration types: СYPHER, PYTHON. Other types of migrations, such as JAVA, are not supported.
Note: the `project` option are incompatible with this schema.
When using the option, each migration nodes will have an additional property named `project`.
Raw data
{
"_id": null,
"home_page": "https://github.com/booqoffsky/neo4j-python-migrations",
"name": "neo4j-python-migrations",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "neo4j,migrations,python,migrator",
"author": "Grigory Bukovsky",
"author_email": "booqoffsky@yandex.ru",
"download_url": "https://files.pythonhosted.org/packages/ec/79/d041e7cd414fa186603ff9d56424ebdeb14bb2f4005d5197afcedecd7502/neo4j-python-migrations-0.1.1.tar.gz",
"platform": null,
"description": " \n[](https://pypi.org/project/neo4j-python-migrations/)\n\n\n# neo4j-python-migrations\n\n> It is a database migration tool for [Neo4j](http://neo4j.com) written in Python\n> that allows to apply not only Cypher migrations, but also arbitrary Python-based migrations.\n> \n> This tool is inspired by [Michael Simons tool for Java](https://github.com/michael-simons/neo4j-migrations)\n> and works directly on [neo4j-python-driver](https://github.com/neo4j/neo4j-python-driver).\n\n# Features\n- Python migration support makes it possible to do any things in your migration that Python allows you to do.\n- Cypher-based migrations support.\n- It can be used either via the command line or directly in your code.\n- Multi-database support for Neo4j Enterprise Edition users.\n- The ability to separate logically independent migration chains within a single database (see the `project` option).\nMay be useful for Neo4j Community Edition users.\n\n# Installation\nFrom PyPi:\n\n`pip3 install neo4j-python-migrations`\n\nIf you want to install it from sources, try this:\n\n```\npython3 -m pip install poetry\npython3 -m pip install .\npython3 -m neo4j_python_migrations \n```\n\n# Usage\n## Creating migrations\n### Naming Convention\nEach migration will be a Cypher or Python file following the format `V<sem_ver>__<migration_name>.ext`.\n\nMake sure to follow the naming convention as stated in \n[Michael's tool documentation](https://michael-simons.github.io/neo4j-migrations/current/#concepts_naming-conventions)\n(except that .py files are allowed).\n\n### Cypher\nJust create a Cypher file with your custom script, for example `./migrations/V0001__initial.cypher`:\n```\nCREATE CONSTRAINT UniqueAuthor IF NOT EXISTS ON (a:AUTHOR) ASSERT a.uuid IS UNIQUE;\nCREATE INDEX author_uuid_index IF NOT EXISTS FOR (a:AUTHOR) ON (a.uuid);\n```\nThis script will be executed within a single transaction.\nTherefore, if you need both DDL and DML commands, split them into different files.\n\n### Python\nPython-based migrations should have a special format, for example `./migrations/V0002__drop_index.py`:\n```\nfrom neo4j import Session\n\n\n# This function must be present\ndef up(session: Session):\n with session.begin_transaction() as tx:\n tx.run(\"DROP INDEX author_uuid_index\")\n```\n\n## Applying migrations\n### CLI\nYou can apply migrations or verify the status of migrations using the command line interface:\n```\nUsage: python -m neo4j_python_migrations [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --username TEXT The login of the user connecting to the\n database. [env var: NEO4J_MIGRATIONS_USER;\n default: neo4j]\n --password TEXT The password of the user connecting to the\n database. [env var: NEO4J_MIGRATIONS_PASS;\n required]\n --path PATH The path to the directory for scanning\n migration files. [env var:\n NEO4J_MIGRATIONS_PATH; required]\n --port INTEGER Port for connecting to the database [env\n var: NEO4J_MIGRATIONS_PORT; default: 7687]\n --host TEXT Host for connecting to the database [env\n var: NEO4J_MIGRATIONS_HOST; default:\n 127.0.0.1]\n --scheme TEXT Scheme for connecting to the database\n [default: neo4j]\n --project TEXT The name of the project for separating\n logically independent migration chains\n within a single database. [env var:\n NEO4J_MIGRATIONS_PROJECT]\n --schema-database TEXT The database that should be used for storing\n information about migrations (Neo4j EE). If\n not specified, then the database that should\n be migrated is used. [env var:\n NEO4J_MIGRATIONS_SCHEMA_DATABASE]\n --database TEXT The database that should be migrated (Neo4j\n EE) [env var: NEO4J_MIGRATIONS_DATABASE]\n --install-completion [bash|zsh|fish|powershell|pwsh]\n Install completion for the specified shell.\n --show-completion [bash|zsh|fish|powershell|pwsh]\n Show completion for the specified shell, to\n copy it or customize the installation.\n --help Show this message and exit.\n\nCommands:\n analyze Analyze migrations, find pending and missed.\n migrate Retrieves all pending migrations, verify and applies them.\n```\n\nSo, to apply migrations, just run the command:\n\n`python3 -m neo4j_python_migrations --username neo4j --password test --path ./migrations migrate`\n\n_Note: it is more secure to store the password in the environment variable NEO4J_MIGRATIONS_PASS._\n\n### Python Code\nYou can apply migrations directly into your application:\n\n```\nfrom pathlib import Path\n\nfrom neo4j import GraphDatabase\n\nfrom neo4j_python_migrations.executor import Executor\n\nwith GraphDatabase.driver(\"neo4j://localhost:7687\", auth=(\"neo4j\", \"test\")) as driver:\n executor = Executor(driver, migrations_path=Path(\"./migrations\"))\n executor.migrate()\n```\nAvailable methods: `migrate`, `analyze`. \n\n# How migrations are tracked\nInformation about the applied migrations is stored in the database using the schema\ndescribed in [Michael's README](https://michael-simons.github.io/neo4j-migrations/current/#concepts_chain).\n\nSupported migration types: \u0421YPHER, PYTHON. Other types of migrations, such as JAVA, are not supported.\n\nNote: the `project` option are incompatible with this schema. \nWhen using the option, each migration nodes will have an additional property named `project`.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A database migration tool for Neo4j that allows to apply Cypher-based and arbitrary Python-based migrations.",
"version": "0.1.1",
"split_keywords": [
"neo4j",
"migrations",
"python",
"migrator"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "62f53a8dc8200e71206d344e656f734a",
"sha256": "39015a912f4eb8ad2d55244de9a3b55ac6dc31b5fe173959f75c807d6df30225"
},
"downloads": -1,
"filename": "neo4j_python_migrations-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62f53a8dc8200e71206d344e656f734a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 12284,
"upload_time": "2022-11-30T10:48:47",
"upload_time_iso_8601": "2022-11-30T10:48:47.201065Z",
"url": "https://files.pythonhosted.org/packages/22/96/017e39a15b759acfb3d51bf047f0aa115e4d1a0c616bcfe1470f6b0f1a56/neo4j_python_migrations-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "10f609b607539f325eeb3fd006896bfb",
"sha256": "1302d56990ce1eaea23826e3c51c197d81e1d7ab4d54675aa808aeb7d748261c"
},
"downloads": -1,
"filename": "neo4j-python-migrations-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "10f609b607539f325eeb3fd006896bfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 12054,
"upload_time": "2022-11-30T10:48:45",
"upload_time_iso_8601": "2022-11-30T10:48:45.318175Z",
"url": "https://files.pythonhosted.org/packages/ec/79/d041e7cd414fa186603ff9d56424ebdeb14bb2f4005d5197afcedecd7502/neo4j-python-migrations-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-30 10:48:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "booqoffsky",
"github_project": "neo4j-python-migrations",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "neo4j-python-migrations"
}
JSON
