seankilleen / neo4j-migrations

Automated script runner aka "Migrations" for Neo4j. Inspired by Flyway.

Neo4j-Migrations

Neo4j-Migrations is a database migration and refactoring tool that allows running Cypher scripts and programmatic refactorings in a controlled and repeatable fashion against one or more Neo4j database.

Neo4j-Migrations is a proud member of the Neo4j-Labs and maintained by authors of the Neo4j-Drivers- and SDN/OGM team.

Introduction

Neo4j-Migrations are a set of tools to make your schema migrations as easy as possible. They provide a uniform way for applications, the command line and build tools alike to track, manage and apply changes to your database, in short: to refactor your database. The project is inspired to a large extend by FlywayDB, which is an awesome tool for migration of relational databases. Most things evolve around Cypher scripts, however the Core API of Neo4j-Migrations allows defining Java classes as migrations as well.

Neo4j-Migrations builds directly on top of the official Neo4j Java driver, supports Neo4j from 3.5 up to 4.4, including enterprise features such as multidatabase support and impersonation. The only dependencies are said driver and ClassGraph, the latter being used to find migrations on the classpath.

The history of migrations applied is stored as a subgraph in your database.

The graph will look like this:

Downloads

Binary downloads for the CLI are available on our release page for each version. Maven artifacts are available on central under the following coordinates:

• Core API: eu.michael-simons.neo4j:neo4j-migrations:1.8.3

• Spring-Boot-Starter: eu.michael-simons.neo4j:neo4j-migrations-spring-boot-starter:1.8.3

• Quarkus extension: eu.michael-simons.neo4j:neo4j-migrations-quarkus:1.8.3

• Maven-Plugin: eu.michael-simons.neo4j:neo4j-migrations-maven-plugin:1.8.3

The quickest way to use the CLI is JBang. With JBang installed, just enter jbang neo4j-migrations@neo4j --help to get started. Other options include Homebrew and Zip bundles. Please checkout the full list of download options.

Compatibility

Neo4j-Migrations can be used against Neo4j 3.5 and all Neo4j 4.x versions upto 4.4, including Neo4j-Aura.

The Core API and the JVM based version of the CLI module of Neo4j-Migrations requires at least Java 8 to run. Native binaries are provided for 64bit versions of macOS, Linux and Windows. The native binaries don’t require a JVM to be installed.

All releases of Neo4j-Migrations are compiled with JDK 17 while targeting JDK 8. Thus, we ensure both source, target and API compatibility with JDK 8. In addition, the Core API is provided as a Multi-Release-Jar, providing a module-info.java for JDK 11 and higher, making it a good citizen on the Java module path.

For JDK 17 and higher we do restrict the usage of some interfaces and have better boundaries for you what you can safely implement and what you should not.

While the CLI module actually does not require a JVM installed (it is a native binary, available for a Linux, macOS and Windows alike), some people might prefer a solution native to their ecosystem. The following projects serve the same purpose as Neo4j-Migrations and use the same graph, checksumming and versioning scheme as this project:

• Morpheus, written in TypeScript and published as NPM package, by @marianozunino

If you want to be listed here too, please reach out and we can collaborate to ensure compatibility.

Manual

The complete manual is available here: michael-simons.github.io/neo4j-migrations. The API documentation for the core module is available here: Neo4j Migrations (Core) 1.8.3 API.