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
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
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.
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.Authentication
The user in the URI needsreadWrite 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.mdis the filenameusers/42/data/notes.md. A leading/is dropped and a trailing/added; an empty prefix means none. - Range reads:
head -candtail -cseek by chunk, so a large file is never downloaded whole. A file smaller than the chunk size is one chunk. - Trash:
rm, and a filemvoverwrites, 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, soGridFSVFS 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 -Randtree: one recursive listing.grep -r,rgandcp -r: onefs.filesquery 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.
- 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.