Skip to main content
GridFSVFS mounts a MongoDB GridFS bucket: every file in the bucket becomes a file and every / in a filename a folder. Metadata lives in the <bucket>.files collection and content in <bucket>.chunks. Set up the connection URI as in GridFS setup.

Install

Configure

The mongodb peer package loads only when a GridFSVFS is built. bucket names a bucket other than fs, keyPrefix scopes the mount to part of it, and keepRevisions bounds the history each file keeps. A mount takes MountMode.READ, WRITE or EXEC.

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
secret
MongoDB connection URI.
string
required
Database that holds the GridFS bucket.
string
default:"'fs'"
GridFS bucket name; its collections are <bucket>.files and <bucket>.chunks.
string
Filename prefix the mount treats as its root; files outside it are not listed.
number
Chunk size in bytes for files the mount writes; unset uses the driver’s default, 255 KiB.
number
Revisions kept per file, newest first: a write or an rm deletes the rest, under the file’s name and in the trash rm moves revisions to (/trash/<filename>, which no mount path reaches). Unset keeps every revision, so a snapshot pinned to any of them still reads.
Fields marked secret are redacted in snapshots.

Authentication

The user in the URI needs readWrite on the database that holds the bucket, or read for a read mount. On Atlas, the built-in Read and write to any database role also works.

Layout

/gridfs/data/file.txt is the GridFS filename data/file.txt. Folders come from the / in filenames; mkdir stores a zero-byte data/ marker so an empty folder stays visible.

Behavior

  • Key prefix: keyPrefix: 'users/42/' mounts only that part of the bucket, so /gridfs/data/notes.md is the filename users/42/data/notes.md. A leading / is dropped and a trailing / added; an empty prefix means none.
  • Range reads: head -c and tail -c seek by chunk, so a large file is never downloaded whole. A file smaller than the chunk size is one chunk.
  • Trash: rm, and a file mv overwrites, retag every revision to /trash/<filename>. No mount path reaches the trash, so the name reads as gone, and the full original filename stays traceable.

Revisions

GridFS filenames are not unique: every write uploads a new revision and keeps the old ones. Reads and listings serve the newest revision per filename, and a snapshot-pinned read resolves an older revision by its _id. mv retags every revision’s filename on the server, so history moves with the file. keepRevisions bounds the history. Set it, and a write or an rm deletes the revisions past that count per filename, oldest first, under the file’s name and in the trash alike; a snapshot pinned to a pruned revision then fails to read it. Unset keeps every revision.

Browser

GridFS needs a direct MongoDB connection, so GridFSVFS ships in @struktoai/mirage-node only. A browser workspace reaches GridFS through a Node-side Mirage server instead.

Integration

GridFS answers these commands through its own API, so fewer files are read. See Integration.
  • find: one recursive listing.
  • du: one recursive listing.
  • ls -R and tree: one recursive listing.
  • grep -r, rg and cp -r: one fs.files query for the whole tree; see Walks.

VFS.md

The VFS.md an agent reads with GridFS 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.