Documentation
¶
Overview ¶
Package dbconn is the engine's database connectivity layer: pgx pool construction with safe session defaults (lock_timeout, statement_timeout), RDS/Aurora TLS, bounded retries for transient errors, and a helper to terminate backends blocking a session's lock acquisition.
Index ¶
- Constants
- func IsRDSHost(host string) bool
- func NewPool(ctx context.Context, cfg Config) (*pgxpool.Pool, error)
- func Retry(ctx context.Context, attempts int, backoff time.Duration, ...) error
- func Retryable(err error) bool
- func ServerMajor(ctx context.Context, pool *pgxpool.Pool) (int, error)
- func ServerVersion(ctx context.Context, pool *pgxpool.Pool) (string, error)
- func TerminateBlockers(ctx context.Context, q Querier, pid int) ([]int, error)
- type Config
- type IndexBuildProgress
- type Querier
- type RowQuerier
Constants ¶
const ( DefaultLockTimeout = 3 * time.Second DefaultStatementTimeout = 30 * time.Second // DefaultConnectTimeout bounds each dial attempt. DefaultConnectTimeout = 10 * time.Second )
Defaults for the session timeouts every pooled connection runs under. Every statement the engine issues is bounded: lock_timeout keeps the engine from sitting at the head of the lock queue (the lock-queue pile-up), and statement_timeout bounds runaway work.
Variables ¶
This section is empty.
Functions ¶
func NewPool ¶
NewPool builds a pgx pool from cfg, applies the session defaults, and verifies connectivity with a ping before returning.
func Retry ¶
func Retry(ctx context.Context, attempts int, backoff time.Duration, fn func(context.Context) error) error
Retry runs fn up to attempts times with linear backoff, retrying only errors Retryable classifies as transient. Non-transient errors return immediately; context cancellation always wins.
func Retryable ¶
Retryable reports whether err is transient: a bounded lock wait that timed out, a deadlock or serialization failure, or a connection-level error.
func ServerMajor ¶
ServerMajor reads the connected server's numeric major version.
func ServerVersion ¶
ServerVersion reads the connected server's server_version setting. Plan reports carry it because classification is version-sensitive: a stored report names the server whose rules produced it.
func TerminateBlockers ¶
TerminateBlockers terminates every backend currently blocking pid's lock acquisition (per pg_blocking_pids) and returns the pids it terminated.
This is the bounded-cutover escape hatch: it targets only the backends standing in front of a specific waiting session (e.g. the cutover swap), never a broad sweep. Callers decide whether evicting those backends is acceptable; this function only does the targeted termination.
Types ¶
type Config ¶
type Config struct {
// URL is a libpq connection string or URL (postgres://...).
URL string
// LockTimeout is applied as the session lock_timeout on every connection.
// Zero means DefaultLockTimeout.
LockTimeout time.Duration
// StatementTimeout is applied as the session statement_timeout on every
// connection. Zero means DefaultStatementTimeout.
StatementTimeout time.Duration
// ConnectTimeout bounds each dial attempt. Zero means
// DefaultConnectTimeout.
ConnectTimeout time.Duration
// CACertPath, when set, enables verify-full TLS using the given CA bundle
// (e.g. the RDS/Aurora global bundle). Unset, RDS/Aurora endpoints are
// auto-verified with the embedded bundle (see rds.go).
CACertPath string
// Pool sizing and lifecycle. Zero values keep pgxpool's defaults.
//
// NOTE: the advisory-lock connection (LK-1) must NOT come from this pool:
// session-scoped locks die with their session, and lifetime/idle
// recycling would silently release the lock. The lock helper owns a
// dedicated single-connection pool exempt from recycling.
MaxConns int32
MinConns int32
MaxConnLifetime time.Duration
MaxConnLifetimeJitter time.Duration
MaxConnIdleTime time.Duration
HealthCheckPeriod time.Duration
// QueryExecMode overrides pgx's default protocol usage — e.g.
// pgx.QueryExecModeExec when a transaction-pooling proxy that cannot
// handle prepared statements sits in front of the pool. Zero keeps pgx's
// default (statement caching).
QueryExecMode pgx.QueryExecMode
// Logger, when set, enables statement-level tracing (pgx tracelog) at
// debug level through the given slog logger.
Logger *slog.Logger
// BeforeConnect, when set, can mutate each new connection's config just
// before dialing — the hook for short-lived credentials such as RDS IAM
// authentication tokens.
BeforeConnect func(context.Context, *pgx.ConnConfig) error
}
Config describes a connection target. Zero values keep sensible defaults (ours for the session timeouts, pgxpool's for pool sizing and lifecycle) — decisions, not options.
type IndexBuildProgress ¶
type IndexBuildProgress struct {
Phase string
BlocksDone uint64
BlocksTotal uint64
TuplesDone uint64
TuplesTotal uint64
}
IndexBuildProgress is one server observation of a concurrent index build.
func ConcurrentIndexProgress ¶
func ConcurrentIndexProgress(ctx context.Context, session RowQuerier, backendPID uint32) (IndexBuildProgress, bool, error)
ConcurrentIndexProgress reads the active build owned by backendPID. The boolean is false when PostgreSQL has not published the row yet or the build has already left the progress view.
Source Files