Plan your upgrade

How to prepare for upgrading your Neo4j deployment.

1. Important information

Upgrading your Neo4j deployment ensures that you are provided with the latest improvements in performance, security, and bug fixes.

1.1. Understanding upgrades and migration

The following are methods of keeping your Neo4j deployment up-to-date:


The process of upgrading an existing Neo4j deployment (single or clustered) to a newer Neo4j version, when such process does not require changes to the configuration or to the applications that use Neo4j.

  • Between patches, for example, from 4.0.9 to 4.0.10.

  • Between minor versions, for example from 4.0.10 to 4.1.0.

What needs to be upgraded

  • The Neo4j product to a later version of Neo4j.

  • (Optional) The store formats (the file formats on disk, which usually auto-upgrade at server startup, but sometimes an older version may remain on a running server).

  • The system database schema, which restructures the contents of that database. This is done automatically on standalone server and in static cluster upgrades (where you temporarily set each server as standalone), but need to be run manually on rolling upgrades after the other two upgrades (product and stores) have been done.


The process of upgrading an existing Neo4j deployment (single or clustered) to a newer Neo4j version, when such process requires a review of the configuration(s) and the applications that use Neo4j.

  • Between major versions, for example, from 3.5.13 to 4.0.10.

What needs to be upgraded and migrated

  • The Neo4j product to a later major version of Neo4j.

  • Store formats - same as in upgrade.

  • The system database schema - same as in upgrade.

  • Configuration settings - the configuration changes from the newer version must be applied to the old configuration file.

  • Application code - the source code of your application(s) must be updated as per the new version in order to work properly.

  • Custom plugins - all custom plugins must be compatible with the new version of Neo4j.

For more information on the available supported paths, see Neo4j Migration Guide → Supported upgrade and migration paths.

1.2. Limitations

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

  • A Neo4j upgrade must be performed as an isolated operation. If you are planning to upgrade from a single-instance installation to a Causal Cluster, this must be performed separately from the upgrade to 4.2.

  • In order to further minimize risk, it is recommended that while upgrading, you do not switch from Community Edition to Enterprise Edition, change configuration, perform architectural restructuring, database administration, or similar tasks.

2. Upgrade checklist

The following upgrade checklist provides a high-level overview of the tasks you have to perform:

If you are upgrading a Causal Cluster, do the tasks for each member of the cluster.

2.1. Prerequisites

  1. Verify that you have installed Java 11.

  2. Review the improvements and fixes that have been carried out in the version that you want to upgrade to. See the Neo4j 4.2 Change log.

2.2. Back up your current deployment

It is recommended to perform and verify the following backups, to avoid losing data in case of a failure.

  • Back up neo4j.conf.

  • Back up all the files used for encryption, i.e., private key, public certificate, and the contents of the trusted and revoked directories. The locations of these are described in SSL framework.

  • Back up each of your databases, including the system database, by either using neo4j-admin backup (online) or neo4j-admin dump (offline), and store them in a safe location.

  • (Optional/Recommended) If using custom plugins, make sure that you have the plugins in an accessible location.

2.3. Prepare the new neo4j.conf file to be used by the new installation

Even though a Neo4j upgrade does not require changes to the configuration, you still have to prepare the new neo4j.conf file to be used by the new deployment.

  • Update the new neo4j.conf file with any non-default settings from your old installation.

  • When upgrading, it is particularly important to note any custom values of the settings dbms.directories.* and dbms.default_database.

  • In cluster installations, pay attention to cluster-specific configuration settings, which might be different for the different cluster members.

2.4. Perform a test upgrade

Based on the findings in this chapter, allocate a staging test environment for the upgrade and do a test upgrade. The test upgrade will give you valuable information about the time required for the production upgrade. Follow the steps as per your deployment type. For more information, see Upgrade a single instance or Upgrade a Causal Cluster.

2.5. Monitor the logs

The neo4j.log file contains information on how many steps the upgrade will involve and how far it has progressed. It is a good idea to monitor this log.

2.6. Update metrics

The metrics that are enabled by default have been changed in the 4.2 release.

Any specific metrics that you want to be enabled must be specified in the metrics.filter.

For more information, see Enable metrics logging.