Understanding upgrades and migration

This section explains the difference between upgrade, migration, and store copy.

Before you start migrating to a newer version of Neo4j, you should clearly understand upgrades and migration.

1. Upgrade

Neo4j upgrade is the process of upgrading an existing single or clustered deployment to a newer minor or patch version. Such upgrades do not require changes to the Neo4j configurations or the applications that use Neo4j. For example, upgrades 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.

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

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

What to upgrade:

  • The Neo4j product.

  • The store formats.
    These are the file formats on the disk, which usually auto-upgrade at server startup, but sometimes older formats 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 a standalone server and in offline cluster upgrades (where you temporarily set each server as standalone). However, for rolling upgrades, you have to manually upgrade the system database after the other two upgrades (product and stores) finish.

  • Configuration settings. In a minor version upgrade, you do not need to change the configurations. If you leave the neo4j.conf file unchanged, everything should work as in the old version. However, some versions may include new features, so it is recommended to always review the changes to the Configuration settings and Procedures.

2. Migration

Neo4j migration is the process of migrating an existing single or clustered deployment to a newer major version. Such migrations require a review of the Neo4j configurations and the applications that use Neo4j. For example, migration between:

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

What to migrate:

  • The Neo4j product.

  • The store formats.
    These are the file formats on the disk, which usually auto-upgrade at server startup, but sometimes older formats 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 a standalone server and in offline cluster upgrades (where you temporarily set each server as standalone). However, for rolling upgrades, you have to manually upgrade the system database after the other two upgrades (product and stores) finish.

  • 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 reviewed and may require some updates as per the new version to work correctly.

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

3. Store copy

Neo4j store copy is the process of copying the data store of an existing user database from Neo4j Community or Enterprise Edition to Neo4j Enterprise Edition. It uses the neo4j-admin copy command, which does not copy the schema store, and therefore, you can move a database directly into a Neo4j DBMS on the latest version. If a schema is defined, you have to recreate it by running the commands that the neo4j-admin copy operation outputs. Note that to be able to copy a database, it has to be offline.

4. Limitations

  • Neo4j does not support downgrades. If the upgrade is not successful, you have to do a full rollback, including restoring a pre-upgrade backup.

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

  • Migration requires Neo4j DBMS downtime.