管理数据迁移任务

本文介绍了如何使用 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-statusquery-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-taskpause-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-locksunlock-ddl-lockbreak-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-possql-pattern 匹配时,执行该跳过操作。相关参数与结果解释,请参考sql-skip

预设替换 DDL 操作

sql-replace 命令用于预设一个替换执行操作。当 binlog event 的 position 或 SQL 语句与指定的 binlog-possql-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
© 2024 PingCAP. All Rights Reserved.
Privacy Policy.