db

README

dbbootstrap

Opinionated database lifecycle helpers for Go:

Config -> Open -> Migrate -> SQL/Tx -> Close

The package keeps database/sql visible and leaves repositories, SQL, and generated sqlc code to the consuming service.

Custom adapters used with Migrate must implement Dialect() string and return db.DialectPostgres or db.DialectSQLite. Do not pass typed-nil adapters to db.Open; Go's interface nil check does not detect them.

Install

go get github.com/ZanzyTHEbar/dbbootstrap@v0.1.0

PostgreSQL

database, err := db.Open(ctx, db.Config{
	DSN:             cfg.DatabaseURL,
	MaxOpenConns:    20,
	MaxIdleConns:    5,
	ConnMaxLifetime: time.Hour,
}, db.Postgres())
if err != nil {
	return err
}
defer database.Close()

if err := database.Migrate(ctx, migrations); err != nil {
	return err
}

_, err = database.SQL().ExecContext(ctx, "SELECT 1")

Tx exposes the native *sql.Tx, so generated sqlc queries can be created or used directly by the consuming service.

SQLite

db.SQLite() uses the pure-Go modernc.org/sqlite driver. For an in-memory database, keep at least one idle connection so the database remains alive:

database, err := db.Open(ctx, db.Config{
	DSN:          ":memory:",
	MaxOpenConns: 1,
	MaxIdleConns: 1,
}, db.SQLite())

libSQL

The two upstream libSQL drivers are isolated in subpackages:

import libsql "github.com/ZanzyTHEbar/dbbootstrap/libsql"

database, err := db.Open(ctx, db.Config{DSN: cfg.DatabaseURL}, libsql.New())

For the cgo-backed driver:

import golibsql "github.com/ZanzyTHEbar/dbbootstrap/golibsql"

database, err := db.Open(ctx, db.Config{DSN: cfg.DatabaseURL}, golibsql.New())

golibsql requires CGO_ENABLED=1 and the platform support provided by github.com/tursodatabase/go-libsql.

Do not import both libSQL subpackages into one executable. Both upstream drivers register the libsql database/sql driver name.

Errors

Package errors use faults-go. Inspect failures with faults.CodeOf or faults.IsCode.

Documentation

Overview

Package db owns database/sql lifecycle operations without abstracting SQL.

SQLite is available through SQLite. The libsql and go-libsql implementations live in the libsql and golibsql subpackages. Choose one libSQL implementation per executable because both upstream packages register the database/sql driver name "libsql".

Index

• Constants
• type Adapter
  • func Postgres() Adapter
  • func SQLite() Adapter
• type Config
• type DB
  • func Open(ctx context.Context, cfg Config, adapter Adapter) (*DB, error)
  • func (db *DB) Close() error
  • func (db *DB) Migrate(ctx context.Context, migrations fs.FS) error
  • func (db *DB) Ping(ctx context.Context) error
  • func (db *DB) SQL() *sql.DB
  • func (db *DB) Tx(ctx context.Context, fn func(*sql.Tx) error) error

Constants

const (
	DialectPostgres = "postgres"
	DialectSQLite   = "sqlite3"
)

Types

type Adapter

type Adapter interface {
	Open(context.Context, Config) (*sql.DB, error)
	Ping(context.Context, *sql.DB) error
}

Adapter opens a database/sql pool and provides its health check. Adapters used with DB.Migrate must also implement Dialect() string and return a supported migration dialect.

func Postgres

func Postgres() Adapter

Postgres returns the PostgreSQL database/sql adapter backed by pgx.

func SQLite

func SQLite() Adapter

SQLite returns a pure-Go SQLite database/sql adapter.

type Config

type Config struct {
	DSN             string
	MaxOpenConns    int
	MaxIdleConns    int
	ConnMaxLifetime time.Duration
	ConnMaxIdleTime time.Duration
}

Config contains the connection string and database/sql pool settings.

type DB

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

DB owns a database/sql connection pool.

func Open

func Open(ctx context.Context, cfg Config, adapter Adapter) (*DB, error)

Open creates a database pool, applies its settings, and verifies connectivity. Callers must not pass a typed-nil adapter; only a nil interface is detected.

func (*DB) Close

func (db *DB) Close() error

Close closes the underlying connection pool.

func (*DB) Migrate

func (db *DB) Migrate(ctx context.Context, migrations fs.FS) error

Migrate applies pending SQL migrations from migrations. The adapter must implement Dialect() string and return a supported migration dialect.

func (*DB) Ping

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

Ping checks the database connection using the configured adapter.

func (*DB) SQL

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

SQL returns the underlying pool. The DB remains responsible for closing it.

func (*DB) Tx

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

Tx runs fn in a transaction, committing on success and rolling back on error.