pgmcp: Instructions file for Codex

AGENTS.md

doc.go/README are authoritative; this file records what is not derivable from code.

Commands

go test -race -cover ./...
go vet ./...
gofmt -l .                                              # any filename printed = unformatted; run before finishing
go run honnef.co/go/tools/cmd/staticcheck@latest ./...
go build ./cmd/pgmcp
bin/up                                                  # docker compose up --build -d, follow logs
bin/down                                                # tear down, including volumes
bin/exec <command>                                      # run a command in a throwaway go container

Integration tests are skipped unless PGMCP_TEST_DSN points at a Postgres with pg_stat_statements preloaded; the scratch-container recipe is in the README's Testing section. The conformance suite runs against a live HTTP server:

npx -y @modelcontextprotocol/conformance server --url http://127.0.0.1:8080/mcp \
  --expected-failures .github/conformance-expected-failures.yaml

The release pipeline — six binaries, the darwin universal binary, the Claude Desktop bundle, checksums — can be run end to end without publishing (needs Node for the pinned @anthropic-ai/mcpb CLI):

go run github.com/goreleaser/goreleaser/v2@latest release --snapshot --clean --skip=publish,docker

Invariants — keep the tests that pin them

Each line is a property the codebase must not lose. If a change makes one of these tests fail, the change is wrong until proven otherwise.

Read-only enforcement

• Every statement the adapter runs is inside a READ ONLY transaction, and a write inside it fails with SQLSTATE 25006 — pinned by TestStoreReadOnly (infrastructure/postgres).
• statement_timeout and lock_timeout are set on every such transaction, and the transaction is always rolled back — pinned by TestStoreReadOnly (infrastructure/postgres).
• Only a single top-level SELECT/EXPLAIN/SHOW is allowed; a nested write statement (including one hidden in a CTE), a FOR UPDATE/FOR SHARE locking clause, a SELECT INTO, or a denied function is rejected — pinned by TestValidate (domain/sqlguard).
• The libpg_query adapter reports the node types, function names and schemas the guard's rules are written against — pinned by TestParserParse and TestParserSatisfiesTheSqlguardParserPort (infrastructure/postgres).