Breaking changes between Neo4j 4.4 and Neo4j 5 LTS

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 Neo4j Database 5.26 LTS is the last version that will use the Java SE 17 Platform. It is recommended to move to Java SE 21, which is supported with the Neo4j Database 5.14 onwards.

The following table shows the compatible Java Virtual Machine (JVM) to run a Neo4j instance.

Table 1. Neo4j version and JVM requirements
Neo4j version Java version

5.26 LTS

Java SE 17 and Java SE 21

5.14

Java SE 17 and Java SE 21

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.

Clustering in Neo4j 5.x

In Neo4j 5, the Causal Cluster is replaced by a new clustering implementation. 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. Clustering in Neo4j 5.x offers improved orchestration capabilities.

When migrating to Neo4j 5.x, 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 clustering in Neo4j 5.x

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

Deprecated terms

  • Core — replaced by primary database copy.

  • Read Replica — replaced by secondary database copy.

  • Standalone — no longer a distinct server behavior, it is just a cluster of size one. This does mean that it opens additional ports compared to 4.4.

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

neo4j admin 5.x

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

console

neo4j-admin server console

restart

neo4j-admin server restart

start

neo4j-admin server start

status

neo4j-admin server status

stop

neo4j-admin server stop

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, and client. This means several settings are renamed. For example, metrics.enabled is renamed server.metrics.enabled.

  • The existing Fabric configuration settings identified by the fabric namespace are removed from the neo4j.conf file.

  • The term internal replaces the terms unsupported and experimental 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 parameter dbms.config.strict_validation=false by default is replaced by server.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 now ON_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 server.config.strict_validation.enabled is set to true, the database will not start. Further to that, if server.config.strict_validation.enabled is disabled, any apoc.* settings left in neo4j.conf will not be read and therefore not set.

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:

  • Any BTREE index exists and there is not at least one index of RANGE/POINT/TEXT type on the same schema.

  • Any index-backed constraints with providers native-btree-1.0 or lucene+native-3.0 exist unless there is a constraint of the same constraint type on the same schema with the range-1.0 provider.

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 command

    db.indexDetails

    SHOW INDEXES YIELD * command

    db.schemaStatements

    SHOW INDEXES YIELD * command and SHOW CONSTRAINTS YIELD * command

    db.constraints

    SHOW CONSTRAINTS command

    db.createIndex

    CREATE INDEX command

    db.createUniquePropertyConstraint

    CREATE CONSTRAINT …​ IS UNIQUE command

    db.index.fulltext.createNodeIndex

    CREATE FULLTEXT INDEX command

    db.index.fulltext.createRelationshipIndex

    CREATE FULLTEXT INDEX command

    db.index.fulltext.drop

    DROP INDEX command

    dbms.procedures

    SHOW PROCEDURES command

    dbms.functions

    SHOW FUNCTIONS command

    dbms.listTransactions

    SHOW TRANSACTIONS command

    dbms.killTransaction

    TERMINATE TRANSACTIONS command

    dbms.killTransactions

    TERMINATE TRANSACTIONS command

    dbms.listQueries

    SHOW TRANSACTIONS command

    dbms.killQuery

    TERMINATE TRANSACTIONS command

    dbms.killQueries

    TERMINATE TRANSACTIONS command

    dbms.scheduler.profile

    -

Deprecations

  • apoc.create.uuid() and apoc.create.uuids() — deprecated and replaced by the existing UUID.randomUUID().

External dependencies

All Neo4j 5 external dependencies and their versions are listed at Neo4j Maven repository.