使用 OBKV-Table Java 客户端连接集群

更新时间：2026-04-15 16:01:32

OBKV-Table Java 客户端提供了丰富的 API 接口访问 OceanBase 数据库，本文介绍如何初始化 OBKV-Table Java 客户端和如何使用 OBKV-Table Java 客户端连接集群。

使用 OBKV-Table 客户端连接 OBKV-Table 集群进行数据处理之前，请确保您已经完成准备工作。具体请参见 OBKV-Table 开发准备。

安装 OBKV-Table Java SDK

在 Maven 项目中使用OBKV-Table Java SDK，只需在 pom.xml 文件中加入相应依赖即可。在文件的 dependencies 部分加入如下内容：

<dependency>
    <groupId>com.oceanbase</groupId>
    <artifactId>obkv-table-client</artifactId>
    <version>1.2.12</version>
</dependency>

需要注意如下事项：

OBKV-Table Java SDK 需使用 JDK 1.8 及以上版本。
尽量使用最新版本 jar 包，旧版本的 jar 包可能不支持新的服务端。
这里的版本号可能非最新，你可以参考中央仓库的已发布 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 开发准备中的 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 开发准备中提到的系统租户下的用户，直连模式下只有系统租户下的用户才有访问路由表的权限。
sysPassword		用户访问 SYS 租户的密码，即 `sysUserName` 参数中`sysUserName` 对应的密码。

初始化示例

## 假设当前集群如下
## 集群名：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	用户需要访问的数据库名。

初始化示例

## 假设当前集群如下
## 集群名：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 支持的操作类型。
OBKV-Table 支持的所有值类型请参见 OBKV-Table 支持的数据类型。
使用客户端的数据操作示例参见数据操作示例。
OBKV-Table 客户端连接配置信息可以通过以下几个视图查看： GV$OB_KV_CLIENT_INFO V$OB_KV_CLIENT_INFO