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 4.x and Neo4j 5.x.

  • See Cypher® Manual → Deprecations, additions and compatibility for changes in the Cypher language.

  • Enterprise Edition Starting from 5.23, block format is the recommended format for Enterprise Edition due to its superior performance and scalability. It uses advanced data structures and inlining techniques to enhance data locality, which leads to better resource utilization. Therefore, it is highly-recommended that Enterprise Edition users migrate all databases to block format at their earliest convenience to ensure the best possible performance. block format is the default format for new databases created in 5.23 and later, and is the default format for all databases in 5.26 and later. For more information, see Operations Manual → Store formats → Changing the store format of existing databases.

  • standard and high_limit formats are deprecated in 5.23 and will be removed in a future release. For more information, see Operations Manual → Store formats → Format deprecations.

  • Starting from Neo4j 5.26 LTS, deploying the database on the following operating systems is deprecated but remains supported with the 5.26.x LTS releases:

    • MacOs 11, 12

    • Windows Desktop 10

    • Amazon Linux 2022 AMI

    • Unbuntu Server 16.04, 18.04, 20.04

    • Windows Server 2016, 2019

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 4.4 and 5 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 5, BTREE indexes are replaced by RANGE, POINT, and TEXT indexes. It is good to create a matching RANGE, POINT, or TEXT index for each BTREE index and index-backed constraint and populate them in Neo4j 4.4 before migration. This helps to avoid any performance impairment when Neo4j 5 drops the BTREE indexes during the migration.

Do not remove the old BTREE indexes. They must co-exist with the newly created ones in Neo4j 4.4, as the new indexes cannot be used by your 4.4 installation. The old indexes will be dropped automatically during the migration.

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.

Creating an index

You can run SHOW INDEXES on your Neo4j 4.4 database to display its indexes. For each index and index-backed constraint, create an additional index or constraint of type RANGE, POINT or TEXT.

The following code block shows 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'}

During database migration, it is possible to force Neo4j 5 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.

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

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 4.4 and Neo4j 5.x.

Drivers

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

Clustering in Neo4j 5.x

Neo4j’s clustering has been significantly improved in 5.x series, and the old causal clusters are no longer supported. The new clustering infrastructure decouples servers from databases, improving scalability and cloud-readiness. To familiarise yourself with the new concepts, read Operations Manual → Introduction to clustering.

In Neo4j version 5.23, the discovery service v1 was deprecated, and the discovery service v2 was introduced. In the 2025.01 release, discovery service v1 is removed. Therefore, transitioning from v1 to v2 is strongly recommended and must be completed before upgrading to Neo4j 2025.01. For more details, please refer to the Operations Manual → Moving from discovery service v1 to v2.

Plugins (including custom plugins)

Take note of the plugins you are using and make sure they are compatible with Neo4j 5.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 Deployment 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 5.x.