feat(db-mysql): initial implementation — database/sql MySQL with lifecycle and UnitOfWork (v1.0.0)
Introduces code.nochebuena.dev/einherjar/db-mysql — the MySQL database starter for the Einherjar framework. Absorbs the mysql package from micro-lib using the go-sql-driver/mysql driver, replacing fmt.Errorf wrapping with core/xerrors. Interfaces (CT-6: one TypeSpec per file): - Executor — ExecContext, QueryContext, QueryRowContext (database/sql types) - Tx — Executor + Commit(), Rollback() — no ctx; honest database/sql contract - Provider — GetExecutor, Begin, BeginTx, Ping, HandleError - Component — lifecycle.Component + observability.Checkable + Provider + Stats() - UnitOfWork — Do(ctx, fn) Implementation: - New(logger, cfg) Component — pool not created until OnInit - OnInit: sql.Open + SetMaxOpenConns/SetMaxIdleConns/SetConnMaxLifetime/SetConnMaxIdleTime - OnStart: Ping with 5s timeout; logs "mysql: connected" - OnStop: db.Close(); logs "mysql: closing pool" - GetExecutor: returns active Tx from context (ctxTxKey) or *sql.DB; explicit nil return when db uninitialized to avoid typed-nil interface pitfall - Begin/BeginTx: wraps db.BeginTx(*sql.TxOptions); wrapped in xerrors on error - HealthCheck: delegates to Ping; Priority LevelCritical - Stats() sql.DBStats — zero value when pool uninitialized - NewUnitOfWork(logger, provider) UnitOfWork — Begin+inject+commit/rollback; no write mutex (MySQL is a server DB with internal concurrency control) - HandleError: 1062→ErrAlreadyExists, 1216/1217/1451/1452→ErrInvalidInput, sql.ErrNoRows→ErrNotFound, all others→ErrInternal - Driver imported as mysqldrv alias in errors.go to avoid package-name collision; registered via blank import in new.go Config (EINHERJAR_MYSQL_* env vars): Host, Port(3306), User, Password, Name, MaxConns(5), MinConns(2), MaxConnLifetime(1h), MaxConnIdleTime(30m), Charset(utf8mb4), Loc(UTC), ParseTime(true) - Component interface embeds observability.Identifiable; identifiable.go implements ModulePath and ModuleVersion via runtime/debug.ReadBuildInfo() — prints in launcher banner
This commit is contained in:
139
README.md
Normal file
139
README.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# einherjar/db-mysql
|
||||
|
||||
[](https://code.nochebuena.dev/einherjar/db-mysql)
|
||||
[](LICENSE)
|
||||
[](https://go.dev)
|
||||
[]()
|
||||
|
||||
> A warrior's deeds are committed to stone so that what they built survives the builder.
|
||||
|
||||
`code.nochebuena.dev/einherjar/db-mysql` is the MySQL/MariaDB database component of the Einherjar framework. It wraps `database/sql` with `go-sql-driver/mysql` behind a lifecycle-aware `Component`, exposes a uniform `Executor` interface for queries and transactions, and provides a `UnitOfWork` that injects the active transaction into context — so repositories never need to know whether they are inside a transaction or not.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Setup
|
||||
|
||||
```go
|
||||
import dbmysql "code.nochebuena.dev/einherjar/db-mysql"
|
||||
|
||||
db := dbmysql.New(logger, dbmysql.DefaultConfig())
|
||||
launcher.Append(db) // OnInit opens pool; OnStop closes it
|
||||
health.Register(db) // PING health check; LevelCritical
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
```go
|
||||
// GetExecutor returns the pool when called outside a UnitOfWork.
|
||||
rows, err := db.GetExecutor(ctx).QueryContext(ctx, "SELECT id, name FROM users WHERE active = ?", true)
|
||||
defer rows.Close()
|
||||
|
||||
var name string
|
||||
err := db.GetExecutor(ctx).QueryRowContext(ctx, "SELECT name FROM users WHERE id = ?", id).Scan(&name)
|
||||
```
|
||||
|
||||
### Manual transaction
|
||||
|
||||
```go
|
||||
tx, err := db.Begin(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer tx.Rollback()
|
||||
|
||||
_, err = tx.ExecContext(ctx, "UPDATE accounts SET balance = balance - ? WHERE id = ?", amount, fromID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return tx.Commit()
|
||||
```
|
||||
|
||||
`BeginTx` is available when you need explicit isolation level control:
|
||||
|
||||
```go
|
||||
tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})
|
||||
```
|
||||
|
||||
### Unit of work (recommended)
|
||||
|
||||
`UnitOfWork` wraps the transaction in context so every call to `GetExecutor` inside `uow.Do` automatically returns the active transaction. Repositories require no changes.
|
||||
|
||||
```go
|
||||
uow := dbmysql.NewUnitOfWork(logger, db)
|
||||
|
||||
err := uow.Do(ctx, func(ctx context.Context) error {
|
||||
_, err := db.GetExecutor(ctx).ExecContext(ctx, "INSERT INTO orders (...) VALUES (...)", ...)
|
||||
return err
|
||||
})
|
||||
```
|
||||
|
||||
If the function returns an error, the transaction is rolled back. If it returns nil, the transaction is committed.
|
||||
|
||||
### Error handling
|
||||
|
||||
```go
|
||||
if err := db.HandleError(someErr); err != nil {
|
||||
// MySQL error numbers mapped to xerrors:
|
||||
// 1062 ER_DUP_ENTRY → ErrAlreadyExists
|
||||
// 1216 ER_NO_REFERENCED_ROW → ErrPreconditionFailed
|
||||
// 1048 ER_BAD_NULL_ERROR → ErrInvalidInput
|
||||
// context.Canceled → ErrCancelled
|
||||
// context.DeadlineExceeded → ErrDeadlineExceeded
|
||||
}
|
||||
```
|
||||
|
||||
`HandleError` is also available as a package-level function: `dbmysql.HandleError(err)`.
|
||||
|
||||
---
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `EINHERJAR_MYSQL_HOST` | Yes | — | MySQL host |
|
||||
| `EINHERJAR_MYSQL_PORT` | No | `3306` | Listen port |
|
||||
| `EINHERJAR_MYSQL_USER` | Yes | — | Database user |
|
||||
| `EINHERJAR_MYSQL_PASSWORD` | Yes | — | Database password |
|
||||
| `EINHERJAR_MYSQL_NAME` | Yes | — | Database name |
|
||||
| `EINHERJAR_MYSQL_MAX_CONNS` | No | `5` | Maximum open connections |
|
||||
| `EINHERJAR_MYSQL_MIN_CONNS` | No | `2` | Minimum idle connections |
|
||||
| `EINHERJAR_MYSQL_MAX_CONN_LIFETIME` | No | `1h` | Maximum connection lifetime |
|
||||
| `EINHERJAR_MYSQL_MAX_CONN_IDLE_TIME` | No | `30m` | Maximum idle time before connection is closed |
|
||||
| `EINHERJAR_MYSQL_CHARSET` | No | `utf8mb4` | Connection charset |
|
||||
| `EINHERJAR_MYSQL_LOC` | No | `UTC` | Timezone location |
|
||||
| `EINHERJAR_MYSQL_PARSE_TIME` | No | `true` | Parse `DATE`/`DATETIME` as `time.Time` |
|
||||
|
||||
> **Note:** Set collation at the schema level (DDL), not in the DSN. MariaDB 11.4+ collation names exceed the 1-byte handshake limit in `go-sql-driver`.
|
||||
|
||||
---
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```
|
||||
contracts (zero dependencies)
|
||||
↑
|
||||
core
|
||||
↑
|
||||
db-mysql (contracts, core, go-sql-driver/mysql)
|
||||
↑
|
||||
your app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd db-mysql/
|
||||
go build ./...
|
||||
go vet ./...
|
||||
go test ./...
|
||||
gofmt -l .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> *The hall is built before the warriors arrive.*
|
||||
> *That is the only guarantee worth making.*
|
||||
Reference in New Issue
Block a user