Skip to main content
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. max_read_rows and max_read_bytes set how much one read of rows.jsonl may return.

Fields

float
default:"30"
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.
str
required
secret
Postgres connection string.
list[str]
Schemas to show in the tree; others are hidden. Unset shows every schema except pg_catalog, information_schema and pg_*.
int
default:"1000"
Rows a windowed read returns when it passes an offset but no limit, and the rows one page of a streamed rows.jsonl fetches.
int
default:"10000"
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.
int
default:"10485760 (10 MiB)"
Most bytes of rows.jsonl one read returns; a whole read past it is refused (File too large).
Fields marked secret are redacted in snapshots.

Authentication

The role in dsn 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.jsonl past max_read_rows (counted on the rows the table really has) or max_read_bytes fails with File too large, and so does a head -n or tail -n count past it; wc -l counts past it. default_row_limit is what a windowed read with an offset but no limit returns.
  • File size: rows.jsonl is rendered on demand, so stat -c %s and ls -l show - while its byte length is unknown. wc -c rows.jsonl counts it, within the read limits. The estimates in the metadata files are named as estimates.
  • Snapshots: the DSN is redacted. Hand the mount back at load (mounts=, or a config over the server and CLI).

Integration

Postgres answers these commands through its own API, so fewer rows are read. See Integration.
  • grep and rg on one file: LIKE (ILIKE for -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.
For one plain text in a 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 max_read_rows 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>.
Virtual FilesystemVFS Layout/<path>
  • Read database.json first to plan joins, and a table’s semantic.json for its dimensions, facts and example values.
  • rows.jsonl is refused above the configured row or byte limit; use head, tail, wc or grep on it instead.
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.