Introduction

About this guide

Keeping your Neo4j deployment always up-to-date ensures that you are provided with the latest improvements in performance, security, and bug fixes.

Who should read this?

This upgrade and migration guide is written for experienced system administrators and operations engineers who want to upgrade or migrate Neo4j.

This page introduces some important Neo4j concepts before referring to the version-specific pages.

Preparation

Preparation is key to any successful upgrade or migration. Before making changes to a production DBMS, it is highly recommended to use a test environment to check:

The upgrade/migration process.
Compatibility with other systems.

Version numbers

Neo4j version numbers are in the pattern MAJOR.MINOR.PATCH.

MAJOR versions introduce significant architectural improvements and features. They are not compatible with previous MAJOR versions. Systems that interact with the database may require updating.
MINOR versions introduce improvements and new features. They are backward compatible with other MINOR versions of the MAJOR version.
PATCH versions fix critical bugs and security issues. They are backward compatible and replace previous releases of the same MAJOR.MINOR version.

Neo4j’s fully managed cloud service Neo4j Aura uses only MAJOR versioning and is always on the latest MINOR version.

Downtime, store formats, discovery service, and downgrades

Downtime

MAJOR version migrations require downtime.
MINOR and PATCH upgrades can be applied to a cluster without downtime.
Standalone servers require downtime to upgrade.

When you move to a new major version of Neo4j, you must migrate the databases from the old server to the new server. Servers are upgraded by updating their binaries and restarting.

Store format

Store format updates are optional unless you are moving to a version that removes support for your old store format. For more information on the available store formats per Neo4j version, see Operations Manual → Store formats.

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.

From 5.25 onwards, the block format supports token names (including node labels, property keys, and relationship type names) of any length up to the GQL identifier max length of 16,383 characters. Thus, token names must adhere to this length limit when migrating from aligned to block format. 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.

Discovery service

Neo4j provides several mechanisms for cluster members to discover each other and form a cluster based on the configuration and the environment in which the cluster is running, as well as the version of Neo4j being used.

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.

Downgrades

Neo4j does not support downgrades. If the upgrade or migration is not successful, you have to do a full rollback, including restoring a pre-upgrade or a pre-migration backup.

Continue reading

If you are already on Neo4j 5, or want to migrate your databases from 4.4 you can proceed to the Neo4j 5 section.

If you are upgrading to a version of Neo4j 4, read the Neo4j 4 section.