This section describes how to plan for an upgrade of Neo4j.
Plan your upgrade by following the steps in this chapter.
The following upgrade paths are supported:
The following steps are required if you need to upgrade from a version earlier than 3.3:
A Neo4j upgrade must be performed as an isolated operation. If you have other changes planned, such as switching from a single-instance installation to a Causal Cluster, you must action these separately.
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: http://neo4j.com/download/other-releases.
Review Release Notes.
To view the details of the changes that are included in each version, see the Release Notes.
Apply configuration changes.
dbms.active_database. In cluster installations, pay attention to cluster-specific configuration settings, which may be different on different cluster members.
Plan index upgrade.
Review Section 11.2, “Index configuration” and determine whether you have indexes that ought to be rebuilt in order to take advantage of performance improvements. Include the rebuilding of these indexes in your test upgrade.
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.
In particular, 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 Cypher Manual.
Upgrade custom plugins.
Check the plugins directory (see Section 4.2, “File locations”) to verify whether custom plugins are used in your deployment. Ensure that any plugins are compatible with Neo4j 3.5.12.
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), where the default database directory is located in: data/databases/graph.db). 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.
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.
Review the logs.
The neo4j.log file contains valuable information on how many steps the upgrade will involve and how far it has progressed. For large upgrades, it is a good idea to monitor this log continuously. Below is a sample of what the log may look like:
2018-09-18 13:24:23.243+0000 INFO Starting... 2018-09-18 13:24:24.262+0000 INFO Initiating metrics... 2018-09-18 13:24:24.488+0000 INFO Starting upgrade of database 2018-09-18 13:24:24.538+0000 INFO Migrating Indexes (1/5): 2018-09-18 13:24:24.542+0000 INFO 10% completed 2018-09-18 13:24:24.543+0000 INFO 20% completed 2018-09-18 13:24:24.543+0000 INFO 30% completed ... ... ... 2018-09-18 13:24:24.574+0000 INFO Migrating Counts store (5/5): 2018-09-18 13:24:24.574+0000 INFO 10% completed 2018-09-18 13:24:24.574+0000 INFO 20% completed 2018-09-18 13:24:24.575+0000 INFO 30% completed ... ... ... 2018-09-18 13:24:24.576+0000 INFO 100% completed 2018-09-18 13:24:24.584+0000 INFO Successfully finished upgrade of database
In addition to the steps outlined in this chapter, it is valuable to review the Upgrade guide at neo4j.com. The upgrade guide is maintained by Neo4j Customer Support, and contains valuable information about upgrade actions particular to this release.