docs: update PLAN REPLAYER object storage behavior

[zeminzhou]

Summary

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:

• document that PLAN REPLAYER can store generated files in the storage configured by tidb_cloud_storage_uri
• clarify that PLAN REPLAYER DUMP now returns either a file token or a presigned URL depending on the backend capability
• document the corresponding download flow and presigned URL validity
• clarify that PLAN REPLAYER CAPTURE files can also be stored in external storage while the token column still records the file token
• update related system variable descriptions in system-variables.md

Reference

This documentation update is based on the following TiDB PRs:

• planner: introduce external storage for plan replayer tidb#65477
• planner: store plan replayer files to obj store tidb#65904
• planner: add presigned url to download files for replayer tidb#66084

Testing

• Not run (documentation only)

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign qiancai for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! 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 PLAN REPLAYER feature to accurately reflect its enhanced object storage capabilities. It details how PLAN REPLAYER can now utilize external cloud storage, the new dual output options (file token or presigned URL) for PLAN REPLAYER DUMP, and the corresponding download procedures. These changes ensure that users have up-to-date information regarding file storage, retrieval, and the role of the tidb_cloud_storage_uri system variable.

Highlights

• External Storage Support: The PLAN REPLAYER feature now supports storing generated files in external storage, configured via the tidb_cloud_storage_uri system variable.
• Flexible Output for DUMP: PLAN REPLAYER DUMP can now return either a file token or a presigned URL, depending on the capabilities of the configured storage backend.
• Enhanced Download Guidance: The documentation provides clear instructions for downloading files using both file tokens and presigned URLs, including details on presigned URL validity.
• CAPTURE Files in External Storage: PLAN REPLAYER CAPTURE files can also be stored in external storage, with the token column continuing to record the file token for retrieval.
• System Variable Updates: Descriptions for tidb_cloud_storage_uri and @@tidb_last_plan_replayer_token system variables have been updated to reflect these new storage behaviors.

🧠 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

• sql-plan-replayer.md
  • Added information about PLAN REPLAYER using tidb_cloud_storage_uri for external storage.
  • Updated PLAN REPLAYER DUMP output to include presigned URLs.
  • Clarified the download process for both presigned URLs and file tokens.
  • Updated note on file retention to include external storage.
  • Added information about PLAN REPLAYER CAPTURE using external storage.
• system-variables.md
  • Updated tidb_cloud_storage_uri description to include PLAN REPLAYER as a feature that uses it.
  • Updated @@tidb_last_plan_replayer_token description to mention presigned URLs.

Activity

• No specific activity has been recorded for this pull request yet.

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

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.

[gemini-code-assist]

For consistency with other instructions in this document that use the second person ("you"), consider rephrasing this sentence to use "you can".

Suggested change

	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

1. 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)

[ti-chi-bot]

@zhaoshangzi: adding LGTM is restricted to approvers and reviewers in OWNERS files.

Details

In 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.