PostgresVFS turns a Postgres database into a read-only tree: every schema is a
folder of tables and views, and each one holds its column types, a summary of
what it means and its rows as JSON lines. Set up the connection string and a read-only role as in Postgres setup.
Install
Configure
schemas limits the tree to those schemas. maxReadRows and maxReadBytes
set how much one read of rows.jsonl may return.
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.
Postgres connection string. The default browser driver connects over Neon’s HTTP transport, so a browser mount needs a Neon connection string.
Schemas to show in the tree; others are hidden. Unset shows every schema except
pg_catalog, information_schema and pg_*.Rows a windowed read returns when it passes an offset but no limit, and the rows one page of a streamed
rows.jsonl fetches.Most rows one read returns. A whole read past it is refused, and so is a
head -n / tail -n count past it on a table that long (File too large); wc -l counts past it.Most bytes of
rows.jsonl one read returns; a whole read past it is refused (File too large).Authentication
The role indsn needs USAGE on each schema the mount shows and SELECT on
its tables and views. Add ?sslmode=require when the server needs TLS.
Layout
database.json: every table with its estimated rows and size, and the relationships between them.schema.json: columns, keys and indexes.semantic.json: what a table means: dimensions, time dimensions and facts, comments, enum domains and example values.rows.jsonl: one row per line.
Behavior
- Read-only: the mount only reads; no command changes the database.
- Read limits: a whole read of
rows.jsonlpastmaxReadRows(counted on the rows the table really has) ormaxReadBytesfails withFile too large, and so does ahead -nortail -ncount past it;wc -lcounts past it.defaultRowLimitis what a windowed read with an offset but no limit returns. - File size:
rows.jsonlis rendered on demand, sostat -c %sandls -lshow-while its byte length is unknown.wc -c rows.jsonlcounts it, within the read limits. - Snapshots: the DSN is redacted. Hand the mount back at load (the third
argument of
Workspace.load, or a config over the server and CLI).
Browser
The browserPostgresVFS from @struktoai/mirage-browser reaches the
database over Neon’s HTTP transport, with the same fields.
- Anyone who opens the page can read the connection string. Use a read-only demo role on Neon, and keep private credentials in a Node backend.
Integration
Postgres answers these commands through its own API, so fewer rows are read. See Integration.grepandrgon one file:LIKE(ILIKEfor-i) fetches only the rows that may match.head -n N:LIMIT N.tail -n N: the last N rows by one query.wc -l:COUNT(*).tail -f: polls for rows past the last key, on a table with a primary key.
rows.jsonl, grep and rg search the rows a LIKE over
each column returns, in the order a plain read returns them. A column is
searched through its cast when a line spells it the same way: text, an integer,
a boolean, a uuid, an enum, jsonb, char(n) for a text without a space, and
an array of text, integers or uuids. A number, date or time column is left out
when the text holds a character it never spells (ada in a float8). The file
is read as usual when another column type is present (json, interval,
bytea), when the text could lie inside one of those values, match a key,
null or the JSON between values, or when more than maxReadRows rows
match. A relation too large to read can still be searched when the output
shows no line numbers or context.
VFS.md
The VFS.md an agent reads with Postgres mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Read
database.jsonfirst to plan joins, and a table’ssemantic.jsonfor its dimensions, facts and example values. rows.jsonlis refused above the configured row or byte limit; usehead,tail,wcorgrepon it instead.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.