Install and configure Neo4j v5

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

Install Neo4j v5

For the initial installation, refer to the Neo4j v5 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 v5. 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 v5.x runs on 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.

Using Debian or RPM packages

If you install Neo4j v5 via Debian or RPM packages, the Neo4j binaries are upgraded "in-place". This means that your v5 installation will overwrite your v4.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 v4.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 v5, 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).

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

  1. Reinstate your previous Neo4j v4.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 v5 using the provided instructions in Backup your databases.

  5. Stop Neo4j and re-attempt the upgrade.

Migrate your configuration

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

Neo4j Admin has a utility that can convert most of your v4.4 settings to v5 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 v4.4 configuration files

  1. Copy the Neo4j v4.4 configuration file(s) to the new Neo4j v5 configuration directory if you want to migrate an existing configuration, and have concurrent Neo4j v4.4 and v5 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 v5 to migrate the configuration file to a v5.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.

Configure roles and privileges

The role-based access control (RBAC) is unchanged in v5 and you can re-create your previous configuration. For more information on roles and privileges, see Operations Manual → Fine-grained access control.

List all configured roles and recreate them

Run the following Cypher command on Neo4j v4.4 to list the configured roles:

SHOW ROLES

Then, recreate them on Neo4j v5 using:

CREATE ROLE <new_role>

List all privileges and recreate them

Run the following Cypher on Neo4j v4.4 to list the privileges assigned to roles:

SHOW PRIVILEGES AS COMMANDS

Then, use the output to recreate the privileges on Neo4j v5.

You cannot create privileges related to specific databases or graphs that do not exist yet on your new Neo4j v5 DBMS. These privileges can be restored as part of the database migration steps, see Restore roles and privileges.

Aliases

If you are using aliases, you must recreate them manually. For more information on aliases, see Cypher Manual → Database alias management.

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 v5.

Plugins

If you are using custom plugins, make sure they are compatible with Neo4j v5 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 Download Center.