Understanding upgrades and migration in 4.x

This section describes the Neo4j DBMS components that might need to be upgraded or migrated as well as the difference between an upgrade, a migration, and a store copy.

DBMS components you should be aware of

It is useful to be aware of the following DBMS components beforehand:

Database

A database is a single database for storing data (e.g. Nodes and Relationships) within a Neo4j DBMS. Its physical structure is organized in files within a directory, which has the same name as the database. The default Neo4j installation contains one default database, called neo4j. A different name can be configured before starting Neo4j for the first time.

Neo4j 3.5 supports only one database. Neo4j 4.0 introduced the support for multiple databases.
Store format

A store format defines how the data of a database is stored on the file system. Each database has its own store format, which can be auto-upgraded at server startup if dbms.allow_upgrade=true is set.

For more information on the available store formats per Neo4j version, how to configure them, and their limits, see Operations Manual → Display store information.
The system database

Neo4j 4.0 and higher versions support the management of multiple databases within the same DBMS. All these databases are controlled through a shared database, called the system database. The role of the system database is to define the configuration for the other databases. There could be various types of configuration for the databases, such as operational configuration, database existence, status (online/offline), security configuration (RBAC).
The structure of the graph contained in the system database changes with each new MAJOR or MINOR version of Neo4j. Therefore, each time a Neo4j deployment is upgraded to a new MAJOR or MINOR version, the contents of the system database must be transformed as well.

Upgrade

Neo4j upgrade is the process of upgrading an existing single or clustered deployment to a newer PATCH or MINOR version.

Such upgrades do not require changes to the Neo4j configurations or the applications that use Neo4j. For example, upgrades between:

  • adjacent and non-adjacent PATCH releases within the same MAJOR and MINOR version, e.g., 4.2.1 to 4.2.2 or 4.3.0 to 4.3.4.

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

What to upgrade:

  • The Neo4j product.

  • The store format, only if a new format has been introduced or you want to change to another format, for example, from standard to aligned or to high_limit. The opposite is not possible.

  • 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 PATCH and MINOR upgrades, you do not need to change the configuration settings. 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 always good to review the changes to the Configuration settings and Procedures and update the settings if needed.

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 format of the database (which is auto-upgraded at server startup).
    For more information on the available store formats per Neo4j version, how to configure them, and their limits, see Operations Manual → Display store information.

  • The system database schema, which restructures the contents of that database (automatically created on the first startup of Neo4j 4.x).

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

  • Plugins (including custom plugins) - all plugins must be compatible with the new version of Neo4j.

Store copy

Neo4j store copy is the process of migrating the store format of a 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 migrate 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.

Limitations

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

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

  • Migration requires Neo4j DBMS downtime.