> ## 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.

# SQL

> Keep a Mirage filesystem in SQL tables.

`SqlVFS` keeps a filesystem in a database's tables: a SQLite file, a Postgres
server, a Durable Object's storage or a D1 database.

## Install

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

## Config

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

const sql = new SqlVFS({ path: './workspace.db' })

const ws = new Workspace({ '/sql': sql }, { mode: MountMode.WRITE })
await ws.shell('echo "hello" | tee /sql/greet')
await ws.shell('cat /sql/greet')
```

| Field | Default | Notes |
| - | - | - |
| `path` | `:memory:` | The SQLite file, opened and closed with the mount. |
| `driver` | none | A database to borrow instead of a file; you close it. |
| `capacity` | none | The most bytes the database's files may hold, like `100MB`. |
| `root` | `/` | The folder of the database the mount serves, made if missing. |

To mount Postgres, install `pg` and pass its driver:

```ts theme={null}
import { PostgresSqlDriver, SqlVFS } from '@struktoai/mirage-node'

const driver = new PostgresSqlDriver('postgres://user:pass@localhost:5432/app')
const sql = new SqlVFS({ driver })
```

The tables are laid out as
[AgentFS](https://github.com/tursodatabase/agentfs)'s:

* `fs_inode`: one row per file and directory, with its size and mtime
* `fs_dentry`: each entry's name under its parent directory
* `fs_data`: a file's bytes, in rows of the database's chunk size (4 KiB unless the database says otherwise)
* `fs_config`: the chunk size

The Python mount reads and writes the same tables, so the two runtimes on one
file serve one filesystem.

## Several mounts on one database

A mount serves one folder of its database, `/` by default. Hand two mounts one
driver to serve the whole database at `/` and its `/workspace` folder as a mount
of its own:

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

const driver = new SqliteDriver('./workspace.db')
const ws = new Workspace(
  {
    '/': new SqlVFS({ driver, capacity: '1GB' }),
    '/workspace': new SqlVFS({ driver, root: '/workspace', capacity: '1GB' }),
  },
  { mode: MountMode.WRITE },
)
```

* `capacity` counts every file in the database, whichever mount wrote it.
  Mounts on one driver with the same `capacity` share one count, so their writes
  together stay within it. Mounts on separate drivers count apart, even on one
  file, and together they can pass it.
* `getState` and `loadState` keep and replace the mount's own folder. A restore
  leaves the rest of the database as it was.

Core's `SqlVFS` takes the same `root` and `capacity` over any driver, a Durable
Object's storage among them.

## VFS.md

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

> [tab] Rendered
>
> ### Virtual Filesystem
>
> | Path | Description |
> | - | - |
> | `/<path>` | write |
>
> #### 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>` | Almost all Unix commands. |
>
> #### Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `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>` | write |
>
> ## 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>` | Almost all Unix commands. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `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.
> ```


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