Neo4j version upgrades

📘
Enterprise Databases
For version upgrades on Enterprise databases, please contact our support engineers. They will walk you through the process, schedule a suitable time window and perform the version upgrade.

Overview

In GrapheneDB, upgrading the Neo4j version is a self-service operation performed by the user. Using the clone feature, the original database is stopped and exported. A new database is provisioned with a version of the users' choice and data is copied over to the new database.

📘
Clone operation
The described procedure works by creating a new database from a copy of the original instance. After the operation is completed, the original database will continue to run. It is up the user to delete it when it is no longer needed. Any modifications to the original database after the clone process is started will not be reflected in the new database.

🚧
Downtime & risks
Please take into account that this operation involves downtime. More details below.

Downtime

After requests to the origin database are stopped, when the clone procedure is initiated, the Neo4j process is stopped, a new database is provisioned and data is copied over.

Database provisioning can take a few seconds for Hobby or Standard databases, and a few minutes for Performance or Enterprise databases. The amount of time it takes to copy over data will mainly depend on your dataset size (a clone operation for a 20GB dataset size will take significantly longer than the same for 500MB of data) . It can also be higher if you are cloning into a different AWS regions since data transfer will be slower.

Neo4j version upgrades will often imply store and/or index migrations. This is most often the case when upgrading through major versions and the amount of time it takes varies depending on the release version and if the are multiple versions ahead of the original one, i.e. upgrading from 2.3 to 3.2 will be generally slower than upgrading from 3.1 to 3.2.

After the clone process and the version upgrade is completed, the database will have different endpoints and a new database user will need to be created in order to connect from your code.

The overall downtime duration will vary depending on the size of your database, the time Neo4j needs to write to disk, any time spent doing the actual Neo4j store and/or index migrations (if any), and the time it takes to create a new user and update the code to point to the new instance and use the new credentials.

Before doing the actual version upgrade

Things can go wrong when doing version upgrades. Just to name a few of the issues you can encounter:

the Neo4j driver you are using to connect to the database may not be compatible with the new version
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

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.

Performing a version upgrade on a Neo4j database

🚧
Version upgrades can break your app
There are a number of things that can go wrong when performing a version upgrade on a Neo4j database, which may result in your app being broken. Before performing the actual upgrade of a Neo4j production database please read the section "Before doing the actual version upgrade" above.

To perform a Neo4j version upgrade for databases in any plan other than Enterprise, please follow these steps below.

Stop requests to the database. Any write request that hits the database after the clone process is started, will not be replicated on the destination database, potentially resulting in data loss.
Click on the Upgrade/Clone button
Select Clone by exporting.
Once completed, verify that the clone process went well and everything looks good.
Create a new user for the new database
Update the Neo4j endpoint and credentials in your code to point to the new database/user
Resume requests to the database, making sure to hit the new database only

Please contact our support team if you have any questions or issues.