pgx - PostgreSQL Driver and Toolkit

pgx is a pure Go driver and toolkit for PostgreSQL.

The pgx driver is a low-level, high performance interface that exposes PostgreSQL-specific features such as LISTEN / NOTIFY and COPY. It also includes an adapter for the standard database/sql interface.

The toolkit component is a related set of packages that implement PostgreSQL functionality such as parsing the wire protocol and type mapping between PostgreSQL and Go. These underlying packages can be used to implement alternative drivers, proxies, load balancers, logical replication clients, etc.

Quick Start

Installation

go get github.com/jackc/pgx/v5

Example Usage

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
)

func main() {
	// urlExample := "postgres://username:password@localhost:5432/database_name"
	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())

	var name string
	var weight int64
	err = conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
	if err != nil {
		fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Println(name, weight)
}

Connection Configuration

pgx.Connect and pgxpool.New accept PostgreSQL connection URLs (such as postgres://user:pass@host:5432/db?sslmode=verify-full) as well as key=value strings. See pgconn.ParseConfig and the PostgreSQL connection string documentation for supported options and environment variables.

For a step-by-step walkthrough, see the getting started guide.

Documentation

Package documentation and API reference are available on pkg.go.dev:

• pgx — base PostgreSQL driver
• pgxpool — concurrency-safe connection pool
• stdlib — database/sql compatibility adapter

Features

• Support for approximately 70 different PostgreSQL types
• Automatic statement preparation and caching
• Batch queries
• Single-round trip query mode
• Full TLS connection control
• Binary format support for custom types (allows for much quicker encoding/decoding)
• COPY protocol support for faster bulk data loads
• Tracing and logging support
• Connection pool with after-connect hook for arbitrary connection setup
• LISTEN / NOTIFY
• Conversion of PostgreSQL arrays to Go slice mappings for integers, floats, and strings
• hstore support
• json and jsonb support
• Maps inet and cidr PostgreSQL types to netip.Addr and netip.Prefix
• Large object support
• NULL mapping to pointer to pointer
• Supports database/sql.Scanner and database/sql/driver.Valuer interfaces for custom types
• Notice response handling
• Simulated nested transactions with savepoints

Choosing Between the pgx and database/sql Interfaces

The pgx interface is faster. Many PostgreSQL specific features such as LISTEN / NOTIFY and COPY are not available through the database/sql interface.

The pgx interface is recommended when:

1. The application only targets PostgreSQL.
2. No other libraries that require database/sql are in use.

It is also possible to use the database/sql interface and convert a connection to the lower-level pgx interface as needed.

Development and Testing

Each checkout has its own PostgreSQL 14-18 clusters and CockroachDB node, so the whole test matrix is available locally on macOS, on Linux, or in the included devcontainer. Only PostgreSQL 18 stays running by default; other targets start and stop around their tests:

scripts/setup-host # native macOS (Homebrew required) or Ubuntu: host packages and mise
export PATH="$HOME/.local/bin:$PATH" # if mise was just installed
mise trust
mise install        # project tools
mise run dev:init   # checkout ports and certificates
mise run dev        # start PostgreSQL 18 and the on-demand database supervisor
./test.sh           # the suite against PostgreSQL 18
./test.sh all       # every target, starting and stopping each server as needed

Host setup installs PostgreSQL 14-18 and Ruby build dependencies. It does not install project tools or initialize the checkout; those remain separate steps above. The devcontainer already provides the host prerequisites.

See DEVELOPMENT.md for the full setup, and CONTRIBUTING.md for how to contribute — including how to run the tests against a PostgreSQL server you already have, without any of the above.

Architecture

See the presentation at Golang Estonia, PGX Top to Bottom for a description of pgx architecture.

Supported Go and PostgreSQL Versions

pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. For Go that is the two most recent major releases and for PostgreSQL the major releases in the last 5 years. This means pgx supports Go 1.25 and higher and PostgreSQL 14 and higher. pgx also is tested against the latest version of CockroachDB.

This is the beginning of the README. Read the rest at the original. Read the full README ↗