--- title: "使用 OBKV-Table Java 客户端连接集群 - OceanBase 数据库 V4.3.5 | OceanBase 文档中心" description: 使用 OBKV-Table Java 客户端连接集群 OBKV-Table Java 客户端提供了丰富的 API 接口访问 OceanBase 数据库，本文介绍如何初始化 OBKV-Table Java 客户端和如何使用 OBKV-Table Java 客户端连接集群。 使用 OBKV-Table 客户端连接 OBK… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库KV 型 - V 4.3.5 LTS # 使用 OBKV-Table Java 客户端连接集群 更新时间：2026-04-15 16:01:32 [编辑](https://github.com/oceanbase/oceanbase-kv/edit/V4.3.5/zh-CN/100.obkv-table/200.use-of-the-obkv-table-client/100.introduction-to-the-obkv-table-client-and-instructions-of-use.md) OBKV-Table Java 客户端提供了丰富的 API 接口访问 OceanBase 数据库，本文介绍如何初始化 OBKV-Table Java 客户端和如何使用 OBKV-Table Java 客户端连接集群。 使用 OBKV-Table 客户端连接 OBKV-Table 集群进行数据处理之前，请确保您已经完成准备工作。具体请参见 [OBKV-Table 开发准备](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002314260)。 ## 安装 OBKV-Table Java SDK 在 Maven 项目中使用OBKV-Table Java SDK，只需在 `pom.xml` 文件中加入相应依赖即可。在文件的 `dependencies` 部分加入如下内容： ```java com.oceanbase obkv-table-client 1.2.12 ``` 需要注意如下事项： - OBKV-Table Java SDK 需使用 JDK 1.8 及以上版本。 - 尽量使用最新版本 jar 包，旧版本的 jar 包可能不支持新的服务端。 - 这里的版本号可能非最新，你可以参考[中央仓库](https://mvnrepository.com/artifact/com.oceanbase/obkv-table-client)的已发布 OBKV-Table 版本，将版本号替换为已发布的最新版本号。 ## 初始化 ObTableClient ObTableClient 是 OBKV-Table Java SDK 访问 OceanBase 数据库的客户端句柄。ObTableClient 的初始化方式与 OBKV-Table 的连接模式强相关，直连模式和 ODP 模式的初始化 ObTableClient 的方式不一样。 ### 直连模式 #### 参数说明 直连模式下，需要设置 ObTableClient 的这 5 个参数： - setParamURL(String paramURL) - setFullUserName(String fullUserName) - setPassword(String password) - setSysUserName(String sysUserName) - setSysPassword(String sysPassword) 具体说明如下： | 参数名称 | 参数格式 | 参数说明 | 参数示例 | | --- | --- | --- | --- | | paramURL | `http://ip:port/services?Action=ObRootServiceInfo&ObCluster=clusterName&database=databaseName` | 参数 URL，即 [OBKV-Table 开发准备](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002314260) 中的 Config URL。注意：直连模式下需要在 `paramURL` 参数中指定需要访问的数据库，即在 `paramURL` 后加上 `&database=databaseName`。 | `http://127.0.0.1:8080/services?Action=ObRootServiceInfo&ObCluster=obkv&database=obkv_table_db` - ip 为：127.0.0.1 - 端口为：8080 - 集群名为：obkv - database 为：obkv_table_db | | fullUserName | `userName@tenantName#clusterName` | 指访问数据库的用户，为全量用户名（三段式用户名），由三部分组成，分别是用户名、租户名和集群名，由分隔符 `@` 和 `#` 进行分隔。 | `test@obkv_table#obkv` - 用户名为：test - 租户名为：obkv_table - 集群名为：obkv | | password | | 用户访问数据库的密码，即 `fullUserName` 参数中 `userName` 对应的密码。 | | | sysUserName | | SYS 租户的用户名，即 [OBKV-Table 开发准备](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002314260) 中提到的系统租户下的用户，直连模式下只有系统租户下的用户才有访问路由表的权限。 | | | sysPassword | | 用户访问 SYS 租户的密码，即 `sysUserName` 参数中`sysUserName` 对应的密码。 | | #### 初始化示例 ```java ## 假设当前集群如下 ## 集群名：obkv ## 租户名：obkv_table ## 数据库名: obkv_table_db ## 用户名：test_user ## 用户密码：admin123 ## 系统租户下用户 : test_sys_user ## 系统租户下用户密码 : sys123 ## Config URL: http://127.0.0.1:8080/services?Action=ObRootServiceInfo&ObCluster=obkv String paramURL = "http://127.0.0.1:8080/services?Action=ObRootServiceInfo&ObCluster=obkv&database=obkv_table_db"; ObTableClient obkvHandle = new ObTableClient(); obkvHandle.setParamURL(paramURL); obkvHandle.setFullUserName("test_user@obkv_table#obkv"); obkvHandle.setPassword("admin123"); obkvHandle.setSysUserName("test_sys_user"); obkvHandle.setSysPassword("sys123"); obkvHandle.init(); ``` ### ODP 模式 ODP模式下，需要设置 ObTableClient 的这 6 个参数： - setOdpMode(boolean odpMode) - setOdpAddr(String odpAddr) - setOdpPort(int odpPort) - setFullUserName(String fullUserName) - setPassword(String password) - setDatabase(String database) 具体说明如下： | 参数名称 | 参数说明 | 参数示例 | | --- | --- | --- | | odpMode | ODP 模式的标识，`true` 表示 ODP 模式，`false` 表示直连模式。ODP 模式下需要设置为 `true`。 | | | odpAddr | ODP 服务端的 域名/IP 地址。 | | | odpPort | ODP 服务端的端口。注意：云上需要使用公网通过 slb 对外暴露的默认端口 `3307`。其他场景默认端口是 `2885`。 | | | fullUserName | fullUserName 代表用户名，格式和直连模式不一样，需要区分情况。 - 公有云（阿里云）：`userName` - 其他云、专有云（私有云）、开源用户等：`userName@tenantName#clusterName` | `test_user` / `test_user@obkv_table#obkv` | | password | 用户访问数据的密码。 | `admin123` | | database | 用户需要访问的数据库名。 | | #### 初始化示例 ```java ## 假设当前集群如下 ## 集群名：obkv ## 租户名：obkv_table ## 数据库名: obkv_table_db ## 用户名：test_user ## 用户密码：admin123 ## ODP 地址: 127.0.0.1 ## ODP 端口: 3307 ObTableClient obkvHandle = new ObTableClient(); obkvHandle.setOdpMode(true); obkvHandle.setOdpAddr("127.0.0.1"); obkvHandle.setOdpPort(3307); obkvHandle.setDatabase("obkv_table_db"); obkvHandle.setFullUserName("test_user"); obkvHandle.setPassword("admin123"); obkvHandle.init(); ``` ## 后续操作 - OBKV-Table 支持的所有操作类型参见 [OBKV-Table 支持的操作类型](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002314258)。 - OBKV-Table 支持的所有值类型请参见 [OBKV-Table 支持的数据类型](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002314259)。 - 使用客户端的数据操作示例参见 [数据操作示例](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002314253)。 - OBKV-Table 客户端连接配置信息可以通过以下几个视图查看： [GV$OB_KV_CLIENT_INFO](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002015153) [V$OB_KV_CLIENT_INFO](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002015132) 上一篇 下一篇 ![有帮助](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) 咨询热线