创建服务

创建服务

更新时间：2026-06-13 09:45:51

OceanBase 数据库支持通过 OCP 或黑屏方式执行 CREATE SERVICE 命令来为用户租户创建服务。本节主要介绍如何通过黑屏方式创建服务，建议使用 OCP 来创建和管理服务，有关使用 OCP 创建服务的详细介绍及操作，参见租户详情页概述和管理服务名。

背景信息

在 OceanBase 数据库 V2.x 或 V3.x 版本中，物理备库的产品形态为集群级主备，互为主备关系的集群的集群名及其对应的租户名均相同，而不同的主备库集群，其集群名也不相同，故集群名可以作为主备集群的唯一标识。用户在通过 ODP 连接数据库时，可以使用指定集群名的方式将连接自动路由到主集群。

从 V4.1.0 版本开始，物理备库的产品形态变更为租户级主备，主备租户所属的集群不一定相同，主备租户之间无感知，即主租户不记录备租户的信息，备租户也不记录主租户信息。为了实现租户级主备的自动路由，OceanBase 数据库引入了服务的概念。一个服务下可以有多个同集群或跨集群的租户。用户在通过 ODP 连接数据库时，可以使用指定服务名的方式将连接自动路由到主租户。

使用限制

不支持为 sys 租户或 Meta 租户创建服务。
一个用户租户最多只能创建一个服务。
不允许在通过服务名建立的 Session 中执行 CREATE SERVICE 命令。
该功能的使用依赖 OCP 和 ODP 等产品，相关产品的版本要求如下：
- ODP：V4.3.1 及之后版本
- OCP：V4.3.1 及之后版本

注意事项

为租户创建服务时，需要保证一个服务下最多只有一个主租户，建议使用 OCP 来维护主备关系并管理服务，有关使用 OCP 管理主备租户的详细介绍及操作，参见 OCP 官方文档。

前提条件

执行 CREATE SERVICE 命令要求用户具有 ALTER SYSTEM 权限。
为租户创建服务时，需要先确认租户的 Unit 中是否有临时下线的机器。如果有临时下线的机器，则在执行 CREATE SERVICE 命令后，可能会有部分机器暂时无法通过该服务名提供服务，建议等待临时下线的机器恢复或永久下线后再执行 CREATE SERVICE 命令。或者，用户也可以先执行 CREATE SERVICE 命令，等待临时下线的机器恢复或永久下线后再执行 START SERVICE 命令启动服务。

确认租户的 Unit 中是否有临时下线的机器的详细操作如下：
1. 使用 root 用户登录当前租户所在集群的 sys 租户。
2. 查询租户的 Unit 中是否有临时下线的机器，并获取临时下线机器的 LAST_OFFLINE_TIME。
```
obclient [oceanbase]> SELECT SVR_IP, SVR_PORT, LAST_OFFLINE_TIME, NOW() FROM oceanbase.DBA_OB_SERVERS WHERE LAST_OFFLINE_TIME IS NOT NULL AND (SVR_IP, SVR_PORT) IN (SELECT DISTINCT SVR_IP, SVR_PORT FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = user_tenant_id);
```
  其中，user_tenant_id 需要替换为目标租户的 TENANT_ID。
  
  如果查询结果为空，则表示无临时下线的机器。如果查询结果不为空，则需要进一步判断机器是否为临时下线。
3. 如果确认租户的 Unit 中有下线的机器，则需要查询配置项 server_permanent_offline_time 的值。然后根据上一步获取的 LAST_OFFLINE_TIME 与配置项的值，判断机器的永久下线时间。集群级配置项 server_permanent_offline_time 用于设置节点心跳中断的时间阈值，即节点心跳中断多久后认为其被永久下线，永久下线的节点上的数据副本需要被自动补足。有关该配置项的更多详细信息，参见 server_permanent_offline_time。
```
obclient [oceanbase]> SHOW PARAMETERS LIKE 'server_permanent_offline_time';
```
根据查询结果，如果 LAST_OFFLINE_TIME + server_permanent_offline_time 小于等于 NOW()，则表示机器已经永久下线了，否则机器就是临时下线。

为租户创建服务时，要求租户的 SWITCHOVER_STATUS 为 NORMAL，即保证租户不处于主备角色切换的中间状态。

查询租户的 TENANT_ROLE 和 SWITCHOVER_STATUS 的方法如下：

系统租户下查询指定租户的 TENANT_ROLE 及 SWITCHOVER_STATUS

obclient [oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_ROLE, SWITCHOVER_STATUS FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = mysql_tenant;

用户租户查询本租户的 TENANT_ROLE 及 SWITCHOVER_STATUS

obclient [oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_ROLE, SWITCHOVER_STATUS FROM oceanbase.DBA_OB_TENANTS;

obclient [SYS]> SELECT TENANT_ID, TENANT_NAME, TENANT_ROLE, SWITCHOVER_STATUS FROM SYS.DBA_OB_TENANTS;

操作步骤

给租户创建服务时，对于具有主备关系的租户，需要分别为主租户和备租户创建同名的服务。

租户管理员登录集群的用户租户或 sys 租户。
查询指定租户的 TENANT_ROLE。

由于一个服务下最多只有一个主租户，故在创建服务前，用户需要确认当前租户的角色。

语句示例如下：
```
obclient [oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = mysql_tenant;
```
查询待创建的服务下的租户情况。

注意

以下语句只能查询当前集群中所有具有指定服务名的主备租户的名称及其租户 ID。对于跨集群的物理备库场景，则对应的集群也需要查询。

语句示例如下：
```
obclient [oceanbase]> SELECT t.tenant_id, t.tenant_name, t.tenant_role
FROM oceanbase.CDB_OB_SERVICES AS s JOIN oceanbase.DBA_OB_TENANTS AS t
ON s.tenant_id = t.tenant_id 
WHERE s.service_name = 's_hz';
```
根据租户角色结合查询结果，自行保证待创建的服务下最多只有一个主租户。
为租户创建服务。

语句如下：
```
ALTER SYSTEM CREATE SERVICE service_name [TENANT [=] tenant_name];
```
语句中：
- service_name：指定待创建的服务名。
- TENANT [=] tenant_name：指定待创建服务的租户名。仅 sys 租户可以指定租户，用户租户不能指定租户。
示例如下：
- 系统租户为租户 mysql_tenant 创建名为 s_hz 的服务。
```
obclient [oceanbase]> ALTER SYSTEM CREATE SERVICE s_hz TENANT = mysql_tenant;
```
- 用户租户为本租户创建名为 s_hz 的服务。
```
obclient > ALTER SYSTEM CREATE SERVICE s_hz;
```
命令执行后，如果返回 Query OK，则表示租户的 Unit 中除了永久下线的机器，其他所有机器均支持通过指定服务名的方式来建立连接；如果返回的是 OB_SERVICE_NOT_FULLY_STARTED，则表示租户的 Unit 中除了永久下线的机器，其他机器中仅部分机器支持通过指定服务名的方式来建立连接。如果需要确认具体有哪些机器支持通过指定服务名的方式连接数据库，可以通过系统租户下的 CDB_OB_TENANT_EVENT_HISTORY 视图或用户租户下的 DBA_OB_TENANT_EVENT_HISTORY（MySQL 模式）和 DBA_OB_TENANT_EVENT_HISTORY（Oracle 模式）视图来确认。

后续操作

主备租户的同名服务均创建成功，并且主备租户所属的集群已被 OCP 接管，同时主备租户所属的集群均关联至相同的 ODP（OBProxy）集群后，用户就可以通过指定服务名的方式来连接数据库，实现主备租户的自动路由。连接串如下：

obclient -hip -Pport -uuser_name@SERVICE:service_name

其中：

ip：ODP 的 IP 地址。
port：ODP 的端口号。
user_name：待登录的租户的用户名。
service_name：待登录的租户的服务名。

连接示例如下：

obclient -h10.xx.xx.xx -P2883 -uuser1@SERVICE:s_hz

更多连接方式的详细介绍及说明，参见连接数据库概述（MySQL 模式）和连接数据库概述（Oracle 模式）。