Postgres

PostgresVFS connects to a Postgres database via a DSN and exposes its schemas and tables as a tree the agent can list, read, and grep. Install the extra:

pip install "mirage-ai[postgres]"

Config

from mirage import MountMode, Workspace
from mirage.vfs.postgres import PostgresConfig, PostgresVFS

vfs = PostgresVFS(PostgresConfig(
    dsn="postgres://user:pass@host:5432/db?sslmode=require",
    schemas=["public", "analytics"],   # optional allowlist
    default_row_limit=1000,
    max_read_rows=10_000,
    max_read_bytes=10 * 1024 * 1024,
))
ws = Workspace({"/pg": vfs}, mode=MountMode.READ)

For DSN format and permissions, see Postgres Setup. To inspect data, run find /pg/ -name rows.jsonl, then head -n 3 on a returned path.

Field	Description
`timeout` 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.
`dsn` required, secret	Postgres connection string.
`schemas`	Schemas to show in the tree; others are hidden. Unset shows every schema except `pg_catalog`, `information_schema` and `pg_*`.
`default_row_limit` 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.
`max_read_rows` 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.
`max_read_bytes` 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.

VFS.md

The VFS.md an agent reads with Postgres mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`postgres`, read

`/<path>` layout

/<path>
  database.json                  cross-schema graph + sizes
  <schema>/                      Postgres schema (namespace)
    tables/<table>/
      schema.json                column types, PK/FK, indexes
      semantic.json              descriptions, roles, sample values
      rows.jsonl                 data (size-guarded)
    views/<view>/
      schema.json
      semantic.json
      rows.jsonl
  Read semantic.json to learn what a table means: it splits columns into
  dimensions (group by), time_dimensions and facts (aggregate), and
  carries COMMENTs, enum domains and example values.
  Read database.json first to plan joins. Reading rows.jsonl is refused
  for tables above the configured row/byte threshold; use head, tail or
  wc, which ask SQL for only what they need, or grep, which fetches only
  the matching rows when SQL can find every match.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `postgres` for the matching lines. `head`, `tail` and `wc -l` ask `postgres` instead of reading a file.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `postgres`, read |

## `/<path>` layout

```text
/<path>
  database.json                  cross-schema graph + sizes
  <schema>/                      Postgres schema (namespace)
    tables/<table>/
      schema.json                column types, PK/FK, indexes
      semantic.json              descriptions, roles, sample values
      rows.jsonl                 data (size-guarded)
    views/<view>/
      schema.json
      semantic.json
      rows.jsonl
  Read semantic.json to learn what a table means: it splits columns into
  dimensions (group by), time_dimensions and facts (aggregate), and
  carries COMMENTs, enum domains and example values.
  Read database.json first to plan joins. Reading rows.jsonl is refused
  for tables above the configured row/byte threshold; use head, tail or
  wc, which ask SQL for only what they need, or grep, which fetches only
  the matching rows when SQL can find every match.
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep` and `rg` ask `postgres` for the matching lines. `head`, `tail` and `wc -l` ask `postgres` instead of reading a file. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Mount mode

read only. Postgres mounts are read-only at the VFS level.

Snapshot behavior

The DSN is redacted on snapshot. Hand the mount back at load (mounts=, or a config over the server and CLI).

File size and `du`

rows.jsonl is rendered on demand. stat -c %s and ls -l show - when its rendered byte length is unknown; physical table storage is never used as a file size. stat checks existence and type without fetching columns, row counts, or relation sizes. Planner counts cannot identify content changes, so they are not used as a content fingerprint. The metadata JSON files expose explicitly named row and storage estimates. Use wc -c rows.jsonl for the rendered byte count; reading the whole export is subject to the configured row and byte limits.

Integration

What PostgreSQL answers through its own API, so fewer files are read. Integration explains each command.

Command	On PostgreSQL
`grep`, `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 table’s or view’s rows.jsonl, grep and rg ask Postgres for the rows that hold it, with a LIKE over each column (ILIKE under -i), in the order a plain read returns them, and search those rows instead of the whole relation. 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. Since only the matching rows are fetched, a relation too large to read can still be searched when the output shows no line numbers or context.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Mount mode

Snapshot behavior

File size and `du`

Integration

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Mount mode

​Snapshot behavior

​File size and du

​Integration

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Mount mode

Snapshot behavior

File size and `du`

Integration