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

import dbmysql "code.nochebuena.dev/einherjar/db-mysql"

db := dbmysql.New(logger, dbmysql.DefaultConfig())
lc.Append(db)   // OnInit opens pool; OnStop closes it
// db is observability.Checkable (PING health check, LevelCritical):
srv.Get("/health", health.NewHandler(logger, db).ServeHTTP)

Querying

// 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

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:

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.

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

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

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.