database

Documentation

Overview

Package database owns SQL pools and exposes explicit primary/replica selection. It does not execute queries or route operations or transactions.

Index

• Variables
• type Config
• type Connection
  • func Open(ctx context.Context, cfg Config) (*Connection, func() error, error)
  • func (c *Connection) Primary() *sql.DB
  • func (c *Connection) Replica(name string) (*sql.DB, error)
• type Endpoint
• type PoolConfig

Variables

var ErrReplicaNotFound = errors.New("pfw: database replica not configured")

ErrReplicaNotFound indicates that the requested replica is not configured.

Types

type Config

type Config struct {
	Primary  Endpoint
	Replicas map[string]Endpoint
}

Config describes one logical database. Replica names are application-defined.

type Connection

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

Connection is an immutable group of pools shared by an application's consumers. Obtain one through Open; its cleanup owns all pools. Consumers must not close the pools returned by Primary or Replica themselves.

func Open

func Open(ctx context.Context, cfg Config) (*Connection, func() error, error)

Open validates every endpoint, configures and pings each pool, and returns a cleanup suitable for Palma's BuildWithCleanup. Initialization is all-or-nothing: a failure closes all acquired pools and returns nil connection and cleanup. Cleanup closes pools in reverse order once, aggregates errors, and is safe for concurrent calls. Invoke it only after all consumers have stopped.

func (*Connection) Primary

func (c *Connection) Primary() *sql.DB

Primary returns the primary pool without consulting request or transaction state.

func (*Connection) Replica

func (c *Connection) Replica(name string) (*sql.DB, error)

Replica returns exactly the named pool, with no implicit primary fallback.

type Endpoint

type Endpoint struct {
	Driver         string
	DSN            string
	ConnectTimeout time.Duration
	Pool           *PoolConfig
}

Endpoint describes one physical SQL pool. The application registers its driver. ConnectTimeout defaults to five seconds. DSN follows the driver's format.

type PoolConfig

type PoolConfig struct {
	MaxOpenConns    int
	MaxIdleConns    int
	ConnMaxLifetime time.Duration
	ConnMaxIdleTime time.Duration
}

PoolConfig uses database/sql semantics: zero MaxOpenConns means unlimited, zero MaxIdleConns disables idle connections, and zero durations disable expiry. A nil Endpoint.Pool preserves database/sql defaults.