Install and configure Neo4j 5

There are changes to how Neo4j is configured. This section discusses how to configure Neo4j 5 in the same way as your Neo4j 4.4 DBMS.

Install Neo4j 5

For the initial installation, refer to the Neo4j 5 Operations Manual for methods of installing Neo4j.

If you have one or more existing databases created with earlier versions of Neo4j, you must back these up before installing 5. For more information, see Backup your databases. This is especially important if you install Neo4j via Debian or RPM packages.

Also note that:

  • You must remove the default database if you are migrating a database with the same name.

  • Neo4j 5.x runs on Java 17, and from Neo4j 5.14, it also supports Java 21. If using Oracle Java 17, there is some minor setup required for compatibility with Oracle Java 17 because Oracle and OpenJDK provide incompatible RPM packages for Java 17. For more information, see the Operations Manual → Oracle Java 17.

    If you have other Java applications running on the machine hosting Neo4j, ensure those applications are compatible with the Java version that your Neo4j is running on. Alternatively, you should configure it to run multiple JDKs on the same machine.

The Neo4j Database 5.26 LTS is the last version that will use the Java SE 17 Platform. It is recommended to move to Java SE 21, which is supported with the Neo4j Database 5.14 onwards.

Using Debian or RPM packages

If you install Neo4j 5 via Debian or RPM packages, the Neo4j binaries are upgraded "in-place". This means that your 5 installation will overwrite your 4.4 installation.
During the upgrade process, the package manager will warn you to take backups before continuing. Moreover, the upgrade creates a folder ${NEO4J_HOME}/data-unmigrated-from-4.4 with all 4.4 databases and metadata in raw format (not backups or dumps).

If you have already taken valid dumps or backups of every database you want to migrate to Neo4j 5, you should remove this generated folder and its contents to ensure you have sufficient disk space for the restored and migrated copies produced later in the upgrade process (see Migrate your databases).

Due to strict dependencies between Neo4j and Cypher® Shell, both packages must be upgraded simultaneously.

To upgrade both packages simultaneously, you must have the Cypher Shell RPM and Neo4j RPM files available on the offline machine.

  1. Download the Neo4j and Cypher Shell RPM installers from Deployment Center or run the following to obtain the required packages. You must replace neo4j-version-exact with the exact version of Neo4j you are upgrading to.

    • Cypher Shell:

      curl -O https://dist.neo4j.org/cypher-shell/cypher-shell-neo4j-version-exact-1.noarch.rpm

    • Neo4j Community Edition:

      curl -O https://dist.neo4j.org/rpm/neo4j-neo4j-version-exact-1.noarch.rpm

    • Neo4j Enterprise Edition:

      curl -O https://dist.neo4j.org/rpm/neo4j-enterprise-neo4j-version-exact-1.noarch.rpm

  2. Manually move the downloaded RPM packages to the offline machine.

  3. Run the following on the offline machine as root, to install Neo4j Cypher Shell and Neo4j simultaneously:

    rpm -U <Cypher Shell RPM file name> <Neo4j RPM file name>

    This must be one single command, and Neo4j Cypher Shell must be the first package in the command. The same applies to Debian packages.

If you do not possess such dumps or backups you must perform the following steps:

  1. Reinstate your previous Neo4j 4.4 installation: Operations Manual → Linux installation.

  2. Rename the previously generated unmigrated data folder:

    mv ${NEO4J_HOME}/data-unmigrated-from-4.4 ${NEO4j_HOME}/data

  3. Start this earlier version of Neo4j:

    $NEO4J_HOME/bin/neo4j start

  4. Take backups of all databases you want to migrate to Neo4j 5 using the provided instructions in Backup your databases.

  5. Stop Neo4j and re-attempt the upgrade to Neo4j 5.

Migrate your configuration

Neo4j 5 changes many configuration settings. For the complete list of changes, see Changes to configuration settings in Neo4j 5.

Neo4j Admin has a utility that can convert most of your 4.4 settings to 5 equivalents. For more information, see the Operations Manual → Migrate the Neo4j configuration file. The changes to clustering are such that it is recommended to configure those from scratch.

As mentioned in Prepare for your migration, Neo4j clustering has changed significantly in v5, with the introduction of Autonomous clusters. While it is technically possible to automatically migrate the configuration file for a Neo4j cluster member, not all clustering settings can be directly translated. Given the scope of the changes, it is recommended that you configure your new cluster from scratch.

Steps for migrating 4.4 configuration files

  1. Copy the Neo4j 4.4 configuration file(s) to the new Neo4j 5 configuration directory if you want to migrate an existing configuration, and have concurrent Neo4j 4.4 and 5 installations (e.g., if installing using the tarball executable).

    The default location that Neo4j looks for configuration files depends on how Neo4j is installed:

  2. Use the neo4j-admin server migrate-configuration command in Neo4j 5 to migrate the configuration file to a 5.x-compatible format:

    $NEO4J_5_HOME/bin/neo4j-admin server migrate-configuration

  3. Check the report written to the console for messages related to settings that could not be converted.

Performance metrics

  • All metric names now include dbms or database namespaces, and the setting metrics.namespaces.enabled is removed.

    A complete list of metrics is available in Operations Manual → Metrics reference

  • All settings to enable and disable a metric type (metrics.*.enabled) are removed. They are replaced by server.metrics.filter, which takes a regex of what metrics to enable.

Certificates

Copy all the files used for encryption, such as private key, public certificate, and the contents of the trusted and revoked directories over to Neo4j 5.

Plugins

If you are using custom plugins, make sure they are compatible with Neo4j 5 and Java 17, and place them in the /plugins directory.

Enterprise Edition includes APOC Core, Bloom, and Graph Data Science. The latest versions of these plugins are also available at the Neo4j Deployment Center.