Add description on admin pause ddl jobs and admin resume ddl jobs
#13897
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| title: ADMIN PAUSE DDL | ||
| summary: An overview of the usage of ADMIN PAUSE DDL for the TiDB database. | ||
| --- | ||
|
|
||
| # ADMIN PAUSE DDL | ||
|
There was a problem hiding this comment. 需要统一成 ADMIN PAUSE DDL JOBS 吗？
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| `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. | ||
|
There was a problem hiding this comment. "If you try to pause a DDL job that has already been completed, you will see the 这里用上了虚拟语气，可能需要保持一致
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| > **Warning:** | ||
| > | ||
| > This feature is an experimental feature. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. | ||
|
|
||
| ## Synopsis | ||
|
|
||
| ```ebnf+diagram | ||
| AdminStmt ::= | ||
| 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'PAUSE' 'DDL' 'JOBS' NumList | 'RESUME' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) | ||
|
|
||
| NumList ::= | ||
| Int64Num ( ',' Int64Num )* | ||
| ``` | ||
|
|
||
| ## Examples | ||
|
|
||
| `ADMIN PAUSE DDL JOBS` pauses the currently running DDL job and returns whether the job is paused successfully. The job can be resumed by `ADMIN RESUME DDL JOBS`. | ||
|
|
||
| ```sql | ||
| ADMIN PAUSE DDL JOBS job_id [, job_id] ...; | ||
| ``` | ||
|
|
||
| If the pause fails, the specific reason for the failure is displayed. | ||
|
|
||
| > **Note:** | ||
| > | ||
| > + This statement can pause a DDL job, but other operations and environment changes (such as machine restarts and cluster restarts) do not pause DDL jobs except for cluster upgrades. | ||
| > + During the cluster upgrade, the ongoing DDL jobs are paused, and the DDL jobs initiated during the upgrade are also paused. After the upgrade, all paused DDL jobs will resume. The pause and resume operations during the upgrade are taken automatically. For details, see [TiDB Smooth Upgrade](/smooth-upgrade-tidb.md). | ||
| > + This statement can pause multiple DDL jobs. You can use the [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md) statement to obtain the `job_id` of a DDL job. | ||
| > + If the job to be paused has already been completed or is about to be completed, the pause operation will fail. | ||
|
|
||
| ## MySQL compatibility | ||
|
|
||
| This statement is a TiDB extension to MySQL syntax. | ||
|
|
||
| ## See also | ||
|
|
||
| * [`ADMIN SHOW DDL [JOBS|QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) | ||
| * [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) | ||
| * [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| title: ADMIN RESUME DDL | ||
| summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. | ||
| --- | ||
|
|
||
| # ADMIN RESUME DDL | ||
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| `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. | ||
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| > **Warning:** | ||
| > | ||
| > This feature is an experimental feature. It is not recommended that you use it in the production environment. This feature might be changed or removed without prior notice. If you find a bug, you can report an [issue](https://github.com/pingcap/tidb/issues) on GitHub. | ||
|
|
||
| ## Synopsis | ||
|
|
||
| ```ebnf+diagram | ||
| AdminStmt ::= | ||
| 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'PAUSE' 'DDL' 'JOBS' NumList | 'RESUME' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) | ||
|
|
||
| NumList ::= | ||
| Int64Num ( ',' Int64Num )* | ||
| ``` | ||
|
|
||
| ## Examples | ||
|
|
||
| `ADMIN RESUME DDL JOBS` resumes the currently paused DDL job and returns whether the job is resumed successfully. | ||
|
|
||
| ```sql | ||
| ADMIN RESUME DDL JOBS job_id [, job_id] ...; | ||
| ``` | ||
|
|
||
| If the resume fails, the specific reason for the failure is displayed. | ||
|
|
||
| > **Note:** | ||
| > | ||
| > + During the cluster upgrade, the ongoing DDL jobs are paused, and the DDL jobs initiated during the upgrade are also paused. After the upgrade, all paused DDL jobs will resume. The pause and resume operations during the upgrade are taken automatically. For details, see [TiDB Smooth Upgrade](/smooth-upgrade-tidb.md). | ||
| > + This statement can resume multiple DDL jobs. You can use the [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-ddl.md) statement to obtain the `job_id` of a DDL job. | ||
| > + A DDL job in other status (other than `paused`) cannot be resumed and the resume operation will fail. | ||
| > + If you try to resume a job more than once, TiDB reports an error `Error Number: 8261`. | ||
|
|
||
| ## MySQL compatibility | ||
|
|
||
| This statement is a TiDB extension to MySQL syntax. | ||
|
|
||
| ## See also | ||
|
|
||
| * [`ADMIN SHOW DDL [JOBS|QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) | ||
| * [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) | ||
| * [`ADMIN PAUSE DDL`](/sql-statements/sql-statement-admin-pause-ddl.md) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
tasks ----> jobs
We'd better keep the concept identical.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"After the command is executed"
---->
"After the command was executed"
假设语句要用虚拟语气
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"displayed as being executed, and the background task is pause"
---->
"displayed as executing, while the background job has been paused"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Used to pause the DDL tasks that are being executed."
---->
"Used to pause the DDL tasks that are being executing." 感觉这样要更好些