morpheus4j

Morpheus

Morpheus is a database migration tool for Neo4j written in Typescript.

Morpheus is a modern, open-source, database migration tool for Neo4j. It is designed to be a simple, intuitive tool for database migrations. It is inspired by Michael Simons tool for Java.

This project has been tested with Neo4j 4.4.4

Installation

Install the latest version of Morpheus:

npm install morpheus4j

Add a script to your project's package.json file:

"scripts": {
  "morpheus": "morpheus"
}

Usage

Create Migrations

You can create migrations using the morpheus command or manually.

For the first, just issue the command:

npm run morpheus create <migration_name>

Migrations will be created under the neo4j/migrations directory. Each migration will be a Cypher file with the name V1_0_0_<migration_name>.cypher.

Or you can create/add the migration manually as long as it follows the naming convention as stated in the Michael's tool.

Initial Configuration

To run migrations, you need to configure Morpheus. To do so, create a .morpheus.json file in your project root directory and create a neo4j/migrations directory as well.

Or, you can use the init command:

npm run morpheus init

If you don't want to use a morpheus.json file, you can also use ENV variables as follows:

NEO4J_SCHEME=neo4j
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=neo4j

Run Migrations

You can run migrations by running the following command:

npm run morpheus migrate

This will run all migrations in the neo4j/migrations directory.

How it works

The approach is simple. Morpheus will read all migrations in the neo4j/migrations directory and execute them in order.

For each migration, Morpheus will create a transaction and execute the migration. Thus a migration may contain multiple Cypher statements (each statement must end with ;).

Once a migration file is executed, Morpheus will keep track of the migration and will not execute em again.

Existing migration files that have already been executed can not be modified since they are stored in a database with their corresponding checksum (crc32).

If you want to revert a migration, create a new migration and revert the changes.

How does neo4j keep track of the migrations?

You can take a look at schema and explanation on Michael's README there's a neat graph that shows the migration chain.