5.2. Upgrade a single instance

This section describes how to upgrade a single Neo4j instance.

For instructions on upgrading a Neo4j Causal Cluster, see Section 5.3, “Upgrade a Neo4j Causal Cluster”. For instructions on upgrading a Neo4j HA cluster, see Section C.5, “Upgrade”.

5.2.1. Upgrade from 2.x

If you use Debian, refer to Section 2.2.1.2, “Upgrade”.

Pre-upgrade steps
Read Section 5.1, “Upgrade planning” thoroughly and perform all the steps listed there.
Shutdown and backup
  1. If the database is running, shut it down cleanly.
  2. If using offline backups, take a backup of Neo4j.

    If using the online backup tool, ensure that backups have completed successfully.

  3. Back up neo4j.conf.
Upgrade
  1. Install Neo4j 3.4.7.
  2. Review the settings in the configuration files of the previous installation and transfer any custom settings to the 3.4.7 installation:

    • Since many settings have been changed between Neo4j 2.x and 3.4.7, it is advisable to use the 2.x-config-migrator (available in the tools directory) to migrate the configuration files for you.

      For example, the 2.x-config-migrator can be invoked with a command like:

      java -jar 2.x-config-migrator.jar path/to/neo4j2.3 path/to/neo4j3.4.7.

    • Take note of any warnings printed, and manually review the edited configuration files produced.
  3. Use the following to import your data from the old installation:

    neo4j-admin import --mode=database --database=<database-name> --from=<source-directory>

  4. If the database is not called graph.db, set dbms.active_database in neo4j.conf to the name of the database.
  5. Set dbms.allow_upgrade=true in neo4j.conf of the 3.4.7 installation. Neo4j will fail to start without this configuration.
  6. Start up Neo4j 3.4.7. The database upgrade will take place during startup.
  7. For information about the upgrade and a progress indicator, these are logged into debug.log.
Post-upgrade steps
  1. When the upgrade has finished, dbms.allow_upgrade should be set to false or be removed.
  2. Restart the database.
  3. It is good practice to make a full backup immediately after the upgrade.

5.2.2. Upgrade from 3.x

Pre-upgrade steps
Read Section 5.1, “Upgrade planning” thoroughly and perform all the steps listed there.
Shutdown and backup
  1. If the database is running, shut it down cleanly.
  2. If using offline backups, take a backup of Neo4j.

    If using the online backup tool, ensure that backups have completed successfully.

  3. Back up neo4j.conf.
  4. If using native user and role management, back up the dbms directory (in a default configuration: data/dbms).
Upgrade
  1. Install Neo4j 3.4.7 using one of the following methods, specific to your technology:

    1. If using a tarball or zipfile for installation:

      1. Untar or unzip Neo4j 3.4.7.
      2. Transfer any custom settings to the 3.4.7 installation, as noted under the Apply configuration changes step in Section 5.1, “Upgrade planning”.
      3. Set dbms.allow_upgrade=true in neo4j.conf of the 3.4.7 installation. Neo4j will fail to start without this configuration.
      4. Copy the data directory from the old installation to the new one. This step is not applicable if you have dbms.directories.data pointing to a directory outside of NEO4J_HOME.
    2. If using a Debian or RPM distribution:

      1. Set dbms.allow_upgrade=true in neo4j.conf.
      2. Install Neo4j 3.4.7.
      3. When prompted, review the differences between the neo4j.conf files of the previous version and Neo4j 3.4.7. Transfer any custom settings to the 3.4.7 installation, as noted under the Apply configuration changes step in Section 5.1, “Upgrade planning”. Make sure to preserve dbms.allow_upgrade=true as set in the instruction above. Neo4j will fail to start without this configuration.
  2. Start up Neo4j 3.4.7. The database upgrade will take place during startup.
  3. For information about the upgrade and a progress indicator, these are logged into debug.log.
Post-upgrade steps
  1. When the upgrade has finished, dbms.allow_upgrade should be set to false or be removed.
  2. Restart the database.
  3. It is good practice to make a full backup immediately after the upgrade.