pgx v4

pgx is a pure Go driver and toolkit for PostgreSQL that aims to be low-level, fast, and performant while exposing PostgreSQL-specific features the standard database/sql package leaves out. This v4 release requires Go modules and is the previous stable major version, kept alive for existing projects that have not yet migrated to v5.

The driver can be used directly through its native interface for maximum speed, or through the bundled stdlib compatibility layer to work as a conventional database/sql driver while still allowing the native interface to be reclaimed for performance-sensitive code paths. Around 70 PostgreSQL types are supported, along with automatic statement preparation and caching, batch queries, full TLS control, LISTEN/NOTIFY, COPY protocol bulk loads, and large object support.

pgx v4 is the head of a small family of decoupled libraries: pgconn handles the low-level wire protocol, pgtype implements the PostgreSQL type system, and pgxpool (bundled in this repo) provides a concurrency-safe connection pool that sits entirely outside the core driver, so pgx can be used with a different pool implementation or none at all.

What You Get

• A native Postgres driver (pgx.Connect, Query, Exec) that uses the binary wire format for faster encoding/decoding than text-based drivers
• A database/sql-compatible layer (stdlib) so pgx can be dropped into existing code that expects the standard interface
• pgxpool, a bundled concurrency-safe connection pool with an after-connect hook for per-connection setup
• Support for roughly 70 PostgreSQL types, including arrays, hstore, JSON/JSONB, inet/cidr, and large objects
• Batch query support and a single-round-trip query mode to cut network overhead
• COPY protocol support for high-throughput bulk data loads
• LISTEN/NOTIFY support and simulated nested transactions via savepoints
• Pluggable logging adapters for log15, logrus, zap, and zerolog

Common Use Cases

• Building a Postgres-backed Go service that needs more throughput than database/sql’s text-based scanning provides
• Migrating an existing database/sql codebase onto pgx incrementally via the stdlib compatibility layer
• Running high-volume bulk imports or exports through the COPY protocol instead of row-by-row inserts
• Implementing pub/sub-style notifications inside Postgres using LISTEN/NOTIFY
• Managing a pool of Postgres connections with custom per-connection setup via pgxpool’s after-connect hook
• Working directly with advanced PostgreSQL types (arrays, hstore, JSON, network types) without hand-rolled marshaling

Under The Hood

Architecture pgx v4 is organized as a thin core driver (conn.go, rows.go, tx.go, batch.go at the module root) layered directly on top of the lower-level pgconn and pgproto3 packages, which handle connection establishment and PostgreSQL’s binary wire protocol respectively; ConnConfig embeds pgconn.Config and is produced by ParseConfig before being handed to ConnectConfig, keeping connection setup and connection use as separate concerns. Type encoding/decoding is delegated entirely to the sibling pgtype package rather than implemented inline, and the connection pool (pgxpool/) and database/sql compatibility shim (stdlib/) are both separate, decoupled subpackages that consume the core pgx.Conn rather than being baked into it — so a caller can use the pool, the stdlib shim, both, or neither. This separation means the core driver has no opinion about pooling strategy, and swapping in a different pool implementation touches nothing in the driver itself.

Tech Stack The module (module github.com/jackc/pgx/v4, Go 1.17) depends on a family of sibling jackc packages for protocol- and type-level work — pgconn, pgproto3/v2, pgtype, pgio, pgpassfile, pgservicefile, and the puddle pooling primitive used inside pgxpool — plus github.com/cockroachdb/apd for arbitrary-precision decimals and github.com/shopspring/decimal for a second decimal representation. Structured logging is pluggable via adapters over go-kit/log, sirupsen/logrus, uber-go/zap, rs/zerolog, and log15, none of which are hard dependencies of the core driver. There is no ORM or build tooling beyond the Go toolchain itself; deployment is simply go get, and CI (GitHub Actions) runs the suite against real Postgres versions 10 through 14 plus CockroachDB.

Code Quality Testing is extensive and integration-first: root-level _test.go files (conn_test.go, query_test.go, values_test.go, tx_test.go, copy_from_test.go, batch_test.go) run against a live PostgreSQL instance rather than mocks, and CI’s matrix runs the full suite with the Go race detector (go test -race ./...) across two Go versions and five Postgres targets, including CockroachDB, giving real cross-version and cross-database compatibility coverage. Error handling favors explicit returned errors over panics throughout the public API, and the Rows result type is deliberately defined as an interface (rather than a concrete struct) specifically so tests can mock query behavior. Naming is consistent with Go conventions and the package is fully godoc-commented; there’s no separate linter config beyond go vet/gofmt conventions enforced by CI.

API Design pgx v4’s public surface mirrors database/sql’s Query/Scan idiom closely enough that a Go developer already familiar with the standard library can be productive immediately, while adding pgx-specific extensions (batch queries, COPY, LISTEN/NOTIFY) as opt-in additions rather than replacements. The doc.go package documentation walks through connection setup, pooling, and querying in order with runnable code samples, and the bundled examples/ directory (chat, todo, url_shortener) demonstrates realistic application usage rather than toy snippets, keeping the ramp-up cost low despite the driver’s larger feature set than database/sql.