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, cb circuitbreaking.CircuitBreaker, ...) (distributedlock.Locker, error)
• func NewPostgresScopedLocker(cfg *Config, db database.Client, cb circuitbreaking.CircuitBreaker, ...) (distributedlock.ScopedLocker, error)
• type Config
  • func (cfg *Config) ValidateWithContext(_ context.Context) error
• type Option
  • func WithLogger(logger logging.Logger) Option
  • func WithMetricsProvider(metricsProvider metrics.Provider) Option
  • func WithTracerProvider(tracerProvider tracing.TracerProvider) Option

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,
	cb circuitbreaking.CircuitBreaker,
	opts ...Option,
) (distributedlock.Locker, error)

NewPostgresLocker constructs a new postgres-backed distributedlock.Locker.

func NewPostgresScopedLocker

func NewPostgresScopedLocker(
	cfg *Config,
	db database.Client,
	cb circuitbreaking.CircuitBreaker,
	opts ...Option,
) (distributedlock.ScopedLocker, error)

NewPostgresScopedLocker constructs a transaction-scoped distributedlock.ScopedLocker. Unlike NewPostgresLocker it needs only the safe database.Client surface (WithTransaction), not RawAccess.

fn runs while the calling transaction holds the advisory lock, but receives only a context: any database work fn performs goes through its own connections and is NOT part of the lock-holding transaction. WithLock waits in the database (pg_advisory_xact_lock queues server-side, so waiters need no polling and are granted the lock in request order); each in-flight call occupies one write-pool connection for fn's duration.

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" yaml:"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" yaml:"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.

type Option

type Option func(*options)

Option configures the postgres-backed lockers this package constructs. The zero configuration works: an absent logger logs nowhere, an absent tracer provider traces nowhere, and an absent metrics provider records nothing.

func WithLogger

func WithLogger(logger logging.Logger) Option

WithLogger attaches a logger.

func WithMetricsProvider

func WithMetricsProvider(metricsProvider metrics.Provider) Option

WithMetricsProvider attaches a metrics provider for the locker's counters and latency histogram.

func WithTracerProvider

func WithTracerProvider(tracerProvider tracing.TracerProvider) Option

WithTracerProvider attaches a tracer provider, enabling spans on every lock operation.