...
▽

Package stdlib

import "github.com/jackc/pgx/v4/stdlib"
Overview
Index

Overview ▾

Package stdlib is the compatibility layer from pgx to database/sql.

A database/sql connection can be established through sql.Open. 

db, err := sql.Open("pgx", "postgres://pgx_md5:secret@localhost:5432/pgx_test?sslmode=disable")
if err != nil {
	return err
}

Or from a DSN string. 

db, err := sql.Open("pgx", "user=postgres password=secret host=localhost port=5432 database=pgx_test sslmode=disable")
if err != nil {
	return err
}

Or a pgx.ConnConfig can be used to set configuration not accessible via connection string. In this case the pgx.ConnConfig must first be registered with the driver. This registration returns a connection string which is used with sql.Open. 

connConfig, _ := pgx.ParseConfig(os.Getenv("DATABASE_URL"))
connConfig.Logger = myLogger
connStr := stdlib.RegisterConnConfig(connConfig)
db, _ := sql.Open("pgx", connStr)

pgx uses standard PostgreSQL positional parameters in queries. e.g. $1, $2. It does not support named parameters. 

db.QueryRow("select * from users where id=$1", userID)

In Go 1.13 and above (*sql.Conn) Raw() can be used to get a *pgx.Conn from the standard database/sql.DB connection pool. This allows operations that use pgx specific functionality. 

// Given db is a *sql.DB
conn, err := db.Conn(context.Background())
if err != nil {
	// handle error from acquiring connection from DB pool
}

err = conn.Raw(func(driverConn interface{}) error {
	conn := driverConn.(*stdlib.Conn).Conn() // conn is a *pgx.Conn
	// Do pgx specific stuff with conn
	conn.CopyFrom(...)
	return nil
})
if err != nil {
	// handle error that occurred while using *pgx.Conn
}

Index ▾

Variables
func AcquireConn(db *sql.DB) (*pgx.Conn, error)
func GetConnector(config pgx.ConnConfig, opts ...OptionOpenDB) driver.Connector
func GetDefaultDriver() driver.Driver
func OpenDB(config pgx.ConnConfig, opts ...OptionOpenDB) *sql.DB
func RandomizeHostOrderFunc(ctx context.Context, connConfig *pgx.ConnConfig) error
func RegisterConnConfig(c *pgx.ConnConfig) string
func ReleaseConn(db *sql.DB, conn *pgx.Conn) error
func UnregisterConnConfig(connStr string)
type Conn
    func (c *Conn) Begin() (driver.Tx, error)
    func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)
    func (c *Conn) CheckNamedValue(*driver.NamedValue) error
    func (c *Conn) Close() error
    func (c *Conn) Conn() *pgx.Conn
    func (c *Conn) ExecContext(ctx context.Context, query string, argsV []driver.NamedValue) (driver.Result, error)
    func (c *Conn) Ping(ctx context.Context) error
    func (c *Conn) Prepare(query string) (driver.Stmt, error)
    func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)
    func (c *Conn) QueryContext(ctx context.Context, query string, argsV []driver.NamedValue) (driver.Rows, error)
    func (c *Conn) ResetSession(ctx context.Context) error
type Driver
    func (d *Driver) Open(name string) (driver.Conn, error)
    func (d *Driver) OpenConnector(name string) (driver.Connector, error)
type OptionOpenDB
    func OptionAfterConnect(ac func(context.Context, *pgx.Conn) error) OptionOpenDB
    func OptionBeforeConnect(bc func(context.Context, *pgx.ConnConfig) error) OptionOpenDB
    func OptionResetSession(rs func(context.Context, *pgx.Conn) error) OptionOpenDB
type Rows
    func (r *Rows) Close() error
    func (r *Rows) ColumnTypeDatabaseTypeName(index int) string
    func (r *Rows) ColumnTypeLength(index int) (int64, bool)
    func (r *Rows) ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
    func (r *Rows) ColumnTypeScanType(index int) reflect.Type
    func (r *Rows) Columns() []string
    func (r *Rows) Next(dest []driver.Value) error
type Stmt
    func (s *Stmt) Close() error
    func (s *Stmt) Exec(argsV []driver.Value) (driver.Result, error)
    func (s *Stmt) ExecContext(ctx context.Context, argsV []driver.NamedValue) (driver.Result, error)
    func (s *Stmt) NumInput() int
    func (s *Stmt) Query(argsV []driver.Value) (driver.Rows, error)
    func (s *Stmt) QueryContext(ctx context.Context, argsV []driver.NamedValue) (driver.Rows, error)

Package files

sql.go

Variables

var ErrNotPgx = errors.New("not pgx *sql.DB")

func AcquireConn 

func AcquireConn(db *sql.DB) (*pgx.Conn, error)

AcquireConn acquires a *pgx.Conn from database/sql connection pool. It must be released with ReleaseConn.

In Go 1.13 this functionality has been incorporated into the standard library in the db.Conn.Raw() method.

func GetConnector 

func GetConnector(config pgx.ConnConfig, opts ...OptionOpenDB) driver.Connector

func GetDefaultDriver 

func GetDefaultDriver() driver.Driver

GetDefaultDriver returns the driver initialized in the init function and used when the pgx driver is registered.

func OpenDB 

func OpenDB(config pgx.ConnConfig, opts ...OptionOpenDB) *sql.DB

func RandomizeHostOrderFunc 

func RandomizeHostOrderFunc(ctx context.Context, connConfig *pgx.ConnConfig) error

RandomizeHostOrderFunc is a BeforeConnect hook that randomizes the host order in the provided connConfig, so that a new host becomes primary each time. This is useful to distribute connections for multi-master databases like CockroachDB. If you use this you likely should set https://golang.org/pkg/database/sql/#DB.SetConnMaxLifetime as well to ensure that connections are periodically rebalanced across your nodes.

func RegisterConnConfig 

func RegisterConnConfig(c *pgx.ConnConfig) string

RegisterConnConfig registers a ConnConfig and returns the connection string to use with Open.

func ReleaseConn 

func ReleaseConn(db *sql.DB, conn *pgx.Conn) error

ReleaseConn releases a *pgx.Conn acquired with AcquireConn.

func UnregisterConnConfig 

func UnregisterConnConfig(connStr string)

UnregisterConnConfig removes the ConnConfig registration for connStr.

type Conn 

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

func (*Conn) Begin 

func (c *Conn) Begin() (driver.Tx, error)

func (*Conn) BeginTx 

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

func (*Conn) CheckNamedValue 

func (c *Conn) CheckNamedValue(*driver.NamedValue) error

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) Conn 

func (c *Conn) Conn() *pgx.Conn

Conn returns the underlying *pgx.Conn

func (*Conn) ExecContext 

func (c *Conn) ExecContext(ctx context.Context, query string, argsV []driver.NamedValue) (driver.Result, error)

func (*Conn) Ping 

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

func (*Conn) Prepare 

func (c *Conn) Prepare(query string) (driver.Stmt, error)

func (*Conn) PrepareContext 

func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

func (*Conn) QueryContext 

func (c *Conn) QueryContext(ctx context.Context, query string, argsV []driver.NamedValue) (driver.Rows, error)

func (*Conn) ResetSession 

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

type Driver 

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

func (*Driver) Open 

func (d *Driver) Open(name string) (driver.Conn, error)

func (*Driver) OpenConnector 

func (d *Driver) OpenConnector(name string) (driver.Connector, error)

type OptionOpenDB

OptionOpenDB options for configuring the driver when opening a new db pool. 

type OptionOpenDB func(*connector)

func OptionAfterConnect 

func OptionAfterConnect(ac func(context.Context, *pgx.Conn) error) OptionOpenDB

OptionAfterConnect provides a callback for after connect.

func OptionBeforeConnect 

func OptionBeforeConnect(bc func(context.Context, *pgx.ConnConfig) error) OptionOpenDB

OptionBeforeConnect provides a callback for before connect. It is passed a shallow copy of the ConnConfig that will be used to connect, so only its immediate members should be modified.

func OptionResetSession 

func OptionResetSession(rs func(context.Context, *pgx.Conn) error) OptionOpenDB

OptionResetSession provides a callback that can be used to add custom logic prior to executing a query on the connection if the connection has been used before. If ResetSessionFunc returns ErrBadConn error the connection will be discarded.

type Rows 

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

func (*Rows) Close 

func (r *Rows) Close() error

func (*Rows) ColumnTypeDatabaseTypeName 

func (r *Rows) ColumnTypeDatabaseTypeName(index int) string

ColumnTypeDatabaseTypeName returns the database system type name. If the name is unknown the OID is returned.

func (*Rows) ColumnTypeLength 

func (r *Rows) ColumnTypeLength(index int) (int64, bool)

ColumnTypeLength returns the length of the column type if the column is a variable length type. If the column is not a variable length type ok should return false.

func (*Rows) ColumnTypePrecisionScale 

func (r *Rows) ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)

ColumnTypePrecisionScale should return the precision and scale for decimal types. If not applicable, ok should be false.

func (*Rows) ColumnTypeScanType 

func (r *Rows) ColumnTypeScanType(index int) reflect.Type

ColumnTypeScanType returns the value type that can be used to scan types into.

func (*Rows) Columns 

func (r *Rows) Columns() []string

func (*Rows) Next 

func (r *Rows) Next(dest []driver.Value) error

type Stmt 

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

func (*Stmt) Close 

func (s *Stmt) Close() error

func (*Stmt) Exec 

func (s *Stmt) Exec(argsV []driver.Value) (driver.Result, error)

func (*Stmt) ExecContext 

func (s *Stmt) ExecContext(ctx context.Context, argsV []driver.NamedValue) (driver.Result, error)

func (*Stmt) NumInput 

func (s *Stmt) NumInput() int

func (*Stmt) Query 

func (s *Stmt) Query(argsV []driver.Value) (driver.Rows, error)

func (*Stmt) QueryContext 

func (s *Stmt) QueryContext(ctx context.Context, argsV []driver.NamedValue) (driver.Rows, error)