-
Notifications
You must be signed in to change notification settings - Fork 702
Add description on admin pause ddl jobs and admin resume ddl jobs
#13897
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
ti-chi-bot
merged 11 commits into
pingcap:master
from
ran-huang:dev/admin_pause_resume-14199
Jun 26, 2023
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
ae34b74
Add temp.md
ran-huang 62a3c65
Delete temp.md
ran-huang 23f8ed5
sql: add doc for pause/resume ddl jobs
ran-huang 0248353
Update error-codes.md
ran-huang 385afb1
Apply suggestions from code review
ran-huang e0dae6e
Apply suggestions from code review
ran-huang b6bead8
Apply suggestions from code review
ran-huang afb3361
Apply suggestions from code review
ran-huang a952ac3
Merge branch 'master' into dev/admin_pause_resume-14199
ran-huang 48fde00
add links to TOC-tidb-cloud
ran-huang 1a58d86
add custom content
ran-huang File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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 hidden or 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 hidden or 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 hidden or 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 hidden or 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,65 @@ | ||
| --- | ||
| title: ADMIN PAUSE DDL JOBS | ||
| summary: An overview of the usage of ADMIN PAUSE DDL JOBS for the TiDB database. | ||
| --- | ||
|
|
||
| # ADMIN PAUSE DDL JOBS | ||
|
|
||
| `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 issued 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. | ||
|
|
||
| > **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. | ||
|
|
||
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## 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. | ||
|
|
||
| <CustomContent platform="tidb"> | ||
|
|
||
| > **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. | ||
|
|
||
| </CustomContent> | ||
| <CustomContent platform="tidb-cloud"> | ||
|
|
||
| > **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](https://docs.pingcap.com/tidb/stable/smooth-upgrade-tidb). | ||
| > + 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. | ||
|
|
||
| </CustomContent> | ||
|
|
||
| ## 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 hidden or 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,65 @@ | ||
| --- | ||
| title: ADMIN RESUME DDL JOBS | ||
| summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. | ||
| --- | ||
|
|
||
| # ADMIN RESUME DDL JOBS | ||
|
|
||
| `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 completed, 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. | ||
|
|
||
| > **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. | ||
|
|
||
ran-huang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## 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. | ||
|
|
||
| <CustomContent platform="tidb"> | ||
|
|
||
| > **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`. | ||
|
|
||
| </CustomContent> | ||
| <CustomContent platform="tidb-cloud"> | ||
|
|
||
| > **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](https://docs.pingcap.com/tidb/stable/smooth-upgrade-tidb). | ||
| > + 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`. | ||
|
|
||
| </CustomContent> | ||
|
|
||
| ## 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 hidden or 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 hidden or 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.
Uh oh!
There was an error while loading. Please reload this page.