README
¶
sqlite
Pure-Go SQLite client (modernc.org/sqlite, no CGO) with launcher lifecycle and health check integration.
Install
go get code.nochebuena.dev/go/sqlite
Usage
db := sqlite.New(logger, cfg)
lc.Append(db)
r.Get("/health", health.NewHandler(logger, db))
Testing with :memory:
db := sqlite.New(logger, sqlite.Config{Path: ":memory:"})
db.OnInit()
Unit of Work
uow := sqlite.NewUnitOfWork(logger, db)
err := uow.Do(ctx, func(ctx context.Context) error {
exec := db.GetExecutor(ctx) // returns the active Tx
_, err := exec.ExecContext(ctx, "INSERT INTO orders ...")
return err
})
The UnitOfWork serialises writes via an internal mutex to prevent SQLITE_BUSY errors.
Configuration
| Env var | Default | Description |
|---|---|---|
SQLITE_PATH |
required | File path or :memory: |
SQLITE_MAX_OPEN_CONNS |
1 |
Max open connections |
SQLITE_MAX_IDLE_CONNS |
1 |
Max idle connections |
SQLITE_PRAGMAS |
?_journal=WAL&_timeout=5000&_fk=true |
DSN pragmas |
Foreign key enforcement (PRAGMA foreign_keys = ON) is always enabled in OnInit.
Documentation
¶
Overview ¶
Package sqlite provides a pure-Go SQLite client (via modernc.org/sqlite) with launcher lifecycle and health check integration.
All tests can use Config{Path: ":memory:"} for fully isolated, self-contained databases.
WAL mode, foreign key enforcement, and a busy timeout are enabled by default via the Pragmas config field.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HandleError ¶
HandleError maps SQLite and database/sql errors to xerrors types.
Types ¶
type Client ¶
type Client interface {
GetExecutor(ctx context.Context) Executor
Begin(ctx context.Context) (Tx, error)
Ping(ctx context.Context) error
HandleError(err error) error
}
Client is the primary interface for consumers.
type Config ¶
type Config struct {
// Path is the SQLite file path. Use ":memory:" for in-memory databases.
Path string `env:"SQLITE_PATH,required"`
// MaxOpenConns limits concurrent connections. Default: 1.
MaxOpenConns int `env:"SQLITE_MAX_OPEN_CONNS" envDefault:"1"`
// MaxIdleConns is the number of idle connections kept in the pool.
MaxIdleConns int `env:"SQLITE_MAX_IDLE_CONNS" envDefault:"1"`
// Pragmas are appended to the DSN. Default: WAL + 5s busy timeout + FK enforcement.
Pragmas string `env:"SQLITE_PRAGMAS" envDefault:"?_journal=WAL&_timeout=5000&_fk=true"`
}
Config holds connection parameters.
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
}
Executor defines operations shared by the connection and transaction.
type Tx ¶
Tx extends Executor with commit/rollback. Honest contract: database/sql Tx does not accept ctx on Commit/Rollback.
type UnitOfWork ¶
UnitOfWork manages the transaction lifecycle via context injection.
func NewUnitOfWork ¶
func NewUnitOfWork(logger logz.Logger, client Client) UnitOfWork
NewUnitOfWork returns a UnitOfWork backed by the given client. If client is a *sqliteComponent, the write mutex is used to serialise transactions.
Source Files