postgres

Documentation

Overview

Package postgres provides database access utilities with tracing integration.

It offers pool initialization with tracing, health checks, connection metrics, and transaction management with auto-rollback.

Index

• Variables
• func NewPool(ctx context.Context, cfg Config) (*pgxpool.Pool, error)
• func Ping(ctx context.Context, pool *pgxpool.Pool) error
• func WithTx(ctx context.Context, pool *pgxpool.Pool, fn func(tx pgx.Tx) error) error
• type Config
  • func DefaultConfig() Config
• type HealthChecker
  • func NewHealthChecker(pool *pgxpool.Pool) *HealthChecker
  • func (c *HealthChecker) Check(ctx context.Context) bool
• type InMemoryUnitOfWork
  • func NewInMemoryUnitOfWork() *InMemoryUnitOfWork
  • func (u *InMemoryUnitOfWork) Execute(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error
• type PgUnitOfWork
  • func NewUnitOfWork(pool *pgxpool.Pool) *PgUnitOfWork
  • func (u *PgUnitOfWork) Execute(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error
• type Transaction
• type UnitOfWork

Variables

var ErrDSNRequired = errors.New("dsn is required")

ErrDSNRequired is returned when DSN is empty in Config.

Functions

func NewPool

func NewPool(ctx context.Context, cfg Config) (*pgxpool.Pool, error)

NewPool creates a new PostgreSQL connection pool with tracing. It registers a shutdown handler to close the pool gracefully. Returns *pgxpool.Pool directly for sqlc compatibility.

func Ping

func Ping(ctx context.Context, pool *pgxpool.Pool) error

Ping verifies database connectivity. Returns nil if the database is reachable, error otherwise.

func WithTx

func WithTx(ctx context.Context, pool *pgxpool.Pool, fn func(tx pgx.Tx) error) error

WithTx executes fn within a database transaction. The transaction is committed if fn returns nil; rolled back otherwise. Panics within fn cause rollback and re-panic.

Types

type Config

type Config struct {
	// DSN is the PostgreSQL connection string.
	// Required. Example: "postgres://user:pass@localhost:5432/db?sslmode=disable"
	DSN string `koanf:"dsn"`

	// MaxConns is the maximum number of connections in the pool.
	MaxConns int32 `koanf:"max_conns"`

	// MinConns is the minimum number of connections to keep open.
	MinConns int32 `koanf:"min_conns"`

	// MaxConnLifetime is the maximum lifetime of a connection.
	MaxConnLifetime time.Duration `koanf:"max_conn_lifetime"`

	// MaxConnIdleTime is the maximum time a connection can be idle.
	MaxConnIdleTime time.Duration `koanf:"max_conn_idle_time"`

	// HealthCheckPeriod is the interval between health checks.
	HealthCheckPeriod time.Duration `koanf:"health_check_period"`
}

Config holds configuration for PostgreSQL pool initialization.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible default values. DSN is required and must be set by the caller.

type HealthChecker

type HealthChecker struct {
	// contains filtered or unexported fields
}

HealthChecker checks PostgreSQL pool connectivity. Implements grpchealth.HealthChecker interface.

func NewHealthChecker

func NewHealthChecker(pool *pgxpool.Pool) *HealthChecker

NewHealthChecker creates a health checker for the given pool.

func (*HealthChecker) Check

func (c *HealthChecker) Check(ctx context.Context) bool

Check returns true if the database is reachable.

type InMemoryUnitOfWork

type InMemoryUnitOfWork struct{}

InMemoryUnitOfWork implements UnitOfWork as a no-op for testing. The callback receives a nilTransaction where Tx() returns nil. Use with components that handle nil transactions (e.g., InMemoryEventStore).

func NewInMemoryUnitOfWork

func NewInMemoryUnitOfWork() *InMemoryUnitOfWork

NewInMemoryUnitOfWork creates a no-op UnitOfWork for unit testing.

func (*InMemoryUnitOfWork) Execute

func (u *InMemoryUnitOfWork) Execute(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error

Execute runs fn without transaction management.

type PgUnitOfWork

type PgUnitOfWork struct {
	// contains filtered or unexported fields
}

PgUnitOfWork implements UnitOfWork using a PostgreSQL connection pool.

func NewUnitOfWork

func NewUnitOfWork(pool *pgxpool.Pool) *PgUnitOfWork

NewUnitOfWork creates a UnitOfWork backed by the given connection pool.

func (*PgUnitOfWork) Execute

func (u *PgUnitOfWork) Execute(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error

Execute runs fn within a transaction. Commits on success, rolls back on error or panic.

type Transaction

type Transaction interface {
	Tx() pgx.Tx
}

Transaction represents an active database transaction. For in-memory implementations, Tx() returns nil.

type UnitOfWork

type UnitOfWork interface {
	Execute(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error
}

UnitOfWork manages transaction boundaries.