Agent-First PSQL Blog
Updates, deep-dives, and release notes for Agent-First PSQL.
Design
Release notes
Agent-First PSQL v0.11.0: A Cancel Is a Request
Cancelling a query took its terminal event slot before the CancelRequest was even sent, so a write that had already committed came back as 'cancelled' — the worst answer this program can give. That, a COMMIT sent down a brand-new connection after the backend died, and inspection panels rebuilt around objects instead of the snapshot query's row shape.
ReleaseAgent-First PSQL v0.10.0: The Window and the Agent Cannot Disagree
Five panels that open a window onto PostgreSQL — four you read, one you approve. Each runs the exact SQL its inspect sibling runs, an approved statement runs the ordinary path, and only an approval runs anything: a closed window, a refusal and a lapsed credential are the same answer.
ReleaseAgent-First PSQL v0.9.1: The Errors That Are Not Yours
v0.9.0 made every illegal invocation an exit-2 rejection that says «rewrite your command line». v0.9.1 is about the two failures where the caller has nothing to rewrite: a handler that reads an argument its own shape never declared, which used to become an empty string that looked like a value someone passed, and an output sink that could not be opened, which used to be reported as a usage error. Both are exit 1 with a code of their own, and a new test drives all 23 shapes through their handlers so the first one is caught before it ships. Rejections also stopped quoting the token back, so a psql-style `-d<DSN>` typo can no longer echo its password into a logged error event. Picks up Agent-First Data 0.31.0.
ReleaseAgent-First PSQL v0.9.0: Making the Illegal Invocation Unwritable
v0.9.0 compiles the CLI from a closed registry of 17 commands and 23 shapes, so an invocation runs only when it matches one of them and every combination that used to be caught by a runtime check — or quietly ignored — is now an unknown argument at parse time. The nine `--*-secret[-env|-config]` flags collapse into three typed sources (`--dsn`, `--conninfo`, `--password`) that accept a literal, `env:NAME`, or `file:PATH#DOT_PATH`. Container flags name their driver, so an option a driver does not have cannot be written. And the write boundary the README always promised is now actually enforced inside pipe transactions, where three JSONL lines with no permission field could previously delete rows.
ReleaseAgent-First PSQL v0.8.2: A Test That Poisoned Its Neighbours
Two tests mutated PGHOST and AFPSQL_DSN_SECRET inside the shared library test binary while unlocked readers ran in parallel, so five unrelated connection tests failed depending on thread scheduling. Both moved into a dedicated integration binary that owns process-environment mutation outright. Also picks up Agent-First Data 0.26.2.
ReleaseAgent-First PSQL v0.8.1: The Release Check Reads the Right Stream
v0.8.0's own release smoke test still read errors from stdout, so it failed the binary build after publishing and shipped v0.8.0 without downloadable binaries. v0.8.1 fixes the check — including a secret-leak assertion that had started passing against an empty string — and moves it into the release gate so it runs before anything irreversible.
ReleaseAgent-First PSQL v0.8.0: The DSN Crosses the Boundary Intact
v0.8.0 lets `--dsn-secret` and `--conninfo-secret` work with `--ssh` and `--container`: afpsql parses the connection string locally, derives only the transport's internal endpoint from it, and carries authentication, database, startup options, timeouts, keepalives, channel binding, and TLS across the tunnel unchanged — with the SSH stdio bridge now encrypted too. Event routing now follows the invocation: a finite query splits result to stdout and diagnostics to stderr, while `--mode pipe` and `--stream-rows` keep their ordered stream whole on stdout. The canonical CLI surface goes long-flags-only so psql's shorts keep their psql meanings.
ReleaseAgent-First PSQL v0.7.0: Read the Secret From the Config
v0.7.0 lets afpsql read a connection secret straight from the application's own JSON, TOML, YAML, or dotenv config file — `--dsn-secret-config FILE DOT_PATH` and its conninfo/password siblings — resolved once, in-process, with no `jq`/`yq` subprocess and no secret in argv or shell history. Configured secrets always render as `***` in runtime config output regardless of source, and `afpsql-readonly` is redefined as a PostgreSQL write guard rather than a host sandbox: it restores SQL files, config sources, SSH options, container runtimes, redirects, and skill management while still refusing writes.
ReleaseAgent-First PSQL v0.6.3: Look Before You Touch
v0.6.3 gives an agent everything it needs to understand a database before changing it: `afpsql inspect` for schema discovery, `--dry-run` to prepare and validate a statement without running it, `--explain` / `--explain-analyze` for the query plan, and pipe-mode `begin`/`commit`/`rollback` for explicit multi-statement transactions with savepoint-isolated failures. It also soft-truncates oversized inline results instead of erroring, and ships correctness fixes for query cancellation, value decoding (bytea and arrays), and NUMERIC bind precision.
ReleaseAgent-First PSQL v0.6.2: Container Transport Family and Self-Describing Sessions
v0.6.2 generalizes the docker transport into a container transport family (podman, nerdctl, compose, kubectl) with structured scope flags and SSH chaining, adds a session_info pipe request so agents can introspect their session's transport, permission default, and limits instead of probing with failing queries, and surfaces two new log events for implicit behaviors that previously had to be inferred.
ReleaseAgent-First PSQL v0.6.1: Embedded Skill Installer and SQLSTATE on Connect
v0.6.1 ships the Agent-First PSQL skill inside the binary so Claude Code and Codex can install it with one command, and preserves PostgreSQL SQLSTATE plus message, detail, and hint on connect_failed so agents can distinguish auth, role, database, capacity, and startup failures without parsing prose.
ReleaseAgent-First PSQL v0.6: SSH Transport and Explicit Write Permissions
v0.6 adds an SSH transport that keeps the agent local while reaching server-only PostgreSQL, and splits write permission into separate direct and SSH families so an agent cannot silently turn a read across a boundary into a remote write.
ReleaseAgent-First PSQL v0.4: A Native Runtime with Complete Help
The v0.4 line removed MCP server mode, generated CLI docs from the source command definition, and made --help complete for agents.
ReleaseAgent-First PSQL v0.3.1: Output Policy Protected SQL Rows
The v0.3.1 update separated SQL payloads from output-layer redaction and preserved row structure across JSON, YAML, plain, and MCP responses.
ReleaseAgent-First PSQL v0.2.1: SQL Became Previewable
The v0.2.1 update added dry-run SQL previews, actionable error hints, and better config invalidation for stateful sessions.
ReleaseAgent-First PSQL v0.1: SQL Queries as Structured Events
The first Agent-First PSQL release line: PostgreSQL rows, timing, and SQLSTATE failures as machine-readable events instead of terminal prose.