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.
JDK 17 support and Scala upgrade
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.
Neo4j version | Java version |
---|---|
5.x |
Java SE 17 |
v4.x |
Java SE 11 |
v3.x |
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. |
Java API
All breaking changes to Java API classes and settings are listed in the Changelogs section - Changes to Java API in Neo4j 5.
The Traversal API is reintroduced in Neo4j 5 after a thorough code review, more documentation, and examples.
Autonomous clusters Enterprise Only
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. |
Key features of Autonomous clusters
-
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.
Neo4j Admin and Neo4j CLIs
Neo4j Admin CLI
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 help
and 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 CLI
neo4j
has the following general synopsis:
neo4j [command]
The command
is an alias for a command in the neo4j-admin server
category.
[command] | neo4j-admin |
---|---|
|
|
|
|
|
|
|
|
|
|
For more information, see Operations Manual → Neo4j Admin and Neo4j CLI.
Backup and restore Enterprise Only
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.
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 –database=
parameter.
Databases already backed up on a previous URI will be ignored.
Configuration settings refresh
-
In Neo4j 5, all configuration settings are divided into the namespaces
server
,dbms
,db
,initial
,browser
, andclient
. This means several settings are renamed. For example,metrics.enabled
is renamedserver.metrics.enabled
. -
The existing Fabric configuration settings identified by the
fabric
namespace are removed from the neo4j.conf file. -
The term
internal
replaces the termsunsupported
andexperimental
used 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 parameterdbms.config.strict_validation=false
by default is replaced byserver.config.strict_validation.enabled=true
by 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. -
Enterprise Only
db.tx_state.memory_allocation
is nowON_HEAP
by default. -
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
MAJOR
version. 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. |
Composite databases for Fabric
All configuration settings in the fabric
namespace in the neo4j.conf file are moved to the system
database.
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. |
Cypher
Cypher syntax
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.
Error/Warning/Info handling in Cypher
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:
-
SubqueryVariableShadowingWarning
→SubqueryVariableShadowing
-
NoApplicableIndexWarning
→NoApplicableIndex
-
CartesianProductWarning
→CartesianProduct
-
DynamicPropertyWarning
→DynamicProperty
-
EagerOperatorWarning
→EagerOperator
-
ExhustiveShortestPathWarning
→ExhaustiveShortestPath
-
UnboundedVariableLengthPatternWarning
→UnboundedVariableLengthPattern
-
ExperimentalFeature
→RuntimeExperimental
-
Neo4j 5 APOC Core Library
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. |
APOC Core
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 |
APOC Extended
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.
Neo4j indexes
New RANGE and POINT indexes replace BTREE index
The BTREE index type is removed.
Therefore, all BTREE indexes and index-backed constraints with index providers native-btree-1.0
or 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:
|
Logging
As of Neo4j 5, Neo4j uses Log4j 2 for logging.
Changes to configuration
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.
For more advanced usages, see the Log4j official documentation. For more information on how a default Neo4j installation behaves and some typical examples of configuring it to use Log4j, see Operations Manual → Logging. |
Metrics
All metric names now include dbms
or 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.
Removals
Unused and legacy code is removed from the product:
-
Legacy HTTP transactional API - specific requests without the database name in the URI, such as
db/data/transaction
. -
version
/version_info
of 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
causal_clustering.multi_dc_license
. -
Procedures:
Table 2. Removed procedures Procedure Replacement db.indexes
SHOW INDEXES
commanddb.indexDetails
SHOW INDEXES YIELD *
commanddb.schemaStatements
SHOW INDEXES YIELD *
command andSHOW CONSTRAINTS YIELD *
commanddb.constraints
SHOW CONSTRAINTS
commanddb.createIndex
CREATE INDEX
commanddb.createUniquePropertyConstraint
CREATE CONSTRAINT … IS UNIQUE
commanddb.index.fulltext.createNodeIndex
CREATE FULLTEXT INDEX
commanddb.index.fulltext.createRelationshipIndex
CREATE FULLTEXT INDEX
commanddb.index.fulltext.drop
DROP INDEX
commanddbms.procedures
SHOW PROCEDURES
commanddbms.functions
SHOW FUNCTIONS
commanddbms.listTransactions
SHOW TRANSACTIONS
commanddbms.killTransaction
TERMINATE TRANSACTIONS
commanddbms.killTransactions
TERMINATE TRANSACTIONS
commanddbms.listQueries
SHOW TRANSACTIONS
commanddbms.killQuery
TERMINATE TRANSACTIONS
commanddbms.killQueries
TERMINATE TRANSACTIONS
commanddbms.scheduler.profile
-
Deprecations
-
apoc.create.uuid()
andapoc.create.uuids()
— deprecated and replaced by the existingUUID.randomUUID()
.
External dependencies
All Neo4j 5 external dependencies and their versions are listed at Neo4j Maven repository.