Documentation
¶
Overview ¶
Package postgres is the PostgreSQL backend of the database client tier: a lifecycle-managed *sql.DB pool (Client) plus ORM-independent pool utilities — a boot-time reachability probe (Ping) and a Prometheus pool-stats collector. It depends only on database/sql and core, so it wires into any composition root without pulling in an ORM.
Index ¶
Constants ¶
const StatsInterval = 15 * time.Second
StatsInterval is the default cadence at which the pool gauges refresh.
Variables ¶
This section is empty.
Functions ¶
func Check ¶
Check returns a readiness closure that pings db under a bounded (readinessTimeout) context, so a Kubernetes readiness probe can gate /readyz on the pool actually reaching Postgres: the closure returns nil while the database is reachable and a wrapped error once it is not, at which point the pod is pulled from the Service endpoints. Liveness must NOT use this — a slow DB should not restart the pod.
func Ping ¶
Ping verifies the pool can reach the database, so a bad DSN or a down server surfaces as a clear boot-time error at the composition root instead of as the first request's failure. Call it right after building the pool. A failure is coded CodeUnavailable: an unreachable database is transient, so callers that classify by code (IsTransient, the retry policy) may retry it.
func StartStatsCollector ¶
func StartStatsCollector( ctx context.Context, db *sql.DB, m interfaces.Metrics, interval time.Duration, )
StartStatsCollector publishes the *sql.DB connection-pool stats as gauges on m and refreshes them every interval until ctx is cancelled. It returns immediately after publishing once, so the series exist before the first scrape. A non-positive interval falls back to StatsInterval.
The gauge names are stable so a pool-saturation alert can be written against them (e.g. db_pool_active_connections / db_pool_max_connections > 0.8) — wiring this at each server's composition root is what makes such an alert resolve. "active" is the in-use count (connections currently serving a query); the pool nears saturation as in-use approaches the max, at which point new callers wait.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a lifecycle-managed database connection pool: Start opens + pings the pool from config, Stop closes it, and Liveness/Readiness answer Kubernetes probes. It satisfies interfaces.Client so a lifecycle.Manager coordinates its startup and shutdown; DB() exposes the shared *sql.DB the ORM adapters and the raw-SQL callers run over.
func New ¶
func New(cfg *infra.DatabaseConfig) *Client
New builds a lifecycle-managed pool client from config. The pool is not opened until Start. It is the PostgreSQL backend constructor the database tier's NewFromConfig selects for KindPostgres.
Source Files