Rene Nochebuena
237cba9bad
Pure-Go CGO-free SQLite client with launcher lifecycle, write-mutex serialisation, health check, unit-of-work via context injection, and structured error mapping. What's included: - Executor / Tx / Client / Component interfaces using database/sql native types - Tx.Commit() / Tx.Rollback() without ctx, matching the honest database/sql contract - New(logger, cfg) constructor; database opened in OnInit - Config struct with env-tag support; default Pragmas: WAL + 5s busy timeout + FK enforcement - PRAGMA foreign_keys = ON enforced explicitly in OnInit - writeMu sync.Mutex acquired by UnitOfWork.Do to serialise writes and prevent SQLITE_BUSY - UnitOfWork via context injection; GetExecutor(ctx) returns active Tx or *sql.DB - HandleError mapping SQLite extended error codes to xerrors codes (unique/primary-key → AlreadyExists, foreign-key → InvalidInput, ErrNoRows → NotFound) - health.Checkable at LevelCritical; pure-Go modernc.org/sqlite driver (CGO_ENABLED=0 compatible) Tested-via: todo-api POC integration Reviewed-against: docs/adr/
50 lines
1.1 KiB
Markdown
50 lines
1.1 KiB
Markdown
# 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
|
|
|
|
```go
|
|
db := sqlite.New(logger, cfg)
|
|
lc.Append(db)
|
|
r.Get("/health", health.NewHandler(logger, db))
|
|
```
|
|
|
|
## Testing with :memory:
|
|
|
|
```go
|
|
db := sqlite.New(logger, sqlite.Config{Path: ":memory:"})
|
|
db.OnInit()
|
|
```
|
|
|
|
## Unit of Work
|
|
|
|
```go
|
|
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`.
|