📣New in Public Preview: TiDB Cloud BYOC, TiDB Cloud Filesystem, PostgreSQL-compatible TiDB Cloud Starter

Manage File Systems in TiDB Cloud Filesystem

You can use the TiDB Cloud console or TiDB Cloud CLI (ti) to create, inspect, and delete file systems in TiDB Cloud Filesystem. The console also lets you rename a file system; the CLI provides access diagnostics.

For command syntax, flags, and output fields, see the ti fs command reference.

Prerequisites

To use the TiDB Cloud console to manage file systems, log in to the console and select your organization.
To use the TiDB Cloud CLI (ti) to manage file systems, follow Quick Start via CLI to install ti and configure access.

Create a file system

You can create a file system using the TiDB Cloud console or TiDB Cloud CLI.

In the left navigation pane of the TiDB Cloud console, select your organization and click File Systems.
In the upper-right corner, click Create File System.
On the Create File System page, enter a file system name, and select a Cloud Provider and Region.
(Optional) Review and edit the usage limits in the summary.
To edit the usage limits, add a credit card to your organization. Without a credit card, the free limits cannot be edited during creation. For more information, see Manage Usage Limits.
Click Create. The Your File System is Ready! dialog offers optional steps to install TiDB Cloud CLI and mount the file system on macOS or Linux. The default owner token in the mount command is shown only once; save it securely before closing the dialog.

Create a file system and wait until it is ready:

ti fs create-file-system \
  --display-name agent-workspace \
  --label environment=development \
  --wait

From the output, you can get the file system ID in the file_system_id field and the file system owner token in the fs_token field. The CLI automatically stores the file system owner token locally.

Copy the returned file_system_id and select the file system for subsequent commands in the current shell:

export TI_FS_FILE_SYSTEM_ID="<file-system-id>"

Setting TI_FS_FILE_SYSTEM_ID lets subsequent commands identify the target file system without requiring --file-system-id on every command. For data-access commands, the CLI uses the locally stored file system token for the selected file system.

Warning

The file system owner token plaintext in fs_token is returned only when the token is issued. Treat it as a secret and do not expose it in logs, issues, or source control. If you need to use the token on another machine or store a backup, save it securely in a secret manager. For more information, see Manage File System Tokens.

Note

Do not put credentials, connection strings, private paths, or personal data in file system labels.

List and inspect file systems

You can list file systems and view their details using the TiDB Cloud console or TiDB Cloud CLI.

In the left navigation pane of the TiDB Cloud console, select your organization and click File Systems.
On the File Systems page, select a cloud provider and region to list file systems in that location. Use Search Name or Status to narrow the list.

To view details of a file system, click the file system's name to go to its overview page.

To change its display name, click ... in the upper-right corner of the overview page and select Rename.

List the file systems available in the current region:

ti fs list-file-systems --output text

View metadata for a file system:

ti fs describe-file-system --file-system-id "<file-system-id>"

If you work with more than one file system, specify the target file system in one of the following ways:

Pass --file-system-id "<file-system-id>" to an individual command.
Set TI_FS_FILE_SYSTEM_ID to select a file system for subsequent commands in the current shell.

The CLI does not automatically select a file system based on the number of file systems or locally stored credentials.

The current CLI does not provide a command to change a file system's display name or labels after creation. Choose these values when you create the file system.

Check access

Check whether the CLI can access a file system:

ti fs check-file-system --file-system-id "<file-system-id>"

The result includes an overall status and checks local credentials, endpoint selection, the bundled file system runtime, and remote connectivity.

passed means all checks succeeded.
warning or failed identifies a check that needs attention.

For common access and connectivity issues, see Troubleshoot TiDB Cloud Filesystem.

Delete a file system

You can delete a file system using the TiDB Cloud console or TiDB Cloud CLI.

Warning

Deleting a file system permanently removes its remote data. Before deletion, stop applications that are using the file system and successfully unmount any active local mounts. For information about finishing pending writes safely, see Finish safely.

In the TiDB Cloud console, open your organization's File Systems page, then select the Cloud Provider and Region for the target file system.
In the row of the target file system, click ..., and then select Delete.
In the confirmation dialog, enter the requested region and file system name in the form region/name, then click I understand, delete it.

Deletion is asynchronous. After the request is submitted, the file system might remain visible with the status deleting until deletion finishes.

Delete a file system by its ID:

ti fs delete-file-system --file-system-id "<file-system-id>"

File system deletion is asynchronous. After the service accepts the request, the CLI reports the file system status as deleting and removes the matching locally stored credential. This status means that deletion has started, not that the remote file system and its data have already been removed.

What's next

Manage File System Tokens to generate, delegate, rotate, or revoke file system access.
Work with Files and Directories to copy, read, organize, and search file system data.
Mount a File System to access remote files through a local directory.
TiDB Cloud Filesystem CLI Command Reference for command syntax, flags, and output fields.