> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TiDB Cloud Filesystem

> Virtualize a TiDB Cloud Filesystem, or a self-hosted drive9 server, as files.

![](https://mintcdn.com/struktoai/F9Lv_nTaj6By6crk/images/python-logo.svg?fit=max\&auto=format\&n=F9Lv_nTaj6By6crk\&q=85\&s=cf5b268d330f7db46ea5cf6083f309a1)

Node.js

![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/cloudflare-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=23668457afa14abb3b0db0f5b9c0541a)

A TiDB Cloud file system appears under the mount as its own tree of
directories and files, reached through its REST API with no FUSE mount.

## Setup

1. Create a file system in the [TiDB Cloud console](https://tidbcloud.com/) or
   with `ti fs`, and note its region.
2. Copy its owner token, shown once in the **Your File System is Ready!**
   dialog, or create a scoped token: **File Systems**, the file system,
   **Access Tokens**, **Create Token**. See
   [Manage File System Tokens](https://docs.pingcap.com/tidbcloud-filesystem/manage-filesystem-tokens/).
3. Set the host to the endpoint of the file system's region. A token works
   only against its own region.

```bash theme={null}
export TIDB_FILESYSTEM_HOST=https://aws-us-east-1.drive9.ai
export TIDB_FILESYSTEM_TOKEN=...
```

| Region | Host |
| - | - |
| `aws-us-east-1` | `https://aws-us-east-1.drive9.ai` |
| `aws-us-west-2` | `https://aws-us-west-2.drive9.ai` |
| `aws-ap-southeast-1` | `https://aws-ap-southeast-1.drive9.ai` |
| `gcp-us-east1` | `https://gcp-us-east1.drive9.ai` |
| `azure-centralus` | `https://azure-centralus.drive9.ai` |
| `alicloud-ap-southeast-1` | `https://alicloud-ap-southeast-1.drive9.ai` |

A scoped token reaches only the path it was created for, and only with the
operations it allows (`read`, `list`, `search`, `write`, `delete`). Mount it
with `root_path` set to that path, since it cannot list the file system's
root.

TiDB Cloud Filesystem runs on the open-source
[drive9](https://github.com/mem9-ai/drive9) server, and the same VFS mounts a
self-hosted drive9 server: set `host` to its origin and `token` to an API key
it issued.

## Connect

> [tab] YAML
>
> ```yaml workspace.yaml theme={null}
> mounts:
>   /fs:
>     vfs: tidb_filesystem
>     mode: write
>     config:
>       host: ${TIDB_FILESYSTEM_HOST}
>       token: ${TIDB_FILESYSTEM_TOKEN}
> ```
>
> ```bash theme={null}
> mirage workspace create workspace.yaml --id fs
> mirage shell -w fs -c 'ls /fs'
> ```

> [tab] Python
>
> ```python theme={null}
> import os
>
> from mirage import MountMode, Workspace
> from mirage.vfs.tidb_filesystem import TiDBFilesystemConfig, TiDBFilesystemVFS
>
> config = TiDBFilesystemConfig(
>     host=os.environ["TIDB_FILESYSTEM_HOST"],
>     token=os.environ["TIDB_FILESYSTEM_TOKEN"],
> )
> ws = Workspace({"/fs": TiDBFilesystemVFS(config)}, mode=MountMode.WRITE)
> result = await ws.shell("ls /fs")
> print(await result.stdout_str())
> await ws.close()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { buildVfs, MountMode, Workspace } from '@struktoai/mirage-node'
>
> const fs = await buildVfs('tidb_filesystem', {
>   host: process.env.TIDB_FILESYSTEM_HOST!,
>   token: process.env.TIDB_FILESYSTEM_TOKEN!,
> })
> const ws = new Workspace({ '/fs': fs }, { mode: MountMode.WRITE })
> const result = await ws.shell('ls /fs')
> console.log(result.stdoutText)
> await ws.close()
> ```

## Layout

```text theme={null}
/fs/
  notes/
    a.txt
  workspace/
    data.json
```

* Files keep their own names and bytes; nothing is converted.
* `root_path: /workspace` mounts only that directory; `..` is refused.
* A file in the extent layout, which only the file system's FUSE client
  reads, answers `Operation not supported`.

## Sample runs

```bash theme={null}
$ ls /fs
notes
workspace
```

```bash theme={null}
$ ls /fs/notes
a.txt
```

```bash theme={null}
$ cat /fs/notes/a.txt
hello
```

`echo hello > /fs/notes/a.txt` writes a file; `mv` is one server-side rename
and `rm -r` one recursive delete. A file of 50,000 bytes or more uploads in
parts, and `>>` onto it sends only the new bytes.

## SDK guides

> [card] [Python](https://docs.mirage.strukto.ai/python/vfs/tidb_filesystem.md)
>
> Every config field, the VFS.md and write support.

> [card] [TypeScript](https://docs.mirage.strukto.ai/typescript/vfs/tidb_filesystem.md)
>
> Every config field, the VFS.md and write support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.