23.4. Upgrading

This section describes upgrading a single Neo4j instance. To upgrade a Neo4j HA cluster (Neo4j Enterprise), a very specific procedure must be followed. Please see Section 25.5, “Upgrade of a Neo4j HA Cluster”.

Throughout this instruction, the files used to store the Neo4j data are referred to as database files. The location of these files is specified by configuring the org.neo4j.server.database.location variable in conf/neo4j-server.properties.

[Caution]Disk space requirements

An upgrade requires substantial free disk space, as it makes an entire copy of the database. The upgraded database may also require larger data files overall.

It is recommended to make available an extra 50% disk space on top of the existing database files.

In addition to this, don’t forget to reserve the disk space needed for the pre-upgrade backup.

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: http://neo4j.com/download/other-releases. The following Neo4j upgrade paths are supported:

  • 1.9.latest → 2.3.4
  • 2.0.latest → 2.3.4
  • 2.1.latest → 2.3.4
  • 2.2.latest → 2.3.4
  • 2.3.any → 2.3.4

Upgrade instructions

  1. Cleanly shut down the database if it is running.
  2. Make a backup copy of the database files. If using the online backup tool available with Neo4j Enterprise, ensure that backups have completed successfully.
  3. Install Neo4j 2.3.4.
  4. Review the parameter settings in the files under conf directory in the previous installation, and transfer any custom set parameters to the 2.3.4 installation. Be aware of parameters that have changed names between versions. Also, ensure that you configure the 2.3.4 installation to use the same database file directory as the previous installation.
  5. Set the Neo4j configuration parameter allow_store_upgrade=true in the conf/neo4j.properties file of the 2.3.4 installation. Neo4j will fail to start without this configuration.
  6. Start up Neo4j 2.3.4.
  7. The database upgrade will take place during startup.
  8. Information about the upgrade and a progress indicator are logged into the messages.log file inside the database file directory.
  9. When upgrade has finished, the allow_store_upgrade should be set to false or be removed.
  10. It is good practice to make a full backup immediately after the backup.
[Note]Cypher compatibility

The Cypher language may evolve between Neo4j versions. For backward compatibility, Neo4j provides directives which allow explicitly selecting a previous Cypher language version. This is possible to do globally or for individual statements, as described in the Cypher Compatibility section.