From 9e35a438f5ff0410098c2acacefe6cd25b5e7110 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Thu, 12 Mar 2026 17:21:44 +0800 Subject: [PATCH 01/23] docs: update plan replayer object storage behavior --- sql-plan-replayer.md | 38 +++++++++++++++++++++++++++++++++----- system-variables.md | 7 ++++--- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 9f22544cd079c..0a558adb60b96 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -20,6 +20,8 @@ You can use `PLAN REPLAYER` to save the on-site information of a TiDB cluster. T PLAN REPLAYER DUMP [WITH STATS AS OF TIMESTAMP expression] EXPLAIN [ANALYZE] sql-statement; ``` +By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). + Based on `sql-statement`, TiDB sorts out and exports the following on-site information: - TiDB version @@ -54,11 +56,14 @@ plan replayer dump with stats as of timestamp '2023-07-17 12:00:00' explain sele plan replayer dump with stats as of timestamp '442012134592479233' explain select * from t; ``` -`PLAN REPLAYER DUMP` packages the table information above into a `ZIP` file and returns the file identifier as the execution result. +`PLAN REPLAYER DUMP` packages the table information above into a `ZIP` file and returns the download information as the execution result: + +- If the configured storage backend supports presigned URLs, TiDB returns a presigned URL. +- Otherwise, TiDB returns a file token. > **Note:** > -> The `ZIP` file is stored in a TiDB cluster for at most one hour. After one hour, TiDB will delete it. +> The result file is kept for at most one hour. After one hour, TiDB deletes it from the corresponding local or external storage. ```sql MySQL [test]> plan replayer dump explain select * from t; @@ -88,6 +93,17 @@ SELECT @@tidb_last_plan_replayer_token; 1 row in set (0.00 sec) ``` +If the configured storage backend supports presigned URLs, the result returned by `PLAN REPLAYER DUMP` or `@@tidb_last_plan_replayer_token` is a presigned URL instead of a file token. For example: + +```sql ++----------------------------------------------------------------------------------------------------------------------+ +| Dump_link | ++----------------------------------------------------------------------------------------------------------------------+ +| https://storage.example.com/replayer_xxx.zip?X-Amz-Algorithm=...&X-Amz-Credential=...&X-Amz-Signature=... | ++----------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + When there are multiple SQL statements, you can obtain the result of the `PLAN REPLAYER DUMP` execution using a file. The results of multiple SQL statements are separated by `;` in this file. ```sql @@ -111,7 +127,17 @@ SELECT @@tidb_last_plan_replayer_token; 1 row in set (0.00 sec) ``` -Because the file cannot be downloaded on MySQL Client, you need to use the TiDB HTTP interface and the file identifier to download the file: +If `PLAN REPLAYER DUMP` returns a presigned URL, you can use the URL directly to download the file: + +{{< copyable "shell-regular" >}} + +```shell +curl "${presigned_url}" > plan_replayer.zip +``` + +The presigned URL is valid for up to one hour. + +If `PLAN REPLAYER DUMP` returns a file token, you need to use the TiDB HTTP interface and the file token to download the file: {{< copyable "shell-regular" >}} @@ -261,11 +287,13 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` -The method of downloading the file of `PLAN REPLAYER CAPTURE` is the same as that of `PLAN REPLAYER`. For details, see [Examples of exporting cluster information](#examples-of-exporting-cluster-information). +If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column still records the file token. + +To download the file of `PLAN REPLAYER CAPTURE`, use the `token` value together with the TiDB HTTP interface. This is the same as the file-token based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). > **Note:** > -> The result file of `PLAN REPLAYER CAPTURE` is kept in the TiDB cluster for up to one week. After one week, TiDB deletes the file. +> The result file of `PLAN REPLAYER CAPTURE` is kept for up to one week. After one week, TiDB deletes it from the corresponding local or external storage. ### Remove the capture tasks diff --git a/system-variables.md b/system-variables.md index 79af0db79a694..ae796f148b0b8 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1725,10 +1725,11 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` -- This variable is used to specify the Amazon S3 cloud storage URI to enable [Global Sort](/tidb-global-sort.md). After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the Global Sort feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. For more details, see [Amazon S3 URI format](/external-storage-uri.md#amazon-s3-uri-format). -- The following statements can use the Global Sort feature. +- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store the generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- The following statements or features can use this variable. - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. + - [`PLAN REPLAYER`](/sql-plan-replayer.md), including files generated by `PLAN REPLAYER DUMP`, `PLAN REPLAYER CAPTURE`, and `PLAN REPLAYER CONTINUOUS CAPTURE`. ### tidb_ddl_error_count_limit @@ -3701,7 +3702,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified - Scope: SESSION - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: String -- This variable is read-only and is used to obtain the result of the last `PLAN REPLAYER DUMP` execution in the current session. +- This variable is read-only and is used to obtain the result of the last `PLAN REPLAYER DUMP` execution in the current session. The result is either a file token or, if the configured storage backend supports it, a presigned URL. ### tidb_load_based_replica_read_threshold New in v7.0.0 From 97afcb2b29fd439e9c8756310109bf6581e7e34e Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Thu, 12 Mar 2026 17:29:48 +0800 Subject: [PATCH 02/23] docs: clarify plan replayer capture token column --- sql-plan-replayer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 0a558adb60b96..6701a6ba77196 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -287,9 +287,9 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` -If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column still records the file token. +If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column in the `mysql.plan_replayer_status` table still records the file token of the generated capture file. -To download the file of `PLAN REPLAYER CAPTURE`, use the `token` value together with the TiDB HTTP interface. This is the same as the file-token based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). +To download the file of `PLAN REPLAYER CAPTURE`, use the value in the `token` column of `mysql.plan_replayer_status` together with the TiDB HTTP interface. This is the same as the file-token based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). > **Note:** > From 1953809be5d05bf4f714d722eff211d0e9a897f9 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:21:45 +0800 Subject: [PATCH 03/23] Update system-variables.md Co-authored-by: Aolin --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index ae796f148b0b8..1ac0daa0e23d3 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1726,7 +1726,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` - This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store the generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). -- The following statements or features can use this variable. +- The following statements and features use this variable: - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. - [`PLAN REPLAYER`](/sql-plan-replayer.md), including files generated by `PLAN REPLAYER DUMP`, `PLAN REPLAYER CAPTURE`, and `PLAN REPLAYER CONTINUOUS CAPTURE`. From 471832958bff44fba8a728fc8f9b3c8e4671a26f Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:21:57 +0800 Subject: [PATCH 04/23] Update system-variables.md Co-authored-by: Aolin --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 1ac0daa0e23d3..887f8d3f70964 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1725,7 +1725,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` -- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store the generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). - The following statements and features use this variable: - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. From 8202483d6f32dfaa19c76c7947a5584443ed6cce Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:22:09 +0800 Subject: [PATCH 05/23] Update sql-plan-replayer.md Co-authored-by: Aolin --- sql-plan-replayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 6701a6ba77196..18febb570a5ad 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -20,7 +20,7 @@ You can use `PLAN REPLAYER` to save the on-site information of a TiDB cluster. T PLAN REPLAYER DUMP [WITH STATS AS OF TIMESTAMP expression] EXPLAIN [ANALYZE] sql-statement; ``` -By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified location. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). Based on `sql-statement`, TiDB sorts out and exports the following on-site information: From b81d4fbd1856f68e73d902b1a47c356c6da3aca5 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:22:25 +0800 Subject: [PATCH 06/23] Update sql-plan-replayer.md Co-authored-by: Aolin --- sql-plan-replayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 18febb570a5ad..be76d8387eca8 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -93,7 +93,7 @@ SELECT @@tidb_last_plan_replayer_token; 1 row in set (0.00 sec) ``` -If the configured storage backend supports presigned URLs, the result returned by `PLAN REPLAYER DUMP` or `@@tidb_last_plan_replayer_token` is a presigned URL instead of a file token. For example: +If the configured storage backend supports presigned URLs, the result returned by `PLAN REPLAYER DUMP` or `tidb_last_plan_replayer_token` is a presigned URL instead of a file token. For example: ```sql +----------------------------------------------------------------------------------------------------------------------+ From 554bf8a6b9216ecfd8585567f5868691bfebbb5a Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:22:35 +0800 Subject: [PATCH 07/23] Update sql-plan-replayer.md Co-authored-by: Aolin --- sql-plan-replayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index be76d8387eca8..e98f6cb791408 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -289,7 +289,7 @@ mysql> SELECT * FROM mysql.plan_replayer_status; If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column in the `mysql.plan_replayer_status` table still records the file token of the generated capture file. -To download the file of `PLAN REPLAYER CAPTURE`, use the value in the `token` column of `mysql.plan_replayer_status` together with the TiDB HTTP interface. This is the same as the file-token based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). +To download a file generated by `PLAN REPLAYER CAPTURE`, use the value in the `token` column together with the TiDB HTTP interface. This process is the same as the file token-based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). > **Note:** > From fd56d6e4e904f9177ed320f3d79c739e7ff343cd Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:22:45 +0800 Subject: [PATCH 08/23] Update sql-plan-replayer.md Co-authored-by: Aolin --- sql-plan-replayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index e98f6cb791408..9083394f3909d 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -287,7 +287,7 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` -If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column in the `mysql.plan_replayer_status` table still records the file token of the generated capture file. +If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, TiDB also stores captured files in the specified external storage. The `token` column in the `mysql.plan_replayer_status` table records the file token of each captured file. To download a file generated by `PLAN REPLAYER CAPTURE`, use the value in the `token` column together with the TiDB HTTP interface. This process is the same as the file token-based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). From 9e606b67997a86f80b5fa6f7130583bab24a6317 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:22:57 +0800 Subject: [PATCH 09/23] Update sql-plan-replayer.md Co-authored-by: Aolin --- sql-plan-replayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 9083394f3909d..adabb63b618f2 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -127,7 +127,7 @@ SELECT @@tidb_last_plan_replayer_token; 1 row in set (0.00 sec) ``` -If `PLAN REPLAYER DUMP` returns a presigned URL, you can use the URL directly to download the file: +If `PLAN REPLAYER DUMP` returns a presigned URL, you can use the URL directly to download the file. The presigned URL is valid for up to one hour. {{< copyable "shell-regular" >}} From 5782357107745bb29f89d590a539b4248b329825 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 14:23:09 +0800 Subject: [PATCH 10/23] Update sql-plan-replayer.md Co-authored-by: Aolin --- sql-plan-replayer.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index adabb63b618f2..1d403411ae666 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -135,8 +135,6 @@ If `PLAN REPLAYER DUMP` returns a presigned URL, you can use the URL directly to curl "${presigned_url}" > plan_replayer.zip ``` -The presigned URL is valid for up to one hour. - If `PLAN REPLAYER DUMP` returns a file token, you need to use the TiDB HTTP interface and the file token to download the file: {{< copyable "shell-regular" >}} From ae163ffd0efffb53a6294c54d99db225ce9fee84 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 16:45:49 +0800 Subject: [PATCH 11/23] docs: plan replayer use dedicated external storage sysvar --- sql-plan-replayer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 1d403411ae666..351e99bd4e1c4 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -20,7 +20,7 @@ You can use `PLAN REPLAYER` to save the on-site information of a TiDB cluster. T PLAN REPLAYER DUMP [WITH STATS AS OF TIMESTAMP expression] EXPLAIN [ANALYZE] sql-statement; ``` -By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified location. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_plan_replayer_external_storage_uri`](/system-variables.md#tidb_plan_replayer_external_storage_uri-new-in-v900) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified location. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). Based on `sql-statement`, TiDB sorts out and exports the following on-site information: @@ -285,7 +285,7 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` -If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, TiDB also stores captured files in the specified external storage. The `token` column in the `mysql.plan_replayer_status` table records the file token of each captured file. +If [`tidb_plan_replayer_external_storage_uri`](/system-variables.md#tidb_plan_replayer_external_storage_uri-new-in-v900) is configured, TiDB also stores captured files in the specified external storage. The `token` column in the `mysql.plan_replayer_status` table records the file token of each captured file. To download a file generated by `PLAN REPLAYER CAPTURE`, use the value in the `token` column together with the TiDB HTTP interface. This process is the same as the file token-based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). From 31fe998035f7b785a2402b71b21a39750d87abc9 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 16:45:50 +0800 Subject: [PATCH 12/23] docs: plan replayer use dedicated external storage sysvar --- system-variable-reference.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/system-variable-reference.md b/system-variable-reference.md index ef41aa77a6c3c..07d39bcd77090 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3391,6 +3391,14 @@ Referenced in: - [System Variables](/system-variables.md#tidb_plan_cache_max_plan_size-new-in-v710) - [TiDB 7.1.0 Release Notes](/releases/release-7.1.0.md) + +### tidb_plan_replayer_external_storage_uri + +Referenced in: + +- [System Variables](/system-variables.md#tidb_plan_replayer_external_storage_uri-new-in-v900) +- [Use PLAN REPLAYER to Save and Restore the On-Site Information of a Cluster](/sql-plan-replayer.md) + ### tidb_pprof_sql_cpu Referenced in: From b019854f0aa697da34b38afd6ba63a5269c1fb53 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 16:59:06 +0800 Subject: [PATCH 13/23] docs: plan replayer use dedicated external storage sysvar --- system-variables.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/system-variables.md b/system-variables.md index 887f8d3f70964..03a8fe3351d10 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1725,11 +1725,10 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` -- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). -- The following statements and features use this variable: +- This variable is used to specify the Amazon S3 cloud storage URI to enable [Global Sort](/tidb-global-sort.md). After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- The following statements can use the Global Sort feature. - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. - - [`PLAN REPLAYER`](/sql-plan-replayer.md), including files generated by `PLAN REPLAYER DUMP`, `PLAN REPLAYER CAPTURE`, and `PLAN REPLAYER CONTINUOUS CAPTURE`. ### tidb_ddl_error_count_limit @@ -5368,6 +5367,20 @@ SHOW WARNINGS; - Range: `[0, 9223372036854775807]`, in bytes. The memory format with the units "KiB|MiB|GiB|TiB" is also supported. `0` means no limit. - This variable controls the maximum size of a plan that can be cached in prepared or non-prepared plan cache. If the size of a plan exceeds this value, the plan will not be cached. For more details, see [Memory management of prepared plan cache](/sql-prepared-plan-cache.md#memory-management-of-prepared-plan-cache) and [Non-prepared plan cache](/sql-plan-management.md#usage). + +### tidb_plan_replayer_external_storage_uri New in v9.0.0 + +- Scope: GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: String +- Default value: `""` +- This variable is used to specify the external storage URI for files generated by [`PLAN REPLAYER`](/sql-plan-replayer.md). If this variable is empty, `PLAN REPLAYER` uses local storage. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- The following statements and features use this variable: + - [`PLAN REPLAYER DUMP`](/sql-plan-replayer.md) + - [`PLAN REPLAYER CAPTURE`](/sql-plan-replayer.md) + - [`PLAN REPLAYER CONTINUOUS CAPTURE`](/sql-plan-replayer.md) + ### tidb_pprof_sql_cpu New in v4.0 > **Note:** From b80cc0a3b3819e333ffae862926b398d4f334107 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 1 Apr 2026 17:22:10 +0800 Subject: [PATCH 14/23] docs: decouple plan replayer external storage sysvar --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 03a8fe3351d10..1a7e8a81e3eef 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1725,7 +1725,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` -- This variable is used to specify the Amazon S3 cloud storage URI to enable [Global Sort](/tidb-global-sort.md). After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- This variable is used to specify the Amazon S3 cloud storage URI to enable [Global Sort](/tidb-global-sort.md). After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the Global Sort feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. For more details, see [Amazon S3 URI format](/external-storage-uri.md#amazon-s3-uri-format). - The following statements can use the Global Sort feature. - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. From 037efe593cd56dce143aac779a49dde8c2f0e35c Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 2 Apr 2026 11:24:23 +0800 Subject: [PATCH 15/23] fix format --- system-variables.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/system-variables.md b/system-variables.md index 1a7e8a81e3eef..81ce26939e516 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5367,7 +5367,6 @@ SHOW WARNINGS; - Range: `[0, 9223372036854775807]`, in bytes. The memory format with the units "KiB|MiB|GiB|TiB" is also supported. `0` means no limit. - This variable controls the maximum size of a plan that can be cached in prepared or non-prepared plan cache. If the size of a plan exceeds this value, the plan will not be cached. For more details, see [Memory management of prepared plan cache](/sql-prepared-plan-cache.md#memory-management-of-prepared-plan-cache) and [Non-prepared plan cache](/sql-plan-management.md#usage). - ### tidb_plan_replayer_external_storage_uri New in v9.0.0 - Scope: GLOBAL @@ -5375,7 +5374,7 @@ SHOW WARNINGS; - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: String - Default value: `""` -- This variable is used to specify the external storage URI for files generated by [`PLAN REPLAYER`](/sql-plan-replayer.md). If this variable is empty, `PLAN REPLAYER` uses local storage. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- This variable is used to specify the external storage URI for files generated by [`PLAN REPLAYER`](/sql-plan-replayer.md). If this variable is empty, `PLAN REPLAYER` stores files in local storage. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). - The following statements and features use this variable: - [`PLAN REPLAYER DUMP`](/sql-plan-replayer.md) - [`PLAN REPLAYER CAPTURE`](/sql-plan-replayer.md) From 8d3ceb64cc70db3d3432f5049ffde75824d9dfdb Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Thu, 2 Apr 2026 13:46:06 +0800 Subject: [PATCH 16/23] Update sql-plan-replayer.md Co-authored-by: xixirangrang --- sql-plan-replayer.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 351e99bd4e1c4..882aa99ece65f 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -129,8 +129,6 @@ SELECT @@tidb_last_plan_replayer_token; If `PLAN REPLAYER DUMP` returns a presigned URL, you can use the URL directly to download the file. The presigned URL is valid for up to one hour. -{{< copyable "shell-regular" >}} - ```shell curl "${presigned_url}" > plan_replayer.zip ``` From fbf10b9b3ce186118f892752e436dd0189dd08c4 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Thu, 2 Apr 2026 13:46:17 +0800 Subject: [PATCH 17/23] Update sql-plan-replayer.md Co-authored-by: xixirangrang --- sql-plan-replayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 882aa99ece65f..699808071a972 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -56,7 +56,7 @@ plan replayer dump with stats as of timestamp '2023-07-17 12:00:00' explain sele plan replayer dump with stats as of timestamp '442012134592479233' explain select * from t; ``` -`PLAN REPLAYER DUMP` packages the table information above into a `ZIP` file and returns the download information as the execution result: +`PLAN REPLAYER DUMP` packages the preceding table information into a `ZIP` file and returns the download information as the execution result: - If the configured storage backend supports presigned URLs, TiDB returns a presigned URL. - Otherwise, TiDB returns a file token. From 1dc3b35ef9433c5cef47d87773b155abdc2beb48 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Thu, 2 Apr 2026 13:46:29 +0800 Subject: [PATCH 18/23] Update system-variables.md Co-authored-by: xixirangrang --- system-variables.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/system-variables.md b/system-variables.md index 81ce26939e516..6538ceb33bbdc 100644 --- a/system-variables.md +++ b/system-variables.md @@ -5376,9 +5376,9 @@ SHOW WARNINGS; - Default value: `""` - This variable is used to specify the external storage URI for files generated by [`PLAN REPLAYER`](/sql-plan-replayer.md). If this variable is empty, `PLAN REPLAYER` stores files in local storage. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). - The following statements and features use this variable: - - [`PLAN REPLAYER DUMP`](/sql-plan-replayer.md) - - [`PLAN REPLAYER CAPTURE`](/sql-plan-replayer.md) - - [`PLAN REPLAYER CONTINUOUS CAPTURE`](/sql-plan-replayer.md) + - [`PLAN REPLAYER DUMP`](/sql-plan-replayer.md#use-plan-replayer-to-export-cluster-information) + - [`PLAN REPLAYER CAPTURE`](/sql-plan-replayer.md#use-plan-replayer-capture-to-capture-target-plans) + - [`PLAN REPLAYER CONTINUOUS CAPTURE`](/sql-plan-replayer.md#use-plan-replayer-continuous-capture) ### tidb_pprof_sql_cpu New in v4.0 From 98f41c8e85e6d94da66b0e11fe98ad4015fb4971 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Thu, 2 Apr 2026 13:47:07 +0800 Subject: [PATCH 19/23] Update system-variable-reference.md Co-authored-by: xixirangrang --- system-variable-reference.md | 1 - 1 file changed, 1 deletion(-) diff --git a/system-variable-reference.md b/system-variable-reference.md index 07d39bcd77090..3d84a35c87a95 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3391,7 +3391,6 @@ Referenced in: - [System Variables](/system-variables.md#tidb_plan_cache_max_plan_size-new-in-v710) - [TiDB 7.1.0 Release Notes](/releases/release-7.1.0.md) - ### tidb_plan_replayer_external_storage_uri Referenced in: From 2bf1c332aa1a48722034fc095aa235a905175588 Mon Sep 17 00:00:00 2001 From: zeminzhou Date: Wed, 8 Apr 2026 16:17:28 +0800 Subject: [PATCH 20/23] docs: align plan replayer storage path docs --- sql-plan-replayer.md | 6 +++--- system-variable-reference.md | 8 +------- system-variables.md | 18 +++--------------- 3 files changed, 7 insertions(+), 25 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 699808071a972..48f6e043020c4 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -20,7 +20,7 @@ You can use `PLAN REPLAYER` to save the on-site information of a TiDB cluster. T PLAN REPLAYER DUMP [WITH STATS AS OF TIMESTAMP expression] EXPLAIN [ANALYZE] sql-statement; ``` -By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_plan_replayer_external_storage_uri`](/system-variables.md#tidb_plan_replayer_external_storage_uri-new-in-v900) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified location. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). Based on `sql-statement`, TiDB sorts out and exports the following on-site information: @@ -283,9 +283,9 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` -If [`tidb_plan_replayer_external_storage_uri`](/system-variables.md#tidb_plan_replayer_external_storage_uri-new-in-v900) is configured, TiDB also stores captured files in the specified external storage. The `token` column in the `mysql.plan_replayer_status` table records the file token of each captured file. +If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column still records the file token. -To download a file generated by `PLAN REPLAYER CAPTURE`, use the value in the `token` column together with the TiDB HTTP interface. This process is the same as the file token-based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). +To download the file of `PLAN REPLAYER CAPTURE`, use the `token` value together with the TiDB HTTP interface. This is the same as the file-token based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). > **Note:** > diff --git a/system-variable-reference.md b/system-variable-reference.md index 3d84a35c87a95..e17d1285d5080 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -1088,6 +1088,7 @@ Referenced in: - [IMPORT INTO](/sql-statements/sql-statement-import-into.md) - [System Variables](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) +- [Use PLAN REPLAYER to Save and Restore the On-Site Information of a Cluster](/sql-plan-replayer.md) - [TiDB Global Sort](/tidb-global-sort.md) - [TiDB 8.1.1 Release Notes](/releases/release-8.1.1.md) - [TiDB 7.4.0 Release Notes](/releases/release-7.4.0.md) @@ -3391,13 +3392,6 @@ Referenced in: - [System Variables](/system-variables.md#tidb_plan_cache_max_plan_size-new-in-v710) - [TiDB 7.1.0 Release Notes](/releases/release-7.1.0.md) -### tidb_plan_replayer_external_storage_uri - -Referenced in: - -- [System Variables](/system-variables.md#tidb_plan_replayer_external_storage_uri-new-in-v900) -- [Use PLAN REPLAYER to Save and Restore the On-Site Information of a Cluster](/sql-plan-replayer.md) - ### tidb_pprof_sql_cpu Referenced in: diff --git a/system-variables.md b/system-variables.md index 6538ceb33bbdc..887f8d3f70964 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1725,10 +1725,11 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` -- This variable is used to specify the Amazon S3 cloud storage URI to enable [Global Sort](/tidb-global-sort.md). After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the Global Sort feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. For more details, see [Amazon S3 URI format](/external-storage-uri.md#amazon-s3-uri-format). -- The following statements can use the Global Sort feature. +- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- The following statements and features use this variable: - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. + - [`PLAN REPLAYER`](/sql-plan-replayer.md), including files generated by `PLAN REPLAYER DUMP`, `PLAN REPLAYER CAPTURE`, and `PLAN REPLAYER CONTINUOUS CAPTURE`. ### tidb_ddl_error_count_limit @@ -5367,19 +5368,6 @@ SHOW WARNINGS; - Range: `[0, 9223372036854775807]`, in bytes. The memory format with the units "KiB|MiB|GiB|TiB" is also supported. `0` means no limit. - This variable controls the maximum size of a plan that can be cached in prepared or non-prepared plan cache. If the size of a plan exceeds this value, the plan will not be cached. For more details, see [Memory management of prepared plan cache](/sql-prepared-plan-cache.md#memory-management-of-prepared-plan-cache) and [Non-prepared plan cache](/sql-plan-management.md#usage). -### tidb_plan_replayer_external_storage_uri New in v9.0.0 - -- Scope: GLOBAL -- Persists to cluster: Yes -- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No -- Type: String -- Default value: `""` -- This variable is used to specify the external storage URI for files generated by [`PLAN REPLAYER`](/sql-plan-replayer.md). If this variable is empty, `PLAN REPLAYER` stores files in local storage. The configured URI must point to a storage path with the required read, write, and delete permissions. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). -- The following statements and features use this variable: - - [`PLAN REPLAYER DUMP`](/sql-plan-replayer.md#use-plan-replayer-to-export-cluster-information) - - [`PLAN REPLAYER CAPTURE`](/sql-plan-replayer.md#use-plan-replayer-capture-to-capture-target-plans) - - [`PLAN REPLAYER CONTINUOUS CAPTURE`](/sql-plan-replayer.md#use-plan-replayer-continuous-capture) - ### tidb_pprof_sql_cpu New in v4.0 > **Note:** From b49ac50bbb770b93dcc5ed198bc4fb6da5e03952 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 14 Apr 2026 11:31:36 +0800 Subject: [PATCH 21/23] clarify PLAN REPLAYER external storage behavior by deployment type --- sql-plan-replayer.md | 18 +++++++++++++++++- system-variables.md | 23 +++++++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index 48f6e043020c4..c272fc94a03c1 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -20,7 +20,19 @@ You can use `PLAN REPLAYER` to save the on-site information of a TiDB cluster. T PLAN REPLAYER DUMP [WITH STATS AS OF TIMESTAMP expression] EXPLAIN [ANALYZE] sql-statement; ``` -By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). + + +For TiDB Self-Managed clusters, TiDB stores files generated by `PLAN REPLAYER` in local storage, even when [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is set. + + + + + +By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. + +If you set [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) to a valid external storage URI, TiDB stores the generated `ZIP` files in the specified storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). + + Based on `sql-statement`, TiDB sorts out and exports the following on-site information: @@ -283,8 +295,12 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` + + If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column still records the file token. + + To download the file of `PLAN REPLAYER CAPTURE`, use the `token` value together with the TiDB HTTP interface. This is the same as the file-token based download flow described in [Examples of exporting cluster information](#examples-of-exporting-cluster-information). > **Note:** diff --git a/system-variables.md b/system-variables.md index 887f8d3f70964..e097a156ac008 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1725,12 +1725,35 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Default value: `""` + + + +- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- The following statements use this variable: + - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. + - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. + + + + + +- This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). +- The following statements use this variable: + - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. + - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. + + + + + - This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). - The following statements and features use this variable: - The [`ADD INDEX`](/sql-statements/sql-statement-add-index.md) statement. - The [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) statement for import jobs. - [`PLAN REPLAYER`](/sql-plan-replayer.md), including files generated by `PLAN REPLAYER DUMP`, `PLAN REPLAYER CAPTURE`, and `PLAN REPLAYER CONTINUOUS CAPTURE`. + + ### tidb_ddl_error_count_limit > **Note:** From 619babb502f0ba6868d951fcab3730c0801ce779 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 14 Apr 2026 13:32:32 +0800 Subject: [PATCH 22/23] Apply suggestions from code review Co-authored-by: Aolin --- sql-plan-replayer.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sql-plan-replayer.md b/sql-plan-replayer.md index c272fc94a03c1..28515e8b17aa9 100644 --- a/sql-plan-replayer.md +++ b/sql-plan-replayer.md @@ -26,7 +26,7 @@ For TiDB Self-Managed clusters, TiDB stores files generated by `PLAN REPLAYER` i - + By default, TiDB stores files generated by `PLAN REPLAYER` in local storage. @@ -295,7 +295,7 @@ mysql> SELECT * FROM mysql.plan_replayer_status; 3 rows in set (0.00 sec) ``` - + If [`tidb_cloud_storage_uri`](/system-variables.md#tidb_cloud_storage_uri-new-in-v740) is configured, the captured file is also stored in the configured external storage. The `token` column still records the file token. diff --git a/system-variables.md b/system-variables.md index e097a156ac008..af1088a558c7d 100644 --- a/system-variables.md +++ b/system-variables.md @@ -1735,7 +1735,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - + - This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). - The following statements use this variable: @@ -1744,7 +1744,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - + - This variable is used to specify the cloud storage URI for TiDB features that use external storage. After enabling the [TiDB Distributed eXecution Framework (DXF)](/tidb-distributed-execution-framework.md), you can use the [Global Sort](/tidb-global-sort.md) feature by configuring the URI and pointing it to an appropriate cloud storage path with the necessary permissions to access the storage. [`PLAN REPLAYER`](/sql-plan-replayer.md) also uses this URI to store generated files. If this variable is empty, `PLAN REPLAYER` uses local storage. For supported URI formats, see [URI Formats of External Storage Services](/external-storage-uri.md). - The following statements and features use this variable: From ae3c1815ba49a1d501e9191dc158cda695d573c2 Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 14 Apr 2026 16:32:44 +0800 Subject: [PATCH 23/23] update TOC --- TOC-tidb-cloud-premium.md | 1 + 1 file changed, 1 insertion(+) diff --git a/TOC-tidb-cloud-premium.md b/TOC-tidb-cloud-premium.md index 299577ac3e16e..d2e07f55b5829 100644 --- a/TOC-tidb-cloud-premium.md +++ b/TOC-tidb-cloud-premium.md @@ -194,6 +194,7 @@ - [SQL Plan Management](/sql-plan-management.md) - [The Blocklist of Optimization Rules and Expression Pushdown](/blocklist-control-plan.md) - [Optimizer Fix Controls](/optimizer-fix-controls.md) + - [Save and Restore the On-Site Information of an Instance](/sql-plan-replayer.md) - [TiKV Follower Read](/follower-read.md) - [Coprocessor Cache](/coprocessor-cache.md) - [Tune TiFlash Performance](/tiflash/tune-tiflash-performance.md)