database

Documentation

Overview

Package database integrates standard library database/sql connections with Kora configuration, dependency injection, and application lifecycle.

Kora does not select or bundle a SQL driver. Applications import the driver they need and choose it through Config.Driver.

Index

• func Open(config Config) (*sql.DB, error)
• func Register(app *kora.App, config Config) (*sql.DB, error)
• func WithinTransaction(ctx context.Context, db *sql.DB, options *sql.TxOptions, work TransactionFunc) (err error)
• type Config
  • func (c Config) Validate() error
• type TransactionFunc

Functions

func Open

func Open(config Config) (*sql.DB, error)

Open validates config, creates a database/sql pool, and applies pool limits. It does not contact the database; Register adds a startup ping to Kora's lifecycle.

func Register

func Register(app *kora.App, config Config) (*sql.DB, error)

Register opens a database/sql pool, exposes *sql.DB through Kora's service container, verifies connectivity during application startup, and closes the pool during shutdown.

func WithinTransaction

func WithinTransaction(
	ctx context.Context,
	db *sql.DB,
	options *sql.TxOptions,
	work TransactionFunc,
) (err error)

WithinTransaction executes work in a transaction.

It commits when work succeeds, rolls back when work returns an error, and rolls back before re-panicking when work panics.

Types

type Config

type Config struct {
	Driver          string        `env:"DB_DRIVER" required:"true"`
	DSN             string        `env:"DB_DSN" required:"true"`
	MaxOpenConns    int           `env:"DB_MAX_OPEN_CONNS" default:"25"`
	MaxIdleConns    int           `env:"DB_MAX_IDLE_CONNS" default:"5"`
	ConnMaxLifetime time.Duration `env:"DB_CONN_MAX_LIFETIME" default:"30m"`
	ConnMaxIdleTime time.Duration `env:"DB_CONN_MAX_IDLE_TIME" default:"5m"`
	PingTimeout     time.Duration `env:"DB_PING_TIMEOUT" default:"5s"`
}

Config describes a database/sql connection and its pool.

Config can be nested in an application config loaded with kora.LoadConfig. Changing DB_DRIVER and DB_DSN selects another registered database/sql driver without changing application wiring.

func (Config) Validate

func (c Config) Validate() error

Validate checks configuration values without opening a pool.

type TransactionFunc

type TransactionFunc func(context.Context, *sql.Tx) error

TransactionFunc is work executed inside a database transaction.