Neo4j 4.4 与 Neo4j 5 LTS 之间的破坏性变更

以下是 Neo4j 4.4 与 Neo4j 5.x 之间的所有破坏性变更。

JDK 17 支持与 Scala 升级

Neo4j 5 支持 JDK 17 和 Scala 2.13 升级。

Neo4j Database 5.26 LTS 是最后一个使用 Java SE 17 平台的版本。建议迁移至 Java SE 21，该版本从 Neo4j Database 5.14 开始提供支持。

下表显示了运行 Neo4j 实例所需的兼容 Java 虚拟机 (JVM)。

表 1. Neo4j 版本与 JVM 要求
Neo4j 版本 Java 版本

5.26 LTS

Java SE 17 和 Java SE 21

5.14

Java SE 17 和 Java SE 21

5.x

Java SE 17

v4.x

Java SE 11

v3.x

Java SE 8

如果您在托管 Neo4j 的机器上运行其他 Java 应用程序，请确保这些应用程序与您的 Neo4j 所运行的 Java 版本兼容。或者，您应该配置在同一台机器上运行多个 JDK。

Java API

有关 Java API 类和设置的所有破坏性变更，请参阅变更日志部分 - Neo4j 5 中 Java API 的变更。

经过彻底的代码审查、补充文档和示例后，遍历 API (Traversal API) 已在 Neo4j 5 中重新引入。

Neo4j 5.x 中的集群
仅限企业版

在 Neo4j 5 中，因果集群 (Causal Cluster) 被一种新的集群实现所取代。它提供了自动化的数据库放置和水平扩展功能。数据库管理员 (DBA) 可以指定集群内每个数据库的副本数量，从而使服务器数量多于数据库副本数量（例如：5 个数据库，每个数据库 3 个副本，分布在 6 台服务器上）。Neo4j 5.x 中的集群提供了更强大的编排能力。

迁移到 Neo4j 5.x 时，建议从零开始构建新集群。请确保阅读 操作手册 → 集群 中的所有详细信息。

Neo4j 5.x 集群的关键特性

  • 数据库被复制到集群内服务器的子集中。

  • 所有服务器地位平等。

  • 集群决定将哪些数据库分配给哪些服务器。

  • 数据库副本可以是主要副本或次要副本。

  • 随着时间的推移，添加和移除服务器时，分配方案可能会发生变化。

已弃用术语

  • Core（核心）— 被“主要数据库副本 (primary database copy)”取代。

  • Read Replica（只读副本）— 被“次要数据库副本 (secondary database copy)”取代。

  • Standalone（单机）— 不再是一种独特的服务器行为，它只是一个大小为一的集群。这意味着与 4.4 版本相比，它会开启额外的端口。

Neo4j Admin 和 Neo4j CLI

Neo4j Admin CLI

Neo4j Admin 已更新。所有管理功能现已整合到一个工具中，并按范围进行分组。它具有改进的功能、更强的控制力，以及一致的管理参数集。

neo4j-admin 的一般用法如下：

neo4j-admin [category] [command] [subcommand]

除 help 和 version 外，所有管理命令均分为以下三类：

  • dbms - DBMS 范围（适用于单机和集群环境）的管理任务

  • server - 服务器范围的管理任务

  • database - 特定于数据库的管理任务

neo4j admin 5.x

有关新管理命令的更多信息，请参阅 操作手册 → Neo4j Admin 和 Neo4j CLI。

Neo4j CLI

neo4j 的一般用法如下：

neo4j [command]

command 是 neo4j-admin server 分类中命令的别名。

[command] neo4j-admin

console

neo4j-admin server console

restart

neo4j-admin server restart

开始

neo4j-admin server start

状态 (status)

neo4j-admin server status

stop

neo4j-admin server stop

有关更多信息，请参阅 操作手册 → Neo4j Admin 和 Neo4j CLI。

备份与恢复 仅限企业版

Neo4j 5 对备份和恢复进行了重大调整。新的备份和恢复子系统现支持差异备份、（有限的）时间点恢复和制品 (artifacts)。它与旧版子系统不兼容。

其主要功能包括但不限于：

  • 全量和差异备份。

  • 备份是不可变的制品（文件系统中压缩的单个项目）。

  • 用于简化操作的 API。

  • 支持跨差异备份集恢复到特定时间点或事务 ID。

  • 可以在备份链上执行聚合，以创建一个新的、已恢复的全量备份。

    有关更多信息，请参阅 操作手册 → 备份与恢复。

  • 自主集群的备份*

使用自主集群时，不再保证数据库在任何特定服务器上都可用。通过提供一组适当的 URI 和 --database 参数，操作员可以构建合适的备份命令。该命令将循环遍历 URI，尝试处理 –database= 参数中的请求。已经在之前的 URI 上备份过的数据库将被忽略。

配置设置更新

  • 在 Neo4j 5 中，所有配置设置被划分为 server、dbms、db、initial、browser 和 client 命名空间。这意味着多个设置已重命名。例如，metrics.enabled 被重命名为 server.metrics.enabled。

  • neo4j.conf 文件中由 fabric 命名空间标识的现有 Fabric 配置设置已被移除。

  • 术语 internal 取代了之前版本中使用的 unsupported 和 experimental。该命名空间专门用于内部使用且可能随时更改的功能。

  • neo4j.conf 中的设置默认启用严格验证。
    默认情况下，旧参数 dbms.config.strict_validation=false 被 server.config.strict_validation.enabled=true 取代。这确保了配置文件不包含错误或不正确的信息，并防止 Neo4j 在 neo4j.conf 文件中存在错误设置的情况下启动。

  • 仅限企业版 db.tx_state.memory_allocation 现默认设为 ON_HEAP。

  • Neo4j Admin 现在包含一个迁移配置文件的工具。在将 4.4 配置迁移到 5.x 时，如果某些设置因新 MAJOR 版本中不存在相关概念或行为而无法迁移，该工具会发出通知。有关更多信息，请参阅 操作手册 → 迁移 Neo4j 配置文件。

有关已更改设置的完整列表，请参阅 Neo4j 5 中配置设置的变更。

Fabric 的组合数据库

neo4j.conf 文件中 fabric 命名空间下的所有配置设置均已移至 system 数据库。这些设置现在通过 Cypher® 进行管理。

Fabric 用于管理具有动态组合的分片和联邦数据库。组合数据库被视为任何其他数据库，其名称标识了一个更复杂的存储基础设施，由本地、集群和远程数据库的聚合形成。

作为此项改进的一部分，Neo4j 用户现在可以使用 Cypher 来配置 Fabric，并：

  • 无需重启即可更改 Fabric 配置

  • 支持多个 Fabric 数据库

  • 提供一种通用的数据库管理方法，无论是本地、远程还是分片数据库。

  • 通过将 Fabric 与自主集群相结合来整合 Neo4j 数据库基础设施。

有关更多信息，请参阅 操作手册 → 组合数据库。

Cypher

Cypher 语法

Cypher 语言语法的所有变更均详细记录在 Cypher 手册 → 移除、弃用、新增和扩展 中。请仔细审阅您所迁移到的版本中的此部分，并在您的代码中进行必要的修改。

Cypher 中的错误/警告/信息处理

Cypher 发现的许多语义错误以前被报告为 Neo.ClientError.Statement.SyntaxError。在 Neo4j 5 中，Cypher 查询返回的元数据得到了改进。

  • 一些警告代码的严重性等级被降级为信息 (Info)：

    • SubqueryVariableShadowingWarning → SubqueryVariableShadowing

    • NoApplicableIndexWarning → NoApplicableIndex

    • CartesianProductWarning → CartesianProduct

    • DynamicPropertyWarning → DynamicProperty

    • EagerOperatorWarning → EagerOperator

    • ExhustiveShortestPathWarning → ExhaustiveShortestPath

    • UnboundedVariableLengthPatternWarning → UnboundedVariableLengthPattern

    • ExperimentalFeature → RuntimeExperimental

Neo4j 5 APOC 核心库

APOC Core 是 APOC 库的一个子集，由 Neo4j 工程团队提供全面支持。

为了避免混淆，完整的 APOC 库现在被称为 APOC Extended。APOC Extended 仅由 Neo4j 社区提供支持。

Neo4j 不建议或鼓励在生产环境中使用 APOC Extended 方法。

APOC Core

请参阅 APOC Core 文档。

APOC Core 库包含在 Neo4j 安装包和 Docker 镜像中，且大多数功能在 Aura 中可用。有关更多信息，请参阅 Neo4j Aura → APOC 支持。

有关源代码，请参阅 APOC Core 源代码仓库。

从 APOC 5 开始，neo4j.conf 文件不再支持 apoc.* 配置设置。所有配置设置必须在 apoc.conf 中指定，或使用环境变量进行设置。

如果配置设置仍在 neo4j.conf 中且 server.config.strict_validation.enabled 设置为 true，数据库将无法启动。此外，如果 server.config.strict_validation.enabled 被禁用，neo4j.conf 中遗留的任何 apoc.* 设置都不会被读取，因此不会生效。

APOC Extended

APOC Full 包（APOC Core + APOC Extended）不再提供。如果您有兴趣使用不受支持的 APOC Extended 方法，需要参考 https://github.com/neo4j-contrib/neo4j-apoc-procedures 仓库。

源代码位于 APOC Extended 源代码仓库。

Neo4j 索引

新的 RANGE 和 POINT 索引取代了 BTREE 索引

BTREE 索引类型已被移除。因此，在切换到 5.x 二进制文件之前，必须替换或删除所有索引提供程序为 native-btree-1.0 或 lucene+native-3.0 的 BTREE 索引和索引约束。最合适的方法是在迁移到 5.x 之前在 4.4 版本中重新创建它们。随后在迁移过程中，5.x 将检查每个 BTREE 索引和约束是否有等效类型的索引和提供程序，并将其删除。

如果满足以下情况，Neo4j 将无法启动：

  • 存在任何 BTREE 索引，且同一模式上没有至少一个 RANGE/POINT/TEXT 类型的索引。

  • 存在提供程序为 native-btree-1.0 或 lucene+native-3.0 的索引约束，除非同一模式上有相同类型且提供程序为 range-1.0 的约束。

日志记录

从 Neo4j 5 开始，Neo4j 使用 Log4j 2 进行日志记录。

配置变更

文件管理的配置设置已移至 Log4j 配置文件，并对查询日志的内容设置进行了审查和简化。

有关更高级的用法，请参阅 Log4j 官方文档。

有关默认 Neo4j 安装的行为以及配置它使用 Log4j 的一些典型示例的更多信息，请参阅 操作手册 → 日志记录。

指标 (Metrics)

所有指标名称现在都包含 dbms 或 database 命名空间，且用于切换此行为的设置 metrics.namespaces.enabled 已被移除。

所有用于启用和禁用指标类型 (metrics.*.enabled) 的设置已被移除。它们被 server.metrics.filter 取代，该设置接受一个正则表达式来确定启用哪些指标。

移除

产品中已移除未使用的和遗留的代码：

  • 遗留的 HTTP 事务 API - URI 中不包含数据库名称的特定请求，例如 db/data/transaction。

  • 结果摘要的 version / version_info。

  • 来自 Java 驱动程序的 Session #reset（已长期弃用）。

  • BTREE 索引 - 请使用 RANGE 和 POINT 索引代替。

  • Cypher 3.5 模式。

  • 禁止重复的关系变量。

  • 自动将列表强制转换为布尔值。

  • 用于测试属性是否为 null 的 exists() 函数。

  • 多数据中心设置，包括 causal_clustering.multi_dc_license。

  • 存储过程

    表 2. 已移除的过程
    过程 替代方案

    db.indexes

    SHOW INDEXES 命令

    db.indexDetails

    SHOW INDEXES YIELD * 命令

    db.schemaStatements

    SHOW INDEXES YIELD * 命令和 SHOW CONSTRAINTS YIELD * 命令

    db.constraints

    SHOW CONSTRAINTS 命令

    db.createIndex

    CREATE INDEX 命令

    db.createUniquePropertyConstraint

    CREATE CONSTRAINT …​ IS UNIQUE 命令

    db.index.fulltext.createNodeIndex

    CREATE FULLTEXT INDEX 命令

    db.index.fulltext.createRelationshipIndex

    CREATE FULLTEXT INDEX 命令

    db.index.fulltext.drop

    DROP INDEX 命令

    dbms.procedures

    SHOW PROCEDURES 命令

    dbms.functions

    SHOW FUNCTIONS 命令

    dbms.listTransactions

    SHOW TRANSACTIONS 命令

    dbms.killTransaction

    TERMINATE TRANSACTIONS 命令

    dbms.killTransactions

    TERMINATE TRANSACTIONS 命令

    dbms.listQueries

    SHOW TRANSACTIONS 命令

    dbms.killQuery

    TERMINATE TRANSACTIONS 命令

    dbms.killQueries

    TERMINATE TRANSACTIONS 命令

    dbms.scheduler.profile

    -

弃用

  • apoc.create.uuid() 和 apoc.create.uuids() — 已弃用，并由现有的 UUID.randomUUID() 取代。

外部依赖

所有 Neo4j 5 外部依赖及其版本列在 Neo4j Maven 仓库 中。

© . This site is unofficial and not affiliated with Neo4j, Inc.