Skip to main content
TiDBFilesystemVFS mounts a 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 the tokens and region hosts as in TiDB setup. It ships in @struktoai/mirage-node.

Install

Configure

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

Fields

number
default:"DEFAULT_TIMEOUT"
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.
string
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.
string
required
secret
The file system token, sent as a bearer token.
string
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 rootPath set to that path, since it cannot list the file system’s root. TiDB Cloud Filesystem runs on the open-source 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

/fs/notes/a.txt is /notes/a.txt in the file system, or <rootPath>/notes/a.txt with rootPath set. .. segments in rootPath 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 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.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.