Agent-First PSQL v0.2.1: SQL Became Previewable

Generated SQL should not need to touch the database before an agent can inspect it.

Agent-First PSQL v0.2.1 added a dry-run path and clearer hints. It was an early step toward treating the PostgreSQL connector as an agent decision interface, not just a way to ship SQL text to a socket.

The problem: SQL shape matters before execution

A query is more than a string. It has positional params, a session, connection settings, output limits, streaming choices, and timeout behavior.

If an agent can only see the final command line, it has to infer what afpsql will actually execute after parsing and config resolution. That is not enough for a database tool.

The change: dry-run became structured output

--dry-run emits a dry_run event with the resolved SQL, params, and session without executing the query.

{"code":"dry_run","sql":"select * from users where id = $1","params":["42"],"session":"default"}

The agent can show the user what would happen, check that params are positional, or verify it is using the intended named session before any database side effect.

The hint change: errors started suggesting next steps

v0.2.1 also added hints to connection failures and result-size failures. A failed connection can point toward host, port, or environment variables. A result that exceeds inline limits can point toward streaming.

The stable code remains the thing the agent branches on. The hint is the corrective text that helps it recover.

The session change: config invalidation became explicit

Config updates can change which database a session points at. The release added session invalidation behavior around config patches so stale pools do not keep using the wrong resolved connection after the config changes.

That is important for agents because named sessions are a memory mechanism. If the config changes, the session lifecycle has to be visible and predictable.

Where this fits: inspect first, execute second

v0.2.1 established a theme that still matters: database operations need an inspection step. Agents should be able to reason about the query shape before the database has to answer for it.