Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/michael-simons/neo4j-migrations

Automated script runner aka "Migrations" for Neo4j. Inspired by Flyway.
https://github.com/michael-simons/neo4j-migrations

database database-migrations database-refactoring graph neo4j versioning

Last synced: 5 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
= Neo4j-Migrations

Michael Simons 

:doctype: article

:lang: en

:listing-caption: Listing

:source-highlighter: coderay

:icons: font

// tag::properties[]

:fullVersion: 2.15.1

:groupId: eu.michael-simons.neo4j

:artifactIdMavenPlugin: neo4j-migrations-maven-plugin

:artifactIdSpringBoot: neo4j-migrations-spring-boot-starter

:artifactIdQuarkus: neo4j-migrations-quarkus

:artifactIdCore: neo4j-migrations

:artifactIdFormatAdoc: neo4j-migrations-formats-adoc

:artifactIdFormatMarkdown: neo4j-migrations-formats-markdown

:branch: main

:url-apidocs: https://michael-simons.github.io/neo4j-migrations/main/site

:url-projectinfo: https://michael-simons.github.io/neo4j-migrations/main/site

:url-gh-releases: https://github.com/michael-simons/neo4j-migrations/releases

// end::properties[]



[abstract]

--

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 https://neo4j.com/labs/[Neo4j-Labs] and maintained by authors of the Neo4j-Drivers- and SDN/OGM team.

--



image:https://github.com/michael-simons/neo4j-migrations/workflows/build/badge.svg[link=https://github.com/michael-simons/neo4j-migrations/actions] 

image:https://sonarcloud.io/api/project_badges/measure?project=eu.michael-simons.neo4j%3Aneo4j-migrations-parent&metric=coverage[link=https://sonarcloud.io/summary/new_code?id=eu.michael-simons.neo4j%3Aneo4j-migrations-parent]

image:https://sonarcloud.io/api/project_badges/measure?project=eu.michael-simons.neo4j%3Aneo4j-migrations-parent&metric=alert_status[link=https://sonarcloud.io/dashboard?id=eu.michael-simons.neo4j%3Aneo4j-migrations-parent]

image:https://maven-badges.herokuapp.com/maven-central/eu.michael-simons.neo4j/neo4j-migrations/badge.svg[link=https://maven-badges.herokuapp.com/maven-central/eu.michael-simons.neo4j/neo4j-migrations]



== Introduction



// tag::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 extent by https://flywaydb.org[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 https://github.com/neo4j/neo4j-java-driver[Neo4j Java driver], supports Neo4j 3.5, Neo4j 4.1 to 4.4 and Neo4j 5, including enterprise features such as multidatabase support and impersonation.



The only dependencies are said driver and https://github.com/classgraph/classgraph[ClassGraph], the latter being used to find migrations on the classpath.



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

// end::introduction[]



The graph will look like this:



image::docs/modules/ROOT/images/chain-of-migrations.png[]



== Downloads



Binary downloads for the CLI are available on our https://github.com/michael-simons/neo4j-migrations/releases[release page]

for each version. Maven artifacts are available on https://search.maven.org/artifact/eu.michael-simons.neo4j/neo4j-migrations[central] under

the following coordinates:



* Core API: `{groupId}:{artifactIdCore}:{fullVersion}`

* Spring-Boot-Starter: `{groupId}:{artifactIdSpringBoot}:{fullVersion}`

* Quarkus extension: `{groupId}:{artifactIdQuarkus}:{fullVersion}`

* Maven-Plugin: `{groupId}:{artifactIdMavenPlugin}:{fullVersion}`



The quickest way to use the CLI is https://www.jbang.dev[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 https://michael-simons.github.io/neo4j-migrations/current/#download[download options].



== Compatibility



Neo4j-Migrations can be used against Neo4j 3.5, all Neo4j 4 versions from 4.1 up to 4.4 and Neo4j 5, including all current Neo4j-Aura versions.



NOTE: Neo4j 4.0 is only partially supported since version 2.0 due to the fact that Neo4j Java Driver does not support it fully anymore since 5.x. If you need to use this library with Neo4j 4.0 (which you shouldn't, because 4.0 is out of support anyway), look at the latest 1.x version of Neo4j-Migrations. *This does not affect new versions of the 4.x series, such as Neo4j 4.4, which is fully supported by this project!*



// tag::compatibility[]

The Core API and the JVM based version of the CLI module of Neo4j-Migrations requires at least Java 17 or higher since version 2.0.

Neo4j-Migrations can safely be used on both the class- and module-path.

Native binaries are provided for 64bit versions of macOS, Linux and Windows. The native binaries don't require a JVM to be installed.



For a version compatible with JDK 8, check the 1.x releases. We still do maintain the latest minor, including support for older versions of Spring Boot (prio to Spring Boot 3). These are also the versions you should be using against Neo4j 4.0.



The older releases of Neo4j-Migrations are compiled with JDK 17 while targeting JDK 8.

The Core API is provided as a Multi-Release-Jar in the older releases, providing a `module-info.java` for JDK 11 and higher, making it a good citizen on the Java module path as well.

// end::compatibility[]



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, check-summing and versioning scheme as this project:



* https://github.com/marianozunino/morpheus[Morpheus], written in TypeScript and published as NPM package, by https://github.com/marianozunino[@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: https://michael-simons.github.io/neo4j-migrations[michael-simons.github.io/neo4j-migrations].

The API documentation for the core module is available here: https://michael-simons.github.io/neo4j-migrations/main/site/neo4j-migrations/apidocs/index.html[Neo4j Migrations (Core) {fullVersion} API]. The comprehensive set of system diagrams including https://sourcespy.com/github/michaelsimonsneo4jmigrations/[build, module and class diagrams] is automatically generated weekly.



== Presentations and features



We try to promote this project as good as we can internally and externally while trying not to be too obtrusive. If you think it's a good idea to talk about it at your conference, just ask. Happy to answer CfPs. We are grateful about the coverage, presentations and features so far:



* https://www.infoq.com/news/2021/12/neo4j-migrations/[InfoQ: Migrating Neo4j Graph Schemas with Neo4j Migrations (2021-12-28)] by https://www.infoq.com/profile/Johan-Janssen/[Johan Janssen]

* https://jreleaser.org/guide/latest/index.html#_who_is_using_it[JReleaser: Who is using it] by https://twitter.com/aalmiray[Andres Almiray]

* https://speakerdeck.com/michaelsimons/neo4j-migrations-the-lean-way-of-applying-database-refactorings-to-neo4j-efa52ac1-85e1-4688-97f3-566fc78de6cd[Nodes 22: Neo4j-Migrations - The lean way of refactoring Neo4j content] by https://twitter.com/rotnroll666[Michael Simons] (https://github.com/michael-simons/nodes2022[Demo repository] and the https://www.youtube.com/watch?v=5-j0xiVAeoM[recording of the presentation])

* The first major upgrade, Neo4j-Migrations 2.0.0 was included in the https://github.blog/2023-02-08-release-radar-dec-2022-jan-2023/[GitHub Release Radar, Festive Edition ยท December 2022 โ€“ January 2023]



== CLI in a nutshell



image::docs/modules/ROOT/images/cli-demo.gif[]



== Contributors



++++



  

    

      Adam Cowley
Adam Cowley
๐Ÿš‡

      Ali Ince
Ali Ince
๐Ÿ› ๐Ÿ““

      Amit Kumar Yadav
Amit Kumar Yadav
๐Ÿ““ ๐Ÿค”

      Andres Almiray
Andres Almiray
๐Ÿ’ป ๐Ÿ”Œ ๐Ÿค” ๐Ÿง‘โ€๐Ÿซ

      Corneil du Plessis
Corneil du Plessis
๐Ÿ›

      David Giliotti
David Giliotti
๐Ÿค”

      Florent Biville
Florent Biville
๐Ÿค”

    

    

      Frederik Hahne
Frederik Hahne
๐Ÿค”

      Gerrit Meier
Gerrit Meier
๐Ÿ’ป ๐Ÿ“–

      Guillaume Grossetie
Guillaume Grossetie
๐Ÿ’ป ๐Ÿ“–

      Guy Keller
Guy Keller
๐Ÿ”ฌ

      Hosch250
Hosch250
๐Ÿ““ ๐Ÿ›

      Israel Bethencourt
Israel Bethencourt
๐Ÿค”

      Jan ลฝรกk
Jan ลฝรกk
๐Ÿค”

    

    

      Kasper
Kasper
๐Ÿค”

      Kateryna Dovhalets
Kateryna Dovhalets
๐Ÿ’ป

      Mariano Zunino
Mariano Zunino
๐Ÿค”

      Matt Souza
Matt Souza
๐Ÿค” ๐Ÿ’ป

      Maurizio Casciano
Maurizio Casciano
๐Ÿค” ๐Ÿ›

      Michael Simons
Michael Simons
๐Ÿ’ป ๐Ÿ“– ๐Ÿšง ๐Ÿ“ข

      Peter Vavra
Peter Vavra
๐Ÿ› ๐Ÿค”

    

    

      Raf23
Raf23
๐Ÿ›

      Roberto Cortez
Roberto Cortez
๐Ÿง‘โ€๐Ÿซ

      Robsdedude
Robsdedude
๐Ÿ”ฌ ๐Ÿ‘€

      SALES
SALES
๐Ÿค”

      Sascha Peukert
Sascha Peukert
๐Ÿ““

      Sean Killeen
Sean Killeen
๐Ÿ“–

      Sergei Egorov
Sergei Egorov
๐Ÿ‘€

    

    

      Sergey
Sergey
๐Ÿค”

      alexanoid
alexanoid
๐Ÿ›

      ctytgat
ctytgat
๐Ÿ›

      dana canzano
dana canzano
๐Ÿ““ ๐Ÿ›

      injectives
injectives
๐Ÿ’ป ๐Ÿ““

      shanon84
shanon84
๐Ÿ’ป ๐Ÿ›

      szabopeter
szabopeter
๐Ÿ“–

    

    

      ttemple06
ttemple06
๐Ÿค”

    

  



++++