BashGres -- PostgreSQL-backed Virtual Filesystem

Install

Install BashGres with your preferred PostgreSQL driver and just-bash:

npm install bash-gres postgres just-bash

Connect

Create a PgFileSystem , a PostgreSQL-backed virtual filesystem scoped to a workspace. setup() creates tables, indexes, and extensions idempotently.

import postgres from "postgres"
import { setup, PgFileSystem } from "bash-gres/postgres"

const sql = postgres("postgres://localhost:5432/myapp")

await setup(sql) // idempotent, safe on every startup

const fs = new PgFileSystem({ db: sql, workspaceId: "workspace-1" })

Filesystem

The API mirrors Node.js fs. All operations are transactional and scoped to the workspace.

// Write & read
await fs.writeFile("/docs/guide.md", "# Getting Started")
await fs.mkdir("/docs/images", { recursive: true })
const content = await fs.readFile("/docs/guide.md")
const entries = await fs.readdir("/docs")

// Copy, move, remove
await fs.cp("/docs", "/backup", { recursive: true })
await fs.mv("/backup/guide.md", "/archive/guide.md")
await fs.rm("/archive", { recursive: true, force: true })

// Symlinks & stats
await fs.symlink("/docs/guide.md", "/latest")
const stat = await fs.stat("/docs/guide.md")
const tree = await fs.walk("/docs")

// Versioned directories -- scoped working copies & deploy snapshots
await fs.mkdir("/database", { versioned: true })

const dbMain = await fs.versioned("/database")
await dbMain.writeFile("/config.json", '{"env":"staging"}')

const dbDraft = await dbMain.fork("draft")
await dbDraft.writeFile("/config.json", '{"env":"prod"}')

await dbMain.readFile("/config.json") // '{"env":"staging"}' (untouched)
await dbMain.listVersions()           // ["draft", "main"]

// Full-text search (BM25 via pg_textsearch)
const results = await fs.textSearch("machine learning", {
  path: "/docs",
  limit: 20,
})

// Semantic search (pgvector)
const similar = await fs.semanticSearch("how do LLMs work", {
  path: "/docs",
  limit: 10,
})

// Hybrid: BM25 + vector combined
const hybrid = await fs.hybridSearch("transformer architecture", {
  path: "/docs",
  textWeight: 0.4,
  vectorWeight: 0.6,
})

Bash

Pass PgFileSystem to just-bash and get a complete bash environment: 60+ commands, pipes, redirects, variables, loops, all persisted in PostgreSQL.

import { Bash } from "just-bash"
import { PgFileSystem } from "bash-gres"

const fs = new PgFileSystem({ db: client, workspaceId: "workspace-1" })
const bash = new Bash({ fs })

// A full bash environment, backed by PostgreSQL
await bash.exec("mkdir -p /project/src")
await bash.exec('echo "hello world" > /project/src/index.ts')
await bash.exec("cat /project/src/index.ts")