Add description on `admin pause ddl jobs` and `admin resume ddl jobs` #13897

ran-huang · 2023-06-15T08:06:03Z

First-time contributors' checklist

I've signed Contributor License Agreement that's required for repo owners to accept my contribution.

What is changed, added or deleted? (Required)

Add description about the new admin command:

admin pause ddl jobs
admin resume ddl jobs

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions (in Chinese).

What is the related PR or file link(s)?

This PR is translated from: Add description on admin pause ddl jobs and admin resume ddl jobs docs-cn#14199
- ddl, parser, planner: admin Pause/Resume on DDL jobs tidb#43081
- ddl: design doc for admin pause/resume ddl jobs tidb#43159
Other reference link(s):
- Pause add an index(write reorganization) and set a time window to resume tidb#18015
- Add backend task pause|resume feature. tidb#40041

Related issue number:

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

Signed-off-by: Ran <huangran.alex@gmail.com>

error-codes.md

sql-statements/sql-statement-admin-resume-ddl.md

sql-statements/sql-statement-admin.md

hfxsd · 2023-06-20T06:18:37Z

sql-statements/sql-statement-admin-pause-ddl.md

+summary: An overview of the usage of ADMIN PAUSE DDL for the TiDB database.
+---
+
+# ADMIN PAUSE DDL


需要统一成 ADMIN PAUSE DDL JOBS 吗？

sql-statements/sql-statement-admin.md

sql-statements/sql-statement-admin-show-ddl.md

sql-statements/sql-statement-admin-pause-ddl.md

sql-statements/sql-statement-admin-resume-ddl.md

Co-authored-by: xixirangrang <hfxsd@hotmail.com>

sql-statements/sql-statement-admin-pause-ddl.md

sql-statements/sql-statement-admin-resume-ddl.md

dhysum · 2023-06-25T06:42:48Z

ddl-introduction.md

@@ -178,6 +178,14 @@ When TiDB is adding an index, the phase of backfilling data will cause read and

    If a completed DDL task is canceled, you can see the `DDL Job:90 not found` error in the `RESULT` column, which means that the task has been removed from the DDL waiting queue.

+- `ADMIN PAUSE DDL JOBS job_id [, job_id]`: Used to pause the DDL tasks that are being executed. After the command is executed, the SQL statement that executes the DDL task is displayed as being executed, and the background task is paused. For details, refer to [`ADMIN PAUSE DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md). (Experimental feature)


tasks ----> jobs

We'd better keep the concept identical.

"After the command is executed"
---->
"After the command was executed"

假设语句要用虚拟语气

"displayed as being executed, and the background task is pause"

---->

"displayed as executing, while the background job has been paused"

"Used to pause the DDL tasks that are being executed."

---->

"Used to pause the DDL tasks that are being executing." 感觉这样要更好些

dhysum · 2023-06-25T06:55:58Z

sql-statements/sql-statement-admin-pause-ddl.md

+
+`ADMIN PAUSE DDL` allows you to pause a running DDL job. The `job_id` can be found by running [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md).
+
+You can use this statement to pause a DDL job that is committed but not yet completed executing. After the pause, the SQL statement that executes the DDL job does not return immediately, but looks like it is still running. If you try to pause a DDL job that has already been completed, you will see the `DDL Job:90 not found` error in the `RESULT` column, which indicates that the job has been removed from the DDL waiting queue.


"committed" seems not correct.

中文原文中的“已提交”是指已提到后端的意思，刚刚已改为“已发起”

"If you try to pause a DDL job that has already been completed, you will see the DDL Job:90 not found error in the RESULT column, which indicates that the job has been removed from the DDL waiting queue."

这里用上了虚拟语气，可能需要保持一致

dhysum · 2023-06-25T06:56:33Z

sql-statements/sql-statement-admin-resume-ddl.md

+
+`ADMIN RESUME DDL` allows you to resume a paused DDL job. You can find the `job_id` by running [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md).
+
+You can use this statement to resume a paused DDL job. After the resume is complete, the SQL statement that executes the DDL job continues to show as being executed. If you try to resume a DDL job that has already been completed, you will see the `DDL Job:90 not found` error in the `RESULT` column, which indicates that the job has been removed from the DDL waiting queue.


complete ----> completed

dhysum · 2023-06-25T07:04:18Z

ddl-introduction.md

@@ -178,6 +178,14 @@ When TiDB is adding an index, the phase of backfilling data will cause read and

    If a completed DDL task is canceled, you can see the `DDL Job:90 not found` error in the `RESULT` column, which means that the task has been removed from the DDL waiting queue.

+- `ADMIN PAUSE DDL JOBS job_id [, job_id]`: Used to pause the DDL tasks that are being executed. After the command is executed, the SQL statement that executes the DDL task is displayed as being executed, and the background task is paused. For details, refer to [`ADMIN PAUSE DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md). (Experimental feature)
+
+    You can pause only DDL tasks that are in progress or still in the queue. Otherwise, the `Job 3 can't be paused now` error is shown in the `RESULT` column.


"only" 感觉放在 "pause" 前面更好些

dhysum · 2023-06-25T07:11:59Z

lgtm

sql-statements/sql-statement-admin-pause-ddl.md

ddl-introduction.md

sql-statements/sql-statement-admin-resume-ddl.md

ddl-introduction.md

ti-chi-bot · 2023-06-26T02:29:05Z

[LGTM Timeline notifier]

Timeline:

2023-06-26 02:29:04.822910579 +0000 UTC m=+588310.224161026: ☑️ agreed by hfxsd.

ran-huang · 2023-06-26T03:47:00Z

/approve

ti-chi-bot · 2023-06-26T03:47:05Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ran-huang

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [ran-huang]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

add custom content 2 Signed-off-by: Ran <huangran.alex@gmail.com>

Add temp.md

ae34b74

ran-huang added translation/from-docs-cn This PR is translated from a PR in pingcap/docs-cn. v7.2 labels Jun 15, 2023

Delete temp.md

62a3c65

ti-chi-bot bot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Jun 15, 2023

sql: add doc for pause/resume ddl jobs

23f8ed5

Signed-off-by: Ran <huangran.alex@gmail.com>

ran-huang self-assigned this Jun 15, 2023

ti-chi-bot bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Jun 15, 2023

ran-huang requested a review from hfxsd June 19, 2023 03:19