Chapter 5. Upgrade

This section describes how to upgrade Neo4j from an earlier version.

5.1. Upgrade planning

Plan your upgrade by following the steps in this chapter.

Throughout this instruction, the directory used to store the Neo4j data is referred to as database directory. The path of the database directory is Data/databases/database name. There are two settings that may affect the location of the database directory.

The Data directory:

The database name:

  • The default database name is graph.db
  • A custom database name is configured by the parameter dbms.active_database.

5.1.1. Review supported upgrade paths

Before upgrading to a new major or minor release, the database must first be upgraded to the latest version within the relevant release. The latest version is available at this page: The following Neo4j upgrade paths are supported:

  • 2.0.latest → 3.1.2
  • 2.1.latest → 3.1.2
  • 2.2.latest → 3.1.2
  • 2.3.latest → 3.1.2
  • 3.0.any → 3.1.2

5.1.2. Review the Upgrade guide at

Read through the Upgrade guide at The Upgrade guide is being maintained by Neo4j Customer Support and contains valuable information about upgrade actions particular to this release.

5.1.3. Apply configuration changes

It happens that new configuration settings are introduced and that existing configurations are changed between versions. Any such changes are pointed out in the Upgrade guide mentioned above. Make sure that you have taken such changes into account.

5.1.4. Upgrade application code

As part of the upgrade planning, it is vital to test and potentially update the applications using Neo4j. How much development time required to update the code will depend on the particular application.

5.1.5. Upgrade custom plugins

Check the Plugins directory (see Section 3.1, “File locations”) to verify whether custom plugins are used in your deployment. Ensure that any plugins are compatible with Neo4j 3.1.2.

5.1.6. Plan disk space requirements

An upgrade requires substantial free disk space, as it makes an entire copy of the database. For the upgrade, make sure to make available an additional ( 50% * size_of(database directory) ). In addition to this, do not forget to reserve the disk space needed for the pre-upgrade backup.

The upgraded database may require slightly larger data files overall.

5.1.7. Perform a test upgrade

Based on the findings in this chapter, allocate a 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, as well as potential additional action points such as upgrade of plugins and application code.