实例管理

创建 Binlog 实例

该命令主要用于为已开通 Binlog 的租户添加新的 Binlog 实例，此处新创建的 Binlog 实例会继承已有的 Binlog 实例参数配置。

语法

CREATE BINLOG INSTANCE instance_name 
       FOR cluster.tenant [binlog_instance_option [, binlog_instance_option...]];

binlog_instance_option: 
    obcdc_option
  | binlog_option
  | slot_option

obcdc_option: 
    START_TIMESTAMP
  | ROOTSERVER_LIST
  | CLUSTER_URL
  | CLUSTER_USER
  | CLUSTER_PASSWORD
  | EXTRA_OBCDC_CFG

binlog_option:
    MASTER_SERVER_ID
  | MASTER_SERVER_UUID
  | SERVER_ID
  | SERVER_UUID
  | BINLOG_EXPIRE_LOGS_SECONDS
  | BINLOG_EXPIRE_LOGS_SIZE
  | MAX_BINLOG_SIZE
  | AUTO_START_OBCDC
  | FAILOVER
  | _INITIAL_OB_TXN_ID
  | _INITIAL_OB_TXN_GTID_SEQ
  | BINLOG_EXPIRE_LOGS_AUTO_SCALE
  | BINLOG_INSTANCE_SCOPE_CFG

slot_option: 
    IP
  | ZONE
  | REGION
  | GROUP

BINLOG_EXPIRE_LOGS_AUTO_SCALE: {
    "enable": value,
    "max_scale_up_capacity_gb": value,
    "min_scale_down_capacity_gb": value,
    "scale_down_threshold": "value",
    "scale_down_step": "value",
    "scale_up_threshold": "value", 
    "scale_up_step": "value",
    "computed_binlog_expire_logs_size": value
}

参数介绍

obcdc_option

为方便使用，obbinlog 为 obcdc 的常用配置项提供同名配置项用以设置，其他 obcdc 配置项统一通过 EXTRA_OBCDC_CFG 进行配置，具体介绍如下：

• START_TIMESTAMP：obcdc 的启动位点，即任务开始时租户当前时间。单位为秒，默认为当前 unix timestamp。

• ROOTSERVER_LIST：启动时指定 Root Service 所在机器信息，格式为 server_ip:server_rpc_port:server_sql_port。适用于没有部署 OCP 的场景。

• CLUSTER_URL：OceanBase 集群的 config url，配置时需使用引号包裹。可通过 SHOW PARAMETERS LIKE 'obconfig_url'; 获得（value 值）。obcdc 可通过该信息自动获取到 Root Service 所在机器列表。适用于部署有 OCP 的场景，当 OBM 配置了 OCP 相关信息时，将自动生成对应值，否则为空。

• CLUSTER_USER：待创建 Binlog 实例集群 sys 租户下用户名，需要具有 oceanbase 系统库下所有表的的读权限。

• CLUSTER_PASSWORD：CLUSTER_USER 对应的密码。

• EXTRA_OBCDC_CFG：obcdc 其他参数配置，其值是一个由空白符分割的若干 obcdc_cfg_key=value 组成的字符串，需要注意 = 前后不能存在空白符。obcdc_cfg_key=value 中的 value 均被当成字符串类型处理，因此不需要再用引号括起来。

  该配置下指定的如下几个配置项会被忽略，始终使用固定值来启动 obcdc。

  obcdc 配置项	固定值
  enable_output_trans_order_by_sql_operation	1
  sort_trans_participants	1
  enable_output_hidden_primary_key	0
  enable_convert_timestamp_to_unix_timestamp	1
  enable_output_invisible_column	1

binlog_option

您需关注 binlog_option 下的如下配置：

• BINLOG_EXPIRE_LOGS_SECONDS：Binlog 文件过期时间。所有最后文件更新时间戳小于当前时间戳减去 BINLOG_EXPIRE_LOGS_SECONDS 的 Binlog 文件及其对应索引条目都将自动被清理。默认值为 259200，单位为秒，取值范围为 [0, 4294967295]，取值为 0 时表示关闭 Binlog 文件按过期时间进行自动清理的功能。

• BINLOG_EXPIRE_LOGS_SIZE：Binlog 文件过期大小。在 Binlog 文件进行轮转时，检查当前所有 Binlog 文件的总大小和首个 Binlog 文件大小的差值，若大于 BINLOG_EXPIRE_LOGS_SIZE 则删除首个 Binlog 文件及其对应索引条目，重复这一过程直到差值小于等于 BINLOG_EXPIRE_LOGS_SIZE 或者只剩下当前一个 Binlog 文件，在完成清理后再轮转到下一个 Binlog 文件。默认值为 53687091200，单位 byte，取值范围为 [0, 9223372036854775807]，取值为 0 时表示关闭 Binlog 文件按过期大小进行自动清理的功能。

• MAX_BINLOG_SIZE：单个 Binlog 文件大小的最大阈值，单位为字节。当一个事务所有 Binlog Events 追加到 Binlog 文件后，若 Binlog 文件大小大于 MAX_BINLOG_SIZE 则进行 Binlog 文件轮转。默认值为 536870912，取值范围为 [4096, 1073741824]。

• AUTO_START_OBCDC：控制在 Binlog 实例启动后，是否自动开启 obcdc 进行日志拉取。默认为 1，表示自动开启 obcdc 进行日志拉取。

• FAILOVER：控制是否开启该 Binlog 实例本身的故障恢复。若开启，当所在机器节点本身正常但 Binlog 实例故障时，该 Binlog 实例将被自动恢复。默认为 1 表示开启 Binlog 实例本身的故障恢复。

• _INITIAL_OB_TXN_ID：设置 OceanBase 集群事务 ID，表示从该事务 ID 开始进行 Binlog 转换。该参数仅对 OceanBase 租户下第一个 Binlog 实例有效，对于后续 Binlog 实例会忽略该配置，以内部 gtid 一致性保证算法自动选择的结果为准。

• _INITIAL_OB_TXN_GTID_SEQ：指定起始事务对应的 gtid sequence。该参数仅对 OceanBase 租户下第一个 Binlog 实例有效，对于后续 Binlog 实例会忽略该配置，以内部 gtid 一致性保证算法自动选择的结果为准。

• BINLOG_EXPIRE_LOGS_AUTO_SCALE：配置自动扩容，需配置为 json 格式。具体介绍可参见下文 BINLOG_EXPIRE_LOGS_AUTO_SCALE。

  说明

  该参数自 V4.3.0 新增。

• BINLOG_INSTANCE_SCOPE_CFG：用于设置租户级别的配置参数，主要跟高性能配置有关，具体介绍可参见下文 BINLOG_INSTANCE_SCOPE_CFG。

  说明

  该参数自 V4.3.0 新增。

slot_option

该参数用于设置 Binlog 实例资源槽分配相关的配置。每一个机器节点上可以运行多个 Binlog 实例（可以是不同租户下的），在创建一个 Binlog 实例时需要为其分配资源槽，即在某个 IP 上预分配相关的资源。每个机器节点有物理和逻辑两种属性，在分配资源槽的时候是以下几种属性做交集计算后进行分配，若按相关配置分配不出资源槽则返回 ERROR 包。

• 物理属性: IP、ZONE 和 REGION，表示该机器的物理位置。包含关系是: IP 包含于 ZONE 包含于 REGION。

• 逻辑属性: GROUP，表示该机器被划分在哪个逻辑分组中。

参数具体介绍如下表：

BINLOG_EXPIRE_LOGS_AUTO_SCALE

该参数用于设置自动扩缩容相关配置，需配置为 json 格式。示例如下：

CREATE BINLOG INSTANCE binlog1 FOR obdemo.test1 
    CLUSTER_URL = 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo', 
    BINLOG_EXPIRE_LOGS_AUTO_SCALE='{
      "enable":0,
      "scale_up_threshold":"20%",
      "scale_up_step":"20%",
      "max_scale_up_capacity_gb":5000,
      "scale_down_threshold":"50%",
      "scale_down_step":"20%",
      "min_scale_down_capacity_gb":10,
      "computed_binlog_expire_logs_size":10737418240
      }';

支持在 BINLOG_EXPIRE_LOGS_AUTO_SCALE 参数中配置的各个配置项介绍如下表：

BINLOG_INSTANCE_SCOPE_CFG

该参数用于设置租户级别的配置项，主要跟高性能配置有关，其值是一个由空白符分割的若干 obcdc_cfg_key=value 组成的字符串，需要注意 = 前后不能存在空白符。

示例

• 为 obdemo 集群的 test1 租户创建名为 binlog1 的实例。

  CREATE BINLOG INSTANCE binlog1 FOR obdemo.test1 CLUSTER_URL='http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo';
  

• 为 obdemo 集群的 test1 租户创建名为 binlog2 的实例，并指定 obcdc 配置。

  CREATE BINLOG INSTANCE binlog2 FOR obdemo.test1 CLUSTER_URL='http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo',EXTRA_OBCDC_CFG = 'memory_limit=6G progress_limit_sec_for_dml=30';
  

• 为 obdemo 集群的 test1 租户创建名为 binlog2 的实例，并指定自动扩缩容及高性能相关配置。

  说明

  一般情况下不建议设置自动扩缩容，因此示例中将 enable 设置为 0，表示禁用自动扩缩容功能。

  CREATE BINLOG INSTANCE binlog3 FOR obdemo.test1 
      CLUSTER_URL = 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo', 
      BINLOG_INSTANCE_SCOPE_CFG='record_queue_size=150000 read_wait_num=1500 storage_wait_num=1500 binlog_serialize_thread_size=8 throttle_convert_rps=99 throttle_convert_iops=2097152 throttle_dump_rps=111 throttle_dump_iops=2097152 throttle_dump_conn=333',
      BINLOG_EXPIRE_LOGS_AUTO_SCALE='{
        "enable":0,
        "scale_up_threshold":"33%",
        "scale_up_step":"33%",
        "max_scale_up_capacity_gb":4000,
        "scale_down_threshold":"53%",
        "scale_down_step":"12%",
        "min_scale_down_capacity_gb":33,
        "computed_binlog_expire_logs_size":10737418243
        }';
  

查询 Binlog 实例

用于查询 Binlog 实例相关信息，存在相关记录将返回一到多条记录，若无符合条件记录则返回空集。

语法

SHOW BINLOG INSTANCES {
      FOR cluster.tenant 
    | [instance_name [, instance_name...]]
};

参数说明

示例

• 查询 obdemo 集群 test1 租户中的 Binlog 实例信息

  SHOW BINLOG INSTANCES FOR obdemo.test1;
  

• 查询指定 Binlog 实例的信息

  SHOW BINLOG INSTANCES `eo46r4f2e8`,`gldwt7bnco`;
  

命令输出如下：

+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+-----------------------------+-------------------------------+---------+-----------------------------+-------------------------------------------------+----------+
| name       | ob_cluster | ob_tenant | ip            | port | zone | region | group | running | state   | obcdc_running | obcdc_state | service_mode | convert_running | convert_delay | convert_rps | convert_eps | convert_iops | convert_checkpoint_current  |  convert_checkpoint_earliest  | dumpers | last_dumper_disconnect_time |  version                                        | odp_addr |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+-----------------------------+-------------------------------+---------+-----------------------------+-------------------------------------------------+----------+
| eo46r4f2e8 | obdemo     | test1     | 10.10.10.1    | 8104 |      |        |       | Yes     | Running | Yes           | Running     | enabled      | Yes             |           578 |           1 |           0 |            0 |         1757944196          |                1757684969     |      0  |   1757944160                | 4.0.1-92748c6c59534426d187977b13b61b7cdf4fa200  | NULL     |
| gldwt7bnco | obdemo     | test1     | 10.10.10.1    | 8103 |      |        |       | Yes     | Running | Yes           | Running     | enabled      | Yes             |           478 |           1 |           0 |            0 |         1757944196          |                1757684969     |      0  |   1757944160                | 4.0.1-92748c6c59534426d187977b13b61b7cdf4fa200  | NULL     |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+-----------------------------+-------------------------------+---------+-----------------------------+-------------------------------------------------+----------+

结果集说明：

修改 Binlog 实例

用于修改指定 Binlog 实例的参数配置。

语法

ALTER BINLOG INSTANCE instance_name
    SET binlog_instance_option [, binlog_instance_option...];

参数说明

示例

• 修改 binlog1 实例中 binlog 文件的有效时间为 6 天（518400 秒）。

  ALTER BINLOG INSTANCE binlog1 SET BINLOG_EXPIRE_LOGS_SECONDS = 518400;
  

• 修改 binlog2 实例中自动扩缩容及高性能相关配置

  说明

  一般情况下不建议设置自动扩缩容，因此示例中将 enable 设置为 0，表示禁用自动扩缩容功能。

  ALTER BINLOG INSTANCE binlog2 SET 
      BINLOG_INSTANCE_SCOPE_CFG='record_queue_size=100000 read_wait_num=2000 storage_wait_num=2000 binlog_serialize_thread_size=7',
      BINLOG_EXPIRE_LOGS_AUTO_SCALE='{
        "enable":1,
        "scale_up_threshold":"44%",
        "scale_up_step":"44%",
        "max_scale_up_capacity_gb":5000,
        "scale_down_threshold":"54%",
        "scale_down_step":"14%",
        "min_scale_down_capacity_gb":44,
        "computed_binlog_expire_logs_size":10737418244
        }';
  

• 修改 binlog3 实例中 obcdc 参数配置

  修改 obcdc 参数前需先查看对应实例下 binlog_instance.conf 文件中的 cdc_config.extra_obcdc_cfg 值，实例文件存放在 run 目录下。执行修改命令时，需在 cdc_config.extra_obcdc_cfg 值后添加需要修改的 obcdc 参数。

  说明

  • 若 cdc_config.extra_obcdc_cfg 中包含待修改的 obcdc 参数，您需直接修改对应参数值，而不是在 cdc_config.extra_obcdc_cfg 后添加需要修改的 obcdc 参数。

  • 修改 Binlog 实例的 obcdc 参数后，需要重启实例使改动生效。

  此处以修改 enable_output_virtual_generated_column 值为例，您需将示例中的 <cdc_config.extra_obcdc_cfg> 替换为实际查看到的 cdc_config.extra_obcdc_cfg 值。

  ALTER BINLOG INSTANCE binlog3 SET EXTRA_OBCDC_CFG = '<cdc_config.extra_obcdc_cfg> enable_output_virtual_generated_column=1';
  

停止 Binlog 实例

用于停止指定 Binlog 实例。

语法

STOP BINLOG INSTANCE instance_name;

instance_name 为待停止的 Binlog 实例名。

示例

以停止实例名为 eo46r4f2e8 的 Binlog 实例为例，命令如下：

STOP BINLOG INSTANCE eo46r4f2e8;

停止后可执行 SHOW BINLOG INSTANCES eo46r4f2e8; 命令查看 Binlog 实例状态，停止后输出中 state 会变为 Stop，示例如下：

+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+---------+------------------------------------------------+----------+
| name       | ob_cluster | ob_tenant | ip            | port | zone | region | group | running | state   | obcdc_running | obcdc_state | service_mode | convert_running | convert_delay | convert_rps | convert_eps | convert_iops | dumpers | version                                        | odp_addr |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+---------+------------------------------------------------+----------+
| eo46r4f2e8 | obdemo     | test1     | 10.10.10.1    | 8106 |      |        |       | No      | Stop    | No            | Stop        | disabled     | No              |          NULL |        NULL |        NULL |         NULL |    NULL | 4.0.1-92748c6c59534426d187977b13b61b7cdf4fa200 | NULL     |
+------------+------------+-----------+---------------+------+------+--------+-------+---------+---------+---------------+-------------+--------------+-----------------+---------------+-------------+-------------+--------------+---------+------------------------------------------------+----------+

启动 Binlog 实例

用于启动指定 Binlog 实例。

语法

START BINLOG INSTANCE instance_name;

instance_name 为待启动的 Binlog 实例名。

示例

以启动实例名为 eo46r4f2e8 的 Binlog 实例为例，命令如下：

START BINLOG INSTANCE eo46r4f2e8;

切换主 Binlog 实例

用于手动切换指定租户的主 Binlog 实例。

语法

SWITCH MASTER INSTANCE TO instance_name FOR TENANT cluster.tenant [FULL]

参数说明

示例

以 obdemo 集群 test1 租户中的 Binlog 实例为例，示例如下：

1. 查看主 Binlog 实例所在的节点

   SHOW BINLOG SERVER FOR TENANT obdemo.test1;
   

   输出如下，主 Binlog 实例为 10.10.10.1 的 8103 端口对应实例：

   +---------+--------+------------+------+--------+-------+
   | cluster | tenant | ip         | port | status | cause |
   +---------+--------+------------+------+--------+-------+
   | obdemo  | test1  | 10.10.10.1 | 8103 | OK     |  NULL |
   +---------+--------+------------+------+--------+-------+
   

2. 切换主 Binlog 实例

   SWITCH MASTER INSTANCE TO eo46r4f2e8 FOR TENANT obdemo.test1;
   

3. 再次查看主 Binlog 实例所在节点信息

   SHOW BINLOG SERVER FOR TENANT obdemo.test1;
   

   输出如下，主 Binlog 实例切换为了 10.10.10.1 的 8106 端口对应实例：

   +---------+--------+------------+------+--------+-------+
   | cluster | tenant | ip         | port | status | cause |
   +---------+--------+------------+------+--------+-------+
   | obdemo  | test1  | 10.10.10.1 | 8106 | OK     |  NULL |
   +---------+--------+------------+------+--------+-------+
   

释放 Binlog 实例

用于删除指定的 Binlog 实例，Binlog 文件也会被同步清理。

语法

DROP BINLOG INSTANCE instance_name [FORCE]

参数说明

示例

强制删除名为 binlog2 的实例：

DROP BINLOG INSTANCE binlog2 FORCE;