From afad47db764a3eba0534e094fdc408a06dbc55c7 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 28 Feb 2024 16:03:32 +0800 Subject: [PATCH 1/5] *: add a restriction for smooth-upgrade-tidb --- smooth-upgrade-tidb.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 3901bc018e8dd..546488163b49b 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -84,6 +84,10 @@ When using the smooth upgrade feature, note the following limitations. * Run DDL operations on system tables (`mysql.*`, `information_schema.*`, `performance_schema.*`, and `metrics_schema.*`). * Manually cancel DDL jobs: `ADMIN CANCEL DDL JOBS job_id [, job_id] ...;`. * Import data. + * If the TiDB Distributed eXecution Framework (DXF) is enabled before the smooth upgrade, and there are ongoing `ADD INDEX` or `IMPORT INTO` tasks during the upgrade, perform the following steps to mitigate potential issues: + 1. Disable the DXF by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-span-classversion-marknew-in-v710span) to `OFF` (its default value). + 2. Ensure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed before the upgrade starts. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. + 3. After completing the preceding two steps, you can proceed with the smooth upgrade. ### Limitations on tools From 45a4119c2a5c64530089ad8db2829f49b3fe8ae0 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 28 Feb 2024 16:08:41 +0800 Subject: [PATCH 2/5] make ci happy --- smooth-upgrade-tidb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 546488163b49b..91f9d253f45c0 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -85,7 +85,7 @@ When using the smooth upgrade feature, note the following limitations. * Manually cancel DDL jobs: `ADMIN CANCEL DDL JOBS job_id [, job_id] ...;`. * Import data. * If the TiDB Distributed eXecution Framework (DXF) is enabled before the smooth upgrade, and there are ongoing `ADD INDEX` or `IMPORT INTO` tasks during the upgrade, perform the following steps to mitigate potential issues: - 1. Disable the DXF by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-span-classversion-marknew-in-v710span) to `OFF` (its default value). + 1. Disable the DXF by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) to `OFF` (its default value). 2. Ensure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed before the upgrade starts. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. 3. After completing the preceding two steps, you can proceed with the smooth upgrade. From 3dab541fb8e98dce00e513ac0d2bd798f4273953 Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 29 Feb 2024 13:50:22 +0800 Subject: [PATCH 3/5] Apply suggestions from code review --- smooth-upgrade-tidb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index 91f9d253f45c0..a0f4ed71b06e6 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -84,7 +84,7 @@ When using the smooth upgrade feature, note the following limitations. * Run DDL operations on system tables (`mysql.*`, `information_schema.*`, `performance_schema.*`, and `metrics_schema.*`). * Manually cancel DDL jobs: `ADMIN CANCEL DDL JOBS job_id [, job_id] ...;`. * Import data. - * If the TiDB Distributed eXecution Framework (DXF) is enabled before the smooth upgrade, and there are ongoing `ADD INDEX` or `IMPORT INTO` tasks during the upgrade, perform the following steps to mitigate potential issues: + * Run distributed `ADD INDEX` or `IMPORT INTO` tasks. If the TiDB Distributed eXecution Framework (DXF) is enabled before the smooth upgrade, and there are ongoing `ADD INDEX` or `IMPORT INTO` tasks during the upgrade, perform the following steps to mitigate potential issues: 1. Disable the DXF by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) to `OFF` (its default value). 2. Ensure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed before the upgrade starts. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. 3. After completing the preceding two steps, you can proceed with the smooth upgrade. From 2f8404ec9942ab0a65d8aec6c36db9094e4a7591 Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 29 Feb 2024 15:27:40 +0800 Subject: [PATCH 4/5] update --- smooth-upgrade-tidb.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index a0f4ed71b06e6..f467f4b6dd8d9 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -75,7 +75,10 @@ When using the smooth upgrade feature, note the following limitations. ### Limitations on user operations -* Before the upgrade, if there is a canceling DDL job in the cluster, that is, an ongoing DDL job is being canceled by a user, because the job in the canceling state cannot be paused, TiDB will retry canceling the job. If the retry fails, an error is reported and the upgrade is exited. +* Before the upgrade, consider the following restrictions: + + * If there is a canceling DDL job in the cluster, that is, an ongoing DDL job is being canceled by a user, because the job in the canceling state cannot be paused, TiDB will retry canceling the job. If the retry fails, an error is reported and the upgrade is exited. + * If the TiDB Distributed eXecution Framework (DXF) is enabled, disable it by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) to `OFF` (its default value) and ensure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. Otherwise, the `ADD INDEX` operations during the upgrade might cause data index inconsistency. * In scenarios of using TiUP to upgrade TiDB, because TiUP upgrade has a timeout period, if the cluster has a large number of DDL jobs (more than 300) waiting in queues before the upgrade, the upgrade might fail. @@ -84,10 +87,6 @@ When using the smooth upgrade feature, note the following limitations. * Run DDL operations on system tables (`mysql.*`, `information_schema.*`, `performance_schema.*`, and `metrics_schema.*`). * Manually cancel DDL jobs: `ADMIN CANCEL DDL JOBS job_id [, job_id] ...;`. * Import data. - * Run distributed `ADD INDEX` or `IMPORT INTO` tasks. If the TiDB Distributed eXecution Framework (DXF) is enabled before the smooth upgrade, and there are ongoing `ADD INDEX` or `IMPORT INTO` tasks during the upgrade, perform the following steps to mitigate potential issues: - 1. Disable the DXF by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) to `OFF` (its default value). - 2. Ensure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed before the upgrade starts. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. - 3. After completing the preceding two steps, you can proceed with the smooth upgrade. ### Limitations on tools From 84b224269d02f6e1f988e4cdd4cf9e768cb99f54 Mon Sep 17 00:00:00 2001 From: Aolin Date: Fri, 1 Mar 2024 10:03:11 +0800 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Grace Cai --- smooth-upgrade-tidb.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/smooth-upgrade-tidb.md b/smooth-upgrade-tidb.md index f467f4b6dd8d9..c6fb1facc6559 100644 --- a/smooth-upgrade-tidb.md +++ b/smooth-upgrade-tidb.md @@ -78,7 +78,7 @@ When using the smooth upgrade feature, note the following limitations. * Before the upgrade, consider the following restrictions: * If there is a canceling DDL job in the cluster, that is, an ongoing DDL job is being canceled by a user, because the job in the canceling state cannot be paused, TiDB will retry canceling the job. If the retry fails, an error is reported and the upgrade is exited. - * If the TiDB Distributed eXecution Framework (DXF) is enabled, disable it by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) to `OFF` (its default value) and ensure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. Otherwise, the `ADD INDEX` operations during the upgrade might cause data index inconsistency. + * If the TiDB Distributed eXecution Framework (DXF) is enabled, disable it by setting [`tidb_enable_dist_task`](/system-variables.md#tidb_enable_dist_task-new-in-v710) to `OFF` (its default value). Make sure that all ongoing distributed `ADD INDEX` and `IMPORT INTO` tasks are completed. Alternatively, you can cancel these tasks and wait until the upgrade is complete to restart them. Otherwise, the `ADD INDEX` operations during the upgrade might cause data index inconsistency. * In scenarios of using TiUP to upgrade TiDB, because TiUP upgrade has a timeout period, if the cluster has a large number of DDL jobs (more than 300) waiting in queues before the upgrade, the upgrade might fail.