---
title: "数据库 URL - JDBC 驱动程序  V2.4.3 | OceanBase 文档中心"
description: "数据库 URL 数据库 URL 是字符串，用于连接到 OceanBase 数据库并实现指定功能。 OceanBase Connector/J 允许在 URL 中添加额外的连接属性，所支持的完整的 URL 语法如下： jdbc:oceanbase:hamode://host:port/databasename?[use…"
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*bhcER5Qvet8AAAAAAAAAAAAADiGDAQ/original) JDBC 驱动程序 V 2.4.3

# 数据库 URL

更新时间：2026-04-09 15:20:59

[编辑](https://github.com/oceanbase/connector-j-doc/edit/V2.4.3/zh-CN/300.user-guide/200.data-source-and-url/400.database-url.md)  

数据库 URL 是字符串，用于连接到 OceanBase 数据库并实现指定功能。

OceanBase Connector/J 允许在 URL 中添加额外的连接属性，所支持的完整的 URL 语法如下：

```javascript
jdbc:oceanbase:hamode://host:port/databasename?[username&password]&[opt1=val1&opt2=val2...]

```

OceanBase Connector/J 允许在 URL 中添加额外的连接属性。说明如下：

- 属性 `hamode` 是指高可用模式，可选的参数是 `loadbalance`。
 - 属性 `[username/password]` 为可选的用户名和密码，用于唯一标识应用程序所连接的数据库。
 - 属性 `[opt1=val1&opt2=val2...]` 为额外的连接属性，即 URL 参数。

示例如下：

```javascript
jdbc:oceanbase://10.XXX.XXX.XXX:1001/unittests?user=**u**@sys&password=******&
pool=false&useBulkStmts=true&rewriteBatchedStatements=false&useServerPrepStmts=true

```

本节主要介绍 OceanBase Connector/J 可选的 URL 参数。

## OceanBase Connector/J 特有参数

| 参数 | 描述 |
| --- | --- |
| supportLobLocator | LOB Locator 开关。默认值：`true`。 |
| useObChecksum | Checksum 开关，是 OceanBase Protocol 2.0 协议的一个配置。默认值：`true`。 |
| useOceanBaseProtocolV20 | 是否使用 OceanBase Protocol 2.0。默认值：`true`。 |
| complexDataCacheSize | ComplexData Cache 的大小。默认值：50。 |
| cacheComplexData | 是否缓存 `ComplexData`。默认值：`true`。 |
| useSqlStringCache | 是否将 SQLString 缓存在客户端。默认值：`false`。 |
| useServerPsStmtChecksum | 是否使用 PS 的 Checksum。默认值：`true`。 |
| connectProxy | 配置连接到 ODP。此时不能执行对业务 SQL 的查询，只能对 ODP 进行配置或者配置查询。默认值：`false`。 |
| obProxySocket | 启用富客户端功能。默认值：""。 |
| enableOb20Checksum | 基于 OB2.0 协议，控制 OceanBase Connector/J 请求包的头部校验和、尾部校验和。默认值为 `ture`，表示计算 CRC 校验和；否则校验和为 0。 |
| ocpAccessInterval | 访问 OCP 的间隔时间（单位：分钟）。默认值：5。 |
| httpConnectTimeout | 设置指定的超时值（单位：毫秒），以在打开指向此 URLConnection 引用的网络资源的通信链接时使用。默认值：0。 |
| httpReadTimeout | 当 URLConnection 建立到资源时，非零值指定从输入流读取时的超时时间（单位：毫秒）。默认值：0。 |
| useOraclePrepareExecute | 开启 PS 二合一协议，Oracle 模式 `preparedStatement` 在使用 `COM_STMT_PREPARE_EXECUTE` 执行之前不会与 server 通信。默认值：`false`。     当前版本 `useOraclePrepareExecute` 为 `true` 时，`useServerPrepStmts` 被设为 `true`。V2.4.5 之前版本需要共同使用，才能开启 PS 二合一协议。 |

## 基本参数

| **参数** | **描述** |
| --- | --- |
| user | 数据库用户名称。 |
| password | 数据库用户密码。 |
| rewriteBatchedStatements | 对于插入查询，重写 `batchedStatement` 以在单个 `executeQuery` 中执行。例如 `insert into ab (i) values (?)with first batch values = 1, second = 2` 被重写为 `insert into ab (i) values (1), (2)`。 如果无法用"多值"重写查询，则将使用多查询重写 `INSERT INTO TABLE(col1) VALUES (?) ON DUPLICATE KEY UPDATE col2=?` 并附加值[1,2] 和 [2,3] ，将被重写为 `INSERT INTO TABLE(col1) VALUES (1) ON DUPLICATE KEY UPDATE col2=2;INSERT INTO TABLE(col1) VALUES (3) ON DUPLICATE KEY UPDATE col2=4`。 `rewriteBatchedStatements`处于活跃状态时，`useServerPrepStmts` 选项被设置为 `false`。 默认值：`false`。 |
| useServerPrepStmts | 在执行之前，在服务器端准备 `PrepareStatement`。重复使用相同查询的应用程序具有激活该选项的值，但通常情况是使用直接命令（文本协议）。如果 `rewriteBatchedStatements` 设置为 `true`，则此选项将设置为 `false`。 默认值：`false`。 |
| useBatchMultiSend | 驱动程序可以批量发送查询。 如果设置为 `false`，查询将逐一发送，等待返回结果后再发送下一个。 如果设置为 `true`，则将根据与 `useBatchMultiSendNumber` 选项值（默认为 `100`）批量发送查询，如果超出数据包允许发送的查询数量，则根据 `max_allowed_packet` 服务器变量发送查询，之后再读取结果，从而避免了客户端和服务器不在同一主机上时发生的大量网络延迟。 默认值：`true` |
| allowLocalInfile | 允许从文件加载数据。 默认值：`false`。 |
| useMysqlMetadata | `databaseMetaData.getDatabaseProductName()` 根据服务器类型返回 Oracle 或 MySQL。 |
| characterEncoding | 支持 MySQL URL 选项的字符编码。默认值：`utf8`。 |

## 网络连接参数

| 参数 | 描述 |
| --- | --- |
| socksProxyHost | 要连接的 `SOCKS` 主机名称或 IP 地址。 默认值：`null` |
| socksProxyPort | `SOCKS` 服务器的端口。 默认值：1080。 |
| socketFactory | 要使用自定义 Socket Factory，请将其设置为 `javax.net.SocketFactory` 类的全名。 |
| connectTimeout | 连接超时值，以毫秒为单位，如果没有超时则为零。 默认值：30000。 |
| socketTimeout | 定义了网络 Socket 超时（`SO_TIMEOUT`），以毫秒为单位。值为 0 时将禁用此超时。也可以通过设置系统变量 `max_statement_time` 来限制查询时间。 默认值：0（标准配置）或 10000 ms。 |
| localSocketAddress | 将连接 Socket 绑定到本地（UNIX 域）Socket 的主机名或 IP 地址。 |
| tcpKeepAlive | 如果使用 TCP/IP 连接，驱动程序是否应该设置 `SO_KEEPALIVE`。 默认值：`true`。 |
| tcpNoDelay | 如果使用 TCP/IP 连接，驱动程序是否应该设置 `SO_TCP_NODELAY`（禁用 Nagle 算法）。 默认值：`true`。 |
| tcpRcvBuf | 设置 TCP 缓冲区（`SO_RCVBUF`）的大小。 默认值为 0，表示使用该属性的平台默认值。 |
| tcpSndBuf | 设置 TCP 缓冲区（`SO_SNDBUF`）的大小。 默认值为 0，表示使用该属性的平台默认值。 |

## TLS 参数

| **参数** | **描述** |
| --- | --- |
| useSSL | 强制连接时是否使用 SSL/TLS。 默认值：`false`。 |
| trustServerCertificate | 使用 SSL/TLS 时，不检查服务器的证书。 默认值：`false`。 |
| serverSslCert | 允许以 DER 形式提供服务器的证书或服务器的 CA 证书。该服务器将被添加到 `trustStor`，这样可以信任自签名证书。 可以使用以下三种方式之一：   - serverSslCert=/path/to/cert.pem (full path to certificate) - serverSslCert=classpath:relative/cert.pem (relative to current classpath) - as verbatim DER-encoded certificate string "------BEGIN CERTIFICATE-----" |
| keyStore | 包含客户端私钥存储和关联证书的 keyStore 文件的文件路径（类似于Java 系统属性 `javax.net.ssl.keyStore`，但确保仅使用私钥的条目）。旧别名 `clientCertificateKeyStoreUrl`。 |
| keyStorePassword | 客户端证书 keyStore 的密码（类似于 Java 系统属性 `javax.net.ssl.keyStorePassword`）。旧别名 `clientCertificateKeyStorePassword` |
| keyPassword | 客户端证书 keyStore 中私钥的密码。（仅当私钥密码与 keyStore 密码不同时才需要）。 |
| trustStore | trustStore 文件的文件路径（类似于 Java 系统属性 `javax.net.ssl.trustStore`，旧别名 `trustCertificateKeyStoreUrl`）将指定的文件用于受信任的根证书。设置后，将覆盖 `serverSslCert`。 |
| trustStorePassword | 受信任的根证书文件的密码（类似于 Java 系统属性 `javax.net.ssl.trustStorePassword`，旧别名 `trustCertificateKeyStorePassword`）。 |
| enabledSslProtocolSuites | 强制将 TLS/SSL 协议强制为一组特定的 TLS 版本（以逗号分隔的列表）。示例："TLSv1，TLSv1.1，TLSv1.2"（也可以使用别名 `enabledSSLProtocolSuites`）默认值：Java 默认值。 |
| enabledSslCipherSuites | 强制使用 TLS/SSL 密码（以逗号分隔的列表）。 示例：" `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384，TLS_DHE_DSS_WITH_AES_256_GCM_SHA384`"。 默认值：使用 JRE 密码。 |
| disableSslHostnameVerification | 使用 SSL 时，驱动程序将对照服务器证书中显示的服务器身份检查主机名（检查备用名称或证书 CN），以防止中间人攻击。 此选项允许停用此验证。当 `trustServerCertificate` 选项设置为 `default` 时，将禁用主机名验证。 |
| keyStoreType | 指明密钥存储类型（JKS/PKCS12）。 默认值为 `null`，表示使用 Java 默认类型。 |
| trustStoreType | 指明信任库类型（JKS/PKCS12）。 默认值为 `null`，表示使用 Java 默认类型。 |

## 性能扩展参数

| 参数 | 描述 |
| --- | --- |
| useLocalSessionState | 驱动程序是否使用自动提交（由 `Connection.setAutoCommit()` 设置）和事务隔离（由 `Connection.setTransactionIsolation()` 设置）的内部值以及参考协议维护的事务状态。默认值：`true`。   **说明** 当前版本不支持修改此参数。 |
| useLocalTransactionState | 驱动程序是否使用 MySQL 协议提供的事务中状态来确定 `commit()` 或 `rollback()` 确实已发送到数据库。 默认值：`true`。   **说明** 当前版本不支持修改此参数。 |
| useOceanBaseProtocolV20 | 是否开启 OB2.0 协议，默认开启。 |
| enableFullLinkTrace | 是否开启全链路追踪能力，默认关闭。当 `enableFullLinkTrace` 设置为 `true` 时，`useOceanBaseProtocolV20` 也会被强制修改为 `true`。 |

## 连接池参数

| **参数** | **描述** |
| --- | --- |
| pool | 使用连接池。仅当不使用 DataSource 对象而仅使用连接对象时，此选项才有用。 默认值：`false`。 |
| poolName | 允许标识线程的连接池名称。 默认值：自动生成为 `oceanbase-pool- <pool-index>`。 |
| maxPoolSize | 连接池应包含的最大物理连接数。 默认值：8。 |
| minPoolSize | 如果由于使用时间不超过 `maxIdleTime` 而删除了连接，则将关闭连接并将其从池中删除。`minPoolSize` 指明连接池应始终保持可用的物理连接数，应小于或等于 `maxPoolSize`。 默认值：`maxPoolSize`。 |
| poolValidMinDelay | 当询问连接时，连接池将验证连接状态。如果最近借用了连接，则 `poolValidMinDelay` 允许禁用此验证，避免在频繁重复使用连接的情况下进行无用的验证。0 表示每次请求连接时都要进行验证。 默认值：1000（毫秒）。 |
| maxIdleTime | 不使用连接时，连接可以保留在池中的最长时间（以秒为单位）。此值必须始终低于 `@wait_timeout-45s`。 默认值：600 秒（即 10 分钟），最小值为 60 秒。 |
| staticGlobal | 表明不会更改全局变量 `max_allowed_packet`、`wait_timeout`，`autocommit`、`auto_increment_increment`、`time_zone`、`system_time_zoneandtx_isolation` 的值，从而允许连接池更快地创建新连接。 默认值：`false`。 |
| useResetConnection | 当一个连接为 `closed()`（返回给连接池）时，连接池将重置连接状态。设置此选项后，如果服务器允许，则准备命令将被删除，会话变量将被重置，用户变量将被销毁，从而在应用程序大量使用变量时，服务器可以节省内存。不得与 `useServerPrepStmts` 选项一起使用。 默认值：`false`。 |
| registerJmxPool | 注册 JMX 监视池。 默认值：`true`。 |

## 日志参数

| **参数** | **描述** |
| --- | --- |
| log | 启用日志信息。 默认值：`false`。 |
| maxQuerySizeToLog | 日志中仅显示与该选项大小相对应数量的字符。 默认值：1024。 |
| slowQueryThresholdNanos | 记录执行时间超过此值的查询（如果已定义）。 默认值：1024。 |
| profileSql | 日志查询执行时间。 默认值：`false`。 |

## 其他参数

| **参数** | **描述** |
| --- | --- |
| passwordCharacterEncoding | 指明密码编码字符集。字符集值必须是 Java 字符集。例如：UTF-8。默认值：`null`（即平台的默认字符集）。 |
| useFractionalSeconds | 可以处理亚秒精度的时间戳。默认值：`true`。 |
| allowMultiQueries | 单次执行多个查询的 SQL Stirng 格式。 例如 `insert into ab (i) values (1); insert into ab (i) values (2)`。默认值：`false`。 |
| dumpQueriesOnException | 如果设置为 `true`，则在执行查询期间将引发包含查询字符串的异常。默认值：`false`。 |
| useCompression | 通过 `gzip` 压缩与数据库进行网络通信。当数据库网络开销比较大的时候，可以提供更好的性能。默认值：`false`。 |
| tcpAbortiveClose | 此选项可用于快速连续创建和关闭连接的环境中。通常，短时间内无法在这种环境中创建 Socket，因为所有本地"临时"端口都被 TCP 连接用尽了，并处于 `TCP_WAIT` 状态。使用 `tcpAbortiveClose` 通过重置 TCP 连接（主动关闭或硬关闭）而不是有序关闭来解决此问题。使用 `socket.setSoLinger(true,0)` 进行强制关闭。 |
| tinyInt1isBit | 数据类型映射标志，将 MySQL Tiny 作为 BIT（Boolean）处理。默认值：`true`。 |
| yearIsDateType | 将 Year 作为日期类型处理，而不是数字。默认值：`true`。 |
| sessionVariables | 在建立成功连接时设置的 `<var> = <value>` 对，以逗号分隔会话变量。 |
| localSocket | 如果服务器允许，则可以通过 Unix 域 Socket 连接到数据库。值是 Unix 域 Socket 的路径（即 Socket 数据库参数：`select @@ socket`）。 |
| sharedMemory | 如果服务器允许，则通过共享内存连接到数据库。值是共享内存的基本名称。 |
| interactiveClient | 会话超时由 `thewait_timeoutserver` 变量定义。将 `interactiveClient` 设置为 `true` 将告诉服务器使用 `interactive_timeoutserver` 变量。 默认值：`false`。 |
| useOldAliasMetadataBehavior | 元数据通过 `ResultSetMetaData.getTableName()` 返回物理表名称。如果设置了 `useOldAliasMetadataBehavior`，可以获取表别名。默认值：`false`。 |
| createDatabaseIfNotExist | 在 URL 中创建指定的数据库（如果不存在）。默认值：`false`。 |
| serverTimezone | 定义服务器时区。仅在 GRE 服务器实现不同的服务器时区时使用（最好具有相同的服务器时区）。 |
| cachePrepStmts | 如果 `useServerPrepStmts = true`，则将准备好的信息缓存在 LRU 缓存中，以避免重新准备命令。下次使用该命令时，会将准备好的标识符和参数（如果有）发送到服务器，因而可以避免服务器重新解析查询。 默认值：`false`。 |
| prepStmtCacheSize | 如果 `useServerPrepStmts = true`，则可以定义选项 `cachePrepStmts` 所使用的 Prepared 语句缓存大小。默认值：250。 |
| prepStmtCacheSqlLimit | 如果 `useServerPrepStmts = true`，则大于此阈值的查询将不被缓存。 默认值：2048。 |
| jdbcCompliantTruncation | 截断错误（"在行 ％ 处的列 '％' 的数据被截断"，"在行 ％ 处的列 '％' 的值超出范围"）将被视为错误而不是警告。默认值：`true`。 |
| cacheCallableStmts | 启用/禁用 Callable Statement 的缓存。 默认值：`true`。 |
| callableStmtCacheSize | 如果启用了 `cacheCallableStmts`，则设置驱动程序缓存每个 VM 的 Callable Statement 的数量。默认值：150。 |
| useBatchMultiSendNumber | 当选项 `useBatchMultiSend` 是活跃状态时，设置在读取结果前可以连续发送的最大查询。默认值：100。 |
| connectionAttributes | 当 `performance_schema` 处于活跃状态时，允许以键值对格式（例如：`connectionAttributes = key1：value1，key2，value2）`向服务器发送一些客户端信息。这些信息可以在服务器上的表 `performance_schema.session_connect_attrs` 和 `performance_schema.session_account_connect_attrs` 中检索到。 |
| usePipelineAuth | 在连接期间，将执行不同的查询。如果该选项处于活跃状态，则使用管道发送查询（发送所有查询，然后读取所有结果），从而可以更快地创建连接。默认值：`true`。 |
| enablePacketDebug | 驱动程序将保存最近的 16 个 MySQL 数据交换包（限制为前 1000 个字节）。发生 IOException 时，这些数据包的十六进制值将添加到 `stacktrace` 中。此选项对性能没有影响，但驱动程序将占用 16 KB 以上的内存。默认值：`false`。 |
| useBulkStmts | 尽可能使用专用的 `COM_STMT_BULK_EXECUTE` 协议进行批量插入。（不包含 `Statement.RETURN_GENERATED_KEYS` 和流的批处理）。默认值：`false`。 |
| autocommit | 在连接初始化时设置自动提交的默认值。默认值：`true`。 |
| galeraAllowedState | 通常，`Connection.isValid` 只是向服务器发送一个空数据包，并且服务器会发送一个小的响应以确保连接性。设置此选项后，连接器将确保 Galera 服务器状态 `wsrep_local_state` 与允许的值相对应（用逗号分隔）。例如" 4,5"，推荐为" 4"。 默认值：空。 |
| includeInnodbStatusInDeadlockExceptions | 发生死锁异常时，将 `SHOW ENGINE INNODB STATUS` 结果添加到异常跟踪。默认值：`false`。 |
| includeThreadDumpInDeadlockExceptions | 发生死锁异常时将线程转储添加到异常跟踪中。默认值：`false`。 |
| useReadAheadInput | 使用缓冲的 `inputSteam` 读取可用的 Socket 数据。默认值：`true`。 |
| servicePrincipalName | 使用 GSSAPI 身份验证时，将该值用作服务主体名称（SPN），而不是使用为数据库服务器上的用户帐户定义的名称。 |
| useMysqlMetadata | 强制 `DatabaseMetadata.getDatabaseProductName()` 返回 MySQL 作为数据库，而不是实际的数据库类型。默认值：`false`。 |
| defaultFetchSize | 驱动程序将在所有新创建的 Statement 上调用 `setFetchSize(n)`。默认值：0。 |
| blankTableNameMeta | 结果集元数据 `getTableName` 始终返回空白。此选项主要是为了与 Oracle 数据库兼容。默认值：`false`。 |
| serverRsaPublicKeyFile | 指明用于 `sha256_password` 和 `caching_sha2_password` 身份验证密码的 RSA 服务器公钥文件的路径。 |
| allowPublicKeyRetrieval | 当未设置 `serverRsaPublicKeyFile` 时，授权客户端检索 RSA 服务器公钥（对于 `sha256_password` 和 `caching_sha2_password` 身份验证密码）。默认值：`false`。 |
| tlsSocketType | 指明要使用的 TLS `org.oceanbase.jdbc.tls.TlsSocketPlugin` 插件类型。插件必须存在于`classpath` 中。 |
| credentialType | 指明要使用的凭据插件类型。插件必须存在于 `classpath` 中。 |
| trackSchema | 服务器具有 `CLIENT_SESSION_TRACK` 功能时，允许禁用 `session_track_schema` 设置。默认值：`true`。 |
| clobberStreamingResults | 如果在从服务器读取所有数据之前执行另一个查询，这将导致流式结果集自动关闭，并且丢弃当前从服务器进行流式传输但传输未完成的数据。默认值：`false`。 |
| maxRows | 要返回的最大行数。默认值为 `0`，表示返回所有行。 |
| zeroDateTimeBehavior | MySQL 模式下处理无效 Date 的三种方式，有效值为 `convertToNull`、`exception` 或 `round`，即 `ZERO_DATETIME_CONVERT_TO_NULL = "convertToNull";ZERO_DATETIME_EXCEPTION = "exception";ZERO_DATETIME_ROUND = "round";` 默认为 `ZERO_DATETIME_EXCEPTION`。 |
| allowNanAndInf | PreparedStatement.setDouble() 中是否允许使用 NaN 或 +/- INF 值。默认值：`false`。 |
| defaultConnectionAttributesBanList | 当 `sendConnectionAttributes=true`时，可以通过该参数来控制不发送到 Server 的 Connection Attribute 的列表，该列表用 “,”分割且区分大小写。默认值：`null`。 |

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线