> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Postgres

> Mount a Postgres database as a read-only filesystem of schemas, tables, and rows.

`PostgresVFS` connects to Postgres via a DSN and exposes its schemas and tables as a tree.

Setup steps for the DSN and required permissions live at [Postgres Credentials](https://docs.mirage.strukto.ai/home/setup/postgres.md).

## Node

```bash theme={null}
pnpm add @struktoai/mirage-node pg
```

```ts theme={null}
import { MountMode, PostgresVFS, Workspace } from '@struktoai/mirage-node'

const pg = new PostgresVFS({
  dsn: process.env.DATABASE_URL!,
  schemas: ['public', 'analytics'],
})

const ws = new Workspace({ '/pg': pg }, { mode: MountMode.READ })
try {
  const result = await ws.shell('ls /pg/public/')
  console.log(result.stdoutText)
} finally {
  await ws.close()
}
```

## Browser

```bash theme={null}
pnpm add @struktoai/mirage-browser
```

The default browser driver uses Neon's HTTP transport. Replace the connection
string below with one for a read-only demo role on Neon. Browser users can inspect
this credential. Keep private database credentials in a Node backend.

```ts theme={null}
import { MountMode, PostgresVFS, Workspace } from '@struktoai/mirage-browser'

const pg = new PostgresVFS({
  dsn: 'postgresql://mirage_reader:password@your-endpoint.neon.tech/app?sslmode=require',
  schemas: ['public'],
})
const ws = new Workspace({ '/pg': pg }, { mode: MountMode.READ })

try {
  const result = await ws.shell('ls /pg/public/')
  console.log(result.stdoutText)
} finally {
  await ws.close()
}
```

## Config

| Field | Description |
| - | - |
| `timeout` 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. |
| `dsn` required, secret | Postgres connection string. The default browser driver connects over Neon's HTTP transport, so a browser mount needs a Neon connection string. |
| `schemas` | Schemas to show in the tree; others are hidden. Unset shows every schema except `pg_catalog`, `information_schema` and `pg_*`. |
| `defaultRowLimit` 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. |
| `maxReadRows` 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. |
| `maxReadBytes` 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.

## 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 (the third argument of `Workspace.load`, or a config over the server and CLI).

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Postgres mounted at `/<path>`.

> [tab] Rendered
>
> ### Virtual Filesystem
>
> | Path | Description |
> | - | - |
> | `/<path>` | `postgres`, read |
>
> #### VFS Layout
>
> ##### `/<path>`
>
> ```text theme={null}
> /<path>
>   database.json          # cross-schema graph and sizes
>   <schema>/              # a 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 `database.json` first to plan joins.
> * 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.
> * Reading `rows.jsonl` is refused for a table above the configured row
>   or 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.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `postgres`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   database.json          # cross-schema graph and sizes
>   <schema>/              # a 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 `database.json` first to plan joins.
> - 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.
> - Reading `rows.jsonl` is refused for a table above the configured row
>   or 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.
> ````

## Integration

What PostgreSQL answers through its own API, so fewer files are read. [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md) 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 |

The [Python PostgreSQL docs](https://docs.mirage.strukto.ai/python/vfs/postgres.md#integration) list when each search answers and what it can miss.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.