# pgx: The Pure Go PostgreSQL Driver and Toolkit

> pgx is a low-level, high-performance Go driver for PostgreSQL that exposes database-specific features like LISTEN/NOTIFY and COPY that the standard database/sql interface cannot reach. It also ships a toolkit of lower-level packages for building proxies, load balancers, and logical replication clients.

**jackc/pgx** — PostgreSQL driver and toolkit for Go

- Repository: https://github.com/jackc/pgx
- Website: https://pkg.go.dev/github.com/jackc/pgx/v5
- Stars: 14,280 · Forks: 1,130
- Language: Go
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/jackc-pgx

## What pgx Is and Who It Targets

pgx is a pure Go driver and toolkit for PostgreSQL. It is aimed at Go developers who want direct access to PostgreSQL's wire protocol and type system rather than the abstraction layer provided by the standard database/sql interface. The README describes the driver as low-level and high-performance and notes that it exposes PostgreSQL-specific features such as LISTEN/NOTIFY and COPY that the database/sql interface cannot reach.

The toolkit side of pgx is a set of lower-level packages that implement the PostgreSQL wire protocol parsing and type mapping. These packages are designed to be reused outside of the driver itself: the README lists alternative drivers, proxies, load balancers, and logical replication clients as intended uses. The pgconn and pgproto3 subpackages implement the low-level transport and protocol layers respectively, while pgtype handles the mapping between PostgreSQL types and Go values.

The current stable version is v5, available as `github.com/jackc/pgx/v5`. Semantic versioning applies to the documented public API. The module file specifies `go 1.25.0` as the minimum Go version.

## Connecting to PostgreSQL and Running a First Query

pgx supports both PostgreSQL URL strings and `key=value` connection strings. The README shows a URL in the form `postgres://username:password@localhost:5432/database_name`. The `pgconn.ParseConfig` function handles all supported connection options including SSL mode.

Install the module with:

```bash
go get github.com/jackc/pgx/v5
```

The following example from the README opens a connection and runs a parameterized query:

```go
conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
    fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
    os.Exit(1)
}
defer conn.Close(context.Background())
```

The `DATABASE_URL` environment variable holds the connection string. The connection is a single, non-pooled connection. For applications that need concurrent database access, the `pgxpool` subpackage provides a concurrency-safe connection pool with an after-connect hook for arbitrary connection setup per newly created connection.

## Type Support and Binary Encoding

pgx maps approximately 70 PostgreSQL types to Go equivalents. The mapping covers standard types, arrays (converted to Go slices for integers, floats, and strings), composite types, and PostgreSQL-specific types including hstore, json, jsonb, inet, cidr, and large objects. The `inet` and `cidr` types map to Go's `netip.Addr` and `netip.Prefix` types from the standard library.

The binary format option is one of the practical performance advantages pgx offers over drivers that always use text encoding. Binary encoding bypasses the ASCII serialization and deserialization steps for numeric and binary types, which the README describes as allowing for much quicker encoding/decoding for custom types.

The pgtype package also implements the `database/sql.Scanner` and `database/sql/driver.Valuer` interfaces, so custom types written for database/sql will work with pgx without modification. NULL values map to pointer-to-pointer patterns rather than requiring a separate nullable wrapper type.

## Batch Queries, COPY, and LISTEN/NOTIFY

Three capabilities distinguish pgx from drivers that only implement the database/sql surface: batch queries, the COPY protocol, and LISTEN/NOTIFY.

Batch queries group multiple statements into a single round trip. The batch.go file in the repository implements this. The README notes single-round-trip query mode as a separate feature alongside full batch support. Together these reduce latency for workloads that issue many small queries.

The COPY protocol is PostgreSQL's bulk data loading mechanism. pgx exposes it via copy_from.go. The README lists COPY protocol support for faster bulk data loads as a named feature. This is relevant for ETL pipelines or seeding large tables where individual INSERT statements would be impractical.

LISTEN and NOTIFY are PostgreSQL's pub/sub mechanism that operates over the database connection. The database/sql interface has no provision for long-running notification listeners, which requires keeping a connection open and waiting asynchronously. pgx supports this natively. The README names LISTEN/NOTIFY as one of the features unavailable through database/sql, making it a firm reason to choose the native pgx interface over the adapter.

## Choosing Between the Native pgx Interface and the database/sql Adapter

The README is direct about the trade-off: the pgx interface is faster, and PostgreSQL-specific features including LISTEN/NOTIFY and COPY are not available through the database/sql interface. The native interface is recommended when the application targets only PostgreSQL and no other libraries in the project require database/sql.

The stdlib adapter in the `pgx/v5/stdlib` package allows pgx to satisfy the `database/sql` interface. This is the path for projects that use ORMs or query builders that expect a `*sql.DB`. The adapter also allows upgrading a `*sql.DB` connection to the lower-level pgx connection interface when needed, which means you can opt into specific pgx features for a single operation without redesigning the rest of the application.

The pgxpool package is separate from pgx.Connect. A pool is required for concurrent access because a single pgx connection is not safe to use from multiple goroutines. The pool accepts the same connection string formats as pgx.Connect and exposes hooks for running initialization code on each new connection.

## The pgx Family: Migration, Mocking, and Logical Replication

The README documents several companion libraries. pglogrepl provides a client for PostgreSQL logical replication, which is the protocol underlying change data capture systems. It is a separate module at `github.com/jackc/pglogrepl`.

pgmock creates a server that simulates the PostgreSQL wire protocol, used internally to test pgx by inducing unusual error conditions. The README notes that pgproto3 and pgmock together cover most of the tooling needed for a PostgreSQL proxy or man-in-the-middle connection pooler.

tern is a standalone SQL migration system at `github.com/jackc/tern`. It handles schema versioning separate from any application framework. pgerrcode provides Go constants for all PostgreSQL error codes, which is useful for error handling that needs to distinguish specific database errors by code rather than by string matching.

The main pgx repository also lists adapters for third-party Go types: `pgx-gofrs-uuid` for UUID handling and `pgx-shopspring-decimal` for arbitrary-precision decimal values. These are maintained separately from pgx itself.

## Supported Versions, Testing Infrastructure, and License

pgx supports the same Go and PostgreSQL versions as their respective upstream projects. At the time of the last push on 2026-09-28, the README states support for Go 1.25 and higher, and PostgreSQL 14 and higher. The test suite also runs against CockroachDB.

The development setup uses PostgreSQL clusters spanning versions 14 through 18. The README describes a mise-based setup that keeps each checkout self-contained: `mise run dev:init` initializes ports and certificates, and `mise run dev` starts PostgreSQL 18 along with an on-demand database supervisor. The `./test.sh all` command runs the full matrix against all supported targets.

The license is MIT. There are no restrictions on commercial use, redistribution, or embedding in proprietary software. The module path is `github.com/jackc/pgx/v5`, and the go.mod specifies the minimum required Go version for the module's language features.

## Conclusion

pgx is the right driver for Go applications that target PostgreSQL exclusively and need low-level access: LISTEN/NOTIFY, COPY bulk loads, binary type encoding, or logical replication. Teams already committed to the database/sql interface can adopt pgx incrementally through its stdlib adapter, which allows a connection to be promoted to the native pgx interface when needed. The database/sql adapter is a concession point: the faster path and the PostgreSQL-specific features are only available through the native pgx interface. Before adopting, verify that your PostgreSQL version is 14 or newer and your Go version is 1.25 or higher. The MIT license permits commercial use without restriction.

## FAQ

### What is pgx in Go?

pgx is a pure Go driver and toolkit for PostgreSQL. It provides a low-level, high-performance interface with direct access to PostgreSQL-specific features like LISTEN/NOTIFY and COPY, plus a database/sql-compatible adapter for projects that need standard interface compatibility.

### What is pgx for PostgreSQL?

pgx is the driver that handles the connection between a Go application and a PostgreSQL database. It parses the wire protocol, maps approximately 70 PostgreSQL types to Go equivalents, and exposes capabilities like batch queries, binary type encoding, and the COPY bulk-load protocol.

### How can I connect to PostgreSQL using Go?

With pgx, call pgx.Connect(ctx, os.Getenv("DATABASE_URL")) where DATABASE_URL is a PostgreSQL connection URL such as postgres://user:pass@host:5432/db. For concurrent access, use pgxpool.New instead, which creates a connection pool safe for use across multiple goroutines.

### What is github.com/jackc/pgx/v5?

github.com/jackc/pgx/v5 is the Go module path for the current stable major version of pgx. Install it with go get github.com/jackc/pgx/v5. It includes the base driver, pgxpool for connection pooling, stdlib for database/sql compatibility, and the lower-level pgconn, pgproto3, and pgtype packages.

## Sources

- [jackc/pgx on GitHub](https://github.com/jackc/pgx)
- [License: MIT](https://github.com/jackc/pgx/blob/master/LICENSE)
- [Project website](https://pkg.go.dev/github.com/jackc/pgx/v5)
- [README](https://github.com/jackc/pgx/blob/master/README.md)
- [Releases](https://github.com/jackc/pgx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jackc-pgx