1[](https://pkg.go.dev/github.com/jackc/pgx/v5)
2[](https://github.com/jackc/pgx/actions/workflows/ci.yml)
3
4# pgx - PostgreSQL Driver and Toolkit
5
6pgx is a pure Go driver and toolkit for PostgreSQL.
7
8The pgx driver is a low-level, high performance interface that exposes PostgreSQL-specific features such as `LISTEN` /
9`NOTIFY` and `COPY`. It also includes an adapter for the standard `database/sql` interface.
10
11The toolkit component is a related set of packages that implement PostgreSQL functionality such as parsing the wire protocol
12and type mapping between PostgreSQL and Go. These underlying packages can be used to implement alternative drivers,
13proxies, load balancers, logical replication clients, etc.
14
15## Example Usage
16
17```go
18package main
19
20import (
21 "context"
22 "fmt"
23 "os"
24
25 "github.com/jackc/pgx/v5"
26)
27
28func main() {
29 // urlExample := "postgres://username:password@localhost:5432/database_name"
30 conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
31 if err != nil {
32 fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
33 os.Exit(1)
34 }
35 defer conn.Close(context.Background())
36
37 var name string
38 var weight int64
39 err = conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
40 if err != nil {
41 fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err)
42 os.Exit(1)
43 }
44
45 fmt.Println(name, weight)
46}
47```
48
49See the [getting started guide](https://github.com/jackc/pgx/wiki/Getting-started-with-pgx) for more information.
50
51## Features
52
53* Support for approximately 70 different PostgreSQL types
54* Automatic statement preparation and caching
55* Batch queries
56* Single-round trip query mode
57* Full TLS connection control
58* Binary format support for custom types (allows for much quicker encoding/decoding)
59* `COPY` protocol support for faster bulk data loads
60* Tracing and logging support
61* Connection pool with after-connect hook for arbitrary connection setup
62* `LISTEN` / `NOTIFY`
63* Conversion of PostgreSQL arrays to Go slice mappings for integers, floats, and strings
64* `hstore` support
65* `json` and `jsonb` support
66* Maps `inet` and `cidr` PostgreSQL types to `netip.Addr` and `netip.Prefix`
67* Large object support
68* NULL mapping to pointer to pointer
69* Supports `database/sql.Scanner` and `database/sql/driver.Valuer` interfaces for custom types
70* Notice response handling
71* Simulated nested transactions with savepoints
72
73## Choosing Between the pgx and database/sql Interfaces
74
75The pgx interface is faster. Many PostgreSQL specific features such as `LISTEN` / `NOTIFY` and `COPY` are not available
76through the `database/sql` interface.
77
78The pgx interface is recommended when:
79
801. The application only targets PostgreSQL.
812. No other libraries that require `database/sql` are in use.
82
83It is also possible to use the `database/sql` interface and convert a connection to the lower-level pgx interface as needed.
84
85## Testing
86
87See CONTRIBUTING.md for setup instructions.
88
89## Architecture
90
91See the presentation at Golang Estonia, [PGX Top to Bottom](https://www.youtube.com/watch?v=sXMSWhcHCf8) for a description of pgx architecture.
92
93## Supported Go and PostgreSQL Versions
94
95pgx supports the same versions of Go and PostgreSQL that are supported by their respective teams. For [Go](https://golang.org/doc/devel/release.html#policy) that is the two most recent major releases and for [PostgreSQL](https://www.postgresql.org/support/versioning/) the major releases in the last 5 years. This means pgx supports Go 1.20 and higher and PostgreSQL 12 and higher. pgx also is tested against the latest version of [CockroachDB](https://www.cockroachlabs.com/product/).
96
97## Version Policy
98
99pgx follows semantic versioning for the documented public API on stable releases. `v5` is the latest stable major version.
100
101## PGX Family Libraries
102
103### [github.com/jackc/pglogrepl](https://github.com/jackc/pglogrepl)
104
105pglogrepl provides functionality to act as a client for PostgreSQL logical replication.
106
107### [github.com/jackc/pgmock](https://github.com/jackc/pgmock)
108
109pgmock 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).
110
111### [github.com/jackc/tern](https://github.com/jackc/tern)
112
113tern is a stand-alone SQL migration system.
114
115### [github.com/jackc/pgerrcode](https://github.com/jackc/pgerrcode)
116
117pgerrcode contains constants for the PostgreSQL error codes.
118
119## Adapters for 3rd Party Types
120
121* [github.com/jackc/pgx-gofrs-uuid](https://github.com/jackc/pgx-gofrs-uuid)
122* [github.com/jackc/pgx-shopspring-decimal](https://github.com/jackc/pgx-shopspring-decimal)
123* [github.com/twpayne/pgx-geos](https://github.com/twpayne/pgx-geos) ([PostGIS](https://postgis.net/) and [GEOS](https://libgeos.org/) via [go-geos](https://github.com/twpayne/go-geos))
124* [github.com/vgarvardt/pgx-google-uuid](https://github.com/vgarvardt/pgx-google-uuid)
125
126
127## Adapters for 3rd Party Tracers
128
129* [https://github.com/jackhopner/pgx-xray-tracer](https://github.com/jackhopner/pgx-xray-tracer)
130
131## Adapters for 3rd Party Loggers
132
133These adapters can be used with the tracelog package.
134
135* [github.com/jackc/pgx-go-kit-log](https://github.com/jackc/pgx-go-kit-log)
136* [github.com/jackc/pgx-log15](https://github.com/jackc/pgx-log15)
137* [github.com/jackc/pgx-logrus](https://github.com/jackc/pgx-logrus)
138* [github.com/jackc/pgx-zap](https://github.com/jackc/pgx-zap)
139* [github.com/jackc/pgx-zerolog](https://github.com/jackc/pgx-zerolog)
140* [github.com/mcosta74/pgx-slog](https://github.com/mcosta74/pgx-slog)
141* [github.com/kataras/pgx-golog](https://github.com/kataras/pgx-golog)
142
143## 3rd Party Libraries with PGX Support
144
145### [github.com/pashagolub/pgxmock](https://github.com/pashagolub/pgxmock)
146
147pgxmock is a mock library implementing pgx interfaces.
148pgxmock has one and only purpose - to simulate pgx behavior in tests, without needing a real database connection.
149
150### [github.com/georgysavva/scany](https://github.com/georgysavva/scany)
151
152Library for scanning data from a database into Go structs and more.
153
154### [github.com/vingarcia/ksql](https://github.com/vingarcia/ksql)
155
156A carefully designed SQL client for making using SQL easier,
157more productive, and less error-prone on Golang.
158
159### [https://github.com/otan/gopgkrb5](https://github.com/otan/gopgkrb5)
160
161Adds GSSAPI / Kerberos authentication support.
162
163### [github.com/wcamarao/pmx](https://github.com/wcamarao/pmx)
164
165Explicit data mapping and scanning library for Go structs and slices.
166
167### [github.com/stephenafamo/scan](https://github.com/stephenafamo/scan)
168
169Type safe and flexible package for scanning database data into Go types.
170Supports, structs, maps, slices and custom mapping functions.
171
172### [https://github.com/z0ne-dev/mgx](https://github.com/z0ne-dev/mgx)
173
174Code first migration library for native pgx (no database/sql abstraction).
View as plain text