cherry pick pingcap#220 to release-1.0

Signed-off-by: ti-srebot <[email protected]>

zh/dmctl-introduction.md

@@ -0,0 +1,114 @@
+---
+title: dmctl 简介
+summary: 了解如何使用 dmctl 管理数据同步任务。
+aliases: ['/docs-cn/tidb-data-migration/dev/dmctl-introduction/','/docs-cn/tidb-data-migration/dev/manage-replication-tasks/']
+---
+
+# dmctl 简介
+
+dmctl 是用来控制 DM 集群的命令行工具。对于用 DM-Ansible 部署的 DM 集群，dmctl 二进制文件路径为 `dm-ansible/dmctl`。
+
+dmctl 同时支持交互模式和命令模式。
+
+## dmctl 交互模式
+
+进入交互模式，与 DM-master 进行交互：
+
+> **注意：**
+>
+> 交互模式下不具有 bash 的特性，比如不需要通过引号传递字符串参数而应当直接传递。
+
+{{< copyable "shell-regular" >}}
+
+```bash
+./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:
+  check-task           check the config file of the task
+  help                 help about any command
+  migrate-relay        migrate DM-worker's relay unit
+  offline-worker       offline worker which has been closed
+  operate-source       create/update/stop/show upstream MySQL/MariaDB source
+  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
+  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
+  -s, --source strings   MySQL Source ID
+
+Use `dmctl [command] --help` to get more information about a command.
+```
+
+## dmctl 命令模式
+
+命令模式跟交互模式的区别是，执行命令时只需要在 dmctl 命令后紧接着执行任务操作，任务操作同交互模式的参数一致。
+
+> **注意：**
+>
+> + 一条 dmctl 命令只能跟一个任务操作
+> + 任务操作只能放在 dmctl 命令的最后
+
+{{< copyable "shell-regular" >}}
+
+```bash
+./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:
+  check-task            check-task <config-file>
+  migrate-relay         migrate-relay <source> <binlogName> <binlogPos>
+  offline-worker        offline-worker <name> <address>
+  operate-source        operate-source <operate-type> [config-file ...] [--print-sample-config]
+  pause-relay           pause-relay <-s source ...>
+  pause-task            pause-task [-s source ...] <task-name | task-file>
+  purge-relay           purge-relay <-s source> [--filename] [--sub-dir]
+  query-error           query-error [-s source ...] [task-name]
+  query-status          query-status [-s source ...] [task-name] [--more]
+  resume-relay          resume-relay <-s source ...>
+  resume-task           resume-task [-s source ...] <task-name | task-file>
+  show-ddl-locks        show-ddl-locks [-s source ...] [task-name]
+  sql-inject            sql-inject <-s source> <task-name> <sql1;sql2;>
+  sql-replace           sql-replace <-s source> [-b binlog-pos] [-p sql-pattern] [--sharding] <task-name> <sql1;sql2;>
+  sql-skip              sql-skip <-s source> [-b binlog-pos] [-p sql-pattern] [--sharding] <task-name>
+  start-task            start-task [-s source ...] <config-file>
+  stop-task             stop-task [-s source ...] <task-name | task-file>
+  switch-relay-master   switch-relay-master <-s source ...>
+  unlock-ddl-lock       unlock-ddl-lock [-s source ...] <lock-ID>
+  update-master-config  update-master-config <config-file>
+  update-relay          update-relay [-s source ...] <config-file>
+  update-task           update-task [-s source ...] <config-file>
+```

zh/pause-task.md

@@ -0,0 +1,78 @@
+---
+title: 暂停数据同步任务
+summary: 了解 TiDB Data Migration 如何暂停数据同步任务。
+aliases: ['/docs-cn/tidb-data-migration/dev/pause-task/']
+---
+
+# 暂停数据同步任务
+
+`pause-task` 命令用于暂停数据同步任务。
+
+> **注意：**
+>
+> 有关 `pause-task` 与 `stop-task` 的区别如下：
+>
+> - 使用 `pause-task` 仅暂停同步任务的执行，但仍然会在内存中保留任务的状态信息等，且可通过 `query-status` 进行查询；使用 `stop-task` 会停止同步任务的执行，并移除内存中与该任务相关的信息，且不可再通过 `query-status` 进行查询，但不会移除已经写入到下游数据库中的数据以及其中的 checkpoint 等 `dm_meta` 信息。
+> - 使用 `pause-task` 暂停同步任务期间，由于任务本身仍然存在，因此不能再启动同名的新任务，且会阻止对该任务所需 relay log 的清理；使用 `stop-task` 停止任务后，由于任务不再存在，因此可以再启动同名的新任务，且不会阻止对 relay log 的清理。
+> - `pause-task` 一般用于临时暂停同步任务以排查问题等；`stop-task` 一般用于永久删除同步任务或通过与 `start-task` 配合以更新配置信息。
+
+{{< copyable "" >}}
+
+```bash
+help pause-task
+```
+
+```
+pause a specified running task
+
+Usage:
+ dmctl pause-task [-s source ...] <task-name | task-file> [flags]
+
+Flags:
+ -h, --help   help for pause-task
+
+Global Flags:
+ -s, --source strings   MySQL Source ID
+```
+
+## 命令用法示例
+
+{{< copyable "" >}}
+
+```bash
+pause-task [-s "mysql-replica-01"] task-name
+```
+
+## 参数解释
+
+- `-s`：
+    - 可选
+    - 指定在特定的一个 MySQL 源上暂停数据同步任务的子任务
+    - 如果设置，则只暂停该任务在指定 MySQL 源上的子任务
+- `task-name| task-file`：
+    - 必选
+    - 指定任务名称或任务文件路径
+
+## 返回结果示例
+
+{{< copyable "" >}}
+
+```bash
+pause-task test
+```
+
+```
+{
+    "op": "Pause",
+    "result": true,
+    "msg": "",
+    "sources": [
+        {
+            "result": true,
+            "msg": "",
+            "source": "mysql-replica-01",
+            "worker": "worker1"
+        }
+    ]
+}
+```

zh/resume-task.md

@@ -0,0 +1,70 @@
+---
+title: 恢复数据同步任务
+summary: 了解 TiDB Data Migration 如何恢复数据同步任务。
+aliases: ['/docs-cn/tidb-data-migration/dev/resume-task/']
+---
+
+# 恢复数据同步任务
+
+`resume-task` 命令用于恢复处于 `Paused` 状态的数据同步任务，通常用于在人为处理完造成同步任务暂停的故障后手动恢复同步任务。
+
+{{< copyable "" >}}
+
+```bash
+help resume-task
+```
+
+```
+resume a specified paused task
+
+Usage:
+ dmctl resume-task [-s source ...] <task-name | task-file> [flags]
+
+Flags:
+ -h, --help   help for resume-task
+
+Global Flags:
+ -s, --source strings   MySQL Source ID
+```
+
+## 命令用法示例
+
+{{< copyable "" >}}
+
+```bash
+resume-task [-s "mysql-replica-01"] task-name
+```
+
+## 参数解释
+
+- `-s`：
+    - 可选
+    - 指定在特定的一个 MySQL 源上恢复数据同步任务的子任务
+    - 如果设置，则只恢复该任务在指定 MySQL 源上的子任务
+- `task-name | task-file`：
+    - 必选
+    - 指定任务名称或任务文件路径
+
+## 返回结果示例
+
+{{< copyable "" >}}
+
+```bash
+resume-task test
+```
+
+```
+{
+    "op": "Resume",
+    "result": true,
+    "msg": "",
+    "sources": [
+        {
+            "result": true,
+            "msg": "",
+            "source": "mysql-replica-01",
+            "worker": "worker1"
+        }
+    ]
+}
+```

zh/stop-task.md

@@ -0,0 +1,70 @@
+---
+title: 停止数据同步任务
+summary: 了解 TiDB Data Migration 如何停止数据同步任务。
+aliases: ['/docs-cn/tidb-data-migration/dev/stop-task/']
+---
+
+# 停止数据同步任务
+
+`stop-task` 命令用于停止数据同步任务。有关 `stop-task` 与 `pause-task` 的区别，请参考[暂停数据同步任务](pause-task.md)中的相关说明。
+
+{{< copyable "" >}}
+
+```bash
+help stop-task
+```
+
+```
+stop a specified task
+
+Usage:
+ dmctl stop-task [-s source ...] <task-name | task-file> [flags]
+
+Flags:
+ -h, --help   help for stop-task
+
+Global Flags:
+ -s, --source strings   MySQL Source ID
+```
+
+## 命令用法示例
+
+{{< copyable "" >}}
+
+```bash
+stop-task [-s "mysql-replica-01"]  task-name
+```
+
+## 参数解释
+
+- `-s`：
+    - 可选
+    - 指定在特定的一个 MySQL 源上停止数据同步任务的子任务
+    - 如果设置，则只停止该任务在指定 MySQL 源上的子任务
+- `task-name | task-file`：
+    - 必选
+    - 指定任务名称或任务文件路径
+
+## 返回结果示例
+
+{{< copyable "" >}}
+
+```bash
+stop-task test
+```
+
+```
+{
+    "op": "Stop",
+    "result": true,
+    "msg": "",
+    "sources": [
+        {
+            "result": true,
+            "msg": "",
+            "source": "mysql-replica-01",
+            "worker": "worker1"
+        }
+    ]
+}
+```

zh/task-configuration-file.md

@@ -89,6 +89,6 @@ mysql-instances:
 
 1. 修改任务配置文件，将 `remove-meta` 设置为 `false`
 
-2. 通过 `stop-task` 命令停止任务：`stop-task <task-name>`
+2. 通过 `stop-task` 命令停止任务：`stop-task <task-name | task-file>`
 
 3. 通过 `start-task` 命令启动任务：`start-task <config-file>`