docs: add TiDB Cloud CLI (tdc) Preview documentation #23306
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| title: tdc Concepts and Architecture | ||
| summary: Understand tdc profiles, regions, credentials, SQL roles, Filesystem resources, local state, and the bundled Drive9 companion. | ||
| --- | ||
|
|
||
| # tdc Concepts and Architecture | ||
|
|
||
| This document explains the concepts needed to use tdc with TiDB Cloud Starter and TiDB Cloud Filesystem. | ||
|
|
||
| > **Note:** | ||
| > | ||
| > tdc is currently in Preview. Its features and command-line interface might change without prior notice. | ||
|
|
||
| ## Command model | ||
|
|
||
| tdc uses service nouns and explicit operation names: | ||
|
|
||
| ```text | ||
| tdc db create-db-cluster | ||
| tdc fs copy-file | ||
| tdc fs-git clone-git-workspace | ||
| ``` | ||
|
|
||
| The command tree is at most two levels. Long, descriptive command and flag names make intent explicit in logs and agent-generated commands. Commands are non-interactive except for `tdc configure`. | ||
|
|
||
| Structured commands return JSON by default. Use `--output text` for a terminal-oriented representation and `--query` for a JMESPath projection. | ||
|
|
||
| ## Profiles and regions | ||
|
|
||
| A profile is a named local namespace containing TiDB Cloud placement, a default virtual project, and credentials. The default profile is named `default`; select another with `--profile`. | ||
|
|
||
| tdc represents placement with one canonical region code: | ||
|
|
||
| ```text | ||
| aws-us-east-1 | ||
| aws-ap-southeast-1 | ||
| ali-ap-southeast-1 | ||
| ``` | ||
|
|
||
| The prefix identifies the cloud provider. A global `--region` value overrides `TDC_REGION_CODE` and the profile region for one command without changing saved configuration. | ||
|
|
||
| During `tdc configure`, tdc calls the organization API and requires one accessible project with `type = "tidbx_virtual"`. It stores that project ID as the default for Starter cluster creation. | ||
|
|
||
| ## Credential boundaries | ||
|
|
||
| tdc uses separate credentials for separate security boundaries: | ||
|
|
||
| | Credential | Purpose | Storage | | ||
| | --- | --- | --- | | ||
| | TiDB Cloud API public/private key | Organization, Starter control plane, Filesystem provisioning and deletion | `~/.tdc/credentials` | | ||
| | DB SQL username/password | SQL access to one Starter cluster | `~/.tdc/db_users/<cluster-id>/credentials` | | ||
| | Filesystem owner token | Filesystem data plane, mounts, Git, journal, and owner vault operations | Per-resource credentials under `~/.tdc/fs_resources/` or `TDC_FS_TOKEN` | | ||
| | Delegated vault token | Limited access to selected secret fields | `TDC_VAULT_TOKEN` or an explicit command input | | ||
|
|
||
| TiDB Cloud API keys are never reused as SQL passwords or Filesystem tokens. | ||
|
|
||
| ## SQL roles | ||
|
|
||
| `tdc db create-db-sql-users` creates or repairs three stable users for a cluster: | ||
|
|
||
| - `read_only` for queries that must not modify data; | ||
| - `read_write` for normal application and agent work; | ||
| - `admin` for DDL and privilege administration. | ||
|
|
||
| Role selection is explicit with `--read-only`, `--read-write`, or `--admin`. Read-write is the default when no role flag is supplied. | ||
|
|
||
| ## One profile, multiple Filesystems | ||
|
|
||
| One profile can register multiple Filesystem resources. Each resource has an isolated config file and credential file. Select a resource in this order: | ||
|
|
||
| 1. `--file-system-name`; | ||
| 2. `TDC_FS_FILE_SYSTEM_NAME`; | ||
| 3. the profile's default Filesystem; | ||
| 4. the only registered Filesystem, when exactly one exists. | ||
|
|
||
| If multiple resources exist and none is selected, tdc fails instead of guessing. Use `tdc fs set-default-file-system` to choose a default. | ||
|
|
||
| ## Config-free sandbox access | ||
|
|
||
| A clean agent sandbox does not need `tdc configure` or TiDB Cloud API keys to use an existing Filesystem. Supply: | ||
|
|
||
| ```bash | ||
| export TDC_FS_TOKEN="<owner-token>" | ||
| export TDC_REGION_CODE="aws-us-east-1" | ||
| export TDC_FS_FILE_SYSTEM_NAME="workspace" | ||
| ``` | ||
|
|
||
| tdc resolves these values into an in-memory profile namespace. It does not write an `[env]` profile or persist the token. | ||
|
|
||
| ## Local state | ||
|
|
||
| All tdc-owned state is under `~/.tdc/`: | ||
|
|
||
| | Path | Contents | | ||
| | --- | --- | | ||
| | `config` | Non-sensitive profile, default project, and logging settings | | ||
| | `credentials` | TiDB Cloud API keys | | ||
| | `fs_resources/` | Per-profile, per-Filesystem metadata and owner credentials | | ||
| | `db_users/` | Cluster-scoped SQL credentials | | ||
| | `mounts/` | Non-secret locators for active background mounts | | ||
| | `logs/tdc.jsonl` | Redacted local operation log | | ||
| | `bin/` | Installed `tdc` and `tdc-drive9` binaries | | ||
|
|
||
| Operation logging is local and is not telemetry. Set `TDC_LOGGING=off` to disable it for one process. | ||
|
|
||
| ## tdc and the Drive9 companion | ||
|
|
||
| tdc installs [Drive9](https://github.com/mem9-ai/drive9) as the private companion name `tdc-drive9`. | ||
|
|
||
| tdc owns: | ||
|
|
||
| - profile, credential, region, and Filesystem selection; | ||
| - TiDB Cloud control-plane calls; | ||
| - JSON/text output, queries, errors, and local logging; | ||
| - translation from the tdc command surface to the companion. | ||
|
|
||
| The companion owns: | ||
|
|
||
| - Filesystem reads, writes, metadata, links, search, and layers; | ||
| - FUSE and WebDAV mount processes, caches, drain, and unmount; | ||
| - pack/unpack, Git workspace, journal, and vault semantics. | ||
|
|
||
| A background mount leaves a long-running `tdc-drive9 mount --foreground` process. `tdc fs unmount-file-system` gracefully flushes pending FUSE work and stops that process. `tdc fs drain-file-system` provides an explicit, reportable durability barrier while leaving a FUSE mount active so it can accept later writes. Do not abruptly terminate a machine with unflushed writes or local-only overlay data that you need to keep. | ||
|
|
||
| ## What's next | ||
|
|
||
| - [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) | ||
| - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | ||
| - [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| --- | ||
| title: Use TiDB Cloud Filesystem in an Agent Sandbox | ||
| summary: Provision a Filesystem on a trusted machine and give a clean agent sandbox config-free access without TiDB Cloud API keys. | ||
| --- | ||
|
|
||
| # Use TiDB Cloud Filesystem in an Agent Sandbox | ||
|
|
||
| This example gives an ephemeral coding agent a durable workspace without copying a user's complete tdc configuration into the sandbox. | ||
|
|
||
| > **Note:** | ||
| > | ||
| > tdc is currently in Preview. Its features and command-line interface might change without prior notice. | ||
|
|
||
| ## The agent problem | ||
|
|
||
| Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.tdc/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. | ||
|
|
||
| ## Why local storage and full cloud credentials are not enough | ||
|
Check warning on line 18 in ai/tdc/examples/tdc-agent-sandbox-example.md
|
||
|
|
||
| A sandbox-local directory is fast but not durable or shared. Generic object-storage APIs require application-specific download and upload logic instead of ordinary file operations. Giving every sandbox the user's complete cloud credentials solves access at the cost of a much broader security boundary. | ||
|
Check warning on line 20 in ai/tdc/examples/tdc-agent-sandbox-example.md
|
||
|
|
||
| ## How tdc changes the workflow | ||
|
|
||
| A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token, region code, and Filesystem name, and can immediately use data-plane, mount, Git, journal, and vault workflows without `tdc configure`. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Install and configure tdc on a trusted machine. | ||
| - Install tdc in the sandbox. The release installer includes `tdc-drive9`. | ||
| - Use a secure secret manager or encrypted sandbox input for token transfer. | ||
|
|
||
| ## Step 1. Provision on the trusted machine | ||
|
|
||
| ```bash | ||
| export TDC_FS_TOKEN="$(tdc fs create-file-system \ | ||
| --file-system-name agent-sandbox \ | ||
| --wait \ | ||
| --query fs_token \ | ||
| --output text)" | ||
| ``` | ||
|
|
||
| Record the canonical region code used by the profile, for example `aws-us-east-1`. Do not print the token. | ||
|
|
||
| ## Step 2. Inject the minimum sandbox environment | ||
|
|
||
| Configure the sandbox secret/environment mechanism with: | ||
|
|
||
| ```bash | ||
| TDC_FS_TOKEN=<owner-token> | ||
| TDC_REGION_CODE=aws-us-east-1 | ||
| TDC_FS_FILE_SYSTEM_NAME=agent-sandbox | ||
| ``` | ||
|
|
||
| The sandbox does not need `TDC_PUBLIC_KEY`, `TDC_PRIVATE_KEY`, `tdc configure`, or files copied from `~/.tdc/`. | ||
|
|
||
| ## Step 3. Verify direct access | ||
|
|
||
| In the sandbox: | ||
|
|
||
| ```bash | ||
| printf 'sandbox ready\n' | tdc fs copy-file \ | ||
| --from-stdin \ | ||
| --to-remote /sandbox/status.txt | ||
|
|
||
| tdc fs read-file --path /sandbox/status.txt | ||
| ``` | ||
|
|
||
| Expected output: | ||
|
|
||
| ```text | ||
| sandbox ready | ||
| ``` | ||
|
|
||
| ## Step 4. Optionally mount the Filesystem | ||
|
|
||
| On Linux with FUSE: | ||
|
|
||
| ```bash | ||
| mkdir -p "$HOME/workspace" | ||
| tdc fs mount-file-system \ | ||
| --file-system-name agent-sandbox \ | ||
| --mount-path "$HOME/workspace" \ | ||
| --driver fuse | ||
|
|
||
| cat "$HOME/workspace/sandbox/status.txt" | ||
| ``` | ||
|
|
||
| Using a path under `$HOME` also avoids the default `fusermount3` AppArmor mount-path restriction on Ubuntu 26.04. On macOS, omit `--driver fuse` to use the default WebDAV path. Use FUSE only after installing macFUSE. | ||
|
|
||
| After mounting, you can use `tdc fs-git`, `tdc fs-journal`, and owner-authorized `tdc fs-vault` commands with the same FS environment. Give agents a delegated `TDC_VAULT_TOKEN` instead of the owner token when they need only selected secret fields. | ||
|
|
||
| ## Cleanup | ||
|
|
||
| Stop writers and unmount. A graceful FUSE unmount automatically flushes and drains pending work: | ||
|
|
||
| ```bash | ||
| tdc fs unmount-file-system --mount-path "$HOME/workspace" | ||
| ``` | ||
|
|
||
| Use `tdc fs drain-file-system --mount-path "$HOME/workspace"` separately when you need to verify remote durability while keeping the mount online. Back on the trusted machine: | ||
|
|
||
| ```bash | ||
| tdc fs delete-file-system \ | ||
| --file-system-name agent-sandbox | ||
| ``` | ||
|
|
||
| ## Security notes | ||
|
|
||
| - Treat `TDC_FS_TOKEN` as an owner credential. | ||
| - Do not place it in an image, repository, command flag, or operation log. | ||
| - Deleting the sandbox does not delete the remote Filesystem. | ||
| - Graceful unmount drains pending FUSE writes; deleting the sandbox without unmounting does not. | ||
|
|
||
| ## What's next | ||
|
|
||
| - [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) | ||
| - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.