Neo4j version upgrades

Upgrading the Neo4j version of your database in place

We recommend our customers to keep their database version updated. To simplify this operation, GrapheneDB offers a feature that allows you to upgrade your database in-place.

Before doing the actual version upgrade

  • the Neo4j driver you are using to connect to the database may not be compatible with the new version. You can read more here.
  • the new Neo4j version may have a specific bug that affects your application logic, such as a Cypher syntax issue or a specific issue with query results.
  • after upgrading to the new Neo4j version you may find out that the current version of the Neo4j driver does not support that version of Neo4j or it may by buggy.
  • the extensions you have installed on your database are not compatible with the new version.

Before moving forward with the final version upgrade of your production database, we recommend to do extensive testing to reduce the risks.

  • Learn about the new Neo4j version you plan to upgrade to and the changes the upgrade will introduce: Do you need to switch protocols or endpoints? Has the Cypher syntax changed?
  • Find out if your Neo4j driver supports that particular version. You may want to look at the issues in the repo or issue tracker to find out if other users have encountered problems.
  • Running tests in development: Upgrade your development environment, run your test suite, as well as manual tests.
  • Running tests in your QA environment: Upgrade your QA environment to the new version and verify that everything works correctly.
  • Final dry-run: Create a copy of your production using the clone from backup feature (to avoid downtime on your production environment), verify that the store migration worked correctly and make tests against the copy. This will also allow you to get a feeling for how long the process will take and the steps involved.



A Neo4j version upgrade cannot be reverted. Please, make sure all the extensions and stored procedures in use are compatible with the new version. Also, pleases ensure that you are using a compatible driver version.

Compatible drivers

One of the things to consider before upgrading Neo4j is that the driver that you're using is compatible. For Neo4j supported drivers there is a compatibility matrix for you to check if you need to also upgrade your driver:

Neo4j versionCompatible Driver versions
4.44.4, 4.3, 4.2, 4.1, 4.0
4.34.4, 4.3, 4.2, 4.1, 4.0
4.24.4, 4.3, 4.2, 4.1, 4.0
4.14.4, 4.3, 4.2, 4.1, 4.0
4.04.4, 4.3, 4.2, 4.1, 4.0
3.54.4, 4.3, 4.2, 4.1, 4.0, 1.7
3.41.7, 1.6
3.31.7, 1.6, 1.5, 1.4

Upgrading your Neo4j database

Please follow these steps to upgrade your version in-place:

  1. Please ensure your stack and code is compatible with the version that you’re going to upgrade to. Please read more here.

  2. Visit the Admin tab and click on the Update Neo4j plan button. You will get redirected to the Update Neo4j form.

  1. Choose the version you want to upgrade to. GrapheneDB will automatically propose the highest version your database can be updated. More info on upgrade versions here.

  2. Click on Upgrade Neo4j.


Regarding downtime

Please take into account that the operation involves database downtime. The downtime duration can vary depending on the size of your database and the time Neo4j needs to stop it. Please contact our support team if you have any questions about downtime.

There is no action required on your side. Database users, schema and connection settings are not going to change after the operation.

After the version upgrade, all your database extensions will be disabled to avoid version compatibility issues. Please, ensure your extensions are suitable for the new version or search for a compatible version before enabling them.

Supported upgrade paths

If you want to upgrade to a higher version that doesn’t have a supported upgrade path, you will need to run the operation more than one time.

For example if you want to jump from 3.1 to 4.1, you will need to:

  1. Upgrade to 3.1
  2. Upgrade to 3.5
  3. Upgrade to 4.0
  4. Upgrade to 4.1