pgx: github.com/jackc/pgx/pgxpool Index | Files

package pgxpool

import "github.com/jackc/pgx/pgxpool"

Package pgxpool is a 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

Package Files

batch_results.go conn.go doc.go pool.go rows.go stat.go tx.go

type Config Uses

type Config struct {
    ConnConfig *pgx.ConnConfig

    // 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 Uses

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 Uses

func (c *Config) ConnString() string

func (*Config) Copy Uses

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 Uses

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

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

func (*Conn) Begin Uses

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

func (*Conn) BeginTx Uses

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

func (*Conn) Conn Uses

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

func (*Conn) CopyFrom Uses

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

func (*Conn) Exec Uses

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

func (*Conn) Query Uses

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

func (*Conn) QueryRow Uses

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

func (*Conn) Release Uses

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 Uses

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

type Pool Uses

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

func Connect Uses

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 Uses

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 Uses

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

func (*Pool) AcquireAllIdle Uses

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) Begin Uses

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

func (*Pool) BeginTx Uses

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

func (*Pool) Close Uses

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 Uses

func (p *Pool) Config() *Config

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

func (*Pool) CopyFrom Uses

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

func (*Pool) Exec Uses

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

func (*Pool) Query Uses

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

func (*Pool) QueryRow Uses

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

func (*Pool) SendBatch Uses

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

func (*Pool) Stat Uses

func (p *Pool) Stat() *Stat

type Stat Uses

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

func (*Stat) AcquireCount Uses

func (s *Stat) AcquireCount() int64

func (*Stat) AcquireDuration Uses

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

func (*Stat) AcquiredConns Uses

func (s *Stat) AcquiredConns() int32

func (*Stat) CanceledAcquireCount Uses

func (s *Stat) CanceledAcquireCount() int64

func (*Stat) ConstructingConns Uses

func (s *Stat) ConstructingConns() int32

func (*Stat) EmptyAcquireCount Uses

func (s *Stat) EmptyAcquireCount() int64

func (*Stat) IdleConns Uses

func (s *Stat) IdleConns() int32

func (*Stat) MaxConns Uses

func (s *Stat) MaxConns() int32

func (*Stat) TotalConns Uses

func (s *Stat) TotalConns() int32

type Tx Uses

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

func (*Tx) Begin Uses

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

func (*Tx) Commit Uses

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

func (*Tx) Conn Uses

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

func (*Tx) CopyFrom Uses

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

func (*Tx) Exec Uses

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

func (*Tx) LargeObjects Uses

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

func (*Tx) Prepare Uses

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

func (*Tx) Query Uses

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

func (*Tx) QueryRow Uses

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

func (*Tx) Rollback Uses

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

func (*Tx) SendBatch Uses

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

Package pgxpool imports 9 packages (graph). Updated 2020-07-29. Refresh now. Tools for package owners.