Skip to main content
Every schema becomes a folder of tables and views. Each one holds its column types, a summary of what it means and its rows as JSON lines.

Setup

Get a connection string and a role that can read the tables. Then export the string:
  • Local server: postgres://postgres:postgres@localhost:5432/postgres.
  • Neon: select Connect in the console, pick the branch, database and role, and copy the string. Neon requires sslmode=require.
  • Supabase: select Connect at the top of the project and copy a string. Use the direct connection, or the session pooler on an IPv4-only network. Put the database password in it.
  • Other managed servers (RDS and the like) print the string in their dashboard. Add ?sslmode=require when the server needs TLS.
The mount only reads. The role it connects as needs at least:
Repeat the grants for each schema the mount should see.
Python needs pip install "mirage-ai[postgres]"; Node needs the pg peer dependency (pnpm add @struktoai/mirage-node pg).

Connect

workspace.yaml

Layout

  • database.json lists every table with its estimated rows and size; schema.json holds columns, keys and indexes.
  • schemas limits the tree to those schemas. Unset, it shows all but pg_catalog, information_schema and pg_*.
  • A whole read of rows.jsonl past max_read_rows (10,000, counted on the rows the table really has) or max_read_bytes (10 MiB) fails with File too large, and so does a head -n or tail -n count past it; wc -l counts past it. Raise them in config for bigger reads.
  • default_row_limit (1,000) is what a windowed read with an offset but no limit returns.

Sample runs

head, tail, wc -l and grep ask Postgres for only the rows they need. The mount is read-only: no command changes the database.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.