10.1. Plan your upgrade

This section describes how to prepare for upgrading your Neo4j deployment.

It covers the following topics:

10.1.1. Important information

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

10.1.1.1. Understanding upgrades and migration

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

Upgrade

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.3 to 4.0.4.
  • Between minor versions, for example from 4.0.4 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.
Migration

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.7.

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, see Neo4j Migration Guide.

10.1.1.2. Supported upgrade paths

The following upgrade paths are supported:

  • From one version to the next adjacent version, for example 4.0.0 to 4.0.1.
  • From one version to a non-adjacent release, for example, from 4.0.1 to 4.0.3, or from 4.0.2 to 4.1.0.

10.1.1.3. 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.1.
  • 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.

10.1.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.

10.1.2.1. 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 your databases by using neo4j-admin dump and store it in a safe location.
  • (Optional/Recommended) If using custom plugins, make sure that you have the plugins in an accessible location.

10.1.2.2. Prepare a new neo4j.conf file

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.data and dbms.default_database.
  • In cluster installations, pay attention to cluster-specific configuration settings, which might be different for the different cluster members.

10.1.2.3. 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 Section 10.2, “Upgrade a single instance” or Section 10.3, “Upgrade a Causal Cluster”.

10.1.2.4. 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.