从旧版本升级

此页面包含驱动程序从版本 4.4 到 5.x 的新功能和重大变更列表。有关完整的变更列表，请参阅 驱动程序 → 变更日志。

Neo4j 驱动程序迁移助手通过根据您的应用程序语境化变更日志来简化升级过程。它会扫描您的代码库中已弃用和已移除的用法，并将其显示给您。该工具不会自动重写您的代码；它只会指出需要操作的地方，并提供关于如何解决每个命中问题的上下文信息。

5.x 系列的最新驱动程序版本（5.28）兼容 Neo4j 服务器 4.4 和 5.x，因此您可以在升级服务器之前升级驱动程序。同时，驱动程序版本 4.4 向后兼容 Neo4j 服务器 5.x，因此您也可以在升级驱动程序之前升级服务器；然而，鉴于应用程序升级比服务器升级更容易回滚，建议从驱动程序开始。

将 Neo4j 服务器升级到新版本时，应用程序中的 Cypher 查询可能也需要更新。驱动程序迁移助手不涵盖 Cypher 变更。
请参阅 Cypher → 弃用、新增和兼容性。

使用迁移助手，推荐的升级步骤如下：

  1. 设置助手的工作环境。下载 驱动程序迁移助手 zip，将其解压，并进入其目录。然后，假设已安装 python3 和 pip3，

    python3 -m venv virtualenvs/neo4j-migration
source virtualenvs/neo4j-migration/bin/activate
pip3 install -r requirements.txt

  2. 使用默认配置运行迁移助手并解决它发现的所有问题。path 参数支持 通配符匹配，并且可以重复使用。

    python3 main.py -l python /path/*.py /path-recursive/**/*.py

  3. 使用正则表达式解析器重新运行助手，并检查是否有更多合法问题出现。

    python3 main.py -l python --regex-parser /path/*.py /path-recursive/**/*.py

    正则表达式解析器可以检测隐式函数调用和其他难以解析的表达式，但很可能会产生更多的误报（更多信息请参阅 Neo4j 驱动程序迁移助手 → 准确性）。您可以将任何虚假条目添加到忽略列表中，这样助手在未来的运行中就不会再显示它们。

  4. 尽管助手可以检测到大多数需要采取行动的位置，但仍有一些变更日志条目无法以这种形式显示，因此您仍应查阅重大变更部分，并检查您的代码库中表中带有 标记的变更。

  5. 您已准备好将驱动程序包升级到新版本。例如，使用 pip

    pip3 install -U neo4j==5.27

新功能

支持 Python 3.13

该驱动程序兼容从 3.7 到 3.13 的所有 Python 版本。
asyncio 支持

用于通过 asyncio 包异步使用驱动程序功能。

请参阅 运行并发事务。
Driver.execute_query() 用于在对驱动程序内部机制了解较少的情况下运行事务

新函数是 Session.execute_read/write() 的包装器，但它抽象了结果处理部分，并直接向调用者返回记录列表。

请参阅 查询数据库。
Rust 扩展以提高性能

Python 驱动程序的 Rust 扩展是一个替代的驱动程序包，与纯 Python 驱动程序相比，它可以将速度提高多达 10 倍。

您可以使用 pip install neo4j-rust-ext 进行安装，可以与 neo4j 包一起安装，也可以作为其替代品。在用法上，这两个驱动程序是相同的。
导出为 Pandas Dataframe

Result.to_df() 允许将 Result 对象导出到 Pandas DataFrame 中。

请参阅 操作查询结果 → 转换为 Pandas Dataframe。
所有公共 API 的类型提示

所有公共对象都通过 typing 包进行类型注解。可（可选地）与类型检查器和静态代码分析工具一起使用。
重新认证

允许轮换认证令牌，以及会话范围和查询范围的认证。
相互 TLS (mTLS) 作为第二认证因子 (2FA)

允许配置客户端 TLS 证书以对服务器进行认证。

请参阅 相互 TLS。
BookmarkManager 支持

书签管理器使会话的因果链更容易实现。

请参阅 协调并行事务。
通知过滤 API

过滤允许只接收服务器通知的一个子集，并提高服务器端的性能。

请参阅 探索查询执行摘要 → 过滤通知。
ResultSummary 中查询的 GQL 状态

新属性 ResultSummary.gql_status_objects 可用。它包含一系列 GqlStatusObjects，其中包含关于查询执行的信息。

此 API 计划取代当前的通知 API。

请参阅 探索查询执行摘要 → 通知。
更方便地处理服务器端警告和通知

新的子日志记录器 neo4j.notifications 记录服务器发出的每个通知。日志级别由通知的严重性决定。

如果未显式配置日志记录，默认行为是将警告通过 warning.warn() 记录到标准错误输出。此更改的结果是，从 DBMS 接收到的警告（例如弃用）将出现在标准错误输出中。

请参阅 便捷的 DBMS 通知。
遥测

驱动程序向服务器发送匿名 API 使用统计信息。使用驱动程序配置 telemetry_disabled=True 可选择退出。
并发误用检查

对于本地开发，使用 python -X dev ... 运行您的应用程序，或将环境变量 PYTHONNEO4JDEBUG 设置为任何非空值以获取额外的并发误用检查。某些驱动程序原语（例如会话）不能安全地并发使用，否则会导致难以调试的错误。此功能有助于识别此类代码路径（检测本身仍然存在竞态条件，因此无法保证始终有效）。

重大变更和弃用

Assistant 列表示 Neo4j 驱动程序迁移助手是否可以检测与给定变更日志条目相关的问题。带有叉号 的条目需要手动检查。

弃用的功能可能会在版本 6 中移除。

版本 消息 状态 助手

5.0

停止支持 Python 3.6。

已移除

5.0

Driver — 配置选项 update_routing_table_timeout 和 session_connection_timeout 已移除。常规的心跳机制足以避免驱动程序卡住。其他活跃性检查配置选项可用，但通常不需要（keep_alive，liveness_check_timeout）。

已移除

5.0

Result、Session 和 Transaction 不能再从 neo4j.work 导入。请改为从 neo4j 导入。

已移除

5.0

ServerInfo — ResultSummary.server.version_info 已移除。请改为使用 ResultSummary.server.agent、ResultSummary.server.protocol_version，或调用 dbms.components Cypher 过程。

已移除

5.0

Duration — 构造函数不再接受 subseconds。请改为使用 milliseconds、microseconds 或 nanoseconds。

已移除

5.0

Duration — 属性 subseconds 已移除。请改为使用 nanoseconds。

已移除

5.0

Duration — 属性 hours_minutes_seconds 已移除。请改为使用 hours_minutes_seconds_nanoseconds。

已移除

5.0

DateTime — 属性 hour_minute_second 已移除。请改为使用 hour_minute_second_nanosecond。

已移除

5.0

DateTime — 属性 second 返回一个整数而不是浮点数。使用 nanosecond 获取亚秒信息。

已变更

5.0

DateTime 对象上的所有数学运算都在（月、日、纳秒）上按元素进行。这改变了 //、%、/ 和 * 的工作方式。
年等于 12 个月。周等于 7 天。
秒、毫秒、微秒和纳秒会根据需要隐式转换为纳秒或秒。
乘法和除法允许使用浮点数，但结果始终为整数值（四舍五入到最接近的偶数）。

已变更

5.0

Time — 构造函数不再接受浮点数作为 second。请改为使用 nanosecond。

已移除

5.0

Time — 属性 second 返回一个整数而不是浮点数。使用 nanosecond 获取亚秒信息。

已变更

5.0

Time — ticks 属性的类型从浮点数变为整数。现在它表示自午夜以来的纳秒数，而不是秒数。

已变更

5.0

Time — 属性 ticks_ns 已重命名为 ticks。

已移除

5.0

Time — 属性 hour_minute_second 已移除。请改为使用 hour_minute_second_nanosecond。

已移除

5.0

Session — 方法 .read_transaction() 和 .write_transaction() 已弃用，转而使用 .execute_read() 和 .execute_write()。通过新方法，事务函数的第一个参数是一个 ManagedTransaction 对象。它的行为类似于常规的 Transaction 对象，但它不提供 .commit()、.rollback()、.close() 和 .closed() 方法。

已弃用

5.3

包别名 neo4j-driver 已弃用。从 6.0.0 版本开始，它将停止接收更新。请改为安装 neo4j。

已弃用

5.0

Node, Relationship — 属性 id (int) 已弃用，转而使用 element_id (str)。这也影响 Graph 对象，因为使用整数对 graph.nodes[...] 和 graph.relationships[...] 进行索引已弃用，转而使用字符串进行索引。

已弃用

属性
索引

5.0

通过 __del__()（析构函数）隐式关闭驱动程序和会话已弃用。此行为是不确定的，因为无法保证析构函数会被调用。取而代之的是发出 ResourceWarning。
显式调用 driver.close() 或通过 with 语句创建驱动程序。

已弃用

5.0

导入以下模块已弃用且没有替代品，因为它们是内部模块，不应由客户端代码使用：neo4j.packstream、neo4j.routing、neo4j.config、neo4j.meta、neo4j.data。

ExperimentalWarning（以前在 meta 中）应直接从 neo4j 导入。
neo4j.meta.version 通过 neo4j.__version__ 暴露。

已弃用

5.0

Driver — 配置选项 trust 已弃用。新选项 trusted_certificates 和 ssl_context 可用。

已弃用

5.0

Session — 方法 .last_bookmark() 已弃用，转而使用 .last_bookmarks()。逻辑类似，但新方法返回 neo4j.Bookmarks 而不是 str。

已弃用

5.0

neo4j.Bookmark 已弃用，转而使用 neo4j.Bookmarks。

已弃用

5.0

从 neo4j.time 导入子模块已弃用。请改为直接从 neo4j.time 导入所有内容。

已弃用

5.7

导入 neo4j.work 及其子模块已弃用。请改为直接从 neo4j 导入所有内容。

已弃用

5.0

以下对象已弃用且没有替代品，因为它们是内部对象，不应由客户端代码使用：neo4j.spatial.hydrate_point、neo4j.spatial.dehydrate_point、neoj4.Config、neoj4.PoolConfig、neoj4.SessionConfig、neoj4.WorkspaceConfig、neo4j.data.DataDehydrator、neo4j.data.DataHydrator。

已弃用

5.22

类 SummaryNotificationPosition 已弃用，转而使用 SummaryInputPosition。

已弃用

5.0

未记录的方法 Neo4jError.is_fatal_during_discovery() 和 Neo4jError.invalidates_all_connections() 已弃用且没有替代品。

已弃用

5.26

未记录的方法 Neo4jError.hydrate() 已弃用且没有替代品。
更改 Neo4jError 的属性已弃用。

已弃用

© . All rights reserved.