[2.0.2] *: update operate-schema (#606)

en/manage-schema.md

@@ -15,6 +15,8 @@ When you migrate tables using DM, DM performs the following operations on the ta
 
 - For incremental replication, the whole data link contains the following table schemas, which might be the same or different:
 
+    ![schema](/media/operate-schema.png)
+
     * The upstream table schema at the current time, identified as `schema-U`.
     * The table schema of the binlog event currently being consumed by DM, identified as `schema-B`. This schema corresponds to the upstream table schema at a historical time.
     * The table schema currently maintained in DM (the schema tracker component), identified as `schema-I`.
@@ -39,23 +41,26 @@ help operate-schema
 ```
 
 ```
-get/set/remove the schema for an upstream table
+`get`/`set`/`remove` the schema for an upstream table.
 
 Usage:
-  dmctl operate-schema <operate-type> <-s source ...> <task-name | task-file> <-d database> <-t table> [schema-file] [flags]
+  dmctl operate-schema <operate-type> <-s source ...> <task-name | task-file> <-d database> <-t table> [schema-file] [--flush] [--sync] [flags]
 
 Flags:
   -d, --database string   database name of the table
+      --flush             flush the table info and checkpoint immediately
   -h, --help              help for operate-schema
+      --sync              sync the table info to master to resolve shard ddl lock, only for optimistic mode now
   -t, --table string      table name
 
 Global Flags:
-  -s, --source strings   MySQL Source ID
+  -s, --source strings   MySQL Source ID.
 ```
 
 > **Note:**
 >
-> Because a table schema might change during data migration, to obtain a predictable table schema, currently the `operate-schema` command can be used only when the data migration task is in the `Paused` state.
+> - Because a table schema might change during data migration, to obtain a predictable table schema, currently the `operate-schema` command can be used only when the data migration task is in the `Paused` state.
+> - To avoid data loss due to mishandling, it is **strongly recommended** to get and backup the table schema firstly before you modify the schema.
 
 ## Parameters
 
@@ -77,6 +82,12 @@ Global Flags:
 * `schema-file`:
     - Required when the operation type is `set`. Optional for other operation types.
     - The table schema file to be set. The file content should be a valid `CREATE TABLE` statement.
+* `--flush`:
+    - Optional.
+    - Writes the schema to the checkpoint so that DM can load it after restarting the task.
+* `--sync`:
+    - Optional. Only used when an error occurs in the optimistic sharding DDL mode.
+    - Updates the optimistic sharding metadata with this schema.
 
 ## Usage example
 

zh/manage-schema.md

@@ -15,6 +15,8 @@ summary: 了解如何管理待迁移表在 DM 内部的表结构。
 
 对于增量复制，在整个数据链路中则包含以下几类可能相同或不同的表结构。
 
+![表结构](/media/operate-schema.png)
+
 - 上游当前时刻的表结构（记为 `schema-U`）。
 - 当前 DM 正在消费的 binlog event 的表结构（记为 `schema-B`，其对应于上游某个历史时刻的表结构）。
 - DM 内部（schema tracker 组件）当前维护的表结构（记为 `schema-I`）。
@@ -39,23 +41,26 @@ help operate-schema
 ```
 
 ```
-get/set/remove the schema for an upstream table
+`get`/`set`/`remove` the schema for an upstream table.
 
 Usage:
-  dmctl operate-schema <operate-type> <-s source ...> <task-name | task-file> <-d database> <-t table> [schema-file] [flags]
+  dmctl operate-schema <operate-type> <-s source ...> <task-name | task-file> <-d database> <-t table> [schema-file] [--flush] [--sync] [flags]
 
 Flags:
   -d, --database string   database name of the table
+      --flush             flush the table info and checkpoint immediately
   -h, --help              help for operate-schema
+      --sync              sync the table info to master to resolve shard ddl lock, only for optimistic mode now
   -t, --table string      table name
 
 Global Flags:
-  -s, --source strings   MySQL Source ID
+  -s, --source strings   MySQL Source ID.
 ```
 
 > **注意：**
 >
-> 由于表结构在数据迁移过程中可能会发生变更，为获取确定性的表结构，当前 `operate-schema` 命令仅能在数据迁移任务处于 `Paused` 状态时可用。
+> - 由于表结构在数据迁移过程中可能会发生变更，为获取确定性的表结构，当前 `operate-schema` 命令仅能在数据迁移任务处于 `Paused` 状态时可用。
+> - 强烈建议在修改表结构前，首先获取并备份表结构，以免误操作导致数据丢失。
 
 ## 参数解释
 
@@ -77,6 +82,12 @@ Global Flags:
 + `schema-file`:
     - `set` 操作时必选，其他操作不需指定
     - 将被设置的表结构文件，文件内容应为一个合法的 `CREATE TABLE` 语句
++ `--flush`:
+    - 可选
+    - 同时将表结构写入 checkpoint，从而在任务重启后加载到该表结构
++ `--sync`:
+    - 可选
+    - 仅在乐观协调 DDL 出错时使用。使用该表结构更新乐观协调元数据中的表结构
 
 ## 使用示例