pgsandbox: Instructions file for Codex

PGSandbox Agent Guide

Scope

This file is the repo-level operating manual for coding agents working on pgsandbox. Apply it to the whole repository unless a more specific steering file says otherwise.

Project Summary

PGSandbox is a local-first MCP server that lets coding agents create, inspect, use, and delete disposable Postgres databases. The goal is to make a real isolated database the easy default for migrations, SQL validation, seeded demo states, and backend bug reproduction.

The package is a Rust native CLI and MCP stdio server. It manages a local Postgres cluster by default. Setup and ensure_postgres can install missing PostgreSQL binaries through a supported package manager when available. Explicit external Postgres admin profiles remain optional and can be configured by environment variables or a JSON config file.

First Files To Read

• README.md for user-facing install and workflow.
• docs/architecture.md for the resource model and future backend ideas.
• docs/mcp-tools.md for MCP tool contracts.
• docs/open-questions.md before expanding scope.
• PRODUCT.md, TECH.md, STRUCTURE.md, VISION.md, and DESIGN.md for steering context.

Reliable Commands

Run these from the repo root:

npm run check
npm test
npm run build

These npm scripts delegate to Cargo. The direct equivalents are:

cargo check
cargo test
cargo build --release

Useful manual checks with the managed local runtime:

pgsandbox local status
pgsandbox doctor
pgsandbox smoke-test

Release packaging check:

npm run package:homebrew

Implementation Rules

• Keep the MCP tool surface narrow and explicit in rust-src/mcp.rs; put database lifecycle behavior in rust-src/postgres.rs.
• Preserve the distinction between admin connections and sandbox role connections. Admin connections are for lifecycle and metadata only.
• Destructive operations must only target databases recorded in the pgsandbox_databases metadata table for the selected profile.
• Keep TTL enforcement and maxTtlMinutes caps intact when changing create or cleanup behavior.
• Do not log full connection strings. Mask or omit passwords in user-facing output unless the tool intentionally returns sandbox credentials to the caller.
• Use quote_ident and quote_literal from rust-src/names.rs for generated SQL identifiers/literals. Do not interpolate identifiers by hand.
• Preserve run_sql row limiting and truncation behavior. New query paths should have tests that prove large result sets do not dump unbounded rows.
• Prefer structured parsing and validation through Rust types, Serde, JSON, TOML, or Postgres client APIs over regex/string manipulation when practical.
• Do not make Docker a hard requirement. docker-compose.example.yml is only a local demo helper.
• Treat the current server as local/private infrastructure. Hosted database platform work is allowed as an explicit product direction, but it needs a deliberate design for auth, tenancy, quotas, billing, and security before adding a public network admin surface.