Documentation
¶
Overview ¶
Package pool is a small, dependency-free connection pool for *pgz.Client.
Design choices:
- Bounded by MaxConns. Acquire() blocks (with context) when full.
- Idle conns live on a LIFO stack so the warm ones stay warm.
- Background reaper closes conns idle longer than IdleTimeout.
- On a query error, the caller releases with Discard() so the broken conn does not return to the pool.
- All goroutines exit on Close().
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = errors.New("pool: closed")
ErrClosed is returned by Acquire after Close.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
pgz.Config
MaxConns int // default 16
MinIdle int // default 0
IdleTimeout time.Duration // default 5m
AcquireTimeout time.Duration // default unbounded; per-call ctx wins
HealthCheck time.Duration // background reaper interval; default 30s
// PingAfterIdle is the threshold above which Acquire pings the
// idle connection before returning it. Default: 30s. Set to 0 to
// disable. Helps survive PgBouncer's server_idle_timeout (default
// 600s) and middlebox NAT timeouts.
PingAfterIdle time.Duration
// MaxConnLifetime caps the total wall-clock lifetime of a pooled
// connection. Past this, Acquire closes and reopens. Defaults to 1h.
// Bound the long-tail growth of server-side state (prepared stmts,
// catalog caches, etc.) on long-lived backends.
MaxConnLifetime time.Duration
// MaxInFlightBuffers caps the number of scratch buffers checked out
// from the internal buffer pool at any instant. Applied process-wide
// (the buffer pool is a package-level singleton). 0 = unbounded.
// Useful under extreme bursts where 32 KiB × N-thousand concurrent
// queries would otherwise balloon the pool's backing slab. When the
// cap is hit, Get falls back to plain make() and bypasses the pool;
// callers always receive a usable buffer.
MaxInFlightBuffers int
}
Config configures the pool. Zero values are sane defaults.
type Conn ¶
Conn is the handle returned by Acquire. Always call Release or Discard.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a thread-safe pool of *pgz.Client.
func (*Pool) Acquire ¶
Acquire returns a connection from the pool, blocking up to ctx until one is available or the pool is at capacity. Acquire transparently handles:
- max-lifetime expiry (the conn is closed and a fresh one is opened)
- long-idle ping (catches conns the network silently dropped, e.g. after PgBouncer's server_idle_timeout)
- one transparent retry on any failure of the above checks
The retry is bounded — we never loop more than a handful of times so a hard backend failure surfaces fast.
func (*Pool) Close ¶
Close drains the pool and closes every idle connection. Outstanding Acquire callers receive ErrClosed.
func (*Pool) Drain ¶
Drain stops accepting new Acquire calls and waits for in-flight connections to be Released. Idle connections are closed immediately. Returns ctx.Err() if ctx expires before all in-flight conns return. After a successful Drain, Close is a no-op other than cleanup.
Typical rolling-deploy pattern:
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := pool.Drain(ctx); err != nil { /* log; forced shutdown */ }
pool.Close()
Source Files