The highest tagged major version is
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 ¶
- type Config
- type Conn
- func (c *Conn) Begin(ctx context.Context) (pgx.Tx, error)
- func (c *Conn) BeginFunc(ctx context.Context, f func(pgx.Tx) error) error
- func (c *Conn) BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error)
- func (c *Conn) BeginTxFunc(ctx context.Context, txOptions pgx.TxOptions, f func(pgx.Tx) error) error
- func (c *Conn) Conn() *pgx.Conn
- func (c *Conn) CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, ...) (int64, error)
- func (c *Conn) Exec(ctx context.Context, sql string, arguments ...interface{}) (pgconn.CommandTag, error)
- func (c *Conn) Ping(ctx context.Context) error
- func (c *Conn) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)
- func (c *Conn) QueryFunc(ctx context.Context, sql string, args []interface{}, scans []interface{}, ...) (pgconn.CommandTag, error)
- func (c *Conn) QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row
- func (c *Conn) Release()
- func (c *Conn) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
- type Pool
- func (p *Pool) Acquire(ctx context.Context) (*Conn, error)
- func (p *Pool) AcquireAllIdle(ctx context.Context) []*Conn
- func (p *Pool) AcquireFunc(ctx context.Context, f func(*Conn) error) error
- func (p *Pool) Begin(ctx context.Context) (pgx.Tx, error)
- func (p *Pool) BeginFunc(ctx context.Context, f func(pgx.Tx) error) error
- func (p *Pool) BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error)
- func (p *Pool) BeginTxFunc(ctx context.Context, txOptions pgx.TxOptions, f func(pgx.Tx) error) error
- func (p *Pool) Close()
- func (p *Pool) Config() *Config
- func (p *Pool) CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, ...) (int64, error)
- func (p *Pool) Exec(ctx context.Context, sql string, arguments ...interface{}) (pgconn.CommandTag, error)
- func (p *Pool) Ping(ctx context.Context) error
- func (p *Pool) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)
- func (p *Pool) QueryFunc(ctx context.Context, sql string, args []interface{}, scans []interface{}, ...) (pgconn.CommandTag, error)
- func (p *Pool) QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row
- func (p *Pool) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
- func (p *Pool) Stat() *Stat
- type Stat
- func (s *Stat) AcquireCount() int64
- func (s *Stat) AcquireDuration() time.Duration
- func (s *Stat) AcquiredConns() int32
- func (s *Stat) CanceledAcquireCount() int64
- func (s *Stat) ConstructingConns() int32
- func (s *Stat) EmptyAcquireCount() int64
- func (s *Stat) IdleConns() int32
- func (s *Stat) MaxConns() int32
- func (s *Stat) TotalConns() int32
- type Tx
- func (tx *Tx) Begin(ctx context.Context) (pgx.Tx, error)
- func (tx *Tx) BeginFunc(ctx context.Context, f func(pgx.Tx) error) error
- func (tx *Tx) Commit(ctx context.Context) error
- func (tx *Tx) Conn() *pgx.Conn
- func (tx *Tx) CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, ...) (int64, error)
- func (tx *Tx) Exec(ctx context.Context, sql string, arguments ...interface{}) (pgconn.CommandTag, error)
- func (tx *Tx) LargeObjects() pgx.LargeObjects
- func (tx *Tx) Prepare(ctx context.Context, name, sql string) (*pgconn.StatementDescription, error)
- func (tx *Tx) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)
- func (tx *Tx) QueryFunc(ctx context.Context, sql string, args []interface{}, scans []interface{}, ...) (pgconn.CommandTag, error)
- func (tx *Tx) QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row
- func (tx *Tx) Rollback(ctx context.Context) error
- func (tx *Tx) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
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 ¶
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 ¶ added in v4.7.0
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is an acquired *pgx.Conn from a Pool.
func (*Conn) BeginTxFunc ¶ added in v4.11.0
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
func Connect ¶
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 ¶
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) AcquireAllIdle ¶
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 ¶ added in v4.11.0
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) BeginTxFunc ¶ added in v4.11.0
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 ¶ added in v4.7.0
Config returns a copy of config that was used to initialize this pool.
type Stat ¶
type Stat struct {
// contains filtered or unexported fields
}
func (*Stat) AcquireCount ¶
AcquireCount returns the cumulative count of successful acquires from the pool.
func (*Stat) AcquireDuration ¶
AcquireDuration returns the total duration of all successful acquires from the pool.
func (*Stat) AcquiredConns ¶
AcquiredConns returns the number of currently acquired connections in the pool.
func (*Stat) CanceledAcquireCount ¶
CanceledAcquireCount returns the cumulative count of acquires from the pool that were canceled by a context.
func (*Stat) ConstructingConns ¶
ConstructingConns returns the number of conns with construction in progress in the pool.
func (*Stat) EmptyAcquireCount ¶
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) TotalConns ¶
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) LargeObjects ¶
func (tx *Tx) LargeObjects() pgx.LargeObjects
Source Files