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 thesystem
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 thesystem
database changes with each newMAJOR
orMINOR
version of Neo4j. Therefore, each time a Neo4j deployment is upgraded to a newMAJOR
orMINOR
version, the contents of thesystem
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 sameMAJOR
andMINOR
version, e.g.,4.2.1
to4.2.2
or4.3.0
to4.3.4
. -
adjacent
MINOR
versions, e.g.,4.0.0
to4.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
toaligned
or tohigh_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 thesystem
database after the other two upgrades (product and stores) finish. -
Configuration settings. In
PATCH
andMINOR
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.