pgGo v0.1.1

Adds a runnable example, so you can try pgGo without installing anything:

DATABASE_URL=postgres://user:pass@localhost:5432/db \
  go run github.com/pgrundev/pggo/examples/hello@latest

It prints the server version, the result of SELECT 1, and the elapsed time. The library and CLI are unchanged from v0.1.0, and the README now shows install instructions and a usage example at the top.

pgGo v0.1.0

pgGo is now a Go library as well as a CLI. The pggo command is rebuilt on the same core, with an unchanged JSON contract. PgBot now runs on this library instead of pgx.

go get github.com/pgrundev/pggo@v0.1.0                 # library
go install github.com/pgrundev/pggo/cmd/pggo@v0.1.0    # CLI

Library (github.com/pgrundev/pggo)

• Connect / ParseConfig read URLs, key=value strings, PG* environment variables, service files and .pgpass. They take ReadOnly(), StatementTimeout() and LockTimeout() options, and a Config.DialFunc for custom dialers such as SSH tunnels.
• Query streams rows (Next/Scan/Values/RawValues/Err/Close); there are also QueryRow + ErrNoRows, Exec → CommandTag.RowsAffected(), SimpleQuery, Prepare/Deallocate and MaxRows(n).
• BeginTx(ctx, TxOptions{ReadOnly: true}): BEGIN travels with the first statement in the same sync, so the statement can never run outside the transaction, and it costs no extra round trip.
• CollectStructs[T] / CollectOneStruct[T] map rows onto structs using db:"…" tags; CollectStructsByPos[T] maps by position.
• Unknown PostgreSQL types never fail: scan them into *string or *pggo.RawValue.
• *pggo.PgError carries the SQLSTATE, detail, hint and position.
• Every call takes a context.Context. When it's cancelled, pgGo sends a cancel request and closes the connection, so the connection can never be reused in an unknown state.
• A deliberately minimal Pool: max connections, max lifetime, and AfterConnect/BeforeClose hooks.
• Still zero dependencies (standard library only).

CLI

• The JSON contract, limits, timeouts and hints are unchanged, and the full regression suite passes on PostgreSQL 16–19.
• Fix: a connection closed during the handshake is now reported as connection_error.

Verification

• The library and CLI suites pass on PostgreSQL 16, 17, 18 and 19beta1, with the race detector clean and 7 fuzz targets.
• PgBot's suites pass on pgGo across PostgreSQL 13–19, over TLS, and through PgBouncer (transaction mode) and PgDog.
• Agent tests: 6/6.
• Performance matches v0.0.1 within noise. The binary is 4.10 MB (+1.7%) and peak RSS 6.4 MiB.

The PgBot compatibility audit is in docs/pgbot-compatibility.md.

pgGo v0.0.1

First release of pgGo: a tiny PostgreSQL client for AI agents, written in Go. It has zero dependencies, ships as one binary, speaks the PostgreSQL wire protocol directly, and prints JSON everywhere.

go install github.com/pgrundev/pggo/cmd/pggo@v0.0.1

Commands

ping · info · query (read-only) · exec · bench · help · version

Built for agents

• Every response is one line of deterministic JSON on stdout.
• Errors are structured: a fixed set of types, the PostgreSQL SQLSTATE, a retryable flag, and detail/hint/position.
• Queries take parameters via --param / --params. pggo checks the number of $N placeholders before connecting.
• query runs inside BEGIN READ ONLY … ROLLBACK, and each call accepts exactly one statement.
• Every command has a timeout, and on expiry pggo cancels the statement on the server.
• Output is bounded by default (100 rows / 64 KB), and truncation is always reported explicitly.
• TLS supports sslmode from disable to verify-full. Login supports SCRAM-SHA-256, MD5 and cleartext passwords.

Verified

• Integration tests pass on PostgreSQL 16, 17, 18 and 19beta1. The same suites run in CI, alongside the unit, protocol and fuzz tests.
• Agent tests: Claude Sonnet passed 6/6 tasks with no instructions beyond "pggo is installed".

	pggo	pgx v5 (minimal)	psql
binary	4.0 MB (1.7 MB gzip)	8.9 MB	0.7 MB + libpq
connect + SELECT 1, p50	8.5 ms	9.8 ms	23.9 ms
peak RSS	6.4 MiB	9.0 MiB	12.7 MiB

The benchmark ran on macOS arm64 against PostgreSQL 18 in Docker. Warm query latency is the same as pgx within noise.

Binaries

Binaries for Linux and macOS, amd64 and arm64, are statically linked. checksums.txt holds their SHA-256 hashes.