v1.0.0

code.nochebuena.dev/einherjar/db-postgres

Architecture Decisions Resolved

Decision	Outcome
pgx v4 vs v5	pgx v5 — context on Commit/Rollback, improved pgxpool API
Executor method names	`Exec`, `Query`, `QueryRow` — pgx convention (no `Context` suffix)
Pool nil guard in GetExecutor	Explicit `if pool == nil { return nil }` — avoids typed-nil interface pitfall
Health priority	`LevelCritical` — PostgreSQL outage halts the service
UnitOfWork vs manual Tx	UnitOfWork preferred — injects Tx via context; repositories require no changes

API

import "code.nochebuena.dev/einherjar/db-postgres"

// Interfaces
type Executor interface {
    Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
    Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
    QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
}
type Tx interface {
    Executor
    Commit(ctx context.Context) error
    Rollback(ctx context.Context) error
}
type Provider interface {
    GetExecutor(ctx context.Context) Executor
    Begin(ctx context.Context) (Tx, error)
    BeginTx(ctx context.Context, opts pgx.TxOptions) (Tx, error)
    Ping(ctx context.Context) error
    HandleError(err error) error
}
type Component interface {
    lifecycle.Component
    observability.Checkable
    observability.Identifiable
    Provider
    Stats() *pgxpool.Stat
}
type UnitOfWork interface {
    Do(ctx context.Context, fn func(ctx context.Context) error) error
}

// Config
type Config struct {
    Host              string `env:"EINHERJAR_PG_HOST,required"`
    Port              int    `env:"EINHERJAR_PG_PORT"                envDefault:"5432"`
    User              string `env:"EINHERJAR_PG_USER,required"`
    Password          string `env:"EINHERJAR_PG_PASSWORD,required"`
    Name              string `env:"EINHERJAR_PG_NAME,required"`
    SSLMode           string `env:"EINHERJAR_PG_SSL_MODE"            envDefault:"disable"`
    Timezone          string `env:"EINHERJAR_PG_TIMEZONE"            envDefault:"UTC"`
    MaxConns          int    `env:"EINHERJAR_PG_MAX_CONNS"           envDefault:"5"`
    MinConns          int    `env:"EINHERJAR_PG_MIN_CONNS"           envDefault:"2"`
    MaxConnLifetime   string `env:"EINHERJAR_PG_MAX_CONN_LIFETIME"   envDefault:"1h"`
    MaxConnIdleTime   string `env:"EINHERJAR_PG_MAX_CONN_IDLE_TIME"  envDefault:"30m"`
    HealthCheckPeriod string `env:"EINHERJAR_PG_HEALTH_CHECK_PERIOD" envDefault:"1m"`
}
func DefaultConfig() Config
func (c Config) DSN() string

// Constructors
func New(logger logging.Logger, cfg Config) Component
func NewUnitOfWork(logger logging.Logger, client Provider) UnitOfWork

// Package-level error handler (also available as Provider.HandleError)
func HandleError(err error) error

Install

go get code.nochebuena.dev/einherjar/db-postgres@v1.0.0

Dependencies

Module	Version	Role
`code.nochebuena.dev/einherjar/contracts`	v1.0.0	`lifecycle.Component`, `observability.Checkable`, `logging.Logger`
`code.nochebuena.dev/einherjar/core`	v1.0.0	`xerrors`
`github.com/jackc/pgx/v5`	v5.8.0	PostgreSQL driver and connection pool
`github.com/jackc/pgerrcode`	v0.0.0-20250907135507	PostgreSQL error code constants

Downloads

1 Release 1 Tag

Release v1.0.0 Stable

v1.0.0

Architecture Decisions Resolved

API

Install

Dependencies