As we continue to evolve the Neo4j GraphQL Library, we’re excited to share our roadmap for the upcoming major releases. This post outlines our plans for versions 5, 6, and 7, helping you prepare for these transitions and understand the support timeline for each version.
Why now? We’re happy to announce that, in the first half of 2025, we will launch a managed GraphQL service into Neo4j Aura. This will be built on the Neo4j GraphQL Library, and we want to ensure that we can provide a cream-of-the-crop GraphQL API as part of this offering. These major releases and breaking changes will form the foundation on which we will build new features in 2025 and beyond.
Version 5 Moves to LTS
At the end of October 2024, Version 5 of the Neo4j GraphQL Library will transition to Long-Term Support (LTS) status. This version will continue to receive critical updates and security patches until Nov. 30, 2025, aligning with Neo4j 4’s end-of-support date. If you’re currently running Neo4j 4.x, Version 5 of the library will remain your stable, production-ready choice during this period.
The OGM
At the end of October 2024, Version 5 of the OGM (@neo4j/graphql-ogm) will also transition to LTS status. This version will also continue to receive critical updates and security patches until Nov. 30, 2025.
However, after October 2024, the OGM will no longer be in active development and will not be released alongside versions 6 and 7 of the Neo4j GraphQL Library. This break will allow the team to focus on the quality and production-readiness of the Neo4j GraphQL Library as we move quickly through these major releases and into our managed GraphQL service in Neo4j Aura in the first half of 2025.
In summary, if you wish to continue using the OGM, Version 5 of the library and the OGM will continue to be your choice during this period.
Version 6: A Transitional Step
Version 6 is scheduled for release at the end of October 2024. This release brings several important changes that modernize the library and streamline its features. Notably, Version 6 acts as a transitional step for the breaking changes we wish to make between versions 5 and 7, allowing your GraphQL clients to have a smooth migration to the newest API.
Key Changes
Platform requirements:
- Neo4j 5.x is now required
- Node.js 20 or greater is required
Subscription updates:
- Change Data Capture (CDC) becomes the standard engine for subscriptions
- Removed support for relationship subscriptions as these are not supported by CDC
- Simplified configuration of subscriptions
Breaking changes:
- Removed deprecated aggregation filters
- Removed deprecated non-suffixed relationship filters
- Removed deprecated bookmark fields
- Removed deprecated _NOT filters
- Removed deprecated input fields for nested mutations
Migration
A full migration guide will be published in the documentation, but you can find some of the necessary migration steps below.
Updated negation filter syntax:
# Old syntax
query {
movies(where: { title_NOT: "The Matrix" }) {
title
}
}
# New syntax
query {
movies(where: { NOT: { title: "The Matrix" } }) {
title
}
}Nested operations in mutations:
# Old syntax
mutation {
updatePeople(create: { movies: { node: { title: "The Matrix" } } }) {
people {
name
}
}
}
# New syntax
mutation {
updatePeople(update: { movies: { create: { node: { title: "The Matrix" } } } }) {
people {
name
}
}
}
Looking Ahead: Version 7
In early 2025, Version 7 will represent our next major step forward. While specifics will be announced closer to release, below is a taste of one of the plans we have in the pipeline:
# Old syntax (_EQ being introduced in Version 6)
query {
movies(where: { title_EQ: "The Matrix" }) {
title
}
}
# New syntax
query {
movies(where: { title: { eq: "The Matrix" } }) {
title
}
}
While the above might seem like a minor change, it allows us to generate a much more generic schema, and when also applied to mutation inputs, will massively reduce schema size to improve server startup and query time.
Support Timeline
- Version 5 (LTS): Support until Nov. 30, 2025
- Version 6: Active development from October 2024; support dropped upon release of Version 7
- Version 7: Planned for early 2025, with continued active development and support until the eventual release of Version 8, which will primarily be removing leftover deprecation notices from the migration
Getting Ready
Stay tuned for more detailed migration guides and documentation updates as we approach these releases. We’re committed to making these transitions as smooth as possible for our community. With that in mind, now is a great time to begin planning for the upgrades ahead.
After a Smooth Migration
If a smooth migration for GraphQL clients is important to you, we recommend using Version 6 as a stepping stone between versions 5 and 7:
- Ensure that your clients have acted on the existing deprecation warnings in Version 5.
- Test and deploy your API using Version 6 of the Neo4j GraphQL Library.
- Ensure that you keep Version 6 up to date with minor and patch updates, and that your clients act on the deprecation warnings as they are added to the Version 6 API.
- Watch our GitHub repository for information about Version 7, as well as pre-releases with which you can begin testing.
- Test and deploy your API using Version 7 of the Neo4j GraphQL Library.
Tolerant to a Breaking Upgrade?
If you’re able to tolerate a breaking upgrade (say, if you own the full stack of your application and can deploy everything in tandem), we recommend skipping Version 6 and jumping straight to Version 7 when it’s released.
Neo4j GraphQL Library: Our Roadmap for 2024–2025 was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.
