Documentation

Overview

Package pgxpool is a concurrency-safe connection pool for pgx.

pgxpool implements a nearly identical interface to pgx connections.

Establishing a Connection

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

pool, err := pgxpool.Connect(context.Background(), os.Getenv("DATABASE_URL"))

The database connection string can be in URL or DSN format. PostgreSQL settings, pgx settings, and pool 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 := pgxpool.ParseConfig(os.Getenv("DATABASE_URL"))
if err != nil {
    // ...
}
config.AfterConnect = func(ctx context.Context, conn *pgx.Conn) error {
    // do something with every new connection
}

pool, err := pgxpool.ConnectConfig(context.Background(), config)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	ConnConfig *pgx.ConnConfig

	// BeforeConnect is called before a new connection is made. It is passed a copy of the underlying pgx.ConnConfig and
	// will not impact any existing open connections.
	BeforeConnect func(context.Context, *pgx.ConnConfig) error

	// AfterConnect is called after a connection is established, but before it is added to the pool.
	AfterConnect func(context.Context, *pgx.Conn) error

	// BeforeAcquire is called before before a connection is acquired from the pool. It must return true to allow the
	// acquision or false to indicate that the connection should be destroyed and a different connection should be
	// acquired.
	BeforeAcquire func(context.Context, *pgx.Conn) bool

	// AfterRelease is called after a connection is released, but before it is returned to the pool. It must return true to
	// return the connection to the pool or false to destroy the connection.
	AfterRelease func(*pgx.Conn) bool

	// MaxConnLifetime is the duration since creation after which a connection will be automatically closed.
	MaxConnLifetime time.Duration

	// MaxConnIdleTime is the duration after which an idle connection will be automatically closed by the health check.
	MaxConnIdleTime time.Duration

	// MaxConns is the maximum size of the pool.
	MaxConns int32

	// MinConns is the minimum size of the pool. The health check will increase the number of connections to this
	// amount if it had dropped below.
	MinConns int32

	// HealthCheckPeriod is the duration between checks of the health of idle connections.
	HealthCheckPeriod time.Duration

	// If set to true, pool doesn't do any I/O operation on initialization.
	// And connects to the server only when the pool starts to be used.
	// The default is false.
	LazyConnect bool
	// contains filtered or unexported fields
}

Config is the configuration struct for creating a pool. 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) (*Config, error)

ParseConfig builds a Config from connString. It parses connString with the same behavior as pgx.ParseConfig with the addition of the following variables:

pool_max_conns: integer greater than 0 pool_min_conns: integer 0 or greater pool_max_conn_lifetime: duration string pool_max_conn_idle_time: duration string pool_health_check_period: duration string

See Config for definitions of these arguments.

# Example DSN
user=jack password=secret host=pg.example.com port=5432 dbname=mydb sslmode=verify-ca pool_max_conns=10

# Example URL
postgres://jack:secret@pg.example.com:5432/mydb?sslmode=verify-ca&pool_max_conns=10

func (*Config) ConnString

func (c *Config) ConnString() string

func (*Config) Copy

func (c *Config) Copy() *Config

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 Conn

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

Conn is an acquired *pgx.Conn from a Pool.

func (*Conn) Begin

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

func (*Conn) BeginFunc

func (c *Conn) BeginFunc(ctx context.Context, f func(pgx.Tx) error) error

func (*Conn) BeginTx

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

func (*Conn) BeginTxFunc

func (c *Conn) BeginTxFunc(ctx context.Context, txOptions pgx.TxOptions, f func(pgx.Tx) error) error

func (*Conn) Conn

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

func (*Conn) CopyFrom

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

func (*Conn) Exec

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

func (*Conn) Ping

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

func (*Conn) Query

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

func (*Conn) QueryFunc

func (c *Conn) QueryFunc(ctx context.Context, sql string, args []interface{}, scans []interface{}, f func(pgx.QueryFuncRow) error) (pgconn.CommandTag, error)

func (*Conn) QueryRow

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

func (*Conn) Release

func (c *Conn) Release()

Release returns c to the pool it was acquired from. Once Release has been called, other methods must not be called. However, it is safe to call Release multiple times. Subsequent calls after the first will be ignored.

func (*Conn) SendBatch

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

type Pool

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

func Connect

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

Connect creates a new Pool and immediately establishes one connection. ctx can be used to cancel this initial connection. See ParseConfig for information on connString format.

func ConnectConfig

func ConnectConfig(ctx context.Context, config *Config) (*Pool, error)

ConnectConfig creates a new Pool and immediately establishes one connection. ctx can be used to cancel this initial connection. config must have been created by ParseConfig.

func (*Pool) Acquire

func (p *Pool) Acquire(ctx context.Context) (*Conn, error)

func (*Pool) AcquireAllIdle

func (p *Pool) AcquireAllIdle(ctx context.Context) []*Conn

AcquireAllIdle atomically acquires all currently idle connections. Its intended use is for health check and keep-alive functionality. It does not update pool statistics.

func (*Pool) AcquireFunc

func (p *Pool) AcquireFunc(ctx context.Context, f func(*Conn) error) error

AcquireFunc acquires a *Conn and calls f with that *Conn. ctx will only affect the Acquire. It has no effect on the call of f. The return value is either an error acquiring the *Conn or the return value of f. The *Conn is automatically released after the call of f.

func (*Pool) Begin

func (p *Pool) Begin(ctx context.Context) (pgx.Tx, error)

func (*Pool) BeginFunc

func (p *Pool) BeginFunc(ctx context.Context, f func(pgx.Tx) error) error

func (*Pool) BeginTx

func (p *Pool) BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error)

func (*Pool) BeginTxFunc

func (p *Pool) BeginTxFunc(ctx context.Context, txOptions pgx.TxOptions, f func(pgx.Tx) error) error

func (*Pool) Close

func (p *Pool) Close()

Close closes all connections in the pool and rejects future Acquire calls. Blocks until all connections are returned to pool and closed.

func (*Pool) Config

func (p *Pool) Config() *Config

Config returns a copy of config that was used to initialize this pool.

func (*Pool) CopyFrom

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

func (*Pool) Exec

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

func (*Pool) Ping

func (p *Pool) Ping(ctx context.Context) error

func (*Pool) Query

func (p *Pool) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)

func (*Pool) QueryFunc

func (p *Pool) QueryFunc(ctx context.Context, sql string, args []interface{}, scans []interface{}, f func(pgx.QueryFuncRow) error) (pgconn.CommandTag, error)

func (*Pool) QueryRow

func (p *Pool) QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row

func (*Pool) SendBatch

func (p *Pool) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults

func (*Pool) Stat

func (p *Pool) Stat() *Stat

type Stat

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

func (*Stat) AcquireCount

func (s *Stat) AcquireCount() int64

AcquireCount returns the cumulative count of successful acquires from the pool.

func (*Stat) AcquireDuration

func (s *Stat) AcquireDuration() time.Duration

AcquireDuration returns the total duration of all successful acquires from the pool.

func (*Stat) AcquiredConns

func (s *Stat) AcquiredConns() int32

AcquiredConns returns the number of currently acquired connections in the pool.

func (*Stat) CanceledAcquireCount

func (s *Stat) CanceledAcquireCount() int64

CanceledAcquireCount returns the cumulative count of acquires from the pool that were canceled by a context.

func (*Stat) ConstructingConns

func (s *Stat) ConstructingConns() int32

ConstructingConns returns the number of conns with construction in progress in the pool.

func (*Stat) EmptyAcquireCount

func (s *Stat) EmptyAcquireCount() int64

EmptyAcquireCount returns the cumulative count of successful acquires from the pool that waited for a resource to be released or constructed because the pool was empty.

func (*Stat) IdleConns

func (s *Stat) IdleConns() int32

IdleConns returns the number of currently idle conns in the pool.

func (*Stat) MaxConns

func (s *Stat) MaxConns() int32

MaxResources returns the maximum size of the pool.

func (*Stat) TotalConns

func (s *Stat) TotalConns() int32

TotalConns returns the total number of resources currently in the pool. The value is the sum of ConstructingConns, AcquiredConns, and IdleConns.

type Tx

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

func (*Tx) Begin

func (tx *Tx) Begin(ctx context.Context) (pgx.Tx, error)

func (*Tx) BeginFunc

func (tx *Tx) BeginFunc(ctx context.Context, f func(pgx.Tx) error) error

func (*Tx) Commit

func (tx *Tx) Commit(ctx context.Context) error

func (*Tx) Conn

func (tx *Tx) Conn() *pgx.Conn

func (*Tx) CopyFrom

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

func (*Tx) Exec

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

func (*Tx) LargeObjects

func (tx *Tx) LargeObjects() pgx.LargeObjects

func (*Tx) Prepare

func (tx *Tx) Prepare(ctx context.Context, name, sql string) (*pgconn.StatementDescription, error)

func (*Tx) Query

func (tx *Tx) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)

func (*Tx) QueryFunc

func (tx *Tx) QueryFunc(ctx context.Context, sql string, args []interface{}, scans []interface{}, f func(pgx.QueryFuncRow) error) (pgconn.CommandTag, error)

func (*Tx) QueryRow

func (tx *Tx) QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row

func (*Tx) Rollback

func (tx *Tx) Rollback(ctx context.Context) error

func (*Tx) SendBatch

func (tx *Tx) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults