Neo4j JDBC 驱动程序

© 2023-2024

摘要

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

此驱动程序由 Neo4j 正式支持和认可。它是一个独立的驱动程序，独立于且 **不** 建立在 通用 Neo4j Java 驱动程序 之上。虽然后者提供了一种 Neo4j 特有的方式来从 Java 访问 Neo4j，但 JDBC 驱动程序符合 JDBC 4.3。

本文档将 **此** 驱动程序称为 Neo4j JDBC 驱动程序，将惯用的 Neo4j 驱动程序称为 通用 Neo4j Java 驱动程序。

介绍

JDBC 代表“Java 数据库连接”，因此并不局限于关系型数据库。然而，JDBC 的术语、定义和行为受到 SQL 和关系型数据库的高度影响。由于 Neo4j 是一个图数据库，与关系型数据库具有截然不同的范式，并且在某些领域的行为是非标准化的，因此在某些地方可能存在一些细节无法 100% 映射，我们将在本文档中确保向您介绍这些内容。

本文档重点介绍安装、使用和配置 Neo4j JDBC 驱动程序，并讨论驱动程序的设计选择。虽然我们确实提供了可运行的示例，展示如何使用 JDBC 与 Neo4j 进行交互，但这并非关于如何正确使用 JDBC 作为 API 的文档。

Neo4j JDBC 驱动程序在客户端需要 JDK 17，在服务器端需要 Neo4j 5.5+。要将其与 Neo4j 集群一起使用，必须在集群上启用服务器端路由。

功能

  • 完全支持 Java 模块系统

  • 符合 JDBC 4.3

  • 可以运行任何 Cypher® 语句

  • 尽可能完整地实现 DatabaseMetaData 和 ResultSetMetaData，使用近乎无模式的数据库和非常灵活的结果集，允许从 ETL 和 ELT 工具自动检索元数据

  • 提供 SPI 来挂钩从 SQL 到 Cypher 的翻译器

  • 提供可选的默认实现，将许多 SQL 语句转换为语义上相似的 Cypher 语句

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

与通用 Neo4j Java 驱动程序相比，没有连接池和事务管理是 Neo4j JDBC 驱动程序的一大优势。它允许选择和使用任何数据库连接池系统，例如 HikariCP 和事务管理，例如 Jakarta Transactions。

限制

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

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

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

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

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

  • 没有“正确”的方法将 JOIN 语句映射到关系，因此效果可能不尽相同

何时使用 Neo4j JDBC 驱动程序？

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

  • 对于熟悉 JDBC 并希望继续使用该 API 但希望使用 Cypher 和 Neo4j 的人来说，这是一个更轻松的入门方式

  • 对于像 Jakarta EE 这样的生态系统集成，其事务管理直接支持任何符合 JDBC 规范的驱动程序

  • 与数据库迁移工具（例如 Flyway）集成

**没有必要重新设计基于通用 Neo4j Java 驱动程序构建的应用程序以迁移到此驱动程序。**如果您的生态系统已经提供了基于通用 Neo4j Java 驱动程序的更高层级集成，例如 Spring Data Neo4j (SDN) for Spring，则无需切换到其他东西。在 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 驱动程序的旧版本遮蔽了一些依赖项，例如 Jackson 以及其他日志记录框架。这对类路径造成了影响，并且在日志记录的情况下，会导致运行时问题。

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

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

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