Neo4j JDBC 驱动程序

© 2023-2025

摘要

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

此驱动程序获得 Neo4j 的官方支持和认可。它是一个独立的驱动程序，独立于且不构建在 通用 Neo4j Java 驱动程序 之上。虽然后者提供了从 Java 访问 Neo4j 的 Neo4j 惯用方式，但此 JDBC 驱动程序遵循 JDBC 4.3 规范。

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

简介

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

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

Neo4j JDBC 驱动程序要求客户端安装 JDK 17，服务器端安装 Neo4j 5.5+。要在 Neo4j 集群中使用它，必须在集群上启用服务器端路由。

特性

  • 完全支持 Java 模块系统

  • 遵循 JDBC 4.3 规范

  • 可以运行任何 Cypher® 语句

  • 在几乎无模式的数据库和非常灵活的通用结果集中，尽可能全面地实现了 DatabaseMetaData 和 ResultSetMetaData，支持从 ETL 和 ELT 工具自动检索元数据

  • 提供一个 SPI（服务提供者接口），用于接入 SQL 到 Cypher 的转换器

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

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

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

不进行任何连接池和事务管理是 Neo4j JDBC 驱动程序相对于通用 Neo4j Java 驱动程序的优势。它允许选择和使用任何数据库连接池系统，例如 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 的用户，提供更简单的 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 驱动程序的旧版本会内嵌一些依赖项，例如 Jackson 以及额外的日志框架。这会给类路径带来负担，并且在日志记录的情况下，会导致运行时问题。

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

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

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

© . All rights reserved.