github.com/jackc/pgx/v5@v5.5.5/README.md (about)

     1  [![Go Reference](https://pkg.go.dev/badge/github.com/jackc/pgx/v5.svg)](https://pkg.go.dev/github.com/jackc/pgx/v5)
     2  [![Build Status](https://github.com/jackc/pgx/actions/workflows/ci.yml/badge.svg)](https://github.com/jackc/pgx/actions/workflows/ci.yml)
     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  ## Architecture
    90  
    91  See 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  
    95  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.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  
    99  pgx 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  
   105  pglogrepl provides functionality to act as a client for PostgreSQL logical replication.
   106  
   107  ### [github.com/jackc/pgmock](https://github.com/jackc/pgmock)
   108  
   109  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).
   110  
   111  ### [github.com/jackc/tern](https://github.com/jackc/tern)
   112  
   113  tern is a stand-alone SQL migration system.
   114  
   115  ### [github.com/jackc/pgerrcode](https://github.com/jackc/pgerrcode)
   116  
   117  pgerrcode 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  
   133  These 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  
   147  pgxmock is a mock library implementing pgx interfaces.
   148  pgxmock 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  
   152  Library for scanning data from a database into Go structs and more.
   153  
   154  ### [github.com/vingarcia/ksql](https://github.com/vingarcia/ksql)
   155  
   156  A carefully designed SQL client for making using SQL easier,
   157  more productive, and less error-prone on Golang.
   158  
   159  ### [https://github.com/otan/gopgkrb5](https://github.com/otan/gopgkrb5)
   160  
   161  Adds GSSAPI / Kerberos authentication support.
   162  
   163  ### [github.com/wcamarao/pmx](https://github.com/wcamarao/pmx)
   164  
   165  Explicit data mapping and scanning library for Go structs and slices.
   166  
   167  ### [github.com/stephenafamo/scan](https://github.com/stephenafamo/scan)
   168  
   169  Type safe and flexible package for scanning database data into Go types.
   170  Supports, structs, maps, slices and custom mapping functions.
   171  
   172  ### [https://github.com/z0ne-dev/mgx](https://github.com/z0ne-dev/mgx)
   173  
   174  Code first migration library for native pgx (no database/sql abstraction).