refine ti-cli quick start - #23935
guangleibao wants to merge 1 commit into
Conversation
ti-chi-bot
Bot
added
the
first-time-contributor
|
[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
missing-translation-status
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. 📝 WalkthroughWalkthroughThe quick-start guide updates CLI descriptions and setup examples. It replaces the Filesystem workflow with mounting commands and changes the Starter workflow to generate a read-write connection string. ChangesTiDB Cloud CLI quick-start workflows
Priority: ⬇️ Low Estimated code review effort: 1 (Trivial) | ~5 minutes Change: Other Merge Risk: 🟡 Moderate · up to The revised quick start contains commands that will fail for users and can expose database credentials. Correct these workflows before merging. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Description checkResolution Add a summary of the documentation changes and their purpose. Select the applicable TiDB version checkbox, at minimum master or the intended release branch. Complete the related links and other applicable checklist items, or state that they do not apply.
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: pingcap/docs/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 278fc322-278b-4662-9d51-c26d116dcf22
📒 Files selected for processing (1)
ai/ti/ti-quick-start.md
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.
| - [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) | ||
| - [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Update the workflow anchors after renaming the headings.
Both links still use the old heading slugs. After the heading changes at Line 114 and Line 140, both links target missing anchors.
Committable replacement
-- [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem)
-- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database)
+- [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-tidb-cloud-filesystem)
+- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-tidb-cloud-starter)As per path instructions, preserve valid Markdown links when headings change.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) | |
| - [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) | |
| - [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-tidb-cloud-filesystem) | |
| - [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-tidb-cloud-starter) |
Source: Path instructions
| A TiDB Cloud Filesystem is a persistent, shareable cloud file system that you can use across local machines, CI jobs, sandboxes, and other ephemeral environments. | ||
|
|
||
| 1. Create a Filesystem, wait until it is ready, and save its server-assigned ID: | ||
| 1. Create a file system and obtain the access token (typically performed outside the sandbox): |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use the documented term owner token.
The CLI returns a one-time owner token, not a generic access token. Use the established term because the token has owner-level semantics and is not returned again. (docs.pingcap.com)
Committable replacement
-1. Create a file system and obtain the access token (typically performed outside the sandbox):
+1. Create a file system and obtain the owner token (typically performed outside the sandbox):As per path instructions: “Do not introduce new terminology when an established term exists.”
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 1. Create a file system and obtain the access token (typically performed outside the sandbox): | |
| 1. Create a file system and obtain the owner token (typically performed outside the sandbox): |
Sources: Path instructions, MCP tools
| --wait \ | ||
| --query file_system_id \ | ||
| --output text)" | ||
| export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Replace the unsupported --file-system-name options.
create-file-system supports --display-name, not --file-system-name. mount-file-system supports --file-system-id and --fs-token, not --file-system-name. These commands will fail with the current options. (docs.pingcap.com)
Use --display-name agent-workspace for creation and --fs-token "$TI_FS_TOKEN" or an explicit filesystem ID for mounting.
Also applies to: 129-129
Source: MCP tools
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Honor the configured default region.
Step 2 lets the user select a default region, but all three Filesystem commands hard-code aws-us-west-2. An explicit --region overrides the profile region, so selecting another region has no effect in this workflow. (docs.pingcap.com)
Remove the explicit flags so the configured region is used, or define one region variable and use it consistently.
Also applies to: 129-129, 137-137
Source: MCP tools
| `ti` stores the Filesystem credential locally, so you do not need to provide it for subsequent file operations. | ||
|
|
||
| 2. Write a file to the Filesystem, and then read the file: | ||
| 2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Restrict the mount workflow to supported platforms.
The installation section supports Windows, but Filesystem mounts are not supported on Windows. A Windows reader who selects Option A reaches a failing command. State that this workflow requires macOS or Linux, or provide a non-mount alternative for Windows. (docs.pingcap.com)
Committable replacement
-2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox):
+2. On macOS or Linux, mount the Filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox):📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): | |
| 2. On macOS or Linux, mount the Filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): |
Source: MCP tools
|
|
||
| ```text | ||
| hello from ti | ||
| export TI_FS_TOKEN=$TI_FS_TOKEN |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
set -eu
printf '%s\n' '--- ai/ti/ti-quick-start.md:100-145 ---'
sed -n '100,145p' ai/ti/ti-quick-start.md
printf '%s\n' '--- TI_FS_TOKEN references ---'
rg -n -C 3 'TI_FS_TOKEN|fs_token|sandbox|sandboxed' ai/ti/ti-quick-start.mdRepository: pingcap/docs
Length of output: 3176
Make the token handoff explicit across the sandbox boundary.
Step 1 creates TI_FS_TOKEN outside the sandbox, while Step 2 runs inside it. export TI_FS_TOKEN=$TI_FS_TOKEN only exports a value already present in the current shell; it does not transfer the token into a separate sandbox. Document the sandbox’s secret or environment-variable injection mechanism, or keep creation and mounting in the same environment.
Source: MCP tools
| ``` | ||
|
|
||
| 3. Delete the Filesystem: | ||
| 3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the typo in the unmount step.
Committable replacement
-3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox):
+3. Unmount the file system to release the workspace before passing it to another sandbox (typically performed within the sandbox):📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): | |
| 3. Unmount the file system to release the workspace before passing it to another sandbox (typically performed within the sandbox): |
| unset TI_DB_CLUSTER_ID | ||
| --read-write --query connection_string \ | ||
| --output text) | ||
| echo $DATABASE_URL |
There was a problem hiding this comment.
🔒 Security & Privacy | 🛡️ Detected with Advanced Tier | 🟠 Major | ⚡ Quick win
Sensitive Data Exposure
Reachability: Internal
Exploitability: Moderate
CWE: CWE-532 — Insertion of Sensitive Information into Log File
Do not print the read-write connection string.
--read-write returns stored SQL credentials. echo $DATABASE_URL writes the full credential-bearing URI to the terminal, where CI or agent logs can retain it. Connection strings contain credentials; the documented secure workflow writes protected environment output instead of displaying it. (docs.pingcap.com)
Remove the echo and use a masked secret handoff or a protected file.
| # Get Started with TiDB Cloud CLI | ||
|
|
||
| [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [TiDB Cloud Filesystems](/ai/ti/ti-overview.md#tidb-cloud-filesystem). It supports both interactive use and automation, with JSON as the default output format for commands. | ||
| [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem) file systems. TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. |
There was a problem hiding this comment.
| [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem) file systems. TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. | |
| [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [file systems in TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem). TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. |
| ## Step 3. Choose a workflow | ||
|
|
||
| Complete either of the following workflows. | ||
| Please proceed with either of the following workflows based on your needs. Would you like to use TiDB Cloud Filesystem or Starter? |
There was a problem hiding this comment.
| Please proceed with either of the following workflows based on your needs. Would you like to use TiDB Cloud Filesystem or Starter? | |
| Proceed with either of the following workflows based on your needs: |
There was a problem hiding this comment.
2 participants
First-time contributors' checklist
What is changed, added, or deleted? (Required)
Which 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)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit