Neo4j JDBC 驱动程序

© 2023-2025

摘要

这是官方 Neo4j JDBC 驱动程序的手册。

该驱动程序由 Neo4j 官方支持和认可。它是一个独立的驱动程序，不依赖于通用 Neo4j Java 驱动程序，也不构建在其之上。虽然通用驱动程序提供了一种从 Java 访问 Neo4j 的地道方式，但此 JDBC 驱动程序遵循 JDBC 4.3 标准。

本文档将本驱动程序称为 Neo4j JDBC 驱动程序，将地道的 Neo4j 驱动程序称为通用 Neo4j Java 驱动程序。

简介

JDBC 代表“Java 数据库连接”（Java Database Connectivity），因此它不仅限于关系型数据库。尽管如此，JDBC 的术语、定义和行为在很大程度上受到了 SQL 和关系型数据库的影响。由于 Neo4j 是一种图数据库，其范式与关系型数据库完全不同，且在某些方面的行为是非标准化的，因此可能存在一些无法完全对应的地方，我们会在本文档中为您详细说明。

本文档侧重于安装、使用和配置 Neo4j JDBC 驱动程序，并讨论该驱动程序的设计选择。虽然我们提供了展示如何在 Neo4j 中使用 JDBC 的可运行示例，但本文档并非关于如何正确使用 JDBC 作为 API 的教程。

Neo4j JDBC 驱动程序要求客户端具备 JDK 17，服务端具备 Neo4j 5.5+。若要将其与 Neo4j 集群配合使用，必须在集群上启用服务端路由。

特征

  • 完全支持 Java 模块系统

  • 遵循 JDBC 4.3 标准

  • 可以执行任何 Cypher® 语句

  • 在几乎无模式（schemaless）的数据库和极其灵活的结果集环境下，尽可能完整地实现 DatabaseMetaData 和 ResultSetMetaData，从而允许 ETL 和 ELT 工具自动获取元数据

  • 提供 SPI 以挂载 SQL 到 Cypher 的翻译器

  • 提供一个可选的默认实现，用于将许多 SQL 语句翻译为语义相似的 Cypher 语句

  • 支持客户端 Cypher 支持的视图

  • 与通用 Neo4j Java 驱动程序或基于该驱动程序的任何 JDBC 驱动程序不同，它可以安全地与 JDBC 连接池一起使用，因为它不执行 JDBC 规范规定之外的内部连接池和事务管理

  • 内置基于令牌的身份验证，包括令牌过期时的重新身份验证，以及一个可选的基于 Keycloak 的 SSO 模块

  • 内置基于 JSON 的对象映射

缺少任何连接池和事务管理是 Neo4j JDBC 驱动程序优于通用 Neo4j Java 驱动程序的地方。它允许用户选择和使用任何数据库连接池系统（如 HikariCP）和事务管理系统（如 Jakarta Transactions）。

限制

  • 数据库元数据使用 Neo4j 的模式方法获取，例如 db.labels, db.schema.nodeTypeProperties()，这些方法可能并不总是准确的

  • 虽然单标签节点可以自然地映射到表名，但具有多个标签的节点则不能

  • 没有可靠的方法可以始终确定节点属性的数据类型，因为这需要读取所有属性（本驱动程序不会这样做）

  • 一些 JDBC 功能尚不支持（例如 CallableStatement）；某些功能将永远不会被支持

  • SQL 到 Cypher 的翻译器仅支持有限的子句和 SQL 结构，这些结构可以等效地翻译为 Cypher（参见 支持的语句）

  • 没有将 JOIN 语句映射到关系的“正确”方式，因此实际效果可能会有所不同

何时使用 Neo4j JDBC 驱动程序？

  • 与不提供基于通用 Neo4j Java 驱动程序集成的 ETL 和 ELT 工具集成

  • 为熟悉 JDBC 的人提供一种更容易进入 Neo4j 的方式，他们希望继续使用该 API，但同时使用 Cypher 和 Neo4j

  • 为像 Jakarta EE 这样生态系统的集成提供支持，其事务管理直接支持任何符合 JDBC 标准的驱动程序

  • 与 Flyway 等数据库迁移工具集成

没有必要为了迁移到本驱动程序而重新设计基于通用 Neo4j Java 驱动程序的现有应用程序。 如果您的生态系统已经提供了基于通用 Neo4j Java 驱动程序的高级集成（例如针对 Spring 的 Spring Data Neo4j (SDN)），则无需切换。对于 Quarkus，Neo4j JDBC 驱动程序是一个值得考虑的选择：尽管我们确实提供了对 通用 Neo4j Java 驱动程序 的集成，但与本驱动程序相比，该集成不支持 Quarkus 的事务系统。

由于将此驱动程序与 Hibernate 一起使用几乎没有动力（Neo4j-OGM 或 SDN 是 Neo4j 的最佳替代方案），因此可以尝试使用 Spring Data JDBC。

与本驱动程序先前版本及其他 Neo4j JDBC 驱动程序的区别

还存在其他几个 Neo4j 的 JDBC 驱动程序，最著名的是本驱动程序的 4 和 5 版本。它们大多数（如果不是全部）都封装了通用 Neo4j Java 驱动程序，并在此基础上实现了 JDBC 规范。这带来了一些问题

  • 您最终会得到一个连接池的连接池，因为通用 Neo4j Java 驱动程序管理着一个连接池，而 JDBC 驱动程序则将此任务委托给专门的池解决方案。

  • 通用 Neo4j Java 驱动程序的事务管理与 JDBC 管理事务的方式不一致。

  • 旧版本的 Neo4j JDBC 驱动程序对一些依赖项进行了 Shade 处理，例如 Jackson 以及额外的日志框架。这会对类路径造成负担，并且在日志记录方面，会导致运行时问题。

  • 具有 SQL 到 Cypher 翻译层的现有驱动程序是“只读”的，不支持写入语句，因此不能用于旨在将数据摄入 Neo4j 的 ETL 用例。

与先前版本不同，此驱动程序不支持自动重塑或扁平化结果集。如果您查询节点、关系、路径或映射，则应在结果集上使用 getObject 并将其转换为适当的类型（您可以在 org.neo4j.jdbc.values 包中找到所有这些类型）。不过，默认的 SQL 到 Cypher 翻译器（在连接到数据库时）会找出节点具有哪些属性，并将星号 (*) 转换为节点和关系的各个列，就像您运行 SELECT * 语句时所期望的那样。

有关从其他驱动程序升级/迁移到此驱动程序的信息，请参阅 从旧版本或其他 Neo4j JDBC 驱动程序迁移。

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