From 76314723d8f2d9b4d382f8cd8f9f66a99ba0efde 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 2874bfee641ebe7dc64a61f98601708ecfe1c1ec 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 c73a21281e94ca73ca2797edeadf5a1aefdbd66b 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 f9ea80fc642c59c77531932cb5d84b8f1fd67e7a 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 68f0f1c92ad5e72ca2ec9bd503abef22eaf47e63 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.