Add jitter and health check options to pg client

Add WithMaxConnLifetimeJitter and WithHealthCheckPeriod so callers
can spread out connection recycle events and tune how often the
pool reaps and tops up idle connections. The jitter option defaults
to 5 minutes to avoid synchronized reconnect storms out of the box;
the health check period leaves the pgx default in place when unset.

Author: gearnode

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **pg**: `WithMaxConnLifetimeJitter` option to smear connection recycle events and avoid synchronized reconnect storms. Defaults to 5 minutes; pass `0` to disable.
+- **pg**: `WithHealthCheckPeriod` option to tune how often the pool checks idle connections and enforces MinConns/MaxConnIdleTime/MaxConnLifetime. A zero value leaves the pgx default (1 minute) in place.
+
 ## [0.7.0] - 2026-04-22
 
 ### Added

pg/client.go

@@ -55,10 +55,12 @@ type (
 
 		debug bool
 
-		poolSize        int32
-		minPoolSize     int32
-		maxConnIdleTime time.Duration
-		maxConnLifetime time.Duration
+		poolSize              int32
+		minPoolSize           int32
+		maxConnIdleTime       time.Duration
+		maxConnLifetime       time.Duration
+		maxConnLifetimeJitter time.Duration
+		healthCheckPeriod     time.Duration
 
 		tlsConfig *tls.Config
 
@@ -198,6 +200,39 @@ func WithMaxConnLifetime(d time.Duration) Option {
 	}
 }
 
+// WithMaxConnLifetimeJitter sets the duration of randomness added to
+// each connection's MaxConnLifetime, smearing recycle events across
+// time. It maps to pgxpool.Config.MaxConnLifetimeJitter.
+//
+// Without jitter, connections opened around the same time (for
+// example after a deploy) tend to be recycled together, producing
+// synchronized reconnect storms that show up as latency spikes on
+// pgxpool_acquire_duration_seconds. A non-zero jitter spreads those
+// recycles out.
+//
+// When unset, the client defaults to 5 minutes. Pass a zero value
+// explicitly via this option to disable jitter.
+func WithMaxConnLifetimeJitter(d time.Duration) Option {
+	return func(c *Client) {
+		c.maxConnLifetimeJitter = d
+	}
+}
+
+// WithHealthCheckPeriod sets how often the pool checks the health of
+// its idle connections and enforces MinConns/MaxConnIdleTime/
+// MaxConnLifetime. It maps to pgxpool.Config.HealthCheckPeriod. A
+// zero value leaves the pgx default (1 minute) in place.
+//
+// Lowering the period makes the pool react faster to dropped
+// connections (for example after a failover) and refill below
+// MinConns more promptly, at the cost of slightly more background
+// work.
+func WithHealthCheckPeriod(d time.Duration) Option {
+	return func(c *Client) {
+		c.healthCheckPeriod = d
+	}
+}
+
 // WithTracerProvider configures OpenTelemetry tracing with the
 // provided tracer provider.
 func WithTracerProvider(tp trace.TracerProvider) Option {
@@ -235,14 +270,15 @@ func WithDebug() Option {
 //	}
 func NewClient(options ...Option) (*Client, error) {
 	c := &Client{
-		addr:           "localhost:5432",
-		user:           "postgres",
-		database:       "postgres",
-		poolSize:       10,
-		minPoolSize:    1,
-		logger:         log.NewLogger(log.WithOutput(io.Discard)),
-		tracerProvider: otel.GetTracerProvider(),
-		registerer:     prometheus.DefaultRegisterer,
+		addr:                  "localhost:5432",
+		user:                  "postgres",
+		database:              "postgres",
+		poolSize:              10,
+		minPoolSize:           1,
+		maxConnLifetimeJitter: 5 * time.Minute,
+		logger:                log.NewLogger(log.WithOutput(io.Discard)),
+		tracerProvider:        otel.GetTracerProvider(),
+		registerer:            prometheus.DefaultRegisterer,
 	}
 
 	for _, o := range options {
@@ -274,6 +310,12 @@ func NewClient(options ...Option) (*Client, error) {
 	if c.maxConnLifetime > 0 {
 		config.MaxConnLifetime = c.maxConnLifetime
 	}
+	if c.maxConnLifetimeJitter > 0 {
+		config.MaxConnLifetimeJitter = c.maxConnLifetimeJitter
+	}
+	if c.healthCheckPeriod > 0 {
+		config.HealthCheckPeriod = c.healthCheckPeriod
+	}
 
 	c.tracer = c.tracerProvider.Tracer(
 		tracerName,

pg/client_test.go

@@ -223,6 +223,26 @@ func TestNewClient(t *testing.T) {
 		},
 	)
 
+	t.Run(
+		"with max conn lifetime jitter option",
+		func(t *testing.T) {
+			_ = newTestClient(
+				t,
+				pg.WithMaxConnLifetimeJitter(2*time.Minute),
+			)
+		},
+	)
+
+	t.Run(
+		"with health check period option",
+		func(t *testing.T) {
+			_ = newTestClient(
+				t,
+				pg.WithHealthCheckPeriod(30*time.Second),
+			)
+		},
+	)
+
 	t.Run(
 		"exposes expected pgxpool metrics",
 		func(t *testing.T) {