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
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.
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.Directory inside the file system that becomes the mount root, such as
/projects/a for a token scoped to it; .. segments are refused.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:
mvis one server-side rename, for a file or a whole directory.rm -ris one recursive delete. - Copies:
cpreads the file and writes the copy, so the two never share content. - Local errors: before a write,
mkdirormv, 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.
- Rendered
- Raw
Virtual Filesystem
Supported 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.