dbopen

README

dbopen — production-safe SQLite open

dbopen ouvre une base SQLite avec les pragmas HOROS (WAL, foreign_keys, busy_timeout, synchronous) et du retry automatique sur SQLITE_BUSY.

Quick start

db, err := dbopen.Open("data/app.db",
    dbopen.WithMkdirAll(),
    dbopen.WithSchema(schema),
)
defer db.Close()

// In tests:
db := dbopen.OpenMemory(t)

Pragmas par défaut

PRAGMA foreign_keys = ON;
PRAGMA journal_mode = WAL;
PRAGMA busy_timeout = 10000;
PRAGMA synchronous = NORMAL;

Exported API

Symbol	Description
Open(path, opts)	Ouvre SQLite avec pragmas + schemas
OpenMemory(t, opts)	In-memory pour tests (MaxOpenConns=1 auto)
RunTx(ctx, db, fn)	Transaction avec retry 3x sur SQLITE_BUSY
Exec(ctx, db, query, args)	Exec avec retry 3x sur SQLITE_BUSY
IsBusy(err)	Détecte SQLITE_BUSY/SQLITE_LOCKED
WithDriver(name)	Driver alternatif (ex: "sqlite-trace")
WithTrace()	Raccourci pour WithDriver("sqlite-trace")
WithSchema(sql)	Applique un schema DDL après ouverture
WithSchemaFile(path)	Schema depuis un fichier
WithMkdirAll()	Crée les répertoires parents si absents
WithBusyTimeout(ms)	Override du busy_timeout
WithCacheSize(pages)	Override du cache_size
WithSynchronous(mode)	Override du synchronous
WithoutForeignKeys()	Désactive foreign_keys
WithoutPing()	Skip le ping initial

Quand utiliser

Toujours. Jamais sql.Open("sqlite", ...) directement. dbopen.Open garantit les pragmas et le retry.

Anti-patterns

Ne pas faire	Faire
sql.Open("sqlite", path)	dbopen.Open(path)
Appliquer les pragmas manuellement	dbopen.Open le fait
OpenMemory sans MaxOpenConns(1)	C'est fait automatiquement
Oublier import _ "modernc.org/sqlite"	Le driver doit être enregistré

Documentation

Overview

Package dbopen provides a single function to open an SQLite database with the HOROS production-safe pragmas applied via EXEC (driver-agnostic).

Default pragmas:

foreign_keys = ON
journal_mode = WAL
busy_timeout = 10000
synchronous  = NORMAL

Usage:

import _ "modernc.org/sqlite"
db, err := dbopen.Open("app.db")

With tracing driver:

import _ "github.com/hazyhaar/pkg/trace"
db, err := dbopen.Open("app.db", dbopen.WithTrace())

In tests:

db := dbopen.OpenMemory(t)

Index

• func Exec(ctx context.Context, db *sql.DB, query string, args ...any) (sql.Result, error)
• func IsBusy(err error) bool
• func Open(path string, opts ...Option) (*sql.DB, error)
• func OpenMemory(t testing.TB, opts ...Option) *sql.DB
• func RunTx(ctx context.Context, db *sql.DB, fn func(*sql.Tx) error) error
• type Option
  • func WithBusyTimeout(ms int) Option
  • func WithCacheSize(pages int) Option
  • func WithDriver(name string) Option
  • func WithMkdirAll() Option
  • func WithSchema(s string) Option
  • func WithSchemaFile(path string) Option
  • func WithSynchronous(mode string) Option
  • func WithTrace() Option
  • func WithoutForeignKeys() Option
  • func WithoutPing() Option

Functions

func Exec

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

Exec executes a statement with automatic retry on SQLITE_BUSY. It retries up to 3 times with 100/200/300 ms backoff.

func IsBusy

func IsBusy(err error) bool

IsBusy reports whether err indicates an SQLite BUSY condition. It checks for SQLITE_BUSY, "database is locked", and "database table is locked".

func Open

func Open(path string, opts ...Option) (*sql.DB, error)

Open opens an SQLite database at path with HOROS production-safe pragmas. The caller must blank-import the appropriate driver before calling Open:

import _ "modernc.org/sqlite"           // default "sqlite" driver
import _ "github.com/hazyhaar/pkg/trace" // "sqlite-trace" driver

func OpenMemory

func OpenMemory(t testing.TB, opts ...Option) *sql.DB

OpenMemory opens an in-memory SQLite database for testing. It sets MaxOpenConns(1) to ensure all queries hit the same in-memory database (each connection to ":memory:" creates a separate database). It registers t.Cleanup to close the database automatically.

func RunTx

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

RunTx executes fn inside a transaction with automatic retry on SQLITE_BUSY. It retries up to 3 times with 100/200/300 ms backoff.

Types

type Option

type Option func(*config)

Option customises Open behaviour.

func WithBusyTimeout

func WithBusyTimeout(ms int) Option

WithBusyTimeout sets PRAGMA busy_timeout in milliseconds. Default: 10000.

func WithCacheSize

func WithCacheSize(pages int) Option

WithCacheSize sets PRAGMA cache_size. 0 (default) keeps the SQLite default. Negative values are KiB (e.g. -64000 = 64 MB).

func WithDriver

func WithDriver(name string) Option

WithDriver sets the database/sql driver name. Default: "sqlite".

func WithMkdirAll

func WithMkdirAll() Option

WithMkdirAll creates parent directories of the database path before opening.

func WithSchema

func WithSchema(s string) Option

WithSchema queues inline SQL to execute after pragmas are applied.

func WithSchemaFile

func WithSchemaFile(path string) Option

WithSchemaFile queues an .sql file to read and execute after pragmas.

func WithSynchronous

func WithSynchronous(mode string) Option

WithSynchronous sets PRAGMA synchronous. Default: "NORMAL".

func WithTrace

func WithTrace() Option

WithTrace is shorthand for WithDriver("sqlite-trace").

func WithoutForeignKeys

func WithoutForeignKeys() Option

WithoutForeignKeys disables PRAGMA foreign_keys (rarely needed).

func WithoutPing

func WithoutPing() Option

WithoutPing skips the db.Ping() verification after opening.