README.md (6689B)
1 [](https://pkg.go.dev/github.com/jackc/pgx/v5) 2  3 4 # pgx - PostgreSQL Driver and Toolkit 5 6 pgx is a pure Go driver and toolkit for PostgreSQL. 7 8 The 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 11 The toolkit component is a related set of packages that implement PostgreSQL functionality such as parsing the wire protocol 12 and type mapping between PostgreSQL and Go. These underlying packages can be used to implement alternative drivers, 13 proxies, load balancers, logical replication clients, etc. 14 15 ## Example Usage 16 17 ```go 18 package main 19 20 import ( 21 "context" 22 "fmt" 23 "os" 24 25 "github.com/jackc/pgx/v5" 26 ) 27 28 func 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 49 See 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 75 The pgx interface is faster. Many PostgreSQL specific features such as `LISTEN` / `NOTIFY` and `COPY` are not available 76 through the `database/sql` interface. 77 78 The pgx interface is recommended when: 79 80 1. The application only targets PostgreSQL. 81 2. No other libraries that require `database/sql` are in use. 82 83 It 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 87 See CONTRIBUTING.md for setup instructions. 88 89 ## Supported Go and PostgreSQL Versions 90 91 pgx 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.19 and higher and PostgreSQL 11 and higher. pgx also is tested against the latest version of [CockroachDB](https://www.cockroachlabs.com/product/). 92 93 ## Version Policy 94 95 pgx follows semantic versioning for the documented public API on stable releases. `v5` is the latest stable major version. 96 97 ## PGX Family Libraries 98 99 ### [github.com/jackc/pglogrepl](https://github.com/jackc/pglogrepl) 100 101 pglogrepl provides functionality to act as a client for PostgreSQL logical replication. 102 103 ### [github.com/jackc/pgmock](https://github.com/jackc/pgmock) 104 105 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). 106 107 ### [github.com/jackc/tern](https://github.com/jackc/tern) 108 109 tern is a stand-alone SQL migration system. 110 111 ### [github.com/jackc/pgerrcode](https://github.com/jackc/pgerrcode) 112 113 pgerrcode contains constants for the PostgreSQL error codes. 114 115 ## Adapters for 3rd Party Types 116 117 * [github.com/jackc/pgx-gofrs-uuid](https://github.com/jackc/pgx-gofrs-uuid) 118 * [github.com/jackc/pgx-shopspring-decimal](https://github.com/jackc/pgx-shopspring-decimal) 119 * [github.com/vgarvardt/pgx-google-uuid](https://github.com/vgarvardt/pgx-google-uuid) 120 121 122 ## Adapters for 3rd Party Tracers 123 124 * [https://github.com/jackhopner/pgx-xray-tracer](https://github.com/jackhopner/pgx-xray-tracer) 125 126 ## Adapters for 3rd Party Loggers 127 128 These adapters can be used with the tracelog package. 129 130 * [github.com/jackc/pgx-go-kit-log](https://github.com/jackc/pgx-go-kit-log) 131 * [github.com/jackc/pgx-log15](https://github.com/jackc/pgx-log15) 132 * [github.com/jackc/pgx-logrus](https://github.com/jackc/pgx-logrus) 133 * [github.com/jackc/pgx-zap](https://github.com/jackc/pgx-zap) 134 * [github.com/jackc/pgx-zerolog](https://github.com/jackc/pgx-zerolog) 135 * [github.com/mcosta74/pgx-slog](https://github.com/mcosta74/pgx-slog) 136 137 ## 3rd Party Libraries with PGX Support 138 139 ### [github.com/pashagolub/pgxmock](https://github.com/pashagolub/pgxmock) 140 141 pgxmock is a mock library implementing pgx interfaces. 142 pgxmock has one and only purpose - to simulate pgx behavior in tests, without needing a real database connection. 143 144 ### [github.com/georgysavva/scany](https://github.com/georgysavva/scany) 145 146 Library for scanning data from a database into Go structs and more. 147 148 ### [github.com/vingarcia/ksql](https://github.com/vingarcia/ksql) 149 150 A carefully designed SQL client for making using SQL easier, 151 more productive, and less error-prone on Golang. 152 153 ### [https://github.com/otan/gopgkrb5](https://github.com/otan/gopgkrb5) 154 155 Adds GSSAPI / Kerberos authentication support. 156 157 ### [github.com/wcamarao/pmx](https://github.com/wcamarao/pmx) 158 159 Explicit data mapping and scanning library for Go structs and slices. 160 161 ### [github.com/stephenafamo/scan](https://github.com/stephenafamo/scan) 162 163 Type safe and flexible package for scanning database data into Go types. 164 Supports, structs, maps, slices and custom mapping functions. 165 166 ### [https://github.com/z0ne-dev/mgx](https://github.com/z0ne-dev/mgx) 167 168 Code first migration library for native pgx (no database/sql abstraction).