跳到主要内容

建立连接

使用 DriverManager.getConnection(...) 建立 JDBC 连接：

将地址替换为实际数据库地址；启用认证时，取消认证配置的注释，并从应用配置中提供自己的凭据，不要将真实密码写入源码。

String url = "jdbc:dbvisitor:mongo://127.0.0.1:27017/testdb";
java.util.Properties properties = new java.util.Properties();
properties.setProperty("socketTimeout", "5000");
// 服务端启用认证时配置：
// properties.setProperty("user", "YOUR_USER");
// properties.setProperty("password", "YOUR_PASSWORD");
// properties.setProperty("mechanism", "SCRAM-SHA-256");
try (java.sql.Connection connection = java.sql.DriverManager.getConnection(url, properties)) {
    // 在此通过 JDBC 执行命令；退出代码块时自动关闭连接。
}

/testdb 指定数据库，同时用于默认认证库，应与账号配置匹配。多主机示例为 jdbc:dbvisitor:mongo://host1:27017;host2:27017/testdb。这是适配器 URL，不是可直接透传任意参数的 MongoDB 客户端 URI。

配置连接参数​

参数可通过 properties.setProperty("参数名", "参数值") 配置，也可放在 URL 的 ?name=value&other=value 部分；已有查询参数时用 & 追加。同名参数以 URL 为准，覆盖 Properties。URL 解析不会执行百分号解码；密码、token 以及包含 & 的值应放在 Properties 中，并避免记录到日志。

参数名称、默认值、单位及限制见连接参数。只使用适配器文档列出的参数，不能将厂商 SDK 的任意选项直接当作 JDBC 参数。

连接建立后的命令执行与结果读取见查询操作和数据写入。

用户名与密码​

在 Properties 中设置 user、password，按需设置 mechanism=SCRAM-SHA-256。JDBC URL 中的数据库同时用于认证。如果账号属于 admin，而操作数据库是 testdb，应通过 customMongo 使用带 authSource=admin 的原生 URI；直接在 JDBC URL 中添加 authSource 不会配置认证库。

多节点连接​

使用 jdbc:dbvisitor:mongo://host1:27017;host2:27017/testdb 向 MongoDB 客户端提供种子地址，不要混合无关的数据库实例。需要指定副本集名称或使用 mongodb+srv:// URI 时，通过 customMongo 配置。

TLS 与证书​

默认客户端不启用 TLS。通过 customMongo 配置原生客户端 URI 或 MongoClientSettings。下例从应用环境变量 MONGODB_URI 读取 URI，例如 mongodb://USER:PASSWORD@mongo.example.com:27017/testdb?authSource=admin&tls=true。凭据中的特殊字符按 MongoDB URI 规则编码，不要记录该 URI。JDBC URL 的数据库路径仍决定命令操作的数据库。

public class SecureMongoFactory implements net.hasor.dbvisitor.adapter.mongo.CustomMongo {
    @Override
    public com.mongodb.client.MongoClient createMongoClient(
            String jdbcUrl, java.util.Map<String, String> props) {
        String uri = System.getenv("MONGODB_URI");
        return com.mongodb.client.MongoClients.create(uri);
    }
}

建立 JDBC 连接时注册工厂：

java.util.Properties properties = new java.util.Properties();
properties.setProperty("customMongo", SecureMongoFactory.class.getName());
try (java.sql.Connection connection = java.sql.DriverManager.getConnection(
        "jdbc:dbvisitor:mongo://mongo.example.com:27017/testdb", properties)) {
    // 在此通过 JDBC 执行命令。
}

使用私有 CA 时，在 JVM 信任库或工厂的 SSL 上下文中配置信任证书；双向 TLS 还需配置客户端证书与私钥。保留证书和主机名校验，不要使用跳过校验的方式连接。本驱动没有内置的 JDBC PEM 证书参数。

自定义客户端​

customMongo 指定实现 net.hasor.dbvisitor.adapter.mongo.CustomMongo 的工厂类，方法为 createMongoClient(String jdbcUrl, Map<String, String> props)。工厂返回客户端由 JDBC 连接使用和关闭。高级客户端配置由工厂自行设置，不能套用 Milvus 的 TLS 参数。

URL 的数据库路径优先于 database 属性，亦用于默认认证库。未选数据库时不能使用 db 前缀。设置连接超时须通过 customMongo 配置客户端，不能使用 connectTimeout 连接参数。选择 X-509 认证机制本身不等于启用了 TLS。

工厂类须位于应用类路径中，并提供可访问的无参构造方法。工厂自行处理地址、认证、TLS 和超时；JDBC 参数会传给工厂，但不会自动应用到工厂创建的客户端。每次调用应返回独立客户端，避免多个 JDBC 连接共享同一客户端后相互关闭。