db

db

import "github.com/brpaz/lib-go/db"

Package db provides driver-agnostic database connectivity helpers built on GORM.

Connection

NewConnection opens a GORM connection using a caller-provided gorm.io/gorm.Dialector (e.g. gorm.io/driver/postgres.Open), keeping this package independent of any specific database driver. Use functional options to configure the connection pool (WithMaxIdleConns, WithMaxOpenConns, WithConnMaxLifetime), enable structured query logging (WithQueryLog) via a github.com/brpaz/lib\-go/logging.Logger (WithLogger), Prometheus metrics (WithMetrics), and OpenTelemetry tracing (WithTracing).

Subpackages

• migrator: schema migration runner backed by goose.
• uow: GORM-backed unit-of-work and transaction manager.
• gormlog: GORM logger adapters (logging.Logger, nop).
• dbtest: test helpers for spinning up ephemeral PostgreSQL instances.

Index

• func NewConnection(dialector gorm.Dialector, opts ...func(*ConnOpts)) (*gorm.DB, error)
• func WithAutomaticPing() func(*ConnOpts)
• func WithConnMaxLifetime(d time.Duration) func(*ConnOpts)
• func WithLogger(logger *logging.Logger) func(*ConnOpts)
• func WithMaxIdleConns(n int) func(*ConnOpts)
• func WithMaxOpenConns(n int) func(*ConnOpts)
• func WithMetrics() func(*ConnOpts)
• func WithQueryLog() func(*ConnOpts)
• func WithQueryLogSlowThreshold(d time.Duration) func(*ConnOpts)
• func WithSkipPoolConfig() func(*ConnOpts)
• func WithTracing() func(*ConnOpts)
• type ConnOpts
  • func (o *ConnOpts) Validate() error

func NewConnection

func NewConnection(dialector gorm.Dialector, opts ...func(*ConnOpts)) (*gorm.DB, error)

NewConnection opens a GORM connection using the provided dialector and options.

The dialector selects the database driver (e.g. gorm.io/driver/postgres.New), keeping this package independent of any specific driver.

func WithAutomaticPing

func WithAutomaticPing() func(*ConnOpts)

WithAutomaticPing enables the automatic ping GORM performs after opening a connection, verifying the database is reachable before the first query.

func WithConnMaxLifetime

func WithConnMaxLifetime(d time.Duration) func(*ConnOpts)

WithConnMaxLifetime sets the maximum amount of time a connection may be reused.

func WithLogger

func WithLogger(logger *logging.Logger) func(*ConnOpts)

WithLogger sets the [logging.Logger] used for GORM query logging. Defaults to a no-op logger when not provided.

func WithMaxIdleConns

func WithMaxIdleConns(n int) func(*ConnOpts)

WithMaxIdleConns sets the maximum number of idle connections in the pool.

func WithMaxOpenConns

func WithMaxOpenConns(n int) func(*ConnOpts)

WithMaxOpenConns sets the maximum number of open connections to the database.

func WithMetrics

func WithMetrics() func(*ConnOpts)

WithMetrics enables GORM Prometheus metrics collection.

func WithQueryLog

func WithQueryLog() func(*ConnOpts)

WithQueryLog enables GORM query logging via the configured logger.

func WithQueryLogSlowThreshold

func WithQueryLogSlowThreshold(d time.Duration) func(*ConnOpts)

func WithSkipPoolConfig

func WithSkipPoolConfig() func(*ConnOpts)

WithSkipPoolConfig skips applying MaxIdleConns, MaxOpenConns and ConnMaxLifetime to the underlying *sql.DB, leaving any pool settings already configured (e.g. on an existing *sql.DB passed via the dialector) untouched.

func WithTracing

func WithTracing() func(*ConnOpts)

WithTracing enables OpenTelemetry tracing for GORM operations.

type ConnOpts

ConnOpts holds configuration for the database connection.

type ConnOpts struct {
    MaxIdleConns           int
    MaxOpenConns           int
    ConnMaxLifetime        time.Duration
    QueryLog               bool
    QueryLogShlowThreshold time.Duration
    Metrics                bool
    Tracing                bool
    DisableAutomaticPing   bool
    SkipPoolConfig         bool
    Logger                 *logging.Logger
}

func (*ConnOpts) Validate

func (o *ConnOpts) Validate() error

Validate checks the connection options for correctness.

Generated by gomarkdoc