配置

驱动程序类名

Neo4j JDBC 驱动程序是 org.neo4j.jdbc.Neo4jDriver。使用现代 Java 工具，您应该不需要直接接触此类，但有些连接池和前端会向您询问此类。该类是公共 API。

我们还提供 org.neo4j.jdbc.Neo4jDataSource 作为 javax.sql.DataSource。

因果集群和书签

Neo4j JDBC 驱动程序默认使用书签在所有 Neo4j 部署中提供因果一致性。书签在驱动程序级别本身进行管理，而不是在驱动程序实例生成的连接上进行管理，因此由一个实例生成的连接将参与同一事务因果链。来自不同驱动程序实例的连接不会使用同一组书签，并且没有内置机制可以启用此功能。如果您想要或需要此功能，您可以直接访问 Neo4jDriver 类型以检索当前已知的书签集并将它们传递给另一个驱动程序实例。

Neo4j 事务元数据

Neo4j 支持将元数据附加到事务，请参阅 SHOW TRANSACTIONS。由于 JDBC 规范中没有明确的事务对象，因此 Neo4j JDBC 驱动程序需要另一种机制来使这些配置成为可能。

JDBC 驱动程序提供扩展接口 Neo4jMetadataWriter。我们的驱动程序、连接实现和所有语句变体都可以相应地解包。配置是累加的：为驱动程序实例配置的元数据将用于该驱动程序生成的所有连接，连接可以添加更多元数据，语句也可以添加自己的元数据。在语句上添加的元数据优先于连接元数据，而连接元数据又优先于驱动程序元数据

清单 1. 配置事务元数据

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Map;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;

import org.neo4j.jdbc.Neo4jDriver;
import org.neo4j.jdbc.Neo4jMetadataWriter;

public final class TransactionMetadata {

    private static final Logger LOGGER = Logger.getLogger(TransactionMetadata.class.getPackageName());

    public static void main(String... args) throws SQLException {
        var url = "jdbc:neo4j://localhost:7687";

        var driver = (Neo4jDriver) DriverManager.getDriver(url);
        driver.withMetadata(Map.of("md_from_driver", "v1", "will_be_overwritten", "irrelevant"));

        var properties = new Properties();
        properties.put("user", "neo4j");
        properties.put("password", "verysecret");

        try (
            var con = driver.connect(url, properties)
                .unwrap(Neo4jMetadataWriter.class)
                .withMetadata(Map.of("md_from_connection", "v2", "will_be_overwritten", "xxx"))
                .unwrap(Connection.class);
            var statement = con.createStatement()
                .unwrap(Neo4jMetadataWriter.class)
                .withMetadata(Map.of("md_from_stmt", "v3", "will_be_overwritten", "v4"))
                .unwrap(Statement.class)
        ) {
            try (var result = statement.executeQuery("SHOW TRANSACTIONS YIELD metaData")) {
                while (result.next()) {
                    var metaData = result.getObject("metaData", Map.class);
                    LOGGER.log(Level.INFO, "{0}", metaData);
                }
            }
        }
    }
}

输出将类似于此

Juli 17, 2024 1:18:16 PM org.neo4j.jdbc.docs.TransactionMetadata main
INFORMATION: {md_from_driver=v1, md_from_connection=v2, md_from_stmt=v3, will_be_overwritten=v4}

URL 和连接属性

Neo4j JDBC 驱动程序的规范 URL 格式为

jdbc:neo4j://<host>:<port>/<database>?param1=value1&param2=value2

数据库名称和所有查询参数都是可选的，可以省略。所有配置参数都可以作为查询参数或通过 java.util.Properties 对象传递。后者有时由工具为您定义。

关于身份验证，我们建议遵循 JDBC 规范，该规范不鼓励使用任何形式的 URL 身份验证。如果所有查询参数包含特殊字符，则必须进行百分比编码，例如 …?param1=space%20separated。

驱动程序支持以下 URI 方案，这些方案调整安全配置

neo4j - 不加密。
neo4j+s - 启用加密，并且仅接受来自服务器的由已知证书颁发机构签名的 SSL 证书。
neo4j+ssc - 启用加密并接受自签名证书（必须将其添加到证书存储区）。

不支持 bolt URI 方案。

驱动程序接受以下配置参数，作为属性或 URL 查询参数

表 1. 配置参数
名称	类型	含义	默认值
`timeout`	`整数`	以毫秒为单位的连接获取超时时间	`1000`
`agent`	`字符串`	用户代理	`neo4j-jdbc`
`enableSQLTranslation`	`布尔值`	启用从 SQL 到 Cypher 的自动转换的标志（需要类路径上的转换器）	`false`
`cacheSQLTranslations`	`布尔值`	启用转换缓存的标志。SQL 转换不是“免费的”：SQL 解析需要一些时间，Cypher^® 呈现也是如此。此外，我们可能会查找元数据以能够投影单个属性。如果这花费的时间太长，则可以缓存转换。	`false`
`rewritePlaceholders`	`布尔值`	允许您在 Cypher 语句中使用 `?` 作为占位符的标志（如 JDBC 所需）。这些将自动重写为 `$1`、`$2` … `$n`，从 1 开始，以便编号与基于 1 的 JDBC 索引匹配。	当 `enableSQLTranslation` 为 `false` 时为 `true`，否则为 `false`
`ssl`	`布尔值`	可选标志，替代 `neo4j+s`。例如，它可用于以编程方式启用完整的 SSL 链。	`null`
`sslMode`	`Enum<SSLMode>`	用于对 SSL 配置进行细粒度控制的可选配置。允许的值为 `disable`、`require`、`verify-full`。请参阅 <ssl_mode, 了解 SSL 模式>>。	`null`
`user`	`字符串`	用于身份验证的用户名（主体）。不建议作为 URL 查询参数用于安全原因。	`neo4j`
`password`	`字符串`	用于身份验证的密码（凭据）。不建议作为 URL 查询参数用于安全原因。	`password`
`authRealm`	`字符串`	用于身份验证的领域。不建议作为 URL 查询参数用于安全原因。	`null`
`authScheme`	`字符串`	要使用的身份验证方案。不建议作为 URL 查询参数用于安全原因。当前支持的值为 `basic`（默认值）用于基本身份验证。 `bearer` 用于承载身份验证 (SSO)。`password` 应设置为承载令牌；`user` 和 `authRealm` 无效。 `kerberos` 用于 Kerberos 身份验证。需要将 `password` 设置为 Kerberos 票证；`user` 和 `authRealm` 无效。 `none` 如果服务器上已禁用身份验证。属性 `user`、`password`、`authRealm` 无效。	`basic`
`useBookmarks`	`布尔值`	启用书签管理以实现完整的因果集群支持。默认情况下启用此功能，并且建议在所有使用连接池的场景中使用此设置。如果禁用它，它将仅对特定连接禁用。从驱动程序实例到相同或其他数据库检索的其他连接不受影响，并且各个连接仍将管理其书签。	`true`

获取驱动程序或连接实例

本节可能仅适用于您将 Neo4j JDBC 驱动程序用作应用程序开发的一部分，而不是将其用作前端工具（如 DBeaver、DataGrip 或基于 UI 的 ETL 工具）的一部分。

获取连接的最简单方法是直接通过 java.sql.DriverManager。

清单 2. 获取到 Neo4j 服务器的 JDBC 连接

import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;

class Configuration {

    void obtainConnection() throws SQLException {

        var url = "jdbc:neo4j://localhost:7687";
        var username = "neo4j";
        var password = "verysecret";
        var connection = DriverManager.getConnection(url, username, password);
    }

}

虽然我们的连接实现是线程安全的，但它只允许每个连接一个并发事务（如 JDBC 规范所规定）。对于多线程应用程序，请使用连接池。有 HikariCP，但通常应用程序服务器和容器/框架会自带连接池。安全使用任何一个，因为 Neo4j JDBC 驱动程序不执行内部池化。

如果您需要访问 Neo4j 驱动程序本身的实例，可以使用以下方法

清单 3. 获取 Neo4j JDBC 驱动程序的实例

import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;

class Configuration {

    void obtainDriverAndConnection() throws SQLException {

        var url = "jdbc:neo4j://localhost:7687";
        var driver = DriverManager.getDriver(url);

        var properties = new Properties();
        properties.put("username", "neo4j");
        properties.put("password", "verysecret");
        var connection = driver.connect(url, properties);
    }

}

使用 SSL 保护您的连接

Neo4j JDBC 驱动程序支持通用 Java 驱动程序相同的 SSL 选项，以及相同的 URL 协议，使用 +s 或 +ssc 作为所需安全级别的附加指示符。

相同的配置也可以通过 URL 查询参数或传递给 DriverManager 或驱动程序实例的属性中的条目来实现。只要您没有指定相互矛盾的值，就可以组合这两种方法。

了解 SSL 模式

以下列表按安全级别升序排列

disable — （默认），“我不关心安全性，也不想为加密支付开销。”
require — “我希望我的数据被加密，并且我接受开销。我相信网络将确保我始终连接到我想要的服务器。”（服务器必须支持加密，不执行主机名/CA 验证。这节省了正确证书的麻烦，并且仅在私有网络上安全；不应在公共网络上真正使用。）
verify-full — “我希望我的数据被加密，并且我接受开销。我想确保我连接到我信任的服务器，并且它是我指定的服务器。”

Neo4j JDBC 驱动程序不包含吊销检查。

最安全的选项也可以通过将 ssl=true 设置为传递给 DriverManager 的查询参数或属性条目来启用。此选项对应于 neo4j+s。另一方面，require 对应于 neo4j+ssc。

额外的枚举允许我们将来可能支持其他模式，例如让服务决定 SSL，或者能够表达对 SSL 的偏好而无需强制要求。

Neo4j 服务器可以提供普通 Bolt 连接和加密 SSL 连接，或者两者之一。您可以使用 neo4j+s 连接这一事实并不意味着您不能仅使用 neo4j 连接，反之亦然。这取决于服务器设置。Neo4j Aura，Neo4j 的托管云服务，仅支持加密连接，因此您*必须*使用 +s、ssl=true 或 sslMode=verify-full。

有效的 URL

以下 URL 均有效

neo4j+s://xyz.databases.neo4j.io: 使用 AuraDB 中的 xzy 实例进行完整验证
neo4j://xyz.databases.neo4j.io?ssl=true: 相同，但使用简写 URL 参数
neo4j://xyz.databases.neo4j.io?sslMode=verfiy-full: 相同，但使用显式模式
neo4j+s://xyz.databases.neo4j.io?ssl=true&sslMode=verify-full: 安全性不高，但不会出错
neo4j+ssc://this.is.a.trustworthy.instance.for.sure.com: 信任任何证书和主机名，但确实使用 SSL
neo4j://my-testing-instance.local: 使用普通连接。

驱动程序仅拒绝相互矛盾的配置，例如

+s 与 ssl=false，或 sslMode 设置为 disable
+ssc 与 ssl=false，或任何不等于 require 的 sslmode

基本上，您不能同时要求使用 SSL 和不使用 SSL。驱动程序提供了几种机制，以便您可以使用具有动态查询参数的固定 URL、动态 URL 或您在编程方式中喜欢的任何配置方式。

使用 .dotenv 文件

当您创建 Neo4j Aura 实例时，系统会要求您下载一个名为 Neo4j-9df57663-Created-2023-06-12.txt 的文本文件。这本质上是一个包含连接到数据库所需信息的 .dotenv 文件。

这些文件可以通过 Neo4jDriver.fromEnv() 直接使用（请参阅通过环境变量获取连接）。此方法存在于多个重载中，允许您配置文件名和目录。此外，构建器允许您配置 Aura 文件中未包含的选项。