postgres

Documentation

Overview

Package postgres implements distributedlock.Locker against PostgreSQL session- scoped advisory locks (pg_try_advisory_lock). It uses an existing platform/database.Client for connection management.

IMPORTANT — TTL semantics: PostgreSQL advisory locks have no native TTL. The TTL argument to Acquire/Refresh on this provider is ADVISORY ONLY. The lock is held until Release is called or the dedicated session is closed (e.g. by a network failure or by Locker.Close). Callers that need a hard upper bound on lock duration should impose it via context deadlines or by tracking elapsed time themselves; the Refresh method on this provider only verifies that the underlying session is still alive — it does not extend any expiry on the database side.

Each Acquire reserves a dedicated *sql.Conn from the database client's pool so that the matching pg_advisory_unlock targets the same session. The Locker tracks outstanding connections internally and releases all of them on Close.

Index

• Constants
• func NewPostgresLocker(cfg *Config, db database.Client, logger logging.Logger, ...) (distributedlock.Locker, error)
• type Config
  • func (cfg *Config) ValidateWithContext(_ context.Context) error

Constants

const DefaultConnWaitTimeout = 5 * time.Second

DefaultConnWaitTimeout bounds how long Acquire waits to reserve a write-pool connection before giving up. See Config.ConnWaitTimeout.

Functions

func NewPostgresLocker

func NewPostgresLocker(
	cfg *Config,
	db database.Client,
	logger logging.Logger,
	tracerProvider tracing.TracerProvider,
	metricsProvider metrics.Provider,
	cb circuitbreaking.CircuitBreaker,
) (distributedlock.Locker, error)

NewPostgresLocker constructs a new postgres-backed distributedlock.Locker.

Types

type Config

type Config struct {
	// Namespace is mixed into the lock-id hash so independent services sharing a
	// Postgres cluster do not collide on the same advisory-lock id space.
	Namespace int32 `env:"NAMESPACE" envDefault:"0" json:"namespace"`

	// ConnWaitTimeout bounds how long Acquire will wait to reserve a connection
	// from the write pool. Each held lock pins one write connection for its whole
	// lifetime, so a saturated pool would otherwise make Acquire block indefinitely
	// in database/sql's Conn(). When the wait is exceeded, Acquire returns
	// distributedlock.ErrLockNotAcquired instead of blocking. Zero uses
	// DefaultConnWaitTimeout; a negative value disables the bound (wait forever).
	ConnWaitTimeout time.Duration `env:"CONN_WAIT_TIMEOUT" envDefault:"5s" json:"connWaitTimeout"`
}

Config configures a Postgres-backed distributed locker. Namespace is mixed into the lock-id hash so independent services that share a Postgres cluster do not collide on the same advisory-lock id space.

func (*Config) ValidateWithContext

func (cfg *Config) ValidateWithContext(_ context.Context) error

ValidateWithContext validates a Config struct. Namespace has no upper bound; any int32 is acceptable.