Important information

This section explains the difference between upgrade and migration, as well as the supported paths for keeping your deployment up-to-date.

Keeping your Neo4j deployment always up-to-date ensures that you are provided with the latest improvements in performance, security, and bug fixes.

1. Understanding upgrades and migration

Before you start migrating to a newer version of Neo4j, you should have a clear understanding of upgrades and migration.

1.1. Upgrade

The process of upgrading an existing Neo4j deployment (single or clustered) to a newer minor or release version of Neo4j, when such process does not require changes to the configuration or to the applications that use Neo4j. For example:

  • Between adjacent patch releases within the same major and minor version, e.g., 3.5.0 to 3.5.1, 4.2.1 to 4.2.2.

  • Between non-adjacent patch releases within the same major and minor version, e.g., 3.5.0 to 3.5.10, 4.2.1 to 4.2.3.

  • Between adjacent minor versions, e.g., 4.0.0 to 4.1.3.

What needs to be upgraded

  • The Neo4j product.

  • The store formats (the file formats on disk, which usually auto-upgrade at server startup, but sometimes an older version may remain on a running server).

  • The system database schema, which restructures the contents of that database.
    (From 4.1 onwards) This is done automatically on standalone server and in offline cluster upgrades (where you temporarily set each server as standalone), but need to be run manually on rolling upgrades after the other two upgrades (product and stores) finish.

1.2. Migration

The process of migrating an existing Neo4j deployment (single or clustered) to a newer major Neo4j version, when such process requires a review of the configuration(s) and the applications that use Neo4j. For example:

  • Between major versions, e.g., from 3.5.13 to 4.0.10.

What needs to be migrated

  • The Neo4j product.

  • The store formats (the file formats on disk, which usually auto-upgrade at server startup, but sometimes an older version may remain on a running server).

  • The system database schema, which restructures the contents of that database.

  • Configuration settings - the configuration changes from the newer version must be applied to the old configuration file.

  • Application code - the source code of your application(s) must be updated as per the new version in order to work properly.

  • Custom plugins - all custom plugins must be compatible with the new version of Neo4j.

Limitations

  • Neo4j does not support downgrades.

  • A Neo4j migration must be performed as an isolated operation.

  • Requires Neo4j DBMS downtime.

1.3. Store copy

You can use the neo4j-admin copy command to migrate from Neo4j Community or Enterprise Edition 3.5.any directly to Neo4j Enterprise Edition 4.2.any, skipping the intermediate steps of 3.5.any → 4.0.any → 4.1.any → 4.2.any. Those steps are needed to migrate the schema, but since the neo4j-admin copy command does not copy the schema store at all, they are not needed. However, if there is a schema defined, you have to recreate it by running the commands that the neo4j-admin copy operation outputs. The neo4j-admin copy command can be applied only to an offline database.

Your copied node IDs will be the same, but the relationships will get new IDs. Therefore, if you want to preserve the relationship IDs, follow the sequential path 3.5.any → 4.0.any → 4.1.any → 4.2.any.

2. Supported paths

Neo4j supports two paths for migrating from an earlier version of Neo4j to the latest:

  • sequential — 3.5.any → 4.0.any → 4.1.any → 4.2.any

  • direct — Neo4j Community or Enterprise Edition 3.5.any → Neo4j Enterprise Edition 4.x.any

    The neo4j-admin copy command is an Enterprise Edition feature. Therefore, it is not possible to migrate to a Community Edition, for example, from Neo4j Community Edition 3.5 to Neo4j Community Edition 4.2. However, you can use it to migrate from Neo4j Community Edition to Neo4j Enterprise Edition.

Depending on your current version, backup and restore strategy, and the version you want to go to, you can choose the most appropriate path for you. You can also move from Community to Enterprise Edition (vice versa is not supported), as well as from a single instance to a Causal cluster.

upgrade paths

Table 1. Documentation for completing your upgrade/migration
Starting version Target version Supported path Operations Documentation

3.4.any

3.5.any

3.4.any → 3.5.any

Upgrade

3.5.any

4.0.any

3.5.any → 4.0.any

Migration

3.5.any

4.1.any

3.5.any → 4.0.any → 4.1.any

Migration and upgrade

3.5.any

4.2.any

3.5.any → 4.0.any → 4.1.any → 4.2.any

Migration and upgrades

4.0.any

4.1.any

4.0.any → 4.1.any

Upgrade

4.0.any

4.2.any

4.0.any → 4.1.any → 4.2.any

Upgrades

4.1.any

4.2.any

4.1.any → 4.2.any

Upgrade

Neo4j Community or Enterprise Edition 3.5.any

Neo4j Enterprise Edition 4.x.any

Neo4j Community or Enterprise Edition 3.5.any → Neo4j Enterprise Edition 4.x.any

Store copy