> ## 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 in Python

> Virtualize a TiDB Cloud Filesystem or a self-hosted drive9 server from Python.

`TiDBFilesystemVFS` mounts a [TiDB Cloud Filesystem](https://www.pingcap.com/tidb/tidb-cloud-filesystem/)
through its REST API: its directories and files appear with their own names
and bytes, with no FUSE mount needed. Set up tokens and region hosts as in [TiDB setup](https://docs.mirage.strukto.ai/home/setup/tidb.md).

## Install

```bash theme={null}
pip install mirage-ai
```

## Configure

```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("mkdir -p /fs/notes && echo hello > /fs/notes/a.txt && ls /fs/notes")
print(await result.stdout_str())
await ws.close()
```

`root_path`, such as `/workspace`, mounts one directory. Use
`MountMode.EXEC` when `python3` or `js` should run scripts from the mount.

### Fields

**timeout** `float` (default: 30)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**host** `str` *required*

The file system's endpoint, such as `https://aws-us-east-1.drive9.ai` for its region, or the origin of a self-hosted drive9 server.

**token** `str` *required*

The file system token, sent as a bearer token.

**root\_path** `str` (default: '/')

Directory inside the file system that becomes the mount root, such as `/projects/a` for a token scoped to it; `..` segments are refused.

Fields marked secret are redacted in snapshots.

## Authentication

`token` is the file system's owner token or a scoped token, sent as a bearer
token. `host` is the endpoint of the file system's region, such as
`https://aws-us-east-1.drive9.ai`; a token works only against its own region.

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.

## Layout

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

`/fs/notes/a.txt` is `/notes/a.txt` in the file system, or
`<root_path>/notes/a.txt` with `root_path` set. `..` segments in `root_path`
are refused.

## Behavior

* **Large files:** a file under 50,000 bytes is written with one request; a
  larger one goes up in parts, a few at a time, and reads of it stream from
  object storage, ranged when a command reads only part of it.
* **Appends:** `>>` onto a file of 50,000 bytes or more sends only the new
  bytes and the file's last part; a smaller file is read and written back.
* **Moves and deletes:** `mv` is one server-side rename, for a file or a whole
  directory. `rm -r` is one recursive delete.
* **Copies:** `cp` reads the file and writes the copy, so the two never share
  content.
* **Local errors:** before a write, `mkdir` or `mv`, the mount checks the
  destination and its parents, so a missing parent, a file in the way or a
  directory target fails as it does on a local disk.
* **Extent layout:** a file in the extent layout, which only the file system's
  FUSE client writes and reads, reads as `Operation not supported`.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with TiDB Cloud Filesystem mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


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