Repository files navigation

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 asLISTEN /NOTIFY andCOPY. It also includes an adapter for the standarddatabase/sql interface.

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

package mainimport ("context""fmt""os""github.com/jackc/pgx/v5")funcmain() {// urlExample := "postgres://username:password@localhost:5432/database_name"conn,err:=pgx.Connect(context.Background(),os.Getenv("DATABASE_URL"))iferr!=nil {fmt.Fprintf(os.Stderr,"Unable to connect to database: %v\n",err)os.Exit(1)}deferconn.Close(context.Background())varnamestringvarweightint64err=conn.QueryRow(context.Background(),"select name, weight from widgets where id=$1",42).Scan(&name,&weight)iferr!=nil {fmt.Fprintf(os.Stderr,"QueryRow failed: %v\n",err)os.Exit(1)}fmt.Println(name,weight)}

See thegetting started guide for more information.

• 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 andjsonb support
• Mapsinet andcidr PostgreSQL types tonetip.Addr andnetip.Prefix
• Large object support
• NULL mapping to pointer to pointer
• Supportsdatabase/sql.Scanner anddatabase/sql/driver.Valuer interfaces for custom types
• Notice response handling
• Simulated nested transactions with savepoints

The pgx interface is faster. Many PostgreSQL specific features such asLISTEN /NOTIFY andCOPY are not availablethrough thedatabase/sql interface.

The pgx interface is recommended when:

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

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

SeeCONTRIBUTING.md for setup instructions.

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

pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. ForGo that is the two most recent major releases and forPostgreSQL the major releases in the last 5 years. This means pgx supports Go 1.24 and higher and PostgreSQL 13 and higher. pgx also is tested against the latest version ofCockroachDB.

pgx follows semantic versioning for the documented public API on stable releases.v5 is the latest stable major version.

pglogrepl provides functionality to act as a client for PostgreSQL logical replication.

pgmock offers the ability to create a server that mocks the PostgreSQL wire protocol. This is used internally to test pgx by purposely inducing unusual errors. pgproto3 and pgmock together provide most of the foundational tooling required to implement a PostgreSQL proxy or MitM (such as for a custom connection pooler).

tern is a stand-alone SQL migration system.

pgerrcode contains constants for the PostgreSQL error codes.

• github.com/jackc/pgx-gofrs-uuid
• github.com/jackc/pgx-shopspring-decimal
• github.com/twpayne/pgx-geos (PostGIS andGEOS viago-geos)
• github.com/vgarvardt/pgx-google-uuid

• github.com/jackhopner/pgx-xray-tracer
• github.com/exaring/otelpgx

These adapters can be used with the tracelog package.

• github.com/jackc/pgx-go-kit-log
• github.com/jackc/pgx-log15
• github.com/jackc/pgx-logrus
• github.com/jackc/pgx-zap
• github.com/jackc/pgx-zerolog
• github.com/mcosta74/pgx-slog
• github.com/kataras/pgx-golog

pgxmock is a mock library implementing pgx interfaces.pgxmock has one and only purpose - to simulate pgx behavior in tests, without needing a real database connection.

Library for scanning data from a database into Go structs and more.

A carefully designed SQL client for making using SQL easier,more productive, and less error-prone on Golang.

Adds GSSAPI / Kerberos authentication support.

Explicit data mapping and scanning library for Go structs and slices.

Type safe and flexible package for scanning database data into Go types.Supports, structs, maps, slices and custom mapping functions.

Code first migration library for native pgx (no database/sql abstraction).

A database monitoring/metrics library for pgx and sqlc. Trace, log and monitor your sqlc query performance using OpenTelemetry.

Simple Golang implementation for transactional outbox pattern for PostgreSQL using jackc/pgx driver.

Simplifies working with the pgx library, providing convenient scanning of nested structures.

Implementation of the pgx query rewriter to use ':' instead of '@' in named query parameters.