db

Documentation

Overview

Package db is the GOWDK database plumbing addon. It enables the db feature and ships a thin, driver-agnostic helper for opening a *sql.DB on top of the standard library's database/sql. It is designed to pair with sqlc and user-authored SQL files: you own the schema, the queries, the generated models, migrations, and all domain logic. GOWDK owns none of that and adds no driver, ORM, repository, or query opinions.

The helper imports no SQL driver. Your application registers a driver with a blank import (for example _ "github.com/jackc/pgx/v5/stdlib") and passes its name to Open, so GOWDK carries no database dependency of its own.

Index

• Constants
• func Addon() gowdk.Addon
• func DollarPlaceholder(position int) string
• func Open(driver, dsn string) (*sql.DB, error)
• func OpenWithOptions(driver, dsn string, options Options) (*sql.DB, error)
• func Ping(ctx context.Context, database *sql.DB) error
• func QuestionPlaceholder(position int) string
• func WithTx(ctx context.Context, database *sql.DB, options *sql.TxOptions, ...) (err error)
• type MigrationOptions
• type MigrationRecord
• type MigrationResult
  • func ApplyMigrations(ctx context.Context, database *sql.DB, source fs.FS, options MigrationOptions) (MigrationResult, error)
• type Options
• type PlaceholderFunc
• type Readiness
  • func CheckReadiness(ctx context.Context, database *sql.DB) Readiness

Constants

const DefaultMigrationTable = "gowdk_schema_migrations"

DefaultMigrationTable is the table used to track applied migrations when MigrationOptions.Table is empty.

const DefaultPingTimeout = 5 * time.Second

DefaultPingTimeout bounds the connectivity check performed by Open.

const ImportPath = "github.com/cssbruno/gowdk/addons/db"

ImportPath is the canonical Go import path for the db addon.

Functions

func Addon

func Addon() gowdk.Addon

Addon enables the database plumbing feature.

func DollarPlaceholder

func DollarPlaceholder(position int) string

DollarPlaceholder returns PostgreSQL-style numbered placeholders.

func Open

func Open(driver, dsn string) (*sql.DB, error)

Open opens a *sql.DB for the given registered driver and DSN, applies pool defaults, and verifies the connection with a bounded ping. The driver must be registered by the caller (typically via a blank import) before Open is called.

func OpenWithOptions

func OpenWithOptions(driver, dsn string, options Options) (*sql.DB, error)

OpenWithOptions is Open with explicit pool configuration.

func Ping

func Ping(ctx context.Context, database *sql.DB) error

Ping verifies database connectivity through database/sql.

func QuestionPlaceholder

func QuestionPlaceholder(position int) string

QuestionPlaceholder returns ? placeholders used by SQLite and MySQL-style drivers.

func WithTx

func WithTx(ctx context.Context, database *sql.DB, options *sql.TxOptions, fn func(context.Context, *sql.Tx) error) (err error)

WithTx runs fn inside a database/sql transaction. The transaction commits when fn returns nil and rolls back when fn returns an error or panics.

Types

type MigrationOptions

type MigrationOptions struct {
	// Dir selects a directory inside Source. Empty means ".".
	Dir string
	// Table names the migration tracking table. Empty uses
	// DefaultMigrationTable. Only simple SQL identifiers are accepted.
	Table string
	// Placeholder adapts bind placeholders for the target driver. Empty uses
	// QuestionPlaceholder. Use DollarPlaceholder for PostgreSQL-style drivers.
	Placeholder PlaceholderFunc
	// Now overrides the applied_at timestamp source for tests.
	Now func() time.Time
	// TxOptions are passed to database/sql BeginTx.
	TxOptions *sql.TxOptions
}

MigrationOptions configures ApplyMigrations.

type MigrationRecord

type MigrationRecord struct {
	Name     string
	Checksum string
}

MigrationRecord describes one migration file and checksum.

type MigrationResult

type MigrationResult struct {
	Applied []MigrationRecord
	Skipped []MigrationRecord
}

MigrationResult records which migration files were applied or already present with the same checksum.

func ApplyMigrations

func ApplyMigrations(ctx context.Context, database *sql.DB, source fs.FS, options MigrationOptions) (MigrationResult, error)

ApplyMigrations applies .sql files from source in lexical path order. It is intentionally only a thin database/sql helper: files are user-owned SQL, and this helper tracks applied file names and checksums in one table.

type Options

type Options struct {
	// MaxOpenConns caps total open connections. Zero means unlimited.
	MaxOpenConns int
	// MaxIdleConns caps idle connections. Zero uses the database/sql default.
	MaxIdleConns int
	// ConnMaxLifetime caps connection reuse time. Zero means unlimited.
	ConnMaxLifetime time.Duration
	// PingTimeout bounds the initial connectivity check. Defaults to 5s.
	PingTimeout time.Duration
}

Options tunes the connection pool. The zero value applies sensible defaults.

type PlaceholderFunc

type PlaceholderFunc func(position int) string

PlaceholderFunc returns the SQL placeholder for a 1-based bind position.

type Readiness

type Readiness struct {
	Ready     bool          `json:"ready"`
	CheckedAt time.Time     `json:"checkedAt"`
	Duration  time.Duration `json:"duration"`
	Error     string        `json:"error,omitempty"`
}

Readiness reports the outcome of a database readiness check.

func CheckReadiness

func CheckReadiness(ctx context.Context, database *sql.DB) Readiness

CheckReadiness returns a small framework-neutral readiness snapshot for a generated app endpoint or startup check.