归档文档中心
TiDB
社区
联系我们

管理数据迁移任务

本文介绍了如何使用 dmctl 组件来进行数据迁移任务的管理和维护。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 dm-ansible/dmctl。

dmctl 支持交互模式用于人工操作，同时也支持命令模式用于脚本。

dmctl 交互模式

本部分描述了在交互模式下一些 dmctl 命令的基本用法。

dmctl 使用帮助

./dmctl --help

Usage of dmctl:
 -V prints version and exit
 -config string
       path to config file
 # 按照 DM 提供的加密方法加密数据库密码，用于 DM 的配置文件
 -encrypt string
       encrypt plaintext to ciphertext
 # DM-master 访问地址，dmctl 与 DM-master 交互以完成任务管理操作
 -master-addr string
       master API server addr
 -rpc-timeout string
       rpc timeout, default is 10m (default "10m")

加密数据库密码

在 DM 相关配置文件中，要求必须使用经 dmctl 加密后的密码，否则会报错。对于同一个原始密码，每次加密后密码不同。

./dmctl -encrypt 123456

VjX8cEeTX+qcvZ3bPaO4h0C80pe/1aU=

任务管理概览

进入交互模式，与 DM-master 进行交互：

./dmctl -master-addr 172.16.30.14:8261

Welcome to dmctl
Release Version: v1.0.1
Git Commit Hash: e63c6cdebea0edcf2ef8c91d84cff4aaa5fc2df7
Git Branch: release-1.0
UTC Build Time: 2019-09-10 06:15:05
Go Version: go version go1.12 linux/amd64

» help
DM control

Usage:
  dmctl [command]

Available Commands:
  break-ddl-lock       forcefully break DM-worker's DDL lock
  check-task           check the config file of the task
  help                 help about any command
  migrate-relay        migrate DM-worker's relay unit
  pause-relay          pause DM-worker's relay unit
  pause-task           pause a specified running task
  purge-relay          purge relay log files of the DM-worker according to the specified filename
  query-error          query task error
  query-status         query task status
  refresh-worker-tasks refresh worker -> tasks mapper
  resume-relay         resume DM-worker's relay unit
  resume-task          resume a specified paused task
  show-ddl-locks       show un-resolved DDL locks
  sql-inject           inject (limited) SQLs into binlog replication unit as binlog events
  sql-replace          replace SQLs matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern); each SQL must end with a semicolon
  sql-skip             skip the binlog event matched by a specific binlog position (binlog-pos) or a SQL pattern (sql-pattern)
  start-task           start a task as defined in the config file
  stop-task            stop a specified task
  switch-relay-master  switch the master server of the DM-worker's relay unit
  unlock-ddl-lock      forcefully unlock DDL lock
  update-master-config update the config of the DM-master
  update-relay         update the relay unit config of the DM-worker
  update-task          update a task's config for routes, filters, or block-allow-list

Flags:
  -h, --help             help for dmctl
  -w, --worker strings   DM-worker ID

# 使用 `dmctl [command] --help` 来获取某个命令的更多信息

管理数据迁移任务

本部分描述了如何使用不同的任务管理命令来执行相应操作。

创建数据迁移任务

start-task 命令用于创建数据迁移任务。 当数据迁移任务启动时，DM 将自动对相应权限和配置进行前置检查。

help start-task

start a task as defined in the config file

Usage:
 dmctl start-task [-w worker ...]  [flags]

Flags:
 -h, --help   help for start-task

Global Flags:
 -w, --worker strings   DM-worker ID

命令用法示例

start-task [ -w "172.16.30.15:8262"] ./task.yaml

参数解释

  • -w：
    • 可选
    • 指定在特定的一组 DM-workers 上执行 task.yaml
    • 如果设置，则只启动指定任务在该组 DM-workers 上的子任务
  • config-file：
    • 必选
    • 指定 task.yaml 的文件路径

返回结果示例

start-task task.yaml

{
     "result": true,
     "msg": "",
     "workers": [
         {
             "result": true,
             "worker": "172.16.30.15:8262",
             "msg": ""
         },
         {
             "result": true,
             "worker": "172.16.30.16:8262",
             "msg": ""
         }
     ]
}

查询数据迁移任务状态

query-status 命令用于查询数据迁移任务状态。有关查询结果及子任务状态，详见查询状态。

help query-status

query task status

Usage:
 dmctl query-status [-w worker ...] [task-name] [flags]

Flags:
 -h, --help   help for query-status

Global Flags:
 -w, --worker strings   DM-worker ID

命令用法示例

query-status

参数解释

  • -w：
    • 可选
    • 查询在指定的一组 DM-workers 上运行的数据迁移任务的子任务
  • task-name：
    • 可选
    • 指定任务名称
    • 如果未设置，则返回全部数据迁移任务的查询结果

返回结果示例

有关查询结果中各参数的意义，详见查询状态结果。

查询运行错误

query-error 可用于查询数据迁移任务与 relay 处理单元的错误信息。相比于 query-status，query-error 一般不用于获取除错误信息之外的其他信息。

query-error 常用于获取 sql-skip/sql-replace 所需的 binlog position 信息，有关 query-error 的参数与结果解释，请参考 “跳过或替代执行异常的 SQL 语句”文档中的 query-error。

暂停数据迁移任务

pause-task 命令用于暂停数据迁移任务。

help pause-task

pause a specified running task

Usage:
 dmctl pause-task [-w worker ...]  [flags]

Flags:
 -h, --help   help for pause-task

Global Flags:
 -w, --worker strings   DM-worker ID

命令用法示例

pause-task [-w "127.0.0.1:8262"] task-name

参数解释

  • -w：
    • 可选
    • 指定在特定的一组 DM-workers 上暂停数据迁移任务的子任务
    • 如果设置，则只暂停该任务在指定 DM-workers 上的子任务
  • task-name | task-file：
    • 必选
    • 指定任务名称或任务文件路径

返回结果示例

pause-task test

{
     "op": "Pause",
     "result": true,
     "msg": "",
     "workers": [
         {
            "meta": {
                "result": true,
                "worker": "172.16.30.15:8262",
                "msg": ""
            },
            "op": "Pause",
            "logID": "2"
         },
         {
            "meta": {
                "result": true,
                "worker": "172.16.30.16:8262",
                "msg": ""
            },
            "op": "Pause",
            "logID": "2"
         }
     ]
}

恢复数据迁移任务

resume-task 命令用于恢复处于 Paused 状态的数据迁移任务，通常用于在人为处理完造成迁移任务暂停的故障后手动恢复迁移任务。

help resume-task

resume a specified paused task

Usage:
 dmctl resume-task [-w worker ...]  [flags]

Flags:
 -h, --help   help for resume-task

Global Flags:
 -w, --worker strings   DM-worker ID

命令用法示例

resume-task [-w "127.0.0.1:8262"] task-name

参数解释

  • -w：
    • 可选
    • 指定在特定的一组 DM-workers 上恢复数据迁移任务的子任务
    • 如果设置，则只恢复该任务在指定 DM-workers 上的子任务
  • task-name | task-file：
    • 必选
    • 指定任务名称或任务文件路径

返回结果示例

resume-task test

{
     "op": "Resume",
     "result": true,
     "msg": "",
     "workers": [
         {
             "meta": {
                 "result": true,
                 "worker": "172.16.30.15:8262",
                 "msg": ""
             },
             "op": "Resume",
             "logID": "3"
         },
         {
             "meta": {
                 "result": true,
                 "worker": "172.16.30.16:8262",
                 "msg": ""
             },
             "op": "Resume",
             "logID": "3"
         }
     ]
}

停止数据迁移任务

stop-task 命令用于停止数据迁移任务。有关 stop-task 与 pause-task 的区别，请参考暂停数据迁移任务中的相关说明。

help stop-task

stop a specified task

Usage:
 dmctl stop-task [-w worker ...]  [flags]

Flags:
 -h, --help   help for stop-task

Global Flags:
 -w, --worker strings   DM-worker ID

命令用法示例

stop-task [-w "127.0.0.1:8262"]  task-name

参数解释

  • -w：
    • 可选
    • 指定在特定的一组 DM-workers 上停止数据迁移任务的子任务
    • 如果设置，则只停止该任务在指定 DM-workers 上的子任务
  • task-name | task-file：
    • 必选
    • 指定任务名称或任务文件路径

返回结果示例

stop-task test

{
     "op": "Stop",
     "result": true,
     "msg": "",
     "workers": [
         {
             "meta": {
                 "result": true,
                 "worker": "172.16.30.15:8262",
                 "msg": ""
             },
             "op": "Stop",
             "logID": "4"
         },
         {
             "meta": {
                 "result": true,
                 "worker": "172.16.30.16:8262",
                 "msg": ""
             },
             "op": "Stop",
             "logID": "4"
         }
     ]
}

更新数据迁移任务

update-task 命令用于更新数据迁移任务。

支持的更新项包括：

  • Table routing 规则
  • Block & allow table lists 规则
  • Binlog event filter 规则

其余项均不支持更新。

支持更新项的更新步骤

  1. 使用 query-status <task-name> 查询对应数据迁移任务的状态。

    • 若 stage 不为 Paused，则先使用 pause-task <task-name | task-file> 暂停任务。

  2. 在 task.yaml 文件中更新需要修改的自定义配置或者错误配置。

  3. 使用 update-task task.yaml 更新任务配置。

  4. 使用 resume-task <task-name | task-file> 恢复任务。

不支持更新项的更新步骤

  1. 使用 query-status <task-name> 查询对应数据迁移任务的状态。

    • 若任务存在，则通过 stop-task <task-name | task-file> 停止任务。

  2. 在 task.yaml 文件中更新需要修改的自定义配置或者错误配置。

  3. 使用 start-task <config-file> 重启恢复任务。

help update-task

update a task's config for routes, filters, or block-allow-list

Usage:
  dmctl update-task [-w worker ...]  [flags]

Flags:
  -h, --help   help for update-task

Global Flags:
  -w, --worker strings   DM-worker ID

命令用法示例

update-task [-w "127.0.0.1:8262"] ./task.yaml

参数解释

  • -w：
    • 可选
    • 指定在特定的一组 DM-workers 上更新数据迁移任务的子任务
    • 如果设置，则只更新指定 DM-workers 上的子任务配置
  • config-file：
    • 必选
    • 指定 task.yaml 的文件路径

返回结果示例

update-task task.yaml

{
     "result": true,
     "msg": "",
     "workers": [
         {
             "result": true,
             "worker": "172.16.30.15:8262",
             "msg": ""
         },
         {
             "result": true,
             "worker": "172.16.30.16:8262",
             "msg": ""
         }
     ]
}

管理 DDL lock

目前与 DDL lock 相关的命令主要包括 show-ddl-locks、unlock-ddl-lock、break-ddl-lock 等。有关它们的功能、用法以及适用场景等，请参考手动处理 sharding DDL lock。

其他任务与集群管理命令

除上述常用的任务管理命令外，DM 还提供了其他一些命令用于管理数据迁移任务或 DM 集群本身。

检查任务配置文件

check-task 命令用于检查指定的数据迁移任务配置文件（task.yaml）是否合法以及上下游数据库的配置、权限、表结构等是否满足迁移需要。具体可参考上游 MySQL 实例配置前置检查。

在使用 start-task 启动迁移任务时，DM 也会执行 check-task 所做的全部检查。

help check-task

check the config file of the task

Usage:
 dmctl check-task  [flags]

Flags:
 -h, --help   help for check-task

Global Flags:
 -w, --worker strings   DM-worker ID

命令用法示例

check-task task.yaml

参数解释

  • config-file：
    • 必选
    • 指定 task.yaml 的文件路径

返回结果示例

check-task task-test.yaml

{
    "result": true,
    "msg": "check pass!!!"
}

暂停 relay 处理单元

relay 处理单元在 DM-worker 进程启动后即开始自动运行。通过使用 pause-relay 命令，我们可以暂停 relay 处理单元的运行。

当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 pause-relay 对 DM 执行变更。具体变更步骤请参考虚拟 IP 环境下切换 DM-worker 与 MySQL 实例的连接。

help pause-relay

pause DM-worker's relay unit

Usage:
  dmctl pause-relay <-w worker ...> [flags]

Flags:
  -h, --help   help for pause-relay

Global Flags:
  -w, --worker strings   DM-worker ID

命令用法示例

pause-relay -w "127.0.0.1:8262"

参数解释

  • -w：
    • 必选
    • 指定需要暂停 relay 处理单元的 DM-worker

返回结果示例

pause-relay -w "172.16.30.15:8262"

{
    "op": "InvalidRelayOp",
    "result": true,
    "msg": "",
    "workers": [
        {
            "op": "PauseRelay",
            "result": true,
            "worker": "172.16.30.15:8262",
            "msg": ""
        }
    ]
}

恢复 relay 处理单元

resume-relay 用于恢复处于 Paused 状态的 relay 处理单元。

当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 resume-relay 对 DM 执行变更。具体变更步骤请参考虚拟 IP 环境下切换 DM-worker 与 MySQL 实例的连接。

help resume-relay

resume DM-worker's relay unit

Usage:
  dmctl resume-relay <-w worker ...> [flags]

Flags:
  -h, --help   help for resume-relay

Global Flags:
  -w, --worker strings   DM-worker ID

命令用法示例

resume-relay -w "127.0.0.1:8262"

参数解释

  • -w：
    • 必选
    • 指定需要恢复 relay 处理单元的 DM-worker

返回结果示例

resume-relay -w "172.16.30.15:8262"

{
    "op": "InvalidRelayOp",
    "result": true,
    "msg": "",
    "workers": [
        {
            "op": "ResumeRelay",
            "result": true,
            "worker": "172.16.30.15:8262",
            "msg": ""
        }
    ]
}

切换 relay log 到新的子目录

relay 处理单元通过使用不同的子目录来存储来自上游不同 MySQL 实例的 binlog 数据。通过使用 switch-relay-master 命令，我们可以变更 relay 处理单元以开始使用一个新的子目录。

当需要切换 DM-worker 通过虚拟 IP 连接的上游 MySQL 时，我们需要使用 switch-relay-master 对 DM 执行变更。具体变更步骤请参考虚拟 IP 环境下切换 DM-worker 与 MySQL 实例的连接。

help switch-relay-master

switch the master server of the DM-worker's relay unit

Usage:
  dmctl switch-relay-master <-w worker ...> [flags]

Flags:
  -h, --help   help for switch-relay-master

Global Flags:
  -w, --worker strings   DM-worker ID

命令用法示例

switch-relay-master -w "127.0.0.1:8262"

参数解释

  • -w：
    • 必选
    • 指定需要切换 relay 处理单元使用子目录的 DM-worker

返回结果示例

switch-relay-master -w "172.16.30.15:8262"

{
    "result": true,
    "msg": "",
    "workers": [
        {
            "result": true,
            "worker": "172.16.30.15:8262",
            "msg": ""
        }
    ]
}

手动清理 relay log

DM 支持自动清理 relay log，但同时 DM 也支持使用 purge-relay 命令手动清理 relay log。

help purge-relay

purge relay log files of the DM-worker according to the specified filename

Usage:
  dmctl purge-relay <-w worker> [--filename] [--sub-dir] [flags]

Flags:
  -f, --filename string   name of the terminal file before which to purge relay log files. Sample format: "mysql-bin.000006"
  -h, --help              help for purge-relay
  -s, --sub-dir string    specify relay sub directory for --filename. If not specified, the latest one will be used. Sample format: "2ae76434-f79f-11e8-bde2-0242ac130008.000001"

Global Flags:
  -w, --worker strings   DM-worker ID

命令用法示例

purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003"

参数解释

  • -w：
    • 必选
    • 指定需要执行 relay log 清理操作的 DM-worker
  • --filename：
    • 必选
    • 指定标识 relay log 将要停止清理的文件名。如指定为 mysql-bin.000100，则只尝试清理到 mysql-bin.000099
  • --sub-dir：
    • 可选
    • 指定 --filename 对应的 relay log 子目录，如果不指定则会使用当前最新的子目录

返回结果示例

purge-relay -w "127.0.0.1:8262" --filename "mysql-bin.000003"

[warn] no --sub-dir specified for --filename; the latest one will be used
{
    "result": true,
    "msg": "",
    "workers": [
        {
            "result": true,
            "worker": "127.0.0.1:8262",
            "msg": ""
        }
    ]
}

预设跳过 DDL 操作

sql-skip 命令用于预设一个跳过操作。当 binlog event 的 position 或 SQL 语句与指定的 binlog-pos 或 sql-pattern 匹配时，执行该跳过操作。相关参数与结果解释，请参考sql-skip。

预设替换 DDL 操作

sql-replace 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 binlog-pos 或 sql-pattern 匹配时，执行该替换执行操作。相关参数与结果解释，请参考sql-replace。

强制刷新 task => DM-workers 映射关系

refresh-worker-tasks 命令用于强制刷新 DM-master 内存中维护的 task => DM-workers 映射关系。

dmctl 命令模式

命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。

./dmctl -master-addr 172.16.30.14:8261 start-task task.yaml
./dmctl -master-addr 172.16.30.14:8261 stop-task task
./dmctl -master-addr 172.16.30.14:8261 query-status

Available Commands:
  break-ddl-lock        break-ddl-lock <-w worker ...>  [--remove-id] [--exec] [--skip]
  check-task            check-task 
  migrate-relay         migrate-relay   
  pause-relay           pause-relay <-w worker ...>
  pause-task            pause-task [-w worker ...] 
  purge-relay           purge-relay <-w worker> [--filename] [--sub-dir]
  query-error           query-error [-w worker ...] [task-name]
  query-status          query-status [-w worker ...] [task-name]
  refresh-worker-tasks  refresh-worker-tasks
  resume-relay          resume-relay <-w worker ...>
  resume-task           resume-task [-w worker ...] 
  show-ddl-locks        show-ddl-locks [-w worker ...] [task-name]
  sql-inject            sql-inject <-w worker>  
  sql-replace           sql-replace <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding]  
  sql-skip              sql-skip <-w worker> [-b binlog-pos] [-s sql-pattern] [--sharding] 
  start-task            start-task [-w worker ...] 
  stop-task             stop-task [-w worker ...] 
  switch-relay-master   switch-relay-master <-w worker ...>
  unlock-ddl-lock       unlock-ddl-lock [-w worker ...] 
  update-master-config  update-master-config 
  update-relay          update-relay [-w worker ...] 
  update-task           update-task [-w worker ...]

废弃或不推荐使用的命令

以下命令已经被废弃或仅用于 debug，在接下来的版本中可能会被移除或修改其语义，强烈不推荐使用。

  • migrate-relay
  • sql-inject
  • update-master-config
  • update-relay
下载 PDF
产品
TiDB
TiDB Cloud
生态
TiKV
TiFlash
OSS Insight
资源
TiDB 路线图
常见问题解答
开发者手册
博客
Education
支持
社区
联系我们
公司
关于我们
招贤纳士
新闻报道
© 2023 PingCAP. All Rights Reserved.