Skip to main content
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

Postgres also needs the pg peer package.

Configure

Leave out 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

The tables are laid out as AgentFS’s:
  • 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: capacity counts every file in the database, whichever mount wrote it. Mounts on one driver with the same capacity share 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.
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.