5.2. Single-instance upgrade

This section describes how to upgrade a single Neo4j instance.

To upgrade a Neo4j HA cluster (Neo4j Enterprise Edition), a very specific procedure must be followed. Please see Section 5.4, “Upgrade a Neo4j HA cluster”.

5.2.1. Upgrade from 2.x

  1. If the database is running, shut it down cleanly.
  2. Make a backup copy of the database directory.

    If using the online backup tool, available with Neo4j Enterprise Edition, ensure that backups have completed successfully.

  3. Install Neo4j 3.3.1.
  4. Review the settings in the configuration files of the previous installation and transfer any custom settings to the 3.3.1 installation:

    • Since many settings have been changed between Neo4j 2.x and 3.3.1, 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.3.1.

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

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

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

The Cypher language may evolve between Neo4j versions. For backward compatibility, Neo4j provides directives which enable you to explicitly select a previous Cypher language version. This is possible to do globally or for individual statements, as described in the Neo4j Developer Manual.

5.2.2. Upgrade from 3.x

  1. If the database is running, shut it down cleanly.
  2. Make a backup copy of the database directory.

    If using the online backup tool, available with Neo4j Enterprise Edition, ensure that backups have completed successfully.

  3. Install Neo4j 3.3.1.
  4. Review the settings in the configuration files of the previous installation and transfer any custom settings to the 3.3.1 installation.
  5. If using the default data directory, copy it from the old installation to the new. If databases are stored in a custom location, configure dbms.directories.data for the new installation to point to this custom location.
  6. If the database is not called graph.db, set dbms.active_database in neo4j.conf to the name of the database.
  7. Set dbms.allow_upgrade=true in neo4j.conf of the 3.3.1 installation. Neo4j will fail to start without this configuration.
  8. Start up Neo4j 3.3.1. The database upgrade will take place during startup.
  9. For information about the upgrade and a progress indicator, these are logged into debug.log.
  10. When upgrade has finished, the dbms.allow_upgrade should be set to false or be removed.
  11. It is good practice to make a full backup immediately after the upgrade.

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