docs: update PLAN REPLAYER object storage behavior

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)

sql-plan-replayer.md

@@ -20,6 +20,20 @@ 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;
 ```
 
+<CustomContent platform="tidb">
+
+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.
+
+</CustomContent>
+
+<CustomContent platform="tidb-cloud" plan="premium">
+
+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).
+
+</CustomContent>
+
 Based on `sql-statement`, TiDB sorts out and exports the following on-site information:
 
 - TiDB version
@@ -54,11 +68,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 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.
 
 > **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 +105,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 +139,13 @@ 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. The presigned URL is valid for up to one hour.
+
+```shell
+curl "${presigned_url}" > plan_replayer.zip
+```
+
+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 +295,17 @@ 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).
+<CustomContent platform="tidb-cloud" plan="premium">
+
+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.
+
+</CustomContent>
+
+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
 

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)

system-variables.md

@@ -1725,11 +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 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.
+
+<CustomContent platform="tidb">
+
+- 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.
+
+</CustomContent>
+
+<CustomContent platform="tidb-cloud" plan="starter,essential,dedicated">
+
+- 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.
 
+</CustomContent>
+
+<CustomContent platform="tidb-cloud" plan="premium">
+
+- 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`.
+
+</CustomContent>
+
 ### tidb_ddl_error_count_limit
 
 > **Note:**
@@ -3701,7 +3725,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 <span class="version-mark">New in v7.0.0</span>