Prepare for your migration

Major versions introduce significant improvements and are not compatible with previous MAJOR versions. Systems that interact with the database will probably need updating. And downtime is always necessary.

Review changes

Start by reviewing the new features, fixes, and breaking changes. As you do, make a list of your external systems that connect to Neo4j that will need updating. In particular,

The Release Notes describe what’s been introduced or changed in the new version.
The Breaking changes page is a consolidated list of all breaking changes between Neo4j v4.x and Neo4j v5.x.
See Cypher Manual → Deprecations, additions and compatibility for changes in the Cypher language.

Downtime

Migrating databases between versions of Neo4j always requires downtime. Although it is possible to leave the old versions online in read-only mode.

Since every case is different, it is recommended that you prepare an environment in which you can test the migration process. This will give you more accurate timings than you can estimate and an idea of what to expect in terms of duration for the process.

The time to migrate a database will depend on the size of the database because each database must be backed up and restored. There’re no file format changes between v4.4 and v5 that require lengthy transformations operations.

Disk space considerations

To migrate a database you must create a backup (or dump-file for Community Edition). The backup/dump-file will require the same amount of disk space as the database it is created from. For this reason, you should reserve at least the size of the database directory in free space before you begin.

Prepare indexes

In Neo4j v5, BTREE indexes are replaced by RANGE, POINT, and TEXT indexes. Before migrating a database, in Neo4j v4.4, you should create a matching RANGE, POINT, or TEXT index for each BTREE index (or index-backed constraint). This allows the new indexes to be populated by Neo4j v4.4 before migration, and avoids any performance impairment when Neo4j v5 drops the BTREE indexes.

During database migration, it is possible to force Neo4j v5 to drop all BTREE indexes and replace them with RANGE indexes using the option --force-btree-indexes-to-range of the neo4j-admin database migrate command. However, this is not advised because RANGE indexes are not always the optimal replacement, and performance will be impaired on start-up while the new indexes are populated.

You can run SHOW INDEXES on your Neo4j v4.4 database to display its indexes. For each index or index-backed constraint, create an additional index or constraint of type RANGE, POINT or TEXT - see below for choosing a replacement.

An example of how to create a RANGE index:

CREATE RANGE INDEX range_index_name FOR (n:Label) ON (n.prop1)

An example of how to create a constraint backed by a RANGE index:

CREATE CONSTRAINT constraint_with_provider FOR (n:Label) REQUIRE (n.prop1) IS UNIQUE OPTIONS {indexProvider: 'range-1.0'}

For more information about creating indexes, see Cypher Manual → Creating indexes.

Choosing a replacement index

In most cases, RANGE indexes can replace BTREE. However, there might be occasions when a different index type is more suitable, such as:

Use POINT indexes if the property value type is point and distance or bounding box queries are used for the property.
Use TEXT indexes if the property value type is text and the values can be larger than 8Kb.
Use TEXT indexes if the property value type is text and CONTAINS and ENDS WITH are used in queries for the property.

It is possible to have multiple indexes of different index types on the property.

Application code

Depending on how your application interacts with Neo4j, you should be prepared to review your application code. All breaking changes that may affect your application and Neo4j can be found in Breaking changes between Neo4j v4.4 and Neo4j v5.x.

Drivers

Neo4j v4.4 drivers are forward compatible with Neo4j v5, and the Neo4j v5 drivers are backward compatible with Neo4j v4.4. This means that you can migrate your app using your existing drivers to a Neo4j v5 first, and then upgrade your drivers or vice versa. Note that you can access new Neo4j v5 database features only if you are using the latest Neo4j v5 drivers.

Autonomous cluster vs Causal cluster

Neo4j’s clustering has been significantly improved in v5, and the old causal clusters are no longer supported. If you are configuring a cluster, please read the clustering chapter in the Operations Manual to familiarise yourself with the new concepts: Operations Manual → Clustering.

Plugins (including custom plugins)

Take note of the plugins you are using and make sure they are compatible with Neo4j v5.x. If you have developed any custom plugins, you should review them as you would your application code.

If you are using Neo4j Bloom or Graph Data Science, you can find the most recent versions of these products in the Neo4j Download Center.

If you are using APOC, see the APOC Migration Guide for guidance.

Other 3rd-party software and tools

Be mindful of any other 3rd-party software and tools you are using alongside Neo4j. Maybe you have leveraged operational scripts to install, manage, backup, or monitor your Neo4j deployment. You might also have set alarms and built complete monitoring dashboards. You need to revise these as there have been changes in the Neo4j Admin tool, backup and restore, clustering, configurations, etc. Therefore, it is recommended to review all scripts/tools/3rd-party software and ensure they are prepared and compatible with Neo4j v5.x.

Was this page helpful?