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 the database directory. The default path of the database directory is: <neo4j-home>/data/databases/graph.db.

If you have a custom value for either the parameter or the dbms.active_database parameter, this will affect the location of the database directory.

5.1.1. Supported upgrade paths

The following Neo4j upgrade paths are supported:

  • 2.3.latest → 3.3.4
  • 3.0.latest → 3.3.4
  • 3.1.latest → 3.3.4
  • 3.2.latest → 3.3.4
  • 3.3.any → 3.3.4

5.1.2. Prepare to upgrade

  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:

  2. Review the Upgrade guide at

    The Upgrade guide is maintained by Neo4j Customer Support, and contains valuable information about upgrade actions particular to this release.

  3. Apply configuration changes.

    With each version, new configuration settings may be introduced and existing configurations may change. Any such changes are detailed in the Upgrade guide, as mentioned above. Please ensure that you have taken such changes into account.

  4. Plan index upgrade

    Neo4j version 3.3 introduces a new index provider for number values. The new index provider comes with significant performance improvements. Note that existing indexes are not automatically using the new provider. Existing indexes that are known to have numeric values must be manually dropped and recreated to take advantage of this feature. New indexes with numeric values will automatically use the new index provider.

  5. Upgrade application code.

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

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

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

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