Skip to content

Commit

Permalink
Add introduction of dm relay log (#8780)
Browse files Browse the repository at this point in the history 
* Add introduction  of  dm relay  log

* Update dm-relay-log.md

* Apply suggestions from code review

Co-authored-by: Ehco <zh19960202@gmail.com>

* Update dm/dm-relay-log.md

* merge two documents into one

* fix dead link

* Apply suggestions from code review

Co-authored-by: Ran <huangran@pingcap.com>

* Apply suggestions from code review

Co-authored-by: shichun-0415 <89768198+shichun-0415@users.noreply.github.com>

* Update relay-log.md

* update

Signed-off-by: Ran <huangran@pingcap.com>

* fix start poistion

* Update relay-log.md

* remove png

* update wording and format

Signed-off-by: Ran <huangran.alex@gmail.com>

* Update dm/relay-log.md

Co-authored-by: Ehco <zh19960202@gmail.com>
Co-authored-by: Ran <huangran@pingcap.com>
Co-authored-by: shichun-0415 <89768198+shichun-0415@users.noreply.github.com>
Co-authored-by: Ran <huangran.alex@gmail.com>
  • Loading branch information
@sunzhaoyang @Ehco1996
@ran-huang @shichun-0415
5 people authored Jun 17, 2022
1 parent d9e67a7 commit 2856a35
Show file tree
Hide file tree
Showing 4 changed files with 138 additions and 112 deletions.
2 changes: 1 addition & 1 deletion dm/dm-export-import-config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ config import [--dir directory]

> **注意：**
>
> 对于 v2.0.2 版本之后的集群，暂不支持自动导入 relay worker 的相关配置，可以手动使用 `start-relay` 命令[开启 relay log](/dm/relay-log.md#启动停止-relay-log)。
> 对于 v2.0.2 版本之后的集群，暂不支持自动导入 relay worker 的相关配置，可以手动使用 `start-relay` 命令[开启 relay log](/dm/relay-log.md#开启关闭-relay-log)。
### 参数解释

Expand Down
6 changes: 3 additions & 3 deletions dm/dm-source-configuration-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,9 @@ from:
| :------------ | :--------------------------------------- |
| `source-id` | 标识一个 MySQL 实例。|
| `enable-gtid` | 是否使用 GTID 方式从上游拉取 binlog，默认值为 false。一般情况下不需要手动配置，如果上游数据库启用了 GTID 支持，且需要做主从切换，则将该配置项设置为 true。 |
| `enable-relay` | 是否开启 relay log，默认值为 false。自 DM v2.0.2 版本起，该配置项弃用，需使用 `start-relay` 命令[开启 relay log](/dm/relay-log.md#启动停止-relay-log)。 |
| `relay-binlog-name` | 拉取上游 binlog 的起始文件名，例如 "mysql-bin.000002"，该配置在 `enable-gtid` 为 false 的情况下生效。如果不配置该项，DM-worker 将从最新时间点的 binlog 文件开始拉取 binlog，一般情况下不需要手动配置。 |
| `relay-binlog-gtid` | 拉取上游 binlog 的起始 GTID，例如 "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"，该配置在 `enable-gtid` 为 true 的情况下生效。如果不配置该项，DM-worker 将从最新时间点的 binlog GTID 开始拉取 binlog，一般情况下不需要手动配置。 |
| `enable-relay` | 是否开启 relay log，默认值为 false。自 DM v2.0.2 版本起，该配置项弃用，需使用 `start-relay` 命令[开启 relay log](/dm/relay-log.md#开启关闭-relay-log)。 |
| `relay-binlog-name` | 拉取上游 binlog 的起始文件名，例如 "mysql-bin.000002"，该配置在 `enable-gtid` 为 false 的情况下生效。如果不配置该项，DM-worker 将从正在同步的最早的 binlog 文件开始拉取，一般情况下不需要手动配置。 |
| `relay-binlog-gtid` | 拉取上游 binlog 的起始 GTID，例如 "e9a1fc22-ec08-11e9-b2ac-0242ac110003:1-7849"，该配置在 `enable-gtid` 为 true 的情况下生效。如果不配置该项，DM-worker 将从正在同步的最早 binlog GTID 开始拉取 binlog，一般情况下不需要手动配置。 |
| `relay-dir` | 存储 relay log 的目录，默认值为 "./relay_log"。|
| `host` | 上游数据库的 host。|
| `port` | 上游数据库的端口。|
Expand Down
2 changes: 1 addition & 1 deletion dm/maintain-dm-using-tiup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ tiup dm scale-in prod-cluster -N 172.16.5.140:8262
>
> 对于 v2.0.5 之前版本的集群，可使用 v2.0.5 及之后版本的 dmctl 导出和导入集群配置。
>
> 对于 v2.0.2 之后的版本，导入集群配置时暂不支持自动恢复 relay worker 相关配置，可手动执行 `start-relay` 命令[开启 relay log](/dm/relay-log.md#启动停止-relay-log)。
> 对于 v2.0.2 之后的版本，导入集群配置时暂不支持自动恢复 relay worker 相关配置，可手动执行 `start-relay` 命令[开启 relay log](/dm/relay-log.md#开启关闭-relay-log)。

滚动升级过程中尽量保证对前端业务透明、无感知，其中对不同节点有不同的操作。

Expand Down
240 changes: 133 additions & 107 deletions dm/relay-log.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,95 +10,23 @@ DM (Data Migration) 工具的 relay log 由若干组有编号的文件和一个

在启用 relay log 功能后，DM-worker 会自动将上游 binlog 迁移到本地配置目录（若使用 TiUP 部署 DM，则迁移目录默认为 `<deploy_dir> / <relay_log>`）。本地配置目录 `<relay_log>` 的默认值是 `relay-dir`，可在[上游数据库配置文件](/dm/dm-source-configuration-file.md)中进行修改。自 v5.4.0 版本起，你可以在 [DM-worker 配置文件](/dm/dm-worker-configuration-file.md)中通过 `relay-dir` 配置本地配置目录，其优先级高于上游数据库的配置文件。

> **警告：**
>
> 上游数据库配置文件中的 `relay-dir` 在 v6.1 版本中标记为弃用，在未来版本可能会被移除。相关命令的输出中您会看到如下提示： `` `relay-dir` in source config will be deprecated soon, please use `relay-dir` in worker config instead``。
DM-worker 在运行过程中，会将上游 binlog 实时迁移到本地文件。DM-worker 的 sync 处理单元会实时读取本地 relay log 的 binlog 事件，将这些事件转换为 SQL 语句，再将 SQL 语句迁移到下游数据库。

> **注意：**
>
> Relay log 功能会额外使用磁盘 IO，导致同步延时上升。在部署环境的磁盘 IO 性能不佳时，开启 relay log 也可能会成为同步链路的瓶颈，导致同步速度变慢。
本文档介绍 DM relay log 的目录结构，初始迁移规则，以及如何暂停、恢复和清理 relay log。

## 目录结构

Relay log 本地存储的目录结构示例如下：

```
<deploy_dir>/<relay_log>/
|-- 7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001
| |-- mysql-bin.000001
| |-- mysql-bin.000002
| |-- mysql-bin.000003
| |-- mysql-bin.000004
| `-- relay.meta
|-- 842965eb-091c-11e9-9e45-9a3bff03fa39.000002
| |-- mysql-bin.000001
| `-- relay.meta
`-- server-uuid.index
```

- `subdir`：

- DM-worker 把从上游数据库迁移到的 binlog 存储在同一目录下，每个目录都为一个 `subdir`。
- `subdir` 的命名格式为 `<上游数据库 UUID>.<本地 subdir 序列号>`。
- 在上游进行 master 和 slave 实例切换后，DM-worker 会生成一个序号递增的新 `subdir` 目录。

- 在以上示例中，对于 `7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001` 这一目录，`7e427cc0-091c-11e9-9e45-72b7c59d52d7` 是上游数据库的 UUID，`000001` 是本地 `subdir` 的序列号。

- `server-uuid.index`：记录当前可用的 `subdir` 目录。

- `relay.meta`：存储每个 `subdir` 中已迁移的 binlog 信息。例如，

```bash
cat c0149e17-dff1-11e8-b6a8-0242ac110004.000001/relay.meta
```
## 适用场景

```
binlog-name = "mysql-bin.000010" # 当前迁移的 binlog 名
binlog-pos = 63083620 # 当前迁移的 binlog 位置
binlog-gtid = "c0149e17-dff1-11e8-b6a8-0242ac110004:1-3328" # 当前迁移的 binlog GTID
```

也可能包含多个 GTID：

```bash
cat 92acbd8a-c844-11e7-94a1-1866daf8accc.000001/relay.meta
```

```
binlog-name = "mysql-bin.018393"
binlog-pos = 277987307
binlog-gtid = "3ccc475b-2343-11e7-be21-6c0b84d59f30:1-14,406a3f61-690d-11e7-87c5-6c92bf46f384:1-94321383,53bfca22-690d-11e7-8a62-18ded7a37b78:1-495,686e1ab6-c47e-11e7-a42c-6c92bf46f384:1-34981190,03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170,10b039fc-c843-11e7-8f6a-1866daf8d810:1-308290454"
```

## 初始迁移规则

Relay log 迁移的起始位置由如下规则决定：
MySQL 的存储空间是有限制的，通常会设置 binlog 的最长保存时间，当上游把 binlog 清除掉之后，如果 DM 还需要对应位置的 binlog 就会拉取失败，导致同步任务出错。每增加一个同步任务，DM 都会在上游建立一条连接用于拉取 binlog，连接数过多会对上游造成比较大的负载。开启 relay log 后，同一个上游的多个同步任务可以复用已经拉到本地的 relay log，**减少了对上游的压力**。

- 从下游数据库 sync 单元 checkpoint 中，获取各同步任务需要该数据源的最早位置。如果该位置晚于下述任何一个位置，则从此位置开始迁移。
在全量加增量数据迁移任务 (`task-mode=all`) 中，DM 需要先进行全量数据迁移，再根据 binlog 进行增量同步。若全量阶段持续时间较长，上游 binlog 可能会被清除，导致增量同步无法进行。若提前开启了 relay log，DM 会自动在本地保留足够的日志，**保证增量任务正常进行**。

- 若本地 relay log 有效（有效是指 relay log 具有有效的 `server-uuid.index`，`subdir` 和 `relay.meta` 文件），DM-worker 从 `relay.meta` 记录的位置恢复迁移。

- 若不存在有效的本地 relay log，但上游数据源配置文件中指定了 `relay-binlog-name` 或 `relay-binlog-gtid`：

- 在非 GTID 模式下，若指定了 `relay-binlog-name`，则 DM-worker 从指定的 binlog 文件开始迁移。
一般情况下建议开启 relay log，但需知晓 relay log 可能导致的负面作用：

- 在 GTID 模式下，若指定了 `relay-binlog-gtid`，则 DM-worker 从指定的 GTID 开始迁移。

- 若不存在有效的本地 relay log，而且 DM 配置文件中未指定 `relay-binlog-name` 或 `relay-binlog-gtid`：
由于 relay log 需要写入到磁盘中，这一过程会产生外部 IO 和一些 CPU 消耗，可能导致整个同步链路变长，从而增加数据同步的时延。对**时延要求十分敏感**的同步任务，暂时不推荐使用 relay log。

- 在非 GTID 模式下，DM-worker 从初始的上游 binlog 开始迁移，并将所有上游 binlog 文件连续迁移至最新。

- 在 GTID 模式下，DM-worker 从初始上游 GTID 开始迁移。
> **注意：**
>
> DM v2.0.7 及之后的版本中，对 relay log 写入进行了优化，增加的时延和 CPU 消耗已相对较小。
> **注意：**
>
> 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定迁移的起始位置。
## 使用 relay log

## 启动、停止 relay log
### 开启/关闭 relay log

<SimpleTab>

Expand All @@ -107,13 +35,13 @@ Relay log 迁移的起始位置由如下规则决定：
在 v5.4.0 及之后的版本中，你可以通过将 `enable-relay` 设为 `true` 开启 relay log。自 v5.4.0 起，DM-worker 在绑定上游数据源时，会检查上游数据源配置中的 `enable-relay` 项。如果 `enable-relay` 为 `true`，则为该数据源启用 relay log 功能。

具体配置方式参见[上游数据源配置文件介绍](/dm/dm-source-configuration-file.md)

除此以外，你也可以通过 `start-relay` 或 `stop-relay` 命令动态调整数据源的 `enable-relay` 并即时开启或关闭 relay log。

{{< copyable "shell-regular" >}}

```bash
» start-relay -s mysql-replica-01
start-relay -s mysql-replica-01
```

```
Expand All @@ -123,14 +51,14 @@ Relay log 迁移的起始位置由如下规则决定：
}
```

</div>
</div>

<div label="v2.0.2（包含）到 v5.3.0（包含）">

> **注意：**
>
>
> 在 v2.0.2 及之后的 v2.0 版本，以及在 v5.3.0 版本中，上游数据源配置中的 `enable-relay` 项失效，你只能通过`start-relay` 和 `stop-relay`命令开启和关闭 relay log。[加载数据源配置](/dm/dm-manage-source.md#数据源操作)时，如果 DM 发现配置中的 `enable-relay` 项为 `true`，会给出如下信息提示：
>
>
> ```
> Please use `start-relay` to specify which workers should pull relay log of relay-enabled sources.
> ```
Expand All @@ -144,7 +72,7 @@ Relay log 迁移的起始位置由如下规则决定：
{{< copyable "" >}}
```bash
» start-relay -s mysql-replica-01 worker1 worker2
start-relay -s mysql-replica-01 worker1 worker2
```
```
Expand All @@ -157,7 +85,7 @@ Relay log 迁移的起始位置由如下规则决定：
{{< copyable "" >}}

```bash
» stop-relay -s mysql-replica-01 worker1 worker2
stop-relay -s mysql-replica-01 worker1 worker2
```

```
Expand All @@ -178,16 +106,19 @@ Relay log 迁移的起始位置由如下规则决定：
</div>
</SimpleTab>

## 查询 relay log
### 查询 relay log

`query-status -s` 命令可以查询 relay log 的状态。
使用 `query-status -s` 命令，可以查询 relay log 的状态：

{{< copyable "" >}}

```bash
» query-status -s mysql-replica-01
query-status -s mysql-replica-01
```

<details>
<summary>期望输出</summary>

```
{
"result": true,
Expand Down Expand Up @@ -239,16 +170,21 @@ Relay log 迁移的起始位置由如下规则决定：
}
```

## 暂停、恢复 relay log
</details>

### 暂停/恢复 relay log

`pause-relay` 与 `resume-relay` 命令可以分别暂停及恢复 relay log 的拉取。这两个命令执行时都需要指定上游数据源的 `source-id`，例如：
`pause-relay` 与 `resume-relay` 命令可以分别暂停及恢复拉取 relay log。这两个命令执行时都需要指定上游数据源的 `source-id`，例如：

{{< copyable "" >}}

```bash
» pause-relay -s mysql-replica-01 -s mysql-replica-02
pause-relay -s mysql-replica-01 -s mysql-replica-02
```

<details>
<summary>期望输出</summary>

```
{
"op": "PauseRelay",
Expand All @@ -270,12 +206,17 @@ Relay log 迁移的起始位置由如下规则决定：
]
}
```


</details>

{{< copyable "" >}}

```bash
» resume-relay -s mysql-replica-01
```
resume-relay -s mysql-replica-01
```

<details>
<summary>期望输出</summary>

```
{
Expand All @@ -293,13 +234,19 @@ Relay log 迁移的起始位置由如下规则决定：
}
```

## 清理 relay log
</details>

因为存在文件读写的检测机制，所以 DM-worker 不会清理正在使用的 relay log，也不会清理当前已有数据迁移任务之后会使用到的 relay log。
### 清理 relay log

Relay log 的数据清理包括自动清理和手动清理这两种方法。
DM 提供两种清理 relay log 的方式，手动清理和自动清理。两种清理方法都不会清理活跃的 relay log。

### 自动数据清理
> **注意：**
>
> - 活跃的 relay log：该 relay log 正在被同步任务使用。活跃的 relay log 当前只在 Syncer Unit 被更新和写入，如果一个为 All 模式的同步任务在全量导出/导入阶段花费了超过数据源 purge 里配置的过期时间，该 relay log 依旧会被清除。
>
> - 过期的 relay log：该 relay log 文件最后被改动的时间与当前时间的差值大于配置文件中的 `expires` 字段。
#### 自动数据清理

启用自动数据清理需在 source 配置文件中进行以下配置：

Expand All @@ -323,7 +270,7 @@ purge:
- 剩余磁盘空间，单位为 GB。若剩余磁盘空间小于该配置，则指定的 DM-worker 机器会在后台尝试自动清理可被安全清理的 relay-log。若这一数字被设为 "0"，则表示不按剩余磁盘空间来清理数据。
- 默认为 "15"，表示可用磁盘空间小于 15GB 时，DM-master 会尝试安全地清理 relay log。

### 手动数据清理
#### 手动数据清理

手动数据清理是指使用 dmctl 提供的 `purge-relay` 命令，通过指定 `subdir` 和 binlog 文件名，来清理掉**指定 binlog 之前**的所有 relay log。若在命令中不填 `-subdir` 选项，则默认清理**最新 relay log 子目录之前**的所有 relay log。

Expand Down Expand Up @@ -370,13 +317,92 @@ deb76a2b-09cc-11e9-9129-5242cf3bb246.000003
{{< copyable "" >}}

```bash
» purge-relay -s mysql-replica-01 --filename mysql-bin.000001 --sub-dir e4e0e8ab-09cc-11e9-9220-82cc35207219.000002
purge-relay -s mysql-replica-01 --filename mysql-bin.000001 --sub-dir e4e0e8ab-09cc-11e9-9220-82cc35207219.000002
```

+ 以下命令默认 `--sub-dir` 为最新的 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003` 子目录。该目录之前的 relay log 子目录为 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000001` 和 `e4e0e8ab-09cc-11e9-9220-82cc35207219.000002`，所以该命令实际清空了这两个子目录，保留了 `deb76a2b-09cc-11e9-9129-5242cf3bb246.000003`。

{{< copyable "" >}}

```bash
» purge-relay -s mysql-replica-01 --filename mysql-bin.000001
purge-relay -s mysql-replica-01 --filename mysql-bin.000001
```

## Relay log 内部机制

### 目录结构

Relay log 本地存储的目录结构示例如下：

```
<deploy_dir>/<relay_log>/
|-- 7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001
| |-- mysql-bin.000001
| |-- mysql-bin.000002
| |-- mysql-bin.000003
| |-- mysql-bin.000004
| `-- relay.meta
|-- 842965eb-091c-11e9-9e45-9a3bff03fa39.000002
| |-- mysql-bin.000001
| `-- relay.meta
`-- server-uuid.index
```
- `subdir`：
- DM-worker 把从上游数据库迁移到的 binlog 存储在同一目录下，每个目录都为一个 `subdir`。
- `subdir` 的命名格式为 `<上游数据库 UUID>.<本地 subdir 序列号>`。
- 在上游进行 primary 和 secondary 实例切换后，DM-worker 会生成一个序号递增的新 `subdir` 目录。
- 在以上示例中，对于 `7e427cc0-091c-11e9-9e45-72b7c59d52d7.000001` 这一目录，`7e427cc0-091c-11e9-9e45-72b7c59d52d7` 是上游数据库的 UUID，`000001` 是本地 `subdir` 的序列号。
- `server-uuid.index`：记录当前可用的 `subdir` 目录。
- `relay.meta`：存储每个 `subdir` 中已迁移的 binlog 信息。例如，
```bash
cat c0149e17-dff1-11e8-b6a8-0242ac110004.000001/relay.meta
```
```
binlog-name = "mysql-bin.000010" # 当前迁移的 binlog 名
binlog-pos = 63083620 # 当前迁移的 binlog 位置
binlog-gtid = "c0149e17-dff1-11e8-b6a8-0242ac110004:1-3328" # 当前迁移的 binlog GTID
```
也可能包含多个 GTID：
```bash
cat 92acbd8a-c844-11e7-94a1-1866daf8accc.000001/relay.meta
```
```
binlog-name = "mysql-bin.018393"
binlog-pos = 277987307
binlog-gtid = "3ccc475b-2343-11e7-be21-6c0b84d59f30:1-14,406a3f61-690d-11e7-87c5-6c92bf46f384:1-94321383,53bfca22-690d-11e7-8a62-18ded7a37b78:1-495,686e1ab6-c47e-11e7-a42c-6c92bf46f384:1-34981190,03fc0263-28c7-11e7-a653-6c0b84d59f30:1-7041423,05474d3c-28c7-11e7-8352-203db246dd3d:1-170,10b039fc-c843-11e7-8f6a-1866daf8d810:1-308290454"
```
### DM 接收 binlog 的位置
- 从保存的 checkpoint 中（默认位于下游 dm_meta 库），获取各同步任务需要该数据源的最早位置。如果该位置晚于下述任何一个位置，则从此位置开始迁移。
- 若本地 relay log 有效（有效是指 relay log 具有有效的 `server-uuid.index`，`subdir` 和 `relay.meta` 文件），DM-worker 从 `relay.meta` 记录的位置恢复迁移。
- 若不存在有效的本地 relay log，但上游数据源配置文件中指定了 `relay-binlog-name` 或 `relay-binlog-gtid`：
- 在非 GTID 模式下，若指定了 `relay-binlog-name`，则 DM-worker 从指定的 binlog 文件开始迁移。
- 在 GTID 模式下，若指定了 `relay-binlog-gtid`，则 DM-worker 从指定的 GTID 开始迁移。
- 若不存在有效的本地 relay log，而且 DM 配置文件中未指定 `relay-binlog-name` 或 `relay-binlog-gtid`：
- 在非 GTID 模式下，DM-worker 从自身所有 subtask 正在同步的最早 binlog 开始迁移，直至最新。
- 在 GTID 模式下，DM-worker 从自身所有 subtask 正在同步的最早 GTID 开始迁移，直至最新。
> **注意：**
>
> 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定迁移的起始位置。
## 探索更多
- [DM 源码阅读系列文章（六）relay log 的实现丨TiDB 工具](https://pingcap.com/zh/blog/dm-source-code-reading-6)

0 comments on commit 2856a35

Please sign in to comment.