pq

lib/pq is a mature, pure-Go PostgreSQL driver that plugs directly into Go’s standard library database/sql interface. Registering it with a blank import lets you open a postgres connection and run queries with the same API you would use for any other SQL database, with no cgo or external C bindings required.

Beyond the basics it covers the parts of the PostgreSQL wire protocol that real applications need: TLS/SSL connections, PASSWORD/MD5/SCRAM-SHA-256 (and optional Kerberos) authentication, high-throughput COPY FROM STDIN bulk imports, asynchronous LISTEN/NOTIFY notifications, array and hstore type support, and libpq-compatible connection strings in both key=value and URL form.

What You Get

• A drop-in postgres driver for database/sql, registered with a single blank import.
• libpq-compatible connection strings in key=value and postgres:// URL form, including any run-time parameter.
• Built-in TLS/SSL plus PASSWORD, MD5, and SCRAM-SHA-256 authentication (Kerberos via a separate module).
• Bulk data loading through COPY FROM STDIN and asynchronous LISTEN/NOTIFY via pq.Listener.
• Rich typed error values (pq.Error) exposing SQLSTATE codes, detail, hint, and source context.

Common Use Cases

• Connecting a Go web service or API server to a PostgreSQL database through database/sql.
• Streaming large datasets into PostgreSQL efficiently with COPY bulk imports.
• Building event-driven features on top of PostgreSQL LISTEN/NOTIFY notifications.
• Handling PostgreSQL-specific errors precisely by inspecting SQLSTATE codes.

Under The Hood

Architecture — pq is organized as a flat root package implementing the database/sql/driver contract, with conn.go handling the connection lifecycle and message loop, connector.go exposing the modern driver.Connector/Config path, copy.go implementing COPY-protocol streaming, notify.go providing the pq.Listener notification loop, and encode.go/array.go handling type encoding; supporting concerns are split into subpackages such as oid (type OIDs), scram (SCRAM-SHA-256), pqerror (SQLSTATE codes), hstore, and auth/kerberos, keeping optional dependencies out of the core.

Tech Stack — Written in pure Go (targeting go 1.23 per go.mod) with zero third-party runtime dependencies, relying solely on the standard library’s database/sql, crypto/tls, and net packages to speak the PostgreSQL wire protocol directly rather than binding to libpq via cgo.

Code Quality — The project is well tested, with 17 _test.go files covering connections, the connector, arrays, encoding, errors, COPY, SSL, and notifications, plus fuzz tests and runnable examples; tests execute against a real PostgreSQL instance (Docker compose provided) and the codebase carries typed error values and extensive doc comments.

API Design — The public surface is intentionally minimal and idiomatic: most users interact only through database/sql after a blank import, with pq.Config/NewConnectorConfig, pq.Listener, and pq.Error available for advanced needs. Package-level documentation in doc.go is thorough, and the libpq-compatible connection strings make the driver approachable for anyone familiar with PostgreSQL.