From ae34b74886e2610b265f41ed83406c94ded07952 Mon Sep 17 00:00:00 2001 From: Ran Date: Thu, 15 Jun 2023 16:06:02 +0800 Subject: [PATCH 01/10] Add temp.md --- temp.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 temp.md diff --git a/temp.md b/temp.md new file mode 100644 index 0000000000000..af27ff4986a7b --- /dev/null +++ b/temp.md @@ -0,0 +1 @@ +This is a test file. \ No newline at end of file From 62a3c655f8d15678ae05401a3c06c8f56ebc6338 Mon Sep 17 00:00:00 2001 From: Ran Date: Thu, 15 Jun 2023 16:06:06 +0800 Subject: [PATCH 02/10] Delete temp.md --- temp.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 temp.md diff --git a/temp.md b/temp.md deleted file mode 100644 index af27ff4986a7b..0000000000000 --- a/temp.md +++ /dev/null @@ -1 +0,0 @@ -This is a test file. \ No newline at end of file From 23f8ed51e845f584e76e2762818f53e14766c3e0 Mon Sep 17 00:00:00 2001 From: Ran Date: Thu, 15 Jun 2023 17:29:19 +0800 Subject: [PATCH 03/10] sql: add doc for pause/resume ddl jobs Signed-off-by: Ran --- TOC.md | 2 + ddl-introduction.md | 8 ++++ error-codes.md | 16 ++++++- .../sql-statement-admin-pause-ddl.md | 47 +++++++++++++++++++ .../sql-statement-admin-resume-ddl.md | 47 +++++++++++++++++++ .../sql-statement-admin-show-ddl.md | 4 ++ sql-statements/sql-statement-admin.md | 5 +- 7 files changed, 126 insertions(+), 3 deletions(-) create mode 100644 sql-statements/sql-statement-admin-pause-ddl.md create mode 100644 sql-statements/sql-statement-admin-resume-ddl.md diff --git a/TOC.md b/TOC.md index 53686e6656776..8bd9e554af52d 100644 --- a/TOC.md +++ b/TOC.md @@ -673,7 +673,9 @@ - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) - [`ADMIN CLEANUP`](/sql-statements/sql-statement-admin-cleanup.md) + - [`ADMIN PAUSE DDL`](/sql-statements/sql-statement-admin-pause-ddl.md) - [`ADMIN RECOVER INDEX`](/sql-statements/sql-statement-admin-recover.md) + - [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) - [`ADMIN SHOW DDL [JOBS|JOB QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) - [`ADMIN SHOW TELEMETRY`](/sql-statements/sql-statement-admin-show-telemetry.md) - [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md) diff --git a/ddl-introduction.md b/ddl-introduction.md index ae5501ea66be1..407ae18e6a274 100644 --- a/ddl-introduction.md +++ b/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. + +- `ADMIN RESUME DDL JOBS job_id [, job_id]`: Used to resume the DDL tasks that have been paused. After the command is executed, the SQL statement that executes the DDL task is displayed as being executed, and the background task is resumed. For details, refer to [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md). (Experimental feature) + + You can only resume a paused DDL task. Otherwise, the `Job 3 can't be resumed` error is shown in the `RESULT` column. + ## Common questions For common questions about DDL execution, see [SQL FAQ - DDL execution](/faq/sql-faq.md#ddl-execution). diff --git a/error-codes.md b/error-codes.md index 1e3a17aac1b72..941b7c13bf65a 100644 --- a/error-codes.md +++ b/error-codes.md @@ -468,12 +468,24 @@ TiDB is compatible with the error codes in MySQL, and in most cases returns the * Error Number: 8252 - The complete error message is as follows: - + The complete error message is as follows: + `ERROR 8252 (HY000) : Exceeded resource group quota limitation` This error is returned when the attempted consumption exceeds the resource group limit. This error is usually caused by a single transaction that is too large or too many concurrent transactions. You need to adjust the transaction size or reduce the number of concurrent clients. +* Error Number: 8260 + + DDL operations cannot be paused by `admin pause`. + +* Error Number: 8261 + + DDL operations cannot be resumed by `admin resume`. + +* Error Number: 8262 + + DDL is paused by `admin pause` and cannot be paused again. + * Error Number: 9001 The complete error message: `ERROR 9001 (HY000): PD Server Timeout` diff --git a/sql-statements/sql-statement-admin-pause-ddl.md b/sql-statements/sql-statement-admin-pause-ddl.md new file mode 100644 index 0000000000000..26d16b16d1f03 --- /dev/null +++ b/sql-statements/sql-statement-admin-pause-ddl.md @@ -0,0 +1,47 @@ +--- +title: ADMIN PAUSE DDL +summary: An overview of the usage of ADMIN PAUSE DDL for the TiDB database. +--- + +# ADMIN PAUSE DDL + +`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. + +## 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) diff --git a/sql-statements/sql-statement-admin-resume-ddl.md b/sql-statements/sql-statement-admin-resume-ddl.md new file mode 100644 index 0000000000000..4a07445482ca7 --- /dev/null +++ b/sql-statements/sql-statement-admin-resume-ddl.md @@ -0,0 +1,47 @@ +--- +title: ADMIN RESUME DDL +summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. +--- + +# ADMIN RESUME DDL + +`ADMIN RESUME DDL` allows you to resume a paused 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 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. + +## 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) diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index 1d829f8184cc1..a472b37e771c3 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -70,6 +70,7 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `rollback done`: indicates that the operation has failed and the rollback has been completed. - `rollingback`: indicates that the operation has failed and is rolling back. - `cancelling`: indicates that the operation is being canceled. This state only appears when you use the `ADMIN CANCEL DDL JOBS` command to cancel the DDL job. + - `paused`: indicates that the operation has been paused. This state only appears when you use the `ADMIN PAUSED DDL JOBS` command to pause the DDL job. You can use the `ADMIN RESUME DDL JOBS` command to resume the DDL job. @@ -94,6 +95,7 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `rollback done`: indicates that the operation has failed and the rollback has been completed. - `rollingback`: indicates that the operation has failed and is rolling back. - `cancelling`: indicates that the operation is being canceled. This state only appears when you use the `ADMIN CANCEL DDL JOBS` command to cancel the DDL job. + - `paused`: indicates that the operation has been paused. This state only appears when you use the `ADMIN PAUSED DDL JOBS` command to pause the DDL job. You can use the `ADMIN RESUME DDL JOBS` command to resume the DDL job. @@ -224,3 +226,5 @@ This statement is a TiDB extension to MySQL syntax. ## See also * [ADMIN CANCEL DDL](/sql-statements/sql-statement-admin-cancel-ddl.md) +* [ADMIN PAUSE DDL](/sql-statements/sql-statement-admin-pause-ddl.md) +* [ADMIN RESUME DDL](/sql-statements/sql-statement-admin-resume-ddl.md) diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md index ed3143031aafe..a9a03703ef130 100644 --- a/sql-statements/sql-statement-admin.md +++ b/sql-statements/sql-statement-admin.md @@ -20,7 +20,9 @@ This statement is a TiDB extension syntax, used to view the status of TiDB and c | Statement | Description | |------------------------------------------------------------------------------------------|-----------------------------| -| [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) | Cancels a currently running DDL jobs. | +| [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) | Cancels the currently running DDL jobs. | +| [`ADMIN PAUSE DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) | Pauses the currently running DDL jobs. | +| [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) | Resume the currently running DDL jobs. | | [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) | Calculates the CRC64 of all rows + indexes of a table. | | [ADMIN CHECK [TABLE\|INDEX]](/sql-statements/sql-statement-admin-check-table-index.md) | Checks for consistency of a table or index. | | [ADMIN SHOW DDL [JOBS\|QUERIES]](/sql-statements/sql-statement-admin-show-ddl.md) | Shows details about currently running or recently completed DDL jobs. | @@ -246,6 +248,7 @@ ADMIN SHOW DDL JOBS 5 WHERE state != 'synced' AND db_name = 'test'; * `rollback done`: it indicates that the operation has failed and has finished rolling back. * `rollingback`: it indicates that the operation has failed and is rolling back. * `cancelling`: it indicates that the operation is being cancelled. This state only occurs when you cancel DDL jobs using the `ADMIN CANCEL DDL JOBS` command. + * `paused`: it indicates that the operation has been paused. This state only appears when you use the `ADMIN PAUSED DDL JOBS` command to pause the DDL job. You can use the `ADMIN RESUME DDL JOBS` command to resume the DDL job. ## MySQL compatibility From 0248353b69617906c740e4675e41d45326d905a0 Mon Sep 17 00:00:00 2001 From: Ran Date: Wed, 21 Jun 2023 13:26:00 +0800 Subject: [PATCH 04/10] Update error-codes.md Co-authored-by: xixirangrang --- error-codes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/error-codes.md b/error-codes.md index 941b7c13bf65a..849a9c3e05de2 100644 --- a/error-codes.md +++ b/error-codes.md @@ -476,15 +476,15 @@ TiDB is compatible with the error codes in MySQL, and in most cases returns the * Error Number: 8260 - DDL operations cannot be paused by `admin pause`. + DDL operations cannot be paused by `ADMIN PAUSE`. * Error Number: 8261 - DDL operations cannot be resumed by `admin resume`. + DDL operations cannot be resumed by `ADMIN RESUME`. * Error Number: 8262 - DDL is paused by `admin pause` and cannot be paused again. + DDL is paused by `ADMIN PAUSE` and cannot be paused again. * Error Number: 9001 From 385afb1f6e20c6ad85da98d6efb1a58fb5809be8 Mon Sep 17 00:00:00 2001 From: Ran Date: Wed, 21 Jun 2023 13:27:21 +0800 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: xixirangrang --- sql-statements/sql-statement-admin-resume-ddl.md | 2 +- sql-statements/sql-statement-admin-show-ddl.md | 8 ++++---- sql-statements/sql-statement-admin.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/sql-statements/sql-statement-admin-resume-ddl.md b/sql-statements/sql-statement-admin-resume-ddl.md index 4a07445482ca7..81fa5432a8376 100644 --- a/sql-statements/sql-statement-admin-resume-ddl.md +++ b/sql-statements/sql-statement-admin-resume-ddl.md @@ -5,7 +5,7 @@ summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. # ADMIN RESUME DDL -`ADMIN RESUME DDL` allows you to resume a paused DDL job. The `job_id` can be found by running [`ADMIN SHOW DDL JOBS`](/sql-statements/sql-statement-admin-show-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. diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index a472b37e771c3..9da7821eac9b2 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -69,8 +69,8 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `synced`: indicates that the operation has been executed successfully and all TiDB instances have been synchronized to this state. - `rollback done`: indicates that the operation has failed and the rollback has been completed. - `rollingback`: indicates that the operation has failed and is rolling back. - - `cancelling`: indicates that the operation is being canceled. This state only appears when you use the `ADMIN CANCEL DDL JOBS` command to cancel the DDL job. - - `paused`: indicates that the operation has been paused. This state only appears when you use the `ADMIN PAUSED DDL JOBS` command to pause the DDL job. You can use the `ADMIN RESUME DDL JOBS` command to resume the DDL job. + - `cancelling`: indicates that the operation is being canceled. This state only appears when you use the [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) command to cancel the DDL job. + - `paused`: indicates that the operation has been paused. This state only appears when you use the [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) command to pause the DDL job. You can use the [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) command to resume the DDL job. @@ -94,8 +94,8 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre - `synced`: indicates that the operation has been executed successfully and all TiDB instances have been synchronized to this state. - `rollback done`: indicates that the operation has failed and the rollback has been completed. - `rollingback`: indicates that the operation has failed and is rolling back. - - `cancelling`: indicates that the operation is being canceled. This state only appears when you use the `ADMIN CANCEL DDL JOBS` command to cancel the DDL job. - - `paused`: indicates that the operation has been paused. This state only appears when you use the `ADMIN PAUSED DDL JOBS` command to pause the DDL job. You can use the `ADMIN RESUME DDL JOBS` command to resume the DDL job. + - `cancelling`: indicates that the operation is being canceled. This state only appears when you use the [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) command to cancel the DDL job. + - `paused`: indicates that the operation has been paused. This state only appears when you use the [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) command to pause the DDL job. You can use the [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) command to resume the DDL job. diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md index a9a03703ef130..ba84ab5d59eac 100644 --- a/sql-statements/sql-statement-admin.md +++ b/sql-statements/sql-statement-admin.md @@ -22,7 +22,7 @@ This statement is a TiDB extension syntax, used to view the status of TiDB and c |------------------------------------------------------------------------------------------|-----------------------------| | [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) | Cancels the currently running DDL jobs. | | [`ADMIN PAUSE DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) | Pauses the currently running DDL jobs. | -| [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) | Resume the currently running DDL jobs. | +| [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) | Resumes the paused DDL jobs. | | [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) | Calculates the CRC64 of all rows + indexes of a table. | | [ADMIN CHECK [TABLE\|INDEX]](/sql-statements/sql-statement-admin-check-table-index.md) | Checks for consistency of a table or index. | | [ADMIN SHOW DDL [JOBS\|QUERIES]](/sql-statements/sql-statement-admin-show-ddl.md) | Shows details about currently running or recently completed DDL jobs. | @@ -247,8 +247,8 @@ ADMIN SHOW DDL JOBS 5 WHERE state != 'synced' AND db_name = 'test'; * `synced`: it indicates that the operation has been performed successfully and all TiDB instances have been synced to this state. * `rollback done`: it indicates that the operation has failed and has finished rolling back. * `rollingback`: it indicates that the operation has failed and is rolling back. - * `cancelling`: it indicates that the operation is being cancelled. This state only occurs when you cancel DDL jobs using the `ADMIN CANCEL DDL JOBS` command. - * `paused`: it indicates that the operation has been paused. This state only appears when you use the `ADMIN PAUSED DDL JOBS` command to pause the DDL job. You can use the `ADMIN RESUME DDL JOBS` command to resume the DDL job. + * `cancelling`: it indicates that the operation is being cancelled. This state only occurs when you cancel DDL jobs using the [`ADMIN CANCEL DDL JOBS`](/sql-statements/sql-statement-admin-cancel-ddl.md) command. + * `paused`: it indicates that the operation has been paused. This state only appears when you use the [`ADMIN PAUSED DDL JOBS`](/sql-statements/sql-statement-admin-pause-ddl.md) command to pause the DDL job. You can use the [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md) command to resume the DDL job. ## MySQL compatibility From e0dae6e76aaa58f6152cf25cd7b0c712941beda4 Mon Sep 17 00:00:00 2001 From: Ran Date: Sun, 25 Jun 2023 14:34:12 +0800 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: xixirangrang --- sql-statements/sql-statement-admin-pause-ddl.md | 4 ++++ sql-statements/sql-statement-admin-resume-ddl.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/sql-statements/sql-statement-admin-pause-ddl.md b/sql-statements/sql-statement-admin-pause-ddl.md index 26d16b16d1f03..e7eaa3e8904ce 100644 --- a/sql-statements/sql-statement-admin-pause-ddl.md +++ b/sql-statements/sql-statement-admin-pause-ddl.md @@ -9,6 +9,10 @@ summary: An overview of the usage of ADMIN PAUSE DDL for the TiDB database. 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. +> **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 diff --git a/sql-statements/sql-statement-admin-resume-ddl.md b/sql-statements/sql-statement-admin-resume-ddl.md index 81fa5432a8376..d6c67bc8c8178 100644 --- a/sql-statements/sql-statement-admin-resume-ddl.md +++ b/sql-statements/sql-statement-admin-resume-ddl.md @@ -9,6 +9,10 @@ summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. 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. +> **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 From b6bead89d3386a698d590f9effb05b9b16b03b3c Mon Sep 17 00:00:00 2001 From: Ran Date: Sun, 25 Jun 2023 14:38:50 +0800 Subject: [PATCH 07/10] Apply suggestions from code review --- sql-statements/sql-statement-admin-pause-ddl.md | 6 +++--- sql-statements/sql-statement-admin-resume-ddl.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sql-statements/sql-statement-admin-pause-ddl.md b/sql-statements/sql-statement-admin-pause-ddl.md index e7eaa3e8904ce..01615754fb43b 100644 --- a/sql-statements/sql-statement-admin-pause-ddl.md +++ b/sql-statements/sql-statement-admin-pause-ddl.md @@ -1,9 +1,9 @@ --- -title: ADMIN PAUSE DDL -summary: An overview of the usage of ADMIN PAUSE DDL for the TiDB database. +title: ADMIN PAUSE DDL JOBS +summary: An overview of the usage of ADMIN PAUSE DDL JOBS for the TiDB database. --- -# ADMIN PAUSE DDL +# 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). diff --git a/sql-statements/sql-statement-admin-resume-ddl.md b/sql-statements/sql-statement-admin-resume-ddl.md index d6c67bc8c8178..465b18e44e462 100644 --- a/sql-statements/sql-statement-admin-resume-ddl.md +++ b/sql-statements/sql-statement-admin-resume-ddl.md @@ -1,9 +1,9 @@ --- -title: ADMIN RESUME DDL +title: ADMIN RESUME DDL JOBS summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. --- -# ADMIN RESUME DDL +# 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). From afb33612cb8939a5c71d564c8893b6551019c0ed Mon Sep 17 00:00:00 2001 From: Ran Date: Sun, 25 Jun 2023 16:03:06 +0800 Subject: [PATCH 08/10] Apply suggestions from code review --- ddl-introduction.md | 4 ++-- sql-statements/sql-statement-admin-pause-ddl.md | 2 +- sql-statements/sql-statement-admin-resume-ddl.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/ddl-introduction.md b/ddl-introduction.md index 407ae18e6a274..a7381393b69c7 100644 --- a/ddl-introduction.md +++ b/ddl-introduction.md @@ -178,9 +178,9 @@ 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) +- `ADMIN PAUSE DDL JOBS job_id [, job_id]`: Used to pause the DDL jobs that are being executed. After the command is executed, the SQL statement that executes the DDL job is displayed as being executed, while the background job has been 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. + You can only pause 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. - `ADMIN RESUME DDL JOBS job_id [, job_id]`: Used to resume the DDL tasks that have been paused. After the command is executed, the SQL statement that executes the DDL task is displayed as being executed, and the background task is resumed. For details, refer to [`ADMIN RESUME DDL JOBS`](/sql-statements/sql-statement-admin-resume-ddl.md). (Experimental feature) diff --git a/sql-statements/sql-statement-admin-pause-ddl.md b/sql-statements/sql-statement-admin-pause-ddl.md index 01615754fb43b..a5c2b775d1afd 100644 --- a/sql-statements/sql-statement-admin-pause-ddl.md +++ b/sql-statements/sql-statement-admin-pause-ddl.md @@ -7,7 +7,7 @@ summary: An overview of the usage of ADMIN PAUSE DDL JOBS for the TiDB database. `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. +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:** > diff --git a/sql-statements/sql-statement-admin-resume-ddl.md b/sql-statements/sql-statement-admin-resume-ddl.md index 465b18e44e462..39615a4f9bff2 100644 --- a/sql-statements/sql-statement-admin-resume-ddl.md +++ b/sql-statements/sql-statement-admin-resume-ddl.md @@ -7,7 +7,7 @@ summary: An overview of the usage of ADMIN RESUME DDL for the TiDB database. `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. +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:** > From 48fde002f17ed69463bd4f9ce4bf426607954772 Mon Sep 17 00:00:00 2001 From: Ran Date: Mon, 26 Jun 2023 14:03:57 +0800 Subject: [PATCH 09/10] add links to TOC-tidb-cloud --- TOC-tidb-cloud.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index 1802e1d183456..1958cb1b6caa2 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -263,6 +263,8 @@ - [`ADMIN CANCEL DDL`](/sql-statements/sql-statement-admin-cancel-ddl.md) - [`ADMIN CHECKSUM TABLE`](/sql-statements/sql-statement-admin-checksum-table.md) - [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) + - [`ADMIN PAUSE DDL`](/sql-statements/sql-statement-admin-pause-ddl.md) + - [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) - [`ADMIN SHOW DDL [JOBS|JOB QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) - [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md) - [`ALTER INDEX`](/sql-statements/sql-statement-alter-index.md) From 1a58d864abe69a80760282fbd3848468d19d041d Mon Sep 17 00:00:00 2001 From: Ran Date: Mon, 26 Jun 2023 15:39:08 +0800 Subject: [PATCH 10/10] add custom content add custom content 2 Signed-off-by: Ran --- sql-statements/sql-statement-admin-pause-ddl.md | 14 ++++++++++++++ sql-statements/sql-statement-admin-resume-ddl.md | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/sql-statements/sql-statement-admin-pause-ddl.md b/sql-statements/sql-statement-admin-pause-ddl.md index a5c2b775d1afd..75fd004a424a6 100644 --- a/sql-statements/sql-statement-admin-pause-ddl.md +++ b/sql-statements/sql-statement-admin-pause-ddl.md @@ -33,6 +33,8 @@ 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. @@ -40,6 +42,18 @@ If the pause fails, the specific reason for the failure is displayed. > + 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. + + + +> **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. + + + ## MySQL compatibility This statement is a TiDB extension to MySQL syntax. diff --git a/sql-statements/sql-statement-admin-resume-ddl.md b/sql-statements/sql-statement-admin-resume-ddl.md index 39615a4f9bff2..a68a5ee135a7e 100644 --- a/sql-statements/sql-statement-admin-resume-ddl.md +++ b/sql-statements/sql-statement-admin-resume-ddl.md @@ -33,6 +33,8 @@ 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). @@ -40,6 +42,18 @@ If the resume fails, the specific reason for the failure is displayed. > + 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`. + + + +> **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`. + + + ## MySQL compatibility This statement is a TiDB extension to MySQL syntax.