Help us shape the future of Go! Take the 2026 Go Developer Survey

database

package
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 12 Imported by: 3

Documentation

Overview

Package database manages SQL connections for Vukem: dialects, SQLite defaults (WAL, busy timeout, foreign keys, a single-connection writer pool beside a reader pool), PostgreSQL through driver modules, and transactions that roll back on error or panic.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunInTx

func RunInTx(ctx context.Context, ex Executor, fn func(tx *Tx) error) error

RunInTx runs fn inside ex's transaction when ex is already a *Tx, or in a new transaction when ex is a *DB.

Types

type Config

type Config struct {
	MaxOpen     int
	MaxIdle     int
	MaxLifetime time.Duration
	MaxIdleTime time.Duration
	Log         *slog.Logger
}

Config tunes connection pools.

type DB

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

DB is a connection with its dialect. For SQLite, writes and transactions go to a single-connection writer pool and reads to a reader pool, which avoids SQLITE_BUSY under concurrency.

func FromSQL

func FromSQL(conn *sql.DB, dialect Dialect) *DB

FromSQL wraps an existing *sql.DB (tests, sqlc interop).

func Open

func Open(ctx context.Context, rawURL string, opts ...Option) (*DB, error)

Open connects to url:

  • SQLite: "file:storage/app.db", "sqlite:storage/app.db", ":memory:";
  • other schemes need their Driver (e.g. postgres.Driver()).

func (*DB) Close

func (db *DB) Close() error

Close closes the pools. Always close databases before deleting their files (required on Windows).

func (*DB) Dialect

func (db *DB) Dialect() Dialect

Dialect implements Executor.

func (*DB) ExecContext

func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

ExecContext runs a statement on the writer pool.

func (*DB) Ping

func (db *DB) Ping(ctx context.Context) error

Ping checks connectivity (used by health checks).

func (*DB) QueryContext

func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)

QueryContext runs a query on the reader pool.

func (*DB) QueryRowContext

func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row

QueryRowContext runs a single-row query on the reader pool, except for statements with RETURNING, which write and go to the writer pool.

func (*DB) SQL

func (db *DB) SQL() *sql.DB

SQL returns the writer *sql.DB for libraries such as sqlc.

func (*DB) Tx

func (db *DB) Tx(ctx context.Context, fn func(tx *Tx) error) (err error)

Tx runs fn in a transaction on the writer pool: it commits when fn returns nil and rolls back on error or panic (the panic is re-raised). SQLite write transactions use BEGIN IMMEDIATE.

type Dialect

type Dialect interface {
	// Name is "sqlite" or "postgres".
	Name() string
	// Placeholder returns the n-th (1-based) bind placeholder.
	Placeholder(n int) string
	// Quote quotes an identifier (already validated by callers).
	Quote(ident string) string
}

Dialect describes SQL differences between databases.

var (
	SQLite   Dialect = sqliteDialect{}
	Postgres Dialect = postgresDialect{}
)

SQLite and Postgres are the built-in dialects.

type Driver

type Driver struct {
	// SQLName is the database/sql driver name ("pgx").
	SQLName string
	// Dialect is the SQL dialect.
	Dialect Dialect
	// Schemes are the URL schemes the driver accepts ("postgres").
	Schemes []string
}

Driver connects a dialect to a database/sql driver. PostgreSQL's comes from the drivers/postgres module: database.Open(ctx, url, postgres.Driver()).

type Executor

type Executor interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
	Dialect() Dialect
}

Executor runs SQL; *DB and *Tx implement it, so ORM and schema code works inside and outside transactions.

type Manager

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

Manager holds named connections. The default connection is "default".

func NewManager

func NewManager(db *DB) *Manager

NewManager returns a Manager with db as the default connection.

func (*Manager) Add

func (m *Manager) Add(name string, db *DB) error

Add registers a named connection.

func (*Manager) Close

func (m *Manager) Close() error

Close closes every connection.

func (*Manager) Conn

func (m *Manager) Conn(name string) *DB

Conn returns a named connection or nil.

func (*Manager) Default

func (m *Manager) Default() *DB

Default returns the default connection.

func (*Manager) Names

func (m *Manager) Names() []string

Names lists connection names.

func (*Manager) Ping

func (m *Manager) Ping(ctx context.Context) error

Ping checks every connection.

type Option

type Option func(*openOptions)

Option configures Open.

func WithConfig

func WithConfig(c Config) Option

WithConfig sets pool limits and the logger.

func WithDriver

func WithDriver(d Driver) Option

WithDriver registers a non-SQLite driver for this Open call.

type Tx

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

Tx is a transaction; it implements Executor.

func (*Tx) Dialect

func (tx *Tx) Dialect() Dialect

Dialect implements Executor.

func (*Tx) ExecContext

func (tx *Tx) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)

ExecContext implements Executor.

func (*Tx) QueryContext

func (tx *Tx) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)

QueryContext implements Executor.

func (*Tx) QueryRowContext

func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row

QueryRowContext implements Executor.

func (*Tx) SQL

func (tx *Tx) SQL() *sql.Tx

SQL returns the underlying *sql.Tx.

Directories

Path Synopsis
Package dbtest is the database conformance suite: the same schema, ORM, transaction and migration checks run against every dialect (SQLite in core, Postgres and others in their driver modules).
Package dbtest is the database conformance suite: the same schema, ORM, transaction and migration checks run against every dialect (SQLite in core, Postgres and others in their driver modules).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL