<commit_before>---
title: DM Relay Log
summary: 了解目录结构、初始迁移规则和 DM relay log 的数据清理。
aliases: ['/docs-cn/tidb-data-migration/dev/relay-log/']
---

# DM Relay Log

DM (Data Migration) 工具的 relay log 由若干组有编号的文件和一个索引文件组成。这些有编号的文件包含了描述数据库更改的事件。索引文件包含所有使用过的 relay log 的文件名。

在启用 relay log 功能后，DM-worker 会自动将上游 binlog 迁移到本地配置目录（若使用 TiUP 部署 DM，则迁移目录默认为 `<deploy_dir> / <relay_log>`）。本地配置目录 `<relay_log>` 的默认值是 `relay-dir`，可在[上游数据库配置文件](/dm/dm-source-configuration-file.md)中进行修改）。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 迁移的起始位置由如下规则决定：

- 从下游数据库 sync 单元 checkpoint 中，获取各同步任务需要该数据源的最早位置。如果该位置晚于下述任何一个位置，则从此位置开始迁移。

- 若本地 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 从初始的上游 binlog 开始迁移，并将所有上游 binlog 文件连续迁移至最新。

    - 在 GTID 模式下，DM-worker 从初始上游 GTID 开始迁移。

        > **注意：**
        >
        > 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定迁移的起始位置。

## 启动、停止 relay log

<SimpleTab>
<div label="v2.0.2 及之后的版本">

> **注意：**
> 
> 自 v2.0.2 起，上游数据源配置中的 `enable-relay` 项已经失效。在[加载数据源配置](/dm/dm-manage-source.md#数据源操作)时，如果发现配置中的 `enable-relay` 项为 `true`，DM 会给出如下信息提示：
> 
> ```
> Please use `start-relay` to specify which workers should pull relay log of relay-enabled sources.
> ```

在 v2.0.2 及之后的版本中，`start-relay` 与 `stop-relay` 命令分别用于启动及停止 relay log 的拉取。

`start-relay` 命令可以配置一个或多个 DM-worker 为指定数据源迁移 relay log，但只能指定空闲或者已绑定了该上游数据源的 DM-worker。使用示例如下：

{{< copyable "" >}}

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

```
{
    "result": true,
    "msg": ""
}
```

{{< copyable "" >}}

```bash
» stop-relay -s mysql-replica-01 worker1 worker2<commit_msg>align relay log behaviour in v5.4.0 (#8113)<commit_after>---
title: DM Relay Log
summary: 了解目录结构、初始迁移规则和 DM relay log 的数据清理。
aliases: ['/docs-cn/tidb-data-migration/dev/relay-log/']
---

# DM Relay Log

DM (Data Migration) 工具的 relay log 由若干组有编号的文件和一个索引文件组成。这些有编号的文件包含了描述数据库更改的事件。索引文件包含所有使用过的 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 配置文件中通过 `relay-dir` 配置本地配置目录，其优先级高于上游数据库的配置文件。

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 迁移的起始位置由如下规则决定：

- 从下游数据库 sync 单元 checkpoint 中，获取各同步任务需要该数据源的最早位置。如果该位置晚于下述任何一个位置，则从此位置开始迁移。

- 若本地 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 从初始的上游 binlog 开始迁移，并将所有上游 binlog 文件连续迁移至最新。

    - 在 GTID 模式下，DM-worker 从初始上游 GTID 开始迁移。

        > **注意：**
        >
        > 若上游的 relay log 被清理掉，则会发生错误。在这种情况下，需设置 `relay-binlog-gtid` 来指定迁移的起始位置。

## 启动、停止 relay log

<SimpleTab>

<div label="v5.4.0 及之后的版本">

在 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
```

```
{
    "result": true,
    "msg": ""
}
```

</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.
> ```

`start-relay` 命令可以配置一个或多个 DM-worker 为指定数据源迁移 relay log，但只能指定空闲或者已绑定了该上游数据源的 DM-worker。使用示例如下：

{{< copyable "" >}}

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

```
{
    "result": true,
    "msg": ""
}
```

{{< copyable "" >}}

```bash
» stop-relay -s mysql-replica-01 worker1 worker2
{'fraction_non_alphanumeric': 0.15136625119846597, 'fraction_numerical': 0.11409395973154363, 'mean_word_length': 3.8236994219653178, 'pattern_counts': {'":': 6, '<': 28, '<?xml version=': 0, '>': 54, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '864647', 'n_tokens_mistral': 5558, 'n_tokens_neox': 5429, 'n_words': 642}