使用 Binlog 模式

本文介绍如何开启和使用 Binlog 模式。

前提条件

在使用 Binlog 模式功能前，您需确认如下信息：

环境中已安装 OceanBase 数据库和 OBProxy，并且版本在使用限制以内，请参见产品发布记录。
安装的 OBProxy 已代理 OceanBase 集群，即可通过 OBProxy 地址和端口连接到 OceanBase 集群。
OceanBase 集群中已成功配置 obconfig_url 配置项，可登录 OceanBase 集群后执行 SHOW PARAMETERS LIKE 'obconfig_url'; 命令查看（value 值）。
- 若 OceanBase 集群是通过 OCP 进行安装，OCP 会自动配置 obconfig_url。
- 若 OceanBase 集群通过其他方法安装，查看后未配置 obconfig_url，您需手动配置 obconfig_url。如何安装 Config Server 并配置 obconfig_url 可参见官网文档《OceanBase 安装部署工具》中使用指南/命令行/使用命令行部署 Config Server。

验证 config_url 配置是否生效

通过 OBProxy 代理登录 OceanBase 集群
```
mysql -h10.10.10.1 -P2883 -uroot@sys#obdemo -D oceanbase -A -p
```
- -h：提供 OceanBase 数据库的连接 IP，配置为 OBProxy 地址。此处 10.10.10.1 为示例值，您需根据实际 IP 配置。
- -P：提供 OceanBase 数据库的连接端口，也是 OBProxy 的监听端口，由 listen_port 配置项控制。此处 2883 为示例值，您需根据实际端口配置。
- -u：提供 OceanBase 数据库的连接账户，常用格式为 用户名@租户名#集群名，如需查看 OBProxy 配置项，连接 OceanBase 数据库时必须使用 root@sys 用户。此处 obdemo 为示例值，您需根据实际集群名配置。
  说明
  - 当使用 ODP 连接 OceanBase 集群时，可以通过以下方式获取集群名：
    先通过直连的方式连接 OceanBase 数据库；然后使用 SHOW PARAMETERS LIKE 'cluster'; 命令来获取集群的名称，该命令会返回结果中 VALUE 的值对应 OceanBase 集群的名称。
  - 如果 ODP 代理多个集群，连接时必须指定集群名；如果 ODP 只代理一个集群，连接时则不需指定集群名。

查看 OceanBase 数据库配置项 obconfig_url

obclient [oceanbase]> show parameters like '%config_url%';

输出结果如下，value 列对应的值即为 obconfig_url 的值：

+-------+----------+------------+----------+--------------+-----------+----------------------------------------------------------------------------+--------------------------+----------+---------+---------+-------------------+
| zone  | svr_type | svr_ip     | svr_port | name         | data_type | value                                                                      | info                     | section  | scope   | source  | edit_level        |
+-------+----------+------------+----------+--------------+-----------+----------------------------------------------------------------------------+--------------------------+----------+---------+---------+-------------------+
| zone1 | observer | 10.10.10.1 |     2882 | obconfig_url | STRING    | http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo  | URL for OBConfig service | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE |
+-------+----------+------------+----------+--------------+-----------+----------------------------------------------------------------------------+--------------------------+----------+---------+---------+-------------------+

如果输出的结果中，value 字段的值不是类似 http://xxx.xxx.xxx.xxx:xx/services?Action=ObRootServiceInfo&ObCluster={cluster} 格式，说明 OceanBase 集群还未在 Config Server 进行注册。您可执行如下命令将 OceanBase 集群注册到 Config Server 中。

alter system set obconfig_url = 'http://{vip_address}:{vip_port}/services?Action=ObRootServiceInfo&ObCluster={cluster}'

{vip_address}:{vip_port} 为 Config Server 所在运行的服务器 IP 和端口号，如 10.10.10.1:8080。若 Config Server 是通过 obd 部署，可执行 obd cluster display {cluster} 命令查看 IP 和端口号。
{cluster} 为待注册集群的集群名，可通过执行 SQL 命令 show parameters like 'cluster'; 查看，value 值即为集群名。

验证 config_url 是否生效

从 obconfig_url 配置项输出的 value 值中获取 Config Server 的服务器 IP 和端口号，执行如下命令。

curl -s 'http://10.10.10.1:8080/services?Action=GetObProxyConfig' |jq .

说明

jq 命令的作用是格式化（美化）shell 命令行下 json 的输出，可通过 sudo yum install jq 安装。

查看命令输出中是否包含 obdemo 集群。输出示例如下，ObRootServiceInfoUrlList 中包含 obdemo 集群，且对应的 ObRootServiceInfoUrl 值与 obconfig_url 配置项值一致。

{
   "Code": 200,
   "Message": "successful",
   "Success": true,
   "Data": {
     "ObProxyBinUrl": "http://10.10.10.1:8080/client?Action=GetObProxy",
     "ObProxyDatabaseInfo": {
       "DataBase": "***",
       "MetaDataBase": "http://10.10.10.1:8080/services?Action=ObRootServiceInfo&User_ID=alibaba&UID=admin&ObRegion=obdv1",
       "Password": "***",
       "User": "***"
     },
     "ObRootServiceInfoUrlList": [
       {
         "ObRegion": "obcluster",
         "ObRootServiceInfoUrl": "http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obcluster"
       },
       {
         "ObRegion": "obdemo",
         "ObRootServiceInfoUrl": "http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo"
       }
     ],
     "Version": "4840ade8a158753aa5b9ea69ba014fc1"
   },
   "Trace": "d4b4b27fae24e7b4",
   "Server": "10.10.10.1",
   "Cost": 1
 }

复制 obdemo 集群对应的 ObRootServiceInfoUrl 信息，执行如下命令。

curl -s 'http://10.10.10.1:8080/services?Action=ObRootServiceInfo&ObCluster=obdemo' |jq .

查看命令输出中是否成功解析出集群中 OBServer 节点的 IP 和端口，若成功解析则说明 obconfig_url 配置生效。输出示例如下：

{
  "Code": 200,
  "Message": "successful",
  "Success": true,
  "Data": {
    "ObClusterId": 1,
    "ObRegionId": 1,
    "ObCluster": "obdemo",
    "ObRegion": "obdemo",
    "ReadonlyRsList": [],
    "RsList": [
      {
        "address": "10.10.10.1:2882",
        "role": "LEADER",
        "sql_port": 2881
      }
    ],
    "Type": "PRIMARY",
    "timestamp": 1692699586370950
  },
  "Trace": "362172a2d5de734c",
  "Server": "10.10.10.1",
  "Cost": 1
}

配置 OBProxy

从 Binlog 模式介绍我们可以了解到，binlog 下游服务（即 MySQL binlog 生态工具）实际交互时是与 OBProxy 进行交互的，并不感知 oblogproxy，所有请求均由 OBProxy 转发给 OceanBase 数据库或 oblogproxy 的（SQL 转发给 OceanBase 数据库，binlog 订阅及相关命令转发给 oblogproxy），因此需要在 OBProxy 上配置 oblogproxy 的服务地址（即提供 binlog service 的服务地址）。

参考以下步骤为 OBProxy 配置 oblogproxy 的服务地址：

使用 sys 或 proxysys 租户的账号连接 OBProxy

mysql -h'ip' -P 2883 -u'user'@sys#'cluster' -D oceanbase -A -p'password'

mysql -h'ip' -P 2883 -u'user'@proxysys#'cluster' -D oceanbase -A -p'password'

其中 2883 为 OBProxy 的默认端口。

配置 binlog service 地址 binlog_service_ip，地址形式为 ip:port
```
alter proxyconfig set binlog_service_ip='ip:port';
```
'ip:port' 需配置为 binlog service 的 IP 和端口，可通过如下两种方式查看 IP 和端口：
- 如果 oblogproxy 通过 obd 安装，可执行 obd cluster display {cluster} 命令查看。
- 如果 oblogproxy 通过 RPM 安装，可查看目标机器上 /usr/local/oblogproxy/conf/conf.json 文件内容获取端口号（service_port）。
开启 binlog 服务 enable_binlog_service (OBProxy V4.2.3 及之后版本已经移除该配置项，如果该配置项不存在，则只需关注 binlog_service_ip 配置项即可)。
```
alter proxyconfig set enable_binlog_service='True';
```
设置 init_sql，开启 show_ddl_in_compat_mode，有关于 init_sql 和 _show_ddl_in_compat_mode 介绍可参考 Binlog 模式兼容性章节。
```
alter proxyconfig set init_sql='set _show_ddl_in_compat_mode = 1;';
```
上述操作完成后，可使用下面 SQL 来验证配置是否正确。
```
show proxyconfig like 'config_name';
```
示例：
```
show proxyconfig like 'binlog_service_ip';
```

配置 oblogproxy

下面的操作均在 oblogproxy 项目目录中进行。

如果通过 RPM 安装 oblogproxy, 则项目目录默认为 /usr/local/oblogproxy。
如果通过 obd 安装 oblogproxy，则可以通过执行 obd cluster edit-conf {cluster} 命令找到 oblogproxy 的项目目录（binlog_dir 配置）。

oblogproxy 的配置文件默认放在项目目录下的 conf/conf.json，您可按照如下步骤修改配置文件。

获取加密的用户名和密码。
```
./bin/logproxy -x {username}
./bin/logproxy -x {password}
```
{username} 和 {password} 为 OceanBase 集群 sys 租户下用户的用户名和密码（可以使用 sys 租户下 root 用户和密码）。注意，此处的用户名不应包含集群名称或租户名称，且必须具备 sys 租户下 oceanbase 库的读权限。
修改 conf/conf.json 文件

将 binlog_mode 设置为 true，该配置项默认为 false。

将生成的加密字符串分别配置到 ob_sys_username 和 ob_sys_password 配置项。

有关 oblogproxy 配置的详细介绍，可参见 oblogproxy 配置。另外，每一次修改配置文件，重启 oblogproxy 才能生效。

运行 oblogproxy

启动 oblogproxy 服务

下面的操作均在 oblogproxy 项目目录中进行，假设 oblogproxy 项目目录名称为 ${oblogproxy_DIR}。

如果通过 RPM 安装 oblogproxy，则项目目录默认为 /usr/local/oblogproxy。
如果通过 obd 安装 oblogproxy，则可以通过 obd cluster edit-conf {cluster} 命令找到 oblogproxy 的项目目录（binlog_dir 配置）。

cd ${oblogproxy_DIR}

再通过以下命令启动服务。

sudo ./run.sh start

可以查看 ${oblogproxy_DIR}/log/logproxy.log，确保已经正常启动。

创建 binlog 服务

从 Binlog 模式介绍我们可以了解到，oblogproxy 启动后，需要发一条 SQL 命令到 oblogproxy 来创建 binlog 服务，创建动作需要直连到 oblogproxy，可通过以下命令连接到 oblogproxy。

mysql -h'ip' -P 2983

其中 2983 为 oblogproxy 的默认端口。

命令介绍

CREATE BINLOG [IF NOT EXISTS] FOR TENANT `cluster`.`tenant` [TO USER `user` PASSWORD `pwd`] [FROM <timestamp>] WITH CLUSTER URL `cluster_url`;

cluster 为集群名称。
tenant 为业务租户名称（即：要创建 binlog 服务的业务租户名称）。
user 和 pwd 分别为当前 OceanBase 集群 sys 租户的用户名和密码（此处的用户名不应包含集群名称或租户名称，并且该用户需要具备 sys 租户下 OceanBase 库的读权限）。

注意

这里的 user 和 pwd 配置项为可选项，如果没有在 conf/conf.json 文件中配置 ob_sys_username 和 ob_sys_password 配置项，则需要指定 user 和 pwd。
timestamp 为创建 binlog 服务的起始时间，单位为微秒。
cluster_url 为当前 OceanBase 集群的 config_url，可通过下面 SQL 语句来查询（输出中 value 列对应的值），具体的配置、查看和验证的操作可参见上文验证 config_url 配置是否生效：
```
show parameters like '%config_url%';
```

示例

创建 binlog 服务，不指定 user pwd timestamp
```
CREATE BINLOG FOR TENANT `test_cluster`.`test_tenant` WITH CLUSTER URL 'test_cluster_url';
```
CREATE BINLOG 语句不指定 user pwd 需要在 conf/conf.json 文件中配置 ob_sys_username 和 ob_sys_password，创建时会默认使用已配置 ob_sys_username 和 ob_sys_password。

CREATE BINLOG 语句不指定 timestamp 默认会使用当前时间。

创建 binlog 服务，指定 user pwd

CREATE BINLOG FOR TENANT `test_cluster`.`test_tenant` TO USER `user` PASSWORD `pwd` WITH CLUSTER URL 'test_cluster_url';

CREATE BINLOG 语句指定 user pwd 后会使用指定的 用户名 和 密码。

创建 binlog 服务，指定 timestamp

CREATE BINLOG FOR TENANT `test_cluster`.`test_tenant` FROM 1622476800000000 WITH CLUSTER URL 'test_cluster_url';

创建 BINLOG 成功后，在配置文件指定的 binlog_log_bin_basename 对应的目录下，可以查看到集群目录。

获取 binlog 服务状态

获取 binlog 服务状态需要直连到 oblogproxy，可通过以下命令连接到 oblogproxy。

mysql -h'ip' -P 2983

其中 2983 为 oblogproxy 的默认端口。

获取所有 binlog 服务状态
```
SHOW BINLOG STATUS;
```

获取指定租户 binlog 服务状态

SHOW BINLOG STATUS [FOR TENANT `cluster`.`tenant`];

其他 binlog 操作

要执行以下 SQL，您需要直连到 oblogproxy，可通过以下命令连接到 oblogproxy。

mysql -h'ip' -P 2983

其中 2983 为 oblogproxy 的默认端口。

释放 binlog 服务

DROP BINLOG [IF EXISTS] FOR TENANT `cluster`.`tenant`;

清理 binlog 日志

按时间清理

PURGE BINARY LOGS BEFORE '2021-06-01 00:00:00' [FOR TENANT `cluster`.`tenant`];

按文件清理

PURGE BINARY LOGS TO 'mysql-bin.000001' [FOR TENANT `cluster`.`tenant`];

前提条件

验证 config_url 配置是否生效

说明

说明

配置 OBProxy

配置 oblogproxy

运行 oblogproxy

启动 oblogproxy 服务

创建 binlog 服务

命令介绍

注意

示例

获取 binlog 服务状态

其他 binlog 操作

释放 binlog 服务

清理 binlog 日志