docs: update PLAN REPLAYER object storage behavior#22557
docs: update PLAN REPLAYER object storage behavior#22557zeminzhou wants to merge 2 commits intopingcap:masterfrom
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
bot
added
the
missing-translation-status
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request updates the TiDB documentation for the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
ti-chi-bot
bot
added
the
size/M
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for PLAN REPLAYER to reflect its new object storage capabilities. The changes clarify how PLAN REPLAYER DUMP and PLAN REPLAYER CAPTURE handle file storage with tidb_cloud_storage_uri, including the introduction of presigned URLs. The related system variable documentation is also updated. The changes are clear and accurate. I have one minor suggestion to improve stylistic consistency.
sql-plan-replayer.md
Outdated
| 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). |
There was a problem hiding this comment.
For consistency with other instructions in this document that use the second person ("you"), consider rephrasing this sentence to use "you can".
| 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`, you can 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). |
References
- The style guide recommends writing in the second person ('you') when addressing users. Using 'you can' would be more consistent with other parts of this document. (link)
hfxsd
added
translation/doing
|
@zhaoshangzi: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn response to this: Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
| - 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. |
There was a problem hiding this comment.
| - The following statements or features can use this variable. | |
| - The following statements and features use this variable: |
| - 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). |
There was a problem hiding this comment.
| - 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). |
| 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). |
There was a problem hiding this comment.
| 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). |
| 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: |
There was a problem hiding this comment.
| 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: |
| ``` | ||
|
|
||
| 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 in the `mysql.plan_replayer_status` table still records the file token of the generated capture file. |
There was a problem hiding this comment.
| 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. |
| 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 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). |
There was a problem hiding this comment.
| 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). |
| ``` | ||
|
|
||
| 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: |
There was a problem hiding this comment.
| 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. |
|
|
||
| The presigned URL is valid for up to one hour. |
There was a problem hiding this comment.
| The presigned URL is valid for up to one hour. |
[LGTM Timeline notifier]Timeline:
|
4 participants
What is changed, added or deleted? (Required)
This PR replaces #22548 because the original PR can no longer be reopened.
Update the PLAN REPLAYER documentation to reflect the new object storage behavior introduced in TiDB:
PLAN REPLAYERcan store generated files in the storage configured bytidb_cloud_storage_uriPLAN REPLAYER DUMPnow returns either a file token or a presigned URL depending on the backend capabilityPLAN REPLAYER CAPTUREfiles can also be stored in external storage while thetokencolumn still records the file tokensystem-variables.mdWhich TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
This documentation update is based on the following TiDB PRs:
presigned urlto download files for replayer tidb#66084