Recommended upgrade path from v4 to v5 of Neo4j using OGM

[markoivanovski]

Due to the fact that Neo4j v4 will be EOL next year, we're needing to upgrade from Neo4j v4 to v5. As we're currently using OGM, we have attempted to upgrade from OGM v3.3.2 to OGM v4.0.1 but we're experiencing the MissingIndexException mentioned here #921. We're unable to find any documentation about what the least painful upgrade path is from Neo4j v4 to v5 when using the OGM library, and would appreciate any assistance or links to relevant documentation.

Your Environment

• Java version: 17
• Neo4j version (The version of the database): 5
• OGM Version (The version of this software): 3.3.2
• OGM Transport used (One of Bolt, HTTP or embedded): Bolt
• Neo4j Java Driver version (in case of Bolt transport): 4.4.13
• Spring Data Neo4j: 5.3.9
• Link to your project:

[meistermeier]

There are a few things, I want to explain first to get the whole picture.
The symptom you are facing: As you have already read in the linked issue, the whole auto index feature got discarded from Neo4j-OGM starting with version 4. You might have been aware that OGM supports a wide range of Neo4j versions, and with this comes a wide range of syntaxes to create(maintain, remove) indexes. On the one hand we were pretty proud about this, on the other hand we never wanted to have schema control within OGM but this should be done by the DBA outside the application. We know that this is a convenient feature but besides already knowing that this complex part of the library will grow further, we did not want to give an application (developer) the easy possibility to screw with production indexes anymore ;)

Neo4j-OGM and Spring Data Neo4j:
We split up SDN from OGM back in 2019 with the release of Spring Data Neo4j 6. This is not only a new major version of the library but also a complete rewrite. There were various reasons that prevented us from using OGM as the backbone of Spring Data Neo4j (with Neo4j 4 coming out back then). We decided to keep both mapper libraries maintained but separated.

Migration paths:
If you are using Spring Data Neo4j with Spring Boot as the main Neo4j library for your application, I would advise you to upgrade to SDN/Spring Boot latest. Taking the indexing bit aside, it really depends on your application itself, how much work is required. Since we have seen a lot of very different approaches (also usage-wise), there is no one-size-fits-all migration. For a quick overview, we have a section in the SDN reference documentation about this: https://docs.spring.io/spring-data/neo4j/reference/appendix/migrating.html. This will also introduce changes to the behaviour of loading and updating entities.
If this sounds too much right now, we also have a fork of Spring Data Neo4j 5 that still uses Neo4j-OGM (in version 4.x) https://github.com/neo4j/neo4j-ogm-spring This is a version that is compatible with current Spring Boot (at the time of writing this 3.3.5)

I think this is all for now I can offer you. If there is anything unclear or if you have further questions, feel free to reach out.

(Also thanks for splitting this from the other issue, I had the tab open since Monday to also transfer your comment into a new issue)

[markoivanovski]

Hi @meistermeier - really appreciate the extensive background information and conclusion. We're trying to find the path of least resistance at the moment as the team doesn't have capacity for a significant refactor. Based on this, I wanted to double check the Spring Boot / Commons requirements for the neo4j-ogm-spring project as this was forked from SDN 5.3.9 (which we're currently using), but it mentions that it's compatible with the current Spring Boot (which we aren't using). We're in fact still on:

• Spring 5.3.7
• Spring Boot 2.5.0
• Spring Data Commons 2.5.1

Does this mean we would still need to upgrade Spring (and related frameworks) in order to use neo4j-ogm-spring?

Thanks again!

[meistermeier]

Yes, it would require the update. The idea behind this project is to have support for current versions of Spring (Boot) while keeping the Spring Data Neo4j/Neo4j-OGM combination compatible.
Taking a step back, your initial problem was regarding the unsupported index feature which surfaced through the missing MissingIndexException. Without the use of the autoindex feature, you could still use your combination with Neo4j 5. But there are some restrictions, I have found after running the test suite against the latest version of the database.

1. you cannot make use of any autogenerated exist statement. It just does not exist (no pun intended) anymore in Neo4j 5 Cypher syntax.
2. it is not possible to run auto-generated distance queries because also here the function name has changed.

If you could live with those constraints (no index feature, no exist statements, no point/distance statements), I see no reason why this should currently not work with Neo4j 5 judged from our test suite. As you might assume, I cannot tell you that Neo4j-OGM officially supports Neo4j 5 with all those restrictions, but technically it works.

After all I won't get tired to repeat that trying to upgrade your application from Spring Boot 2.5 is not only in regards of SDN/OGM a pretty good idea to get (security) updates and bugfixes. Your version is out of (open-source) support since 2.5 years(!): https://spring.io/projects/spring-boot#support

[michael-simons]

@markoivanovski We still push out bug fixes for 3.2.x, which is usable with the libs you lists above and the 5.3.9 original SDN.

See also

https://github.com/neo4j-drivers/java-ecosystem-compatibility/blob/main/data/v_neo4j_ogm_support_matrix.csv

The repository has more matrixes like that, check the readme.