README

Build Status

pgx - PostgreSQL Driver and Toolkit

pgx is a pure Go driver and toolkit for PostgreSQL.

pgx aims to be low-level, fast, and performant, while also enabling PostgreSQL-specific features that the standard database/sql package does not allow for.

The driver component of pgx can be used alongside the standard database/sql package.

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.

The current release of pgx v4 requires Go modules. To use the previous version, checkout and vendor the v3 branch.

Example Usage

package main

import (
	"context"
	"fmt"
	"os"

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

func main() {
	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)
}

See the getting started guide for more information.

Choosing Between the pgx and database/sql Interfaces

It is recommended to use the pgx interface if:

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

The pgx interface is faster and exposes more features.

The database/sql interface only allows the underlying driver to return or receive the following types: int64, float64, bool, []byte, string, time.Time, or nil. Handling other types requires implementing the database/sql.Scanner and the database/sql/driver/driver.Valuer interfaces which require transmission of values in text format. The binary format can be substantially faster, which is what the pgx interface uses.

Features

pgx supports many features beyond what is available through database/sql:

  • 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
  • Extendable logging support including built-in support for log15adapter, logrus, zap, and zerolog
  • 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 net.IPNet and net.IP
  • Large object support
  • NULL mapping to Null* struct or pointer to pointer
  • Supports database/sql.Scanner and database/sql/driver.Valuer interfaces for custom types
  • Notice response handling
  • Simulated nested transactions with savepoints

Performance

There are three areas in particular where pgx can provide a significant performance advantage over the standard database/sql interface and other drivers:

  1. PostgreSQL specific types - Types such as arrays can be parsed much quicker because pgx uses the binary format.
  2. Automatic statement preparation and caching - pgx will prepare and cache statements by default. This can provide an significant free improvement to code that does not explicitly use prepared statements. Under certain workloads, it can perform nearly 3x the number of queries per second.
  3. Batched queries - Multiple queries can be batched together to minimize network round trips.

Comparison with Alternatives

For prepared queries with small sets of simple data types, all drivers will have have similar performance. However, if prepared statements aren't being explicitly used, pgx can have a significant performance advantage due to automatic statement preparation. pgx also can perform better when using PostgreSQL-specific data types or query batching. See go_db_bench for some database driver benchmarks.

Compatibility with database/sql

pq is exclusively used with database/sql. go-pg does not use database/sql at all. pgx supports database/sql as well as its own interface.

Level of access, ORM

go-pg is a PostgreSQL client and ORM. It includes many features that traditionally sit above the database driver, such as ORM, struct mapping, soft deletes, schema migrations, and sharding support.

pgx is "closer to the metal" and such abstractions are beyond the scope of the pgx project, which first and foremost, aims to be a performant driver and toolkit.

Testing

pgx tests naturally require a PostgreSQL database. It will connect to the database specified in the PGX_TEST_DATABASE environment variable. The PGX_TEST_DATABASE environment variable can either be a URL or DSN. In addition, the standard PG* environment variables will be respected. Consider using direnv to simplify environment variable handling.

Example Test Environment

Connect to your PostgreSQL server and run:

create database pgx_test;

Connect to the newly-created database and run:

create domain uint64 as numeric(20,0);

Now, you can run the tests:

PGX_TEST_DATABASE="host=/var/run/postgresql database=pgx_test" go test ./...

In addition, there are tests specific for PgBouncer that will be executed if PGX_TEST_PGBOUNCER_CONN_STRING is set.

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.13 and higher and PostgreSQL 9.5 and higher.

Version Policy

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

PGX Family Libraries

pgx is the head of a family of PostgreSQL libraries. Many of these can be used independently. Many can also be accessed from pgx for lower-level control.

github.com/jackc/pgconn

pgconn is a lower-level PostgreSQL database driver that operates at nearly the same level as the C library libpq.

github.com/jackc/pgx/v4/pgxpool

pgxpool is a connection pool for pgx. pgx is entirely decoupled from its default pool implementation. This means that pgx can be used with a different pool. or without any pool at all.

github.com/jackc/pgx/v4/stdlib

This is a database/sql compatibility layer for pgx. pgx can be used as a normal database/sql driver, but at any time, the native interface can be acquired for more performance or PostgreSQL specific functionality.

github.com/jackc/pgtype

Over 70 PostgreSQL types are supported including uuid, hstore, json, bytea, numeric, interval, inet, and arrays. These types support database/sql interfaces and are usable outside of pgx. They are fully tested in pgx and pq. They also support a higher performance interface when used with the pgx driver.

github.com/jackc/pgproto3

pgproto3 provides standalone encoding and decoding of the PostgreSQL v3 wire protocol. This is useful for implementing very low level PostgreSQL tooling.

github.com/jackc/pglogrepl

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

github.com/jackc/pgmock

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).

github.com/jackc/tern

tern is a stand-alone SQL migration system.

github.com/jackc/pgerrcode

pgerrcode contains constants for the PostgreSQL error codes.

3rd Party Libraries with PGX Support

github.com/georgysavva/scany

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

Documentation

Overview

Package pgx is a PostgreSQL database driver.

pgx provides lower level access to PostgreSQL than the standard database/sql. It remains as similar to the database/sql interface as possible while providing better speed and access to PostgreSQL specific features. Import github.com/jackc/pgx/v4/stdlib to use pgx as a database/sql compatible driver.

Establishing a Connection

The primary way of establishing a connection is with `pgx.Connect`.

conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))

The database connection string can be in URL or DSN format. Both PostgreSQL settings and pgx settings can be specified here. In addition, a config struct can be created by `ParseConfig` and modified before establishing the connection with `ConnectConfig`.

config, err := pgx.ParseConfig(os.Getenv("DATABASE_URL"))
if err != nil {
    // ...
}
config.Logger = log15adapter.NewLogger(log.New("module", "pgx"))

conn, err := pgx.ConnectConfig(context.Background(), config)

Connection Pool

`*pgx.Conn` represents a single connection to the database and is not concurrency safe. Use sub-package pgxpool for a concurrency safe connection pool.

Query Interface

pgx implements Query and Scan in the familiar database/sql style.

var sum int32

// Send the query to the server. The returned rows MUST be closed
// before conn can be used again.
rows, err := conn.Query(context.Background(), "select generate_series(1,$1)", 10)
if err != nil {
    return err
}

// rows.Close is called by rows.Next when all rows are read
// or an error occurs in Next or Scan. So it may optionally be
// omitted if nothing in the rows.Next loop can panic. It is
// safe to close rows multiple times.
defer rows.Close()

// Iterate through the result set
for rows.Next() {
    var n int32
    err = rows.Scan(&n)
    if err != nil {
        return err
    }
    sum += n
}

// Any errors encountered by rows.Next or rows.Scan will be returned here
if rows.Err() != nil {
    return rows.Err()
}

// No errors found - do something with sum

pgx also implements QueryRow in the same style as database/sql.

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 {
    return err
}

Use Exec to execute a query that does not return a result set.

commandTag, err := conn.Exec(context.Background(), "delete from widgets where id=$1", 42)
if err != nil {
    return err
}
if commandTag.RowsAffected() != 1 {
    return errors.New("No row found to delete")
}

Base Type Mapping

pgx maps between all common base types directly between Go and PostgreSQL. In particular:

Go           PostgreSQL
-----------------------
string       varchar
             text

// Integers are automatically be converted to any other integer type if
// it can be done without overflow or underflow.
int8
int16        smallint
int32        int
int64        bigint
int
uint8
uint16
uint32
uint64
uint

// Floats are strict and do not automatically convert like integers.
float32      float4
float64      float8

time.Time   date
            timestamp
            timestamptz

[]byte      bytea

Null Mapping

pgx can map nulls in two ways. The first is package pgtype provides types that have a data field and a status field. They work in a similar fashion to database/sql. The second is to use a pointer to a pointer.

var foo pgtype.Varchar
var bar *string
err := conn.QueryRow("select foo, bar from widgets where id=$1", 42).Scan(&foo, &bar)
if err != nil {
    return err
}

Array Mapping

pgx maps between int16, int32, int64, float32, float64, and string Go slices and the equivalent PostgreSQL array type. Go slices of native types do not support nulls, so if a PostgreSQL array that contains a null is read into a native Go slice an error will occur. The pgtype package includes many more array types for PostgreSQL types that do not directly map to native Go types.

JSON and JSONB Mapping

pgx includes built-in support to marshal and unmarshal between Go types and the PostgreSQL JSON and JSONB.

Inet and CIDR Mapping

pgx encodes from net.IPNet to and from inet and cidr PostgreSQL types. In addition, as a convenience pgx will encode from a net.IP; it will assume a /32 netmask for IPv4 and a /128 for IPv6.

Custom Type Support

pgx includes support for the common data types like integers, floats, strings, dates, and times that have direct mappings between Go and SQL. In addition, pgx uses the github.com/jackc/pgx/pgtype library to support more types. See documention for that library for instructions on how to implement custom types.

See example_custom_type_test.go for an example of a custom type for the PostgreSQL point type.

pgx also includes support for custom types implementing the database/sql.Scanner and database/sql/driver.Valuer interfaces.

If pgx does cannot natively encode a type and that type is a renamed type (e.g. type MyTime time.Time) pgx will attempt to encode the underlying type. While this is usually desired behavior it can produce surprising behavior if one the underlying type and the renamed type each implement database/sql interfaces and the other implements pgx interfaces. It is recommended that this situation be avoided by implementing pgx interfaces on the renamed type.

Composite types and row values

Row values and composite types are represented as pgtype.Record (https://pkg.go.dev/github.com/jackc/pgtype?tab=doc#Record). It is possible to get values of your custom type by implementing DecodeBinary interface. Decoding into pgtype.Record first can simplify process by avoiding dealing with raw protocol directly.

For example:

type MyType struct {
    a int      // NULL will cause decoding error
    b *string  // there can be NULL in this position in SQL
}

func (t *MyType) DecodeBinary(ci *pgtype.ConnInfo, src []byte) error {
    r := pgtype.Record{
        Fields: []pgtype.Value{&pgtype.Int4{}, &pgtype.Text{}},
    }

    if err := r.DecodeBinary(ci, src); err != nil {
        return err
    }

    if r.Status != pgtype.Present {
        return errors.New("BUG: decoding should not be called on NULL value")
    }

    a := r.Fields[0].(*pgtype.Int4)
    b := r.Fields[1].(*pgtype.Text)

    // type compatibility is checked by AssignTo
    // only lossless assignments will succeed
    if err := a.AssignTo(&t.a); err != nil {
        return err
    }

    // AssignTo also deals with null value handling
    if err := b.AssignTo(&t.b); err != nil {
        return err
    }
    return nil
}

result := MyType{}
err := conn.QueryRow(context.Background(), "select row(1, 'foo'::text)", pgx.QueryResultFormats{pgx.BinaryFormatCode}).Scan(&r)

Raw Bytes Mapping

[]byte passed as arguments to Query, QueryRow, and Exec are passed unmodified to PostgreSQL.

Transactions

Transactions are started by calling Begin.

tx, err := conn.Begin(context.Background())
if err != nil {
    return err
}
// Rollback is safe to call even if the tx is already closed, so if
// the tx commits successfully, this is a no-op
defer tx.Rollback(context.Background())

_, err = tx.Exec(context.Background(), "insert into foo(id) values (1)")
if err != nil {
    return err
}

err = tx.Commit(context.Background())
if err != nil {
    return err
}

The Tx returned from Begin also implements the Begin method. This can be used to implement pseudo nested transactions. These are internally implemented with savepoints.

Use BeginTx to control the transaction mode.

Prepared Statements

Prepared statements can be manually created with the Prepare method. However, this is rarely necessary because pgx includes an automatic statement cache by default. Queries run through the normal Query, QueryRow, and Exec functions are automatically prepared on first execution and the prepared statement is reused on subsequent executions. See ParseConfig for information on how to customize or disable the statement cache.

Copy Protocol

Use CopyFrom to efficiently insert multiple rows at a time using the PostgreSQL copy protocol. CopyFrom accepts a CopyFromSource interface. If the data is already in a [][]interface{} use CopyFromRows to wrap it in a CopyFromSource interface. Or implement CopyFromSource to avoid buffering the entire data set in memory.

rows := [][]interface{}{
    {"John", "Smith", int32(36)},
    {"Jane", "Doe", int32(29)},
}

copyCount, err := conn.CopyFrom(
    context.Background(),
    pgx.Identifier{"people"},
    []string{"first_name", "last_name", "age"},
    pgx.CopyFromRows(rows),
)

CopyFrom can be faster than an insert with as few as 5 rows.

Listen and Notify

pgx can listen to the PostgreSQL notification system with the `Conn.WaitForNotification` method. It blocks until a context is received or the context is canceled.

_, err := conn.Exec(context.Background(), "listen channelname")
if err != nil {
    return nil
}

if notification, err := conn.WaitForNotification(context.Background()); err != nil {
    // do something with notification
}

Logging

pgx defines a simple logger interface. Connections optionally accept a logger that satisfies this interface. Set LogLevel to control logging verbosity. Adapters for github.com/inconshreveable/log15, github.com/sirupsen/logrus, go.uber.org/zap, github.com/rs/zerolog, and the testing log are provided in the log directory.

Lower Level PostgreSQL Functionality

pgx is implemented on top of github.com/jackc/pgconn a lower level PostgreSQL driver. The Conn.PgConn() method can be used to access this lower layer.

PgBouncer

pgx is compatible with PgBouncer in two modes. One is when the connection has a statement cache in "describe" mode. The other is when the connection is using the simple protocol. This can be set with the PreferSimpleProtocol config option.

Index

Constants

View Source
const (
	LogLevelTrace = 6
	LogLevelDebug = 5
	LogLevelInfo  = 4
	LogLevelWarn  = 3
	LogLevelError = 2
	LogLevelNone  = 1
)

    The values for log levels are chosen such that the zero value means that no log level was specified.

    View Source
    const (
    	Serializable    = TxIsoLevel("serializable")
    	RepeatableRead  = TxIsoLevel("repeatable read")
    	ReadCommitted   = TxIsoLevel("read committed")
    	ReadUncommitted = TxIsoLevel("read uncommitted")
    )

      Transaction isolation levels

      View Source
      const (
      	ReadWrite = TxAccessMode("read write")
      	ReadOnly  = TxAccessMode("read only")
      )

        Transaction access modes

        View Source
        const (
        	Deferrable    = TxDeferrableMode("deferrable")
        	NotDeferrable = TxDeferrableMode("not deferrable")
        )

          Transaction deferrable modes

          View Source
          const (
          	TextFormatCode   = 0
          	BinaryFormatCode = 1
          )

            PostgreSQL format codes

            Variables

            View Source
            var ErrInvalidLogLevel = errors.New("invalid log level")

              ErrInvalidLogLevel occurs on attempt to set an invalid log level.

              View Source
              var ErrNoRows = errors.New("no rows in result set")

                ErrNoRows occurs when rows are expected but none are returned.

                View Source
                var ErrTxClosed = errors.New("tx is closed")
                View Source
                var ErrTxCommitRollback = errors.New("commit unexpectedly resulted in rollback")

                  ErrTxCommitRollback occurs when an error has occurred in a transaction and Commit() is called. PostgreSQL accepts COMMIT on aborted transactions, but it is treated as ROLLBACK.

                  Functions

                  func ScanRow

                  func ScanRow(connInfo *pgtype.ConnInfo, fieldDescriptions []pgproto3.FieldDescription, values [][]byte, dest ...interface{}) error

                    ScanRow decodes raw row data into dest. It can be used to scan rows read from the lower level pgconn interface.

                    connInfo - OID to Go type mapping. fieldDescriptions - OID and format of values values - the raw data as returned from the PostgreSQL server dest - the destination that values will be decoded into

                    Types

                    type Batch

                    type Batch struct {
                    	// contains filtered or unexported fields
                    }

                      Batch queries are a way of bundling multiple queries together to avoid unnecessary network round trips.

                      func (*Batch) Len

                      func (b *Batch) Len() int

                        Len returns number of queries that have been queued so far.

                        func (*Batch) Queue

                        func (b *Batch) Queue(query string, arguments ...interface{})

                          Queue queues a query to batch b. query can be an SQL query or the name of a prepared statement.

                          type BatchResults

                          type BatchResults interface {
                          	// Exec reads the results from the next query in the batch as if the query has been sent with Conn.Exec.
                          	Exec() (pgconn.CommandTag, error)
                          
                          	// Query reads the results from the next query in the batch as if the query has been sent with Conn.Query.
                          	Query() (Rows, error)
                          
                          	// QueryRow reads the results from the next query in the batch as if the query has been sent with Conn.QueryRow.
                          	QueryRow() Row
                          
                          	// Close closes the batch operation. This must be called before the underlying connection can be used again. Any error
                          	// that occurred during a batch operation may have made it impossible to resyncronize the connection with the server.
                          	// In this case the underlying connection will have been closed.
                          	Close() error
                          }

                          type BuildStatementCacheFunc

                          type BuildStatementCacheFunc func(conn *pgconn.PgConn) stmtcache.Cache

                            BuildStatementCacheFunc is a function that can be used to create a stmtcache.Cache implementation for connection.

                            type Conn

                            type Conn struct {
                            	// contains filtered or unexported fields
                            }

                              Conn is a PostgreSQL connection handle. It is not safe for concurrent usage. Use a connection pool to manage access to multiple database connections from multiple goroutines.

                              func Connect

                              func Connect(ctx context.Context, connString string) (*Conn, error)

                                Connect establishes a connection with a PostgreSQL server with a connection string. See pgconn.Connect for details.

                                func ConnectConfig

                                func ConnectConfig(ctx context.Context, connConfig *ConnConfig) (*Conn, error)

                                  Connect establishes a connection with a PostgreSQL server with a configuration struct. connConfig must have been created by ParseConfig.

                                  func (*Conn) Begin

                                  func (c *Conn) Begin(ctx context.Context) (Tx, error)

                                    Begin starts a transaction. Unlike database/sql, the context only affects the begin command. i.e. there is no auto-rollback on context cancellation.

                                    func (*Conn) BeginTx

                                    func (c *Conn) BeginTx(ctx context.Context, txOptions TxOptions) (Tx, error)

                                      BeginTx starts a transaction with txOptions determining the transaction mode. Unlike database/sql, the context only affects the begin command. i.e. there is no auto-rollback on context cancellation.

                                      func (*Conn) Close

                                      func (c *Conn) Close(ctx context.Context) error

                                        Close closes a connection. It is safe to call Close on a already closed connection.

                                        func (*Conn) Config

                                        func (c *Conn) Config() *ConnConfig

                                          Config returns a copy of config that was used to establish this connection.

                                          func (*Conn) ConnInfo

                                          func (c *Conn) ConnInfo() *pgtype.ConnInfo

                                            ConnInfo returns the connection info used for this connection.

                                            func (*Conn) CopyFrom

                                            func (c *Conn) CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)

                                              CopyFrom uses the PostgreSQL copy protocol to perform bulk data insertion. It returns the number of rows copied and an error.

                                              CopyFrom requires all values use the binary format. Almost all types implemented by pgx use the binary format by default. Types implementing Encoder can only be used if they encode to the binary format.

                                              func (*Conn) Deallocate

                                              func (c *Conn) Deallocate(ctx context.Context, name string) error

                                                Deallocate released a prepared statement

                                                func (*Conn) Exec

                                                func (c *Conn) Exec(ctx context.Context, sql string, arguments ...interface{}) (pgconn.CommandTag, error)

                                                  Exec executes sql. sql can be either a prepared statement name or an SQL string. arguments should be referenced positionally from the sql string as $1, $2, etc.

                                                  func (*Conn) IsClosed

                                                  func (c *Conn) IsClosed() bool

                                                  func (*Conn) PgConn

                                                  func (c *Conn) PgConn() *pgconn.PgConn

                                                    PgConn returns the underlying *pgconn.PgConn. This is an escape hatch method that allows lower level access to the PostgreSQL connection than pgx exposes.

                                                    It is strongly recommended that the connection be idle (no in-progress queries) before the underlying *pgconn.PgConn is used and the connection must be returned to the same state before any *pgx.Conn methods are again used.

                                                    func (*Conn) Ping

                                                    func (c *Conn) Ping(ctx context.Context) error

                                                    func (*Conn) Prepare

                                                    func (c *Conn) Prepare(ctx context.Context, name, sql string) (sd *pgconn.StatementDescription, err error)

                                                      Prepare creates a prepared statement with name and sql. sql can contain placeholders for bound parameters. These placeholders are referenced positional as $1, $2, etc.

                                                      Prepare is idempotent; i.e. it is safe to call Prepare multiple times with the same name and sql arguments. This allows a code path to Prepare and Query/Exec without concern for if the statement has already been prepared.

                                                      func (*Conn) Query

                                                      func (c *Conn) Query(ctx context.Context, sql string, args ...interface{}) (Rows, error)

                                                        Query executes sql with args. If there is an error the returned Rows will be returned in an error state. So it is allowed to ignore the error returned from Query and handle it in Rows.

                                                        For extra control over how the query is executed, the types QuerySimpleProtocol, QueryResultFormats, and QueryResultFormatsByOID may be used as the first args to control exactly how the query is executed. This is rarely needed. See the documentation for those types for details.

                                                        func (*Conn) QueryRow

                                                        func (c *Conn) QueryRow(ctx context.Context, sql string, args ...interface{}) Row

                                                          QueryRow is a convenience wrapper over Query. Any error that occurs while querying is deferred until calling Scan on the returned Row. That Row will error with ErrNoRows if no rows are returned.

                                                          func (*Conn) SendBatch

                                                          func (c *Conn) SendBatch(ctx context.Context, b *Batch) BatchResults

                                                            SendBatch sends all queued queries to the server at once. All queries are run in an implicit transaction unless explicit transaction control statements are executed. The returned BatchResults must be closed before the connection is used again.

                                                            func (*Conn) StatementCache

                                                            func (c *Conn) StatementCache() stmtcache.Cache

                                                              StatementCache returns the statement cache used for this connection.

                                                              func (*Conn) WaitForNotification

                                                              func (c *Conn) WaitForNotification(ctx context.Context) (*pgconn.Notification, error)

                                                                WaitForNotification waits for a PostgreSQL notification. It wraps the underlying pgconn notification system in a slightly more convenient form.

                                                                type ConnConfig

                                                                type ConnConfig struct {
                                                                	pgconn.Config
                                                                	Logger   Logger
                                                                	LogLevel LogLevel
                                                                
                                                                	// BuildStatementCache creates the stmtcache.Cache implementation for connections created with this config. Set
                                                                	// to nil to disable automatic prepared statements.
                                                                	BuildStatementCache BuildStatementCacheFunc
                                                                
                                                                	// PreferSimpleProtocol disables implicit prepared statement usage. By default pgx automatically uses the extended
                                                                	// protocol. This can improve performance due to being able to use the binary format. It also does not rely on client
                                                                	// side parameter sanitization. However, it does incur two round-trips per query (unless using a prepared statement)
                                                                	// and may be incompatible proxies such as PGBouncer. Setting PreferSimpleProtocol causes the simple protocol to be
                                                                	// used by default. The same functionality can be controlled on a per query basis by setting
                                                                	// QueryExOptions.SimpleProtocol.
                                                                	PreferSimpleProtocol bool
                                                                	// contains filtered or unexported fields
                                                                }

                                                                  ConnConfig contains all the options used to establish a connection. It must be created by ParseConfig and then it can be modified. A manually initialized ConnConfig will cause ConnectConfig to panic.

                                                                  func ParseConfig

                                                                  func ParseConfig(connString string) (*ConnConfig, error)

                                                                    ParseConfig creates a ConnConfig from a connection string. ParseConfig handles all options that pgconn.ParseConfig does. In addition, it accepts the following options:

                                                                    statement_cache_capacity
                                                                    	The maximum size of the automatic statement cache. Set to 0 to disable automatic statement caching. Default: 512.
                                                                    
                                                                    statement_cache_mode
                                                                    	Possible values: "prepare" and "describe". "prepare" will create prepared statements on the PostgreSQL server.
                                                                    	"describe" will use the anonymous prepared statement to describe a statement without creating a statement on the
                                                                    	server. "describe" is primarily useful when the environment does not allow prepared statements such as when
                                                                    	running a connection pooler like PgBouncer. Default: "prepare"
                                                                    

                                                                    func (*ConnConfig) ConnString

                                                                    func (cc *ConnConfig) ConnString() string

                                                                    func (*ConnConfig) Copy

                                                                    func (cc *ConnConfig) Copy() *ConnConfig

                                                                      Copy returns a deep copy of the config that is safe to use and modify. The only exception is the tls.Config: according to the tls.Config docs it must not be modified after creation.

                                                                      type CopyFromSource

                                                                      type CopyFromSource interface {
                                                                      	// Next returns true if there is another row and makes the next row data
                                                                      	// available to Values(). When there are no more rows available or an error
                                                                      	// has occurred it returns false.
                                                                      	Next() bool
                                                                      
                                                                      	// Values returns the values for the current row.
                                                                      	Values() ([]interface{}, error)
                                                                      
                                                                      	// Err returns any error that has been encountered by the CopyFromSource. If
                                                                      	// this is not nil *Conn.CopyFrom will abort the copy.
                                                                      	Err() error
                                                                      }

                                                                        CopyFromSource is the interface used by *Conn.CopyFrom as the source for copy data.

                                                                        func CopyFromRows

                                                                        func CopyFromRows(rows [][]interface{}) CopyFromSource

                                                                          CopyFromRows returns a CopyFromSource interface over the provided rows slice making it usable by *Conn.CopyFrom.

                                                                          type Identifier

                                                                          type Identifier []string

                                                                            Identifier a PostgreSQL identifier or name. Identifiers can be composed of multiple parts such as ["schema", "table"] or ["table", "column"].

                                                                            func (Identifier) Sanitize

                                                                            func (ident Identifier) Sanitize() string

                                                                              Sanitize returns a sanitized string safe for SQL interpolation.

                                                                              type LargeObject

                                                                              type LargeObject struct {
                                                                              	// contains filtered or unexported fields
                                                                              }

                                                                                A LargeObject is a large object stored on the server. It is only valid within the transaction that it was initialized in. It uses the context it was initialized with for all operations. It implements these interfaces:

                                                                                io.Writer
                                                                                io.Reader
                                                                                io.Seeker
                                                                                io.Closer
                                                                                

                                                                                func (*LargeObject) Close

                                                                                func (o *LargeObject) Close() error

                                                                                  Close closees the large object descriptor.

                                                                                  func (*LargeObject) Read

                                                                                  func (o *LargeObject) Read(p []byte) (int, error)

                                                                                    Read reads up to len(p) bytes into p returning the number of bytes read.

                                                                                    func (*LargeObject) Seek

                                                                                    func (o *LargeObject) Seek(offset int64, whence int) (n int64, err error)

                                                                                      Seek moves the current location pointer to the new location specified by offset.

                                                                                      func (*LargeObject) Tell

                                                                                      func (o *LargeObject) Tell() (n int64, err error)

                                                                                        Tell returns the current read or write location of the large object descriptor.

                                                                                        func (*LargeObject) Truncate

                                                                                        func (o *LargeObject) Truncate(size int64) (err error)

                                                                                          Trunctes the large object to size.

                                                                                          func (*LargeObject) Write

                                                                                          func (o *LargeObject) Write(p []byte) (int, error)

                                                                                            Write writes p to the large object and returns the number of bytes written and an error if not all of p was written.

                                                                                            type LargeObjectMode

                                                                                            type LargeObjectMode int32
                                                                                            const (
                                                                                            	LargeObjectModeWrite LargeObjectMode = 0x20000
                                                                                            	LargeObjectModeRead  LargeObjectMode = 0x40000
                                                                                            )

                                                                                            type LargeObjects

                                                                                            type LargeObjects struct {
                                                                                            	// contains filtered or unexported fields
                                                                                            }

                                                                                              LargeObjects is a structure used to access the large objects API. It is only valid within the transaction where it was created.

                                                                                              For more details see: http://www.postgresql.org/docs/current/static/largeobjects.html

                                                                                              func (*LargeObjects) Create

                                                                                              func (o *LargeObjects) Create(ctx context.Context, oid uint32) (uint32, error)

                                                                                                Create creates a new large object. If oid is zero, the server assigns an unused OID.

                                                                                                func (*LargeObjects) Open

                                                                                                func (o *LargeObjects) Open(ctx context.Context, oid uint32, mode LargeObjectMode) (*LargeObject, error)

                                                                                                  Open opens an existing large object with the given mode. ctx will also be used for all operations on the opened large object.

                                                                                                  func (o *LargeObjects) Unlink(ctx context.Context, oid uint32) error

                                                                                                    Unlink removes a large object from the database.

                                                                                                    type LogLevel

                                                                                                    type LogLevel int

                                                                                                      LogLevel represents the pgx logging level. See LogLevel* constants for possible values.

                                                                                                      func LogLevelFromString

                                                                                                      func LogLevelFromString(s string) (LogLevel, error)

                                                                                                        LogLevelFromString converts log level string to constant

                                                                                                        Valid levels:

                                                                                                        trace
                                                                                                        debug
                                                                                                        info
                                                                                                        warn
                                                                                                        error
                                                                                                        none
                                                                                                        

                                                                                                        func (LogLevel) String

                                                                                                        func (ll LogLevel) String() string

                                                                                                        type Logger

                                                                                                        type Logger interface {
                                                                                                        	// Log a message at the given level with data key/value pairs. data may be nil.
                                                                                                        	Log(ctx context.Context, level LogLevel, msg string, data map[string]interface{})
                                                                                                        }

                                                                                                          Logger is the interface used to get logging from pgx internals.

                                                                                                          type QueryResultFormats

                                                                                                          type QueryResultFormats []int16

                                                                                                            QueryResultFormats controls the result format (text=0, binary=1) of a query by result column position.

                                                                                                            type QueryResultFormatsByOID

                                                                                                            type QueryResultFormatsByOID map[uint32]int16

                                                                                                              QueryResultFormatsByOID controls the result format (text=0, binary=1) of a query by the result column OID.

                                                                                                              type QuerySimpleProtocol

                                                                                                              type QuerySimpleProtocol bool

                                                                                                                QuerySimpleProtocol controls whether the simple or extended protocol is used to send the query.

                                                                                                                type Row

                                                                                                                type Row interface {
                                                                                                                	// Scan works the same as Rows. with the following exceptions. If no
                                                                                                                	// rows were found it returns ErrNoRows. If multiple rows are returned it
                                                                                                                	// ignores all but the first.
                                                                                                                	Scan(dest ...interface{}) error
                                                                                                                }

                                                                                                                  Row is a convenience wrapper over Rows that is returned by QueryRow.

                                                                                                                  Row is an interface instead of a struct to allow tests to mock QueryRow. However, adding a method to an interface is technically a breaking change. Because of this the Row interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

                                                                                                                  type Rows

                                                                                                                  type Rows interface {
                                                                                                                  	// Close closes the rows, making the connection ready for use again. It is safe
                                                                                                                  	// to call Close after rows is already closed.
                                                                                                                  	Close()
                                                                                                                  
                                                                                                                  	// Err returns any error that occurred while reading.
                                                                                                                  	Err() error
                                                                                                                  
                                                                                                                  	// CommandTag returns the command tag from this query. It is only available after Rows is closed.
                                                                                                                  	CommandTag() pgconn.CommandTag
                                                                                                                  
                                                                                                                  	FieldDescriptions() []pgproto3.FieldDescription
                                                                                                                  
                                                                                                                  	// Next prepares the next row for reading. It returns true if there is another
                                                                                                                  	// row and false if no more rows are available. It automatically closes rows
                                                                                                                  	// when all rows are read.
                                                                                                                  	Next() bool
                                                                                                                  
                                                                                                                  	// Scan reads the values from the current row into dest values positionally.
                                                                                                                  	// dest can include pointers to core types, values implementing the Scanner
                                                                                                                  	// interface, []byte, and nil. []byte will skip the decoding process and directly
                                                                                                                  	// copy the raw bytes received from PostgreSQL. nil will skip the value entirely.
                                                                                                                  	Scan(dest ...interface{}) error
                                                                                                                  
                                                                                                                  	// Values returns the decoded row values.
                                                                                                                  	Values() ([]interface{}, error)
                                                                                                                  
                                                                                                                  	// RawValues returns the unparsed bytes of the row values. The returned [][]byte is only valid until the next Next
                                                                                                                  	// call or the Rows is closed. However, the underlying byte data is safe to retain a reference to and mutate.
                                                                                                                  	RawValues() [][]byte
                                                                                                                  }

                                                                                                                    Rows is the result set returned from *Conn.Query. Rows must be closed before the *Conn can be used again. Rows are closed by explicitly calling Close(), calling Next() until it returns false, or when a fatal error occurs.

                                                                                                                    Once a Rows is closed the only methods that may be called are Close(), Err(), and CommandTag().

                                                                                                                    Rows is an interface instead of a struct to allow tests to mock Query. However, adding a method to an interface is technically a breaking change. Because of this the Rows interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

                                                                                                                    type SerializationError

                                                                                                                    type SerializationError string

                                                                                                                      SerializationError occurs on failure to encode or decode a value

                                                                                                                      func (SerializationError) Error

                                                                                                                      func (e SerializationError) Error() string

                                                                                                                      type Tx

                                                                                                                      type Tx interface {
                                                                                                                      	// Begin starts a pseudo nested transaction.
                                                                                                                      	Begin(ctx context.Context) (Tx, error)
                                                                                                                      
                                                                                                                      	// Commit commits the transaction if this is a real transaction or releases the savepoint if this is a pseudo nested
                                                                                                                      	// transaction. Commit will return ErrTxClosed if the Tx is already closed, but is otherwise safe to call multiple
                                                                                                                      	// times. If the commit fails with a rollback status (e.g. the transaction was already in a broken state) then
                                                                                                                      	// ErrTxCommitRollback will be returned.
                                                                                                                      	Commit(ctx context.Context) error
                                                                                                                      
                                                                                                                      	// Rollback rolls back the transaction if this is a real transaction or rolls back to the savepoint if this is a
                                                                                                                      	// pseudo nested transaction. Rollback will return ErrTxClosed if the Tx is already closed, but is otherwise safe to
                                                                                                                      	// call multiple times. Hence, a defer tx.Rollback() is safe even if tx.Commit() will be called first in a non-error
                                                                                                                      	// condition. Any other failure of a real transaction will result in the connection being closed.
                                                                                                                      	Rollback(ctx context.Context) error
                                                                                                                      
                                                                                                                      	CopyFrom(ctx context.Context, tableName Identifier, columnNames []string, rowSrc CopyFromSource) (int64, error)
                                                                                                                      	SendBatch(ctx context.Context, b *Batch) BatchResults
                                                                                                                      	LargeObjects() LargeObjects
                                                                                                                      
                                                                                                                      	Prepare(ctx context.Context, name, sql string) (*pgconn.StatementDescription, error)
                                                                                                                      
                                                                                                                      	Exec(ctx context.Context, sql string, arguments ...interface{}) (commandTag pgconn.CommandTag, err error)
                                                                                                                      	Query(ctx context.Context, sql string, args ...interface{}) (Rows, error)
                                                                                                                      	QueryRow(ctx context.Context, sql string, args ...interface{}) Row
                                                                                                                      
                                                                                                                      	// Conn returns the underlying *Conn that on which this transaction is executing.
                                                                                                                      	Conn() *Conn
                                                                                                                      }

                                                                                                                        Tx represents a database transaction.

                                                                                                                        Tx is an interface instead of a struct to enable connection pools to be implemented without relying on internal pgx state, to support pseudo-nested transactions with savepoints, and to allow tests to mock transactions. However, adding a method to an interface is technically a breaking change. If new methods are added to Conn it may be desirable to add them to Tx as well. Because of this the Tx interface is partially excluded from semantic version requirements. Methods will not be removed or changed, but new methods may be added.

                                                                                                                        type TxAccessMode

                                                                                                                        type TxAccessMode string

                                                                                                                        type TxDeferrableMode

                                                                                                                        type TxDeferrableMode string

                                                                                                                        type TxIsoLevel

                                                                                                                        type TxIsoLevel string

                                                                                                                        type TxOptions

                                                                                                                        type TxOptions struct {
                                                                                                                        	IsoLevel       TxIsoLevel
                                                                                                                        	AccessMode     TxAccessMode
                                                                                                                        	DeferrableMode TxDeferrableMode
                                                                                                                        }

                                                                                                                        Directories

                                                                                                                        Path Synopsis
                                                                                                                        examples
                                                                                                                        log
                                                                                                                        log15adapter
                                                                                                                        Package log15adapter provides a logger that writes to a github.com/inconshreveable/log15.Logger log.
                                                                                                                        Package log15adapter provides a logger that writes to a github.com/inconshreveable/log15.Logger log.
                                                                                                                        logrusadapter
                                                                                                                        Package logrusadapter provides a logger that writes to a github.com/sirupsen/logrus.Logger log.
                                                                                                                        Package logrusadapter provides a logger that writes to a github.com/sirupsen/logrus.Logger log.
                                                                                                                        testingadapter
                                                                                                                        Package testingadapter provides a logger that writes to a test or benchmark log.
                                                                                                                        Package testingadapter provides a logger that writes to a test or benchmark log.
                                                                                                                        zapadapter
                                                                                                                        Package zapadapter provides a logger that writes to a go.uber.org/zap.Logger.
                                                                                                                        Package zapadapter provides a logger that writes to a go.uber.org/zap.Logger.
                                                                                                                        zerologadapter
                                                                                                                        Package zerologadapter provides a logger that writes to a github.com/rs/zerolog.
                                                                                                                        Package zerologadapter provides a logger that writes to a github.com/rs/zerolog.
                                                                                                                        Package pgxpool is a connection pool for pgx.
                                                                                                                        Package pgxpool is a connection pool for pgx.
                                                                                                                        Package stdlib is the compatibility layer from pgx to database/sql.
                                                                                                                        Package stdlib is the compatibility layer from pgx to database/sql.
                                                                                                                        internal