Breaking changes between Neo4j 4.4 and Neo4j 5.x
The following are all the breaking changes between Neo4j 4.4 and Neo4j 5.x.
Neo4j 5 supports JDK 17 and Scala 2.13 upgrade.
The following table shows the compatible Java Virtual Machine (JVM) to run a Neo4j instance.
Java SE 17
Java SE 11
Java SE 8
If you have other Java applications running on the machine hosting Neo4j, make sure those applications are compatible with the Java version your Neo4j is running on. Alternatively, you should configure to run multiple JDKs on the same machine.
In Neo4j 5, the Causal Cluster is replaced by a new clustering implementation, called Autonomous clusters. It provides automated placement of databases and horizontal scaling. DBAs can specify the number of copies of each database within the cluster so that you can have more servers than copies of the database, e.g., 5 databases, with 3 copies of each database distributed across 6 servers. Autonomous clusters offer improved orchestration capabilities.
When migrating to Neo4j 5, it is advisable to start from scratch with the new cluster. Make sure that you read all the details in Operations Manual → Clustering.
Databases are replicated to a subset of servers within a cluster.
All servers are created equal.
The cluster decides which databases are allocated to which servers.
A database copy can be Primary or Secondary.
The allocation may change as servers are added and removed over time.
Ne4j Admin is refreshed. All admin functionalities are consolidated in a single tool and grouped by scope. It has improved features, more control, and a consistent set of arguments for the admin.
neo4j-admin has the following general synopsis:
neo4j-admin [category] [command] [subcommand]
All administration commands, except for
version, are organized into the following three categories:
dbms- DBMS-wide (for single and clustered environments) administration tasks
server- server-wide administration tasks
database- database-specific administration tasks
For more information about the new administration commands, see Operations Manual → Neo4j Admin and Neo4j CLI.
neo4j has the following general synopsis:
command is an alias for a command in the
neo4j-admin server category.
For more information, see Operations Manual → Neo4j Admin and Neo4j CLI.
The backup and restore have undergone a major overhaul for Neo4j 5. The new subsystem for backup and restore now supports differential backups, (limited) point-in-time restore, and artefacts. It is not compatible with the legacy subsystem.
The legacy Neo4j 4 backup/restore commands are still available (with a naming change) for backward compatibility so that you can restore Neo4j 4 backups.
Some of its main features include but are not limited to:
Full and differential backups.
Backups are immutable artifacts (compressed single items in the file system)
An API to ease operability.
Restore until point-in-time or a transaction ID across differential backup sets.
Aggregation can be performed on a backup chain to create a new, recovered Full Backup.
For more information, see Operations Manual → Backup and restore.
Backup for autonomous cluster*
With an autonomous cluster, you no longer have a guarantee that a database will be available on any given server.
By supplying an appropriate set of URIs and
--database parameter, the operator can build an appropriate backup command.
The command will loop through the URIs, attempting to serve the request in the
Databases already backed up on a previous URI will be ignored.
In Neo4j 5, all configuration settings are divided into the namespaces
client. This means several settings are renamed. For example,
The existing Fabric configuration settings identified by the
fabricnamespace are removed from the neo4j.conf file.
internalreplaces the terms
experimentalused in previous versions. This namespace is dedicated to features that are used internally and may change without notice.
Settings in neo4j.conf have strict validation enabled by default.
The old parameter
dbms.config.strict_validation=falseby default is replaced by
server.config.strict_validation.enabled=trueby default. This ensures the configuration file does not contain errors or incorrect information and prevents Neo4j from starting with faulty settings in the neo4j.conf file.
Neo4j Admin now includes a tool for migrating configuration files. When migrating 4.4 configurations to 5.x, the tool notifies about settings that have not migrated, for instance, because a concept or behavior does not exist in the new
MAJORversion. For more information, see the Operations Manual → Migrate the Neo4j configuration file.
For the full list of changed settings, see Changes to configuration settings in Neo4j 5.
All configuration settings in the
fabric namespace in the neo4j.conf file are moved to the
These settings are now managed through Cypher®.
Fabric is used to manage sharded and federated databases with dynamic compositions. A composite database is treated like any other database and created with a name that identifies a more complex storage infrastructure, formed by an aggregation of local, clustered, and remote databases.
As part of this improvement, Neo4j users can now use Cypher to configure Fabric and:
Change the Fabric configuration without a restart
Support for multiple Fabric databases
Provide a common approach to managing databases, whether they are local, remote, or sharded.
Integrate the Neo4j database infrastructure by combining Fabric with autonomous clusters.
For more information, see Operations Manual → Composite databases.
All changes in the Cypher language syntax are detailed in Cypher Manual → Removals, deprecations, additions and extensions. Thoroughly review this section in the version you are moving to and make the necessary changes in your code.
Many semantic errors that Cypher finds are reported as
Neo.ClientError.Statement.SyntaxError when they are semantic errors.
In Neo4j 5, the metadata returned by Cypher queries is improved.
The severity of some of the Warning codes is moved to Info:
APOC Core is a subset of the APOC library that is fully supported by Neo4j engineering.
The complete APOC library is now referred to as APOC Extended to avoid confusion. APOC Extended is supported by the Neo4j Community exclusively.
Neo4j does not recommend or encourage the use of the APOC Extended methods in production.
Please see APOC Core documentation.
The APOC Core Library is included as part of the Neo4j installation package, docker images, and most features are available in Aura. For more information, see Neo4j Aura → APOC support.
For the source code, please see the APOC Core source code repository.
As of APOC 5, the neo4j.conf file no longer supports
apoc.* configuration settings.
All configuration settings must be specified in apoc.conf or set using environment variables.
If the config settings are in the neo4j.conf and
The APOC Full package (APOC Core + APOC Extended) is no longer available. If you are interested in using non-supported APOC Extended methods, you need to refer to the https://github.com/neo4j-contrib/neo4j-apoc-procedures repository.
The source code is available in the APOC Extended source code repository.
The BTREE index type is removed.
Therefore, all BTREE indexes and index-backed constraints with index providers
lucene+native-3.0 must be replaced or removed before switching to the 5.x binaries.
The most appropriate approach would be to recreate them in 4.4 before migrating to 5.x.
Then, during the migration, 5.x will check that each BTREE index and index-backed constraint has an equivalent type of index and provider and will drop them.
Neo4j will not start if:
As of Neo4j 5, Neo4j uses Log4j 2 for logging.
The configuration settings for file management are moved to a Log4j configuration file, and a review and simplification of content settings for the query log are performed.
All metric names now include
database namespaces, and the setting
metrics.namespaces.enabled that toggled this behavior is removed.
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.
Unused and legacy code is removed from the product:
Legacy HTTP transactional API - specific requests without the database name in the URI, such as
version_infoof result summary.
Session #reset from Java driver (long deprecated).
BTREE indexes - use RANGE and POINT indexes instead.
Cypher 3.5 mode.
Disallow repeated relationship variables.
Automatic coercion of a list to a boolean.
exists()function to test if property is null.
Multi-datacenter settings, including
Table 2. Removed procedures Procedure Replacement
SHOW INDEXES YIELD *command
SHOW INDEXES YIELD *command and
SHOW CONSTRAINTS YIELD *command
CREATE CONSTRAINT … IS UNIQUEcommand
CREATE FULLTEXT INDEXcommand
CREATE FULLTEXT INDEXcommand
apoc.create.uuids()— deprecated and replaced by the existing
All Neo4j 5 external dependencies and their versions are listed at Neo4j Maven repository.