SqlVFS keeps a filesystem in a database’s tables: a SQLite file, a Postgres
server, a Durable Object’s storage or a D1 database. Every command that writes
works, and the files persist with the database. Setup is on the
SQL page.
Install
pg peer package.
Configure
path to keep the database in memory. capacity: '100MB' caps the
bytes the database’s files hold; see capacity.
To keep the tables in Postgres, pass its driver:
Fields
Layout
fs_inode: one row per file and folder, with its size and mtime.fs_dentry: each entry’s name under its parent folder.fs_data: a file’s bytes, in rows of the database’s chunk size (4 KiB unless the database says otherwise).fs_config: the chunk size.
Behavior
- One filesystem, both runtimes: the Python mount reads and writes the same tables, so the two runtimes on one file serve one filesystem.
-
Several mounts on one database: a mount serves one folder of its
database,
/by default. Hand two mounts one driver to serve the whole database and one folder as a mount of its own: -
Capacity:
capacitycounts every file in the database, whichever mount wrote it. Mounts on one driver with the samecapacityshare one count, so their writes together stay within it. Mounts on separate drivers count apart, even on one file, and together they can pass it. - Snapshots: a snapshot keeps the mount’s own folder, and loading it replaces that folder. The rest of the database stays as it was.
Cloudflare
@struktoai/mirage-cloudflare takes a driver as the first argument and the
same root and capacity after it: DurableObjectSqlDriver over a Durable
Object’s storage, or D1SqlDriver over a D1 database.
VFS.md
The VFS.md an agent reads with SQL 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.