commit d9d07bcb70662a68a232c49ddb412b118021506f Author: Rene Nochebuena Date: Thu Mar 19 13:21:34 2026 +0000 feat(mysql): initial stable release v0.9.0 database/sql-backed MySQL client with launcher lifecycle, 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 (sql.Result, *sql.Rows, *sql.Row) - Tx.Commit() / Tx.Rollback() without ctx, matching the honest database/sql contract - New(logger, cfg) constructor; *sql.DB opened in OnInit - Config struct with env-tag support for all pool tuning parameters - UnitOfWork via context injection; GetExecutor(ctx) returns active *sql.Tx or *sql.DB - HandleError mapping MySQLError.Number to xerrors codes (1062 → AlreadyExists, 1216/1217/1451/1452 → InvalidInput, ErrNoRows → NotFound) - Driver imported as mysqldrv alias to avoid package name collision - health.Checkable at LevelCritical; HealthCheck delegates to db.PingContext Tested-via: todo-api POC integration Reviewed-against: docs/adr/ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..54f5aae --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,26 @@ +{ + "name": "Go", + "image": "mcr.microsoft.com/devcontainers/go:2-1.25-trixie", + "features": { + "ghcr.io/devcontainers-extra/features/claude-code:1": {} + }, + "forwardPorts": [], + "postCreateCommand": "go version", + "customizations": { + "vscode": { + "settings": { + "files.autoSave": "afterDelay", + "files.autoSaveDelay": 1000, + "explorer.compactFolders": false, + "explorer.showEmptyFolders": true + }, + "extensions": [ + "golang.go", + "eamodio.golang-postfix-completion", + "quicktype.quicktype", + "usernamehw.errorlens" + ] + } + }, + "remoteUser": "vscode" +} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..221da82 --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# Binaries +*.exe +*.exe~ +*.dll +*.so +*.dylib + +# Test binary, built with go test -c +*.test + +# Output of go build +*.out + +# Dependency directory +vendor/ + +# Go workspace file +go.work +go.work.sum + +# Environment files +.env +.env.* + +# Editor / IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# VCS files +COMMIT.md +RELEASE.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..640d141 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog + +All notable changes to this module will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.9.0] - 2026-03-18 + +### Added + +- `Executor` interface: `ExecContext`, `QueryContext`, `QueryRowContext` using `database/sql` types (`sql.Result`, `*sql.Rows`, `*sql.Row`). +- `Tx` interface: embeds `Executor` and adds `Commit() error` and `Rollback() error` (no context argument, matching `database/sql` semantics). +- `Client` interface: `GetExecutor(ctx context.Context) Executor`, `Begin(ctx context.Context) (Tx, error)`, `Ping(ctx context.Context) error`, `HandleError(err error) error`. +- `Component` interface: composes `launcher.Component`, `health.Checkable`, and `Client`. +- `UnitOfWork` interface: `Do(ctx context.Context, fn func(ctx context.Context) error) error`. +- `Config` struct: fields `Host`, `Port`, `User`, `Password`, `Name`, `MaxConns`, `MinConns`, `MaxConnLifetime`, `MaxConnIdleTime`; settable via `MYSQL_*` environment variables with defaults (port `3306`, max conns `5`, idle conns `2`, lifetime `1h`, idle time `30m`). +- `Config.DSN() string`: constructs a `go-sql-driver` DSN in `user:pass@tcp(host:port)/db?parseTime=true&loc=UTC` format. +- `New(logger logz.Logger, cfg Config) Component`: returns a `*sql.DB`-backed component; the connection is opened lazily in `OnInit`. +- Lifecycle hooks: `OnInit` calls `sql.Open`, sets pool limits, and parses duration config fields; `OnStart` pings with a 5-second timeout; `OnStop` closes the `*sql.DB`. +- `health.Checkable` implementation: `HealthCheck` delegates to `Ping`; `Name()` returns `"mysql"`; `Priority()` returns `health.LevelCritical`. +- `NewUnitOfWork(logger logz.Logger, client Client) UnitOfWork`: wraps a `Client` to provide transactional `Do` semantics; rolls back and logs on error, commits on success. +- `HandleError(err error) error` (package-level function): maps `*mysqldrv.MySQLError` error numbers to xerrors — `1062` (duplicate entry) → `ErrAlreadyExists`; `1216`, `1217`, `1451`, `1452` (foreign key violations) → `ErrInvalidInput`; `sql.ErrNoRows` → `ErrNotFound`; all other errors → `ErrInternal`. +- Transaction context injection: the active `*sql.Tx` is stored under an unexported `ctxTxKey{}` context key; `GetExecutor` returns it when found, otherwise returns `*sql.DB`. +- All `*sql.DB` reads guarded by `sync.RWMutex` for safe concurrent access. +- `go-sql-driver/mysql` is imported with a blank identifier in `mysql.go` for driver side-effect registration, and as `mysqldrv` in `errors.go` to avoid the package name collision. + +### Design Notes + +- `Tx.Commit()` and `Tx.Rollback()` intentionally omit a `context.Context` argument, honestly reflecting the `database/sql` limitation rather than accepting and ignoring one. +- The module is structurally parallel to `postgres` but uses `database/sql` types throughout; the two modules are intentionally type-incompatible. +- MySQL error codes are matched by numeric constant via `MySQLError.Number`, not by string parsing, for stability across MySQL and MariaDB versions. + +[0.9.0]: https://code.nochebuena.dev/go/mysql/releases/tag/v0.9.0 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1477220 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,71 @@ +# mysql + +database/sql-backed MySQL client with launcher lifecycle, health check integration, and unit-of-work transaction management. + +## Purpose + +Provides a `Component` that manages a `*sql.DB` connection pool, satisfies the `launcher.Component` lifecycle hooks (`OnInit`, `OnStart`, `OnStop`), and implements `health.Checkable` (priority: critical). Also provides `NewUnitOfWork` for wrapping multiple repository operations in a single transaction via context injection. + +## Tier & Dependencies + +**Tier 3** (infrastructure) — depends on: +- `code.nochebuena.dev/go/health` (Tier 1) +- `code.nochebuena.dev/go/launcher` (Tier 1) +- `code.nochebuena.dev/go/logz` (Tier 0) +- `code.nochebuena.dev/go/xerrors` (Tier 0) +- `github.com/go-sql-driver/mysql` (external driver) + +## Key Design Decisions + +- **database/sql native types** (ADR-001): `Executor` uses `sql.Result`, `*sql.Rows`, and `*sql.Row`. Method names follow `database/sql` convention: `ExecContext`, `QueryContext`, `QueryRowContext`. The `postgres` module uses pgx types; these two are intentionally incompatible. +- **No ctx on Tx.Commit/Rollback** (ADR-002): `database/sql` does not support per-call context on `Commit` or `Rollback`. The `mysql.Tx` interface honestly omits `ctx` from these methods rather than accepting and ignoring it. `UnitOfWork.Do` calls `tx.Commit()` and `tx.Rollback()` without context. +- **Driver import alias** (ADR-003): The `go-sql-driver/mysql` driver package name collides with the package name `mysql`. In `errors.go` it is imported as `mysqldrv` to disambiguate. In `mysql.go` it is imported with `_` for side-effect registration only. +- **Error mapping via MySQLError.Number**: `HandleError` type-asserts to `*mysqldrv.MySQLError` and switches on `.Number`. Error codes 1062 (duplicate key) → `ErrAlreadyExists`; 1216, 1217, 1451, 1452 (foreign key violations) → `ErrInvalidInput`. `sql.ErrNoRows` → `ErrNotFound`. +- **UnitOfWork via context injection**: Same pattern as the `postgres` module — active `*sql.Tx` is stored under `ctxTxKey{}` in the context. `GetExecutor(ctx)` returns the transaction if present, otherwise `*sql.DB`. + +## Patterns + +Lifecycle registration: + +```go +db := mysql.New(logger, cfg) +lc.Append(db) +r.Get("/health", health.NewHandler(logger, db)) +``` + +Unit of Work: + +```go +uow := mysql.NewUnitOfWork(logger, db) +err := uow.Do(ctx, func(ctx context.Context) error { + exec := db.GetExecutor(ctx) // returns active *sql.Tx + _, err := exec.ExecContext(ctx, "INSERT INTO ...") + return err +}) +``` + +Error handling in repository code: + +```go +rows, err := db.GetExecutor(ctx).QueryContext(ctx, "SELECT ...") +if err != nil { + return db.HandleError(err) +} +defer rows.Close() +``` + +## What to Avoid + +- Do not use pgx types (`pgx.Rows`, `pgconn.CommandTag`, etc.) in code that depends on this module. This is `database/sql`; the two are distinct. +- Do not add a `ctx` parameter to `Tx.Commit()` or `Tx.Rollback()`. `database/sql` does not support it; accepting and silently ignoring a context would be misleading. +- Do not import `github.com/go-sql-driver/mysql` directly in application code to type-assert on `*mysql.MySQLError`. Use `db.HandleError(err)` instead — it maps driver errors to portable `xerrors` codes. +- Do not match MySQL errors by message string. Use `HandleError` which switches on `mysqldrv.MySQLError.Number`. +- Do not add package-level `*sql.DB` variables. `mysqlComponent` is the unit of construction; use dependency injection. +- Do not forget `defer rows.Close()` after `QueryContext` — unclosed `*sql.Rows` hold connections from the pool. + +## Testing Notes + +- `compliance_test.go` asserts at compile time that `mysql.New(...)` satisfies `mysql.Component`. +- Integration tests (real queries, transaction rollback) require a live MySQL or MariaDB instance, typically provided by a CI service container. +- `HandleError` can be unit-tested by constructing `*mysqldrv.MySQLError{Number: 1062}` directly — no database connection needed. +- Pool initialization happens in `OnInit`, not `New`. Mocking the `Client` interface bypasses pool setup entirely, making unit tests straightforward. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0b33b48 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 NOCHEBUENADEV + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a422b88 --- /dev/null +++ b/README.md @@ -0,0 +1,54 @@ +# mysql + +`database/sql`-backed MySQL client with launcher lifecycle and health check integration. + +## Install + +``` +go get code.nochebuena.dev/go/mysql +``` + +## Usage + +```go +db := mysql.New(logger, cfg) +lc.Append(db) +r.Get("/health", health.NewHandler(logger, db)) +``` + +## Unit of Work + +```go +uow := mysql.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 +}) +``` + +## Error mapping + +```go +if err := db.HandleError(err); err != nil { ... } +``` + +| MySQL error | xerrors code | +|---|---| +| 1062 (ER_DUP_ENTRY) | `ErrAlreadyExists` | +| 1216/1217/1451/1452 (foreign key) | `ErrInvalidInput` | +| `sql.ErrNoRows` | `ErrNotFound` | +| anything else | `ErrInternal` | + +## Configuration + +| Env var | Default | Description | +|---|---|---| +| `MYSQL_HOST` | required | Database host | +| `MYSQL_PORT` | `3306` | Database port | +| `MYSQL_USER` | required | Username | +| `MYSQL_PASSWORD` | required | Password | +| `MYSQL_NAME` | required | Database name | +| `MYSQL_MAX_CONNS` | `5` | Max open connections | +| `MYSQL_MIN_CONNS` | `2` | Max idle connections | diff --git a/compliance_test.go b/compliance_test.go new file mode 100644 index 0000000..10604f1 --- /dev/null +++ b/compliance_test.go @@ -0,0 +1,8 @@ +package mysql_test + +import ( + "code.nochebuena.dev/go/logz" + "code.nochebuena.dev/go/mysql" +) + +var _ mysql.Component = mysql.New(logz.New(logz.Options{}), mysql.Config{}) diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..ad218c0 --- /dev/null +++ b/doc.go @@ -0,0 +1,8 @@ +// Package mysql provides a database/sql-backed MySQL client with launcher and health integration. +// +// Usage: +// +// db := mysql.New(logger, cfg) +// lc.Append(db) +// r.Get("/health", health.NewHandler(logger, db)) +package mysql diff --git a/docs/adr/ADR-001-database-sql-native-types.md b/docs/adr/ADR-001-database-sql-native-types.md new file mode 100644 index 0000000..36e8ef4 --- /dev/null +++ b/docs/adr/ADR-001-database-sql-native-types.md @@ -0,0 +1,37 @@ +# ADR-001: database/sql Native Types + +**Status:** Accepted +**Date:** 2026-03-18 + +## Context + +Go's standard `database/sql` package was designed as a database-agnostic abstraction. Using it for MySQL is the conventional approach: the `go-sql-driver/mysql` package registers itself as a `database/sql` driver, and all query operations are expressed through `*sql.DB`, `*sql.Tx`, `*sql.Rows`, `*sql.Row`, and `sql.Result`. + +An alternative would be to use a MySQL-specific client library analogous to pgx for PostgreSQL. However, there is no dominant MySQL-specific client with the same level of ecosystem adoption and capability that pgx has for PostgreSQL. Using `database/sql` with a standard driver is the practical and broadly understood choice. + +The `postgres` module deliberately chose pgx native types. MySQL is the counterpart — it uses `database/sql` native types. The two modules are not interchangeable, which is by design. + +## Decision + +The `mysql` module's `Executor` interface uses `database/sql` types throughout: + +```go +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 +} +``` + +Method names follow the `database/sql` convention (`ExecContext`, `QueryContext`, `QueryRowContext`) rather than the pgx convention (`Exec`, `Query`, `QueryRow`). This matches the underlying `*sql.DB` and `*sql.Tx` method signatures exactly, meaning `*sql.DB` satisfies `Executor` structurally without any wrapping. + +The `mysqlComponent` embeds `*sql.DB` and delegates directly. `mysqlTx` wraps `*sql.Tx` and delegates to it. + +## Consequences + +- **Positive**: Familiarity — `database/sql` is Go's standard library API, known to most Go developers. +- **Positive**: `*sql.DB` and `*sql.Tx` natively satisfy the `Executor` interface, reducing the need for wrapper code. +- **Positive**: Any `database/sql`-compatible driver (MariaDB, TiDB, etc.) could be substituted by changing the driver registration without touching the interface. +- **Negative**: `sql.Result` is less informative than `pgconn.CommandTag` (no command string, only `LastInsertId` and `RowsAffected`). Applications that need PostgreSQL-style command metadata must use the `postgres` module. +- **Negative**: `*sql.Rows` must be closed after use (`defer rows.Close()`). Forgetting this leaks connections back to the pool. +- **Note**: The method naming difference from `postgres` (`ExecContext` vs `Exec`) is intentional and honest — it matches the actual API of the underlying library rather than artificially unifying the two modules. diff --git a/docs/adr/ADR-002-no-ctx-on-tx-commit-rollback.md b/docs/adr/ADR-002-no-ctx-on-tx-commit-rollback.md new file mode 100644 index 0000000..0e81a2e --- /dev/null +++ b/docs/adr/ADR-002-no-ctx-on-tx-commit-rollback.md @@ -0,0 +1,42 @@ +# ADR-002: No Context on Tx.Commit and Tx.Rollback + +**Status:** Accepted +**Date:** 2026-03-18 + +## Context + +The `postgres` module's `Tx` interface defines `Commit(ctx context.Context) error` and `Rollback(ctx context.Context) error` because `pgx.Tx` supports context-aware commit and rollback — the operation can be cancelled if the context is already done. + +The `database/sql` standard library's `*sql.Tx` does not support this. Its `Commit()` and `Rollback()` methods have no context parameter: + +```go +// from database/sql: +func (tx *Tx) Commit() error +func (tx *Tx) Rollback() error +``` + +Adding a `ctx` parameter to the `mysql.Tx` interface would be a lie: the implementation would have to ignore the context, potentially masking cancellations or deadlines that callers believe they are enforcing. + +## Decision + +The `mysql.Tx` interface is defined with context-free commit and rollback, matching the `database/sql` contract honestly: + +```go +type Tx interface { + Executor + Commit() error + Rollback() error +} +``` + +The `UnitOfWork.Do` implementation calls `tx.Rollback()` and `tx.Commit()` without passing a context. This is consistent with the interface definition and with `database/sql` semantics. + +This means `mysql.Tx` and `postgres.Tx` are not structurally compatible — this is intentional. Callers must not attempt to use one in place of the other. + +## Consequences + +- **Positive**: The interface is an honest representation of what `database/sql` provides. No silent context-ignore bugs. +- **Positive**: `mysqlTx.Commit()` and `mysqlTx.Rollback()` delegate directly to `*sql.Tx.Commit()` and `*sql.Tx.Rollback()` with no wrapper complexity. +- **Negative**: A commit or rollback cannot be cancelled mid-flight via context in MySQL. If the database is slow or unreachable during commit, the goroutine blocks until the driver-level timeout fires. +- **Negative**: The API asymmetry between `mysql.Tx` and `postgres.Tx` means that generic code written against one cannot be used against the other. This is a known limitation of the design and the reason the two modules are separate. +- **Note**: Go 1.15 added `*sql.Tx.Commit()` and `*sql.Tx.Rollback()` that honour the context passed to `BeginTx` — but still do not accept a per-call context. The limitation is inherent to `database/sql`. diff --git a/docs/adr/ADR-003-driver-alias-name-collision.md b/docs/adr/ADR-003-driver-alias-name-collision.md new file mode 100644 index 0000000..04d1337 --- /dev/null +++ b/docs/adr/ADR-003-driver-alias-name-collision.md @@ -0,0 +1,47 @@ +# ADR-003: Driver Import Alias to Avoid Name Collision + +**Status:** Accepted +**Date:** 2026-03-18 + +## Context + +The `errors.go` file in the `mysql` package uses the `go-sql-driver/mysql` package to type-assert MySQL error values: + +```go +import "github.com/go-sql-driver/mysql" +``` + +The Go package name of `github.com/go-sql-driver/mysql` is also `mysql` — the same as the package being authored. This creates an ambiguous identifier: within `errors.go`, unqualified references to `mysql` would be interpreted as the current package, and the driver's `MySQLError` type would be inaccessible without a disambiguating qualifier. + +## Decision + +The driver is imported under the alias `mysqldrv`: + +```go +import mysqldrv "github.com/go-sql-driver/mysql" +``` + +In `mysql.go`, the driver is imported for its side effect only (registering itself with `database/sql`) using the blank identifier: + +```go +import _ "github.com/go-sql-driver/mysql" // register driver +``` + +The alias `mysqldrv` is used exclusively in `errors.go`, where `MySQLError` must be referenced by name for type assertion via `errors.As`: + +```go +var mysqlErr *mysqldrv.MySQLError +if errors.As(err, &mysqlErr) { + switch mysqlErr.Number { ... } +} +``` + +The alias is chosen to be recognisable — `drv` is a conventional abbreviation for "driver" — while making the boundary between package code and driver code immediately apparent at each call site. + +## Consequences + +- **Positive**: No ambiguity between the `mysql` package and the `mysql` driver. The alias makes the distinction explicit at every use site. +- **Positive**: The blank import in `mysql.go` documents clearly that the driver is needed only for side-effect registration. +- **Positive**: If the driver package is ever replaced (e.g., with a fork or an alternative driver), only the import alias and the `mysqlErr.Number` switch need to change — the rest of the package is unaffected. +- **Negative**: Readers unfamiliar with the convention must understand that `mysqldrv.MySQLError` refers to the external driver, not the current package. The alias name and the import comment mitigate this. +- **Note**: Error number constants (1062, 1216, 1217, 1451, 1452) are not exported by `go-sql-driver/mysql`, so they are used as integer literals with inline comments identifying the MySQL error name (e.g., `// ER_DUP_ENTRY`). diff --git a/errors.go b/errors.go new file mode 100644 index 0000000..0e7d047 --- /dev/null +++ b/errors.go @@ -0,0 +1,31 @@ +package mysql + +import ( + "database/sql" + "errors" + + mysqldrv "github.com/go-sql-driver/mysql" + + "code.nochebuena.dev/go/xerrors" +) + +// HandleError maps MySQL and database/sql errors to xerrors types. +// Also available as client.HandleError(err). +func HandleError(err error) error { + if err == nil { + return nil + } + var mysqlErr *mysqldrv.MySQLError + if errors.As(err, &mysqlErr) { + switch mysqlErr.Number { + case 1062: // ER_DUP_ENTRY + return xerrors.New(xerrors.ErrAlreadyExists, "record already exists").WithError(err) + case 1216, 1217, 1451, 1452: // foreign key violations + return xerrors.New(xerrors.ErrInvalidInput, "data integrity violation").WithError(err) + } + } + if errors.Is(err, sql.ErrNoRows) { + return xerrors.New(xerrors.ErrNotFound, "record not found").WithError(err) + } + return xerrors.New(xerrors.ErrInternal, "unexpected database error").WithError(err) +} diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..79814b7 --- /dev/null +++ b/go.mod @@ -0,0 +1,13 @@ +module code.nochebuena.dev/go/mysql + +go 1.25 + +require ( + code.nochebuena.dev/go/health v0.9.0 + code.nochebuena.dev/go/launcher v0.9.0 + code.nochebuena.dev/go/logz v0.9.0 + code.nochebuena.dev/go/xerrors v0.9.0 + github.com/go-sql-driver/mysql v1.8.1 +) + +require filippo.io/edwards25519 v1.1.0 // indirect diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..14140b8 --- /dev/null +++ b/go.sum @@ -0,0 +1,12 @@ +code.nochebuena.dev/go/health v0.9.0 h1:x0UKjC7CHAE3AgwyFzCyjmGJIjoLBBxeOHxXuqpbKwI= +code.nochebuena.dev/go/health v0.9.0/go.mod h1:f3IsNtU60JSn5yXmBBh9XOvr5pRyEah5+wS4tjDQZso= +code.nochebuena.dev/go/launcher v0.9.0 h1:dJHonA9Xm03AQKK0919FJaQn9ZKHZ+RZfB9yxjnx3TA= +code.nochebuena.dev/go/launcher v0.9.0/go.mod h1:IBtntmbnyddukjEhxlc7Ysdzz9nZsnd9+8FzAIHt77g= +code.nochebuena.dev/go/logz v0.9.0 h1:wfV7vtI4V/8ED7Hm31Fbql7Y5iOGrlHN4X8Z5ajTZZE= +code.nochebuena.dev/go/logz v0.9.0/go.mod h1:qODhSbKb+tWE7rdhHLcKweiP5CgwIaWoZxadCT3bQV8= +code.nochebuena.dev/go/xerrors v0.9.0 h1:8wrDto7e44ZW1YPOnT6JrxYXTqnvNuKpAO1/5bcT4TE= +code.nochebuena.dev/go/xerrors v0.9.0/go.mod h1:mtXo7xscBreCB7w7smlBP5Onv8H1HVohCvF0I/VXbAY= +filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA= +filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4= +github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y= +github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg= diff --git a/mysql.go b/mysql.go new file mode 100644 index 0000000..5ff8474 --- /dev/null +++ b/mysql.go @@ -0,0 +1,250 @@ +package mysql + +import ( + "context" + "database/sql" + "fmt" + "net/url" + "sync" + "time" + + _ "github.com/go-sql-driver/mysql" // register driver + + "code.nochebuena.dev/go/health" + "code.nochebuena.dev/go/launcher" + "code.nochebuena.dev/go/logz" +) + +// Executor defines operations shared by pool and transaction. +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 +} + +// Tx extends Executor with commit/rollback (no ctx — sql.Tx limitation). +type Tx interface { + Executor + Commit() error + Rollback() error +} + +// Client is the database access interface. +type Client interface { + GetExecutor(ctx context.Context) Executor + Begin(ctx context.Context) (Tx, error) + Ping(ctx context.Context) error + HandleError(err error) error +} + +// Component bundles launcher lifecycle, health check, and database client. +type Component interface { + launcher.Component + health.Checkable + Client +} + +// UnitOfWork wraps operations in a single database transaction. +type UnitOfWork interface { + Do(ctx context.Context, fn func(ctx context.Context) error) error +} + +// Config holds MySQL connection settings. +type Config struct { + Host string `env:"MYSQL_HOST,required"` + Port int `env:"MYSQL_PORT" envDefault:"3306"` + User string `env:"MYSQL_USER,required"` + Password string `env:"MYSQL_PASSWORD,required"` + Name string `env:"MYSQL_NAME,required"` + MaxConns int `env:"MYSQL_MAX_CONNS" envDefault:"5"` + MinConns int `env:"MYSQL_MIN_CONNS" envDefault:"2"` + MaxConnLifetime string `env:"MYSQL_MAX_CONN_LIFETIME" envDefault:"1h"` + MaxConnIdleTime string `env:"MYSQL_MAX_CONN_IDLE_TIME" envDefault:"30m"` +} + +// DSN constructs a MySQL DSN from the configuration. +func (c Config) DSN() string { + u := &url.URL{ + Scheme: "mysql", + User: url.UserPassword(c.User, c.Password), + Host: fmt.Sprintf("%s:%d", c.Host, c.Port), + Path: "/" + c.Name, + } + q := u.Query() + q.Set("parseTime", "true") + q.Set("loc", "UTC") + u.RawQuery = q.Encode() + // go-sql-driver uses user:pass@tcp(host:port)/db?params + return fmt.Sprintf("%s:%s@tcp(%s:%d)/%s?%s", + c.User, c.Password, c.Host, c.Port, c.Name, q.Encode()) +} + +// ctxTxKey is the context key for the active transaction. +type ctxTxKey struct{} + +// --- mysqlComponent --- + +type mysqlComponent struct { + logger logz.Logger + cfg Config + db *sql.DB + mu sync.RWMutex +} + +// New returns a mysql Component. Call lc.Append(db) to manage its lifecycle. +func New(logger logz.Logger, cfg Config) Component { + return &mysqlComponent{logger: logger, cfg: cfg} +} + +func (c *mysqlComponent) OnInit() error { + db, err := sql.Open("mysql", c.cfg.DSN()) + if err != nil { + return fmt.Errorf("mysql: open: %w", err) + } + db.SetMaxOpenConns(c.cfg.MaxConns) + db.SetMaxIdleConns(c.cfg.MinConns) + if c.cfg.MaxConnLifetime != "" { + d, err := time.ParseDuration(c.cfg.MaxConnLifetime) + if err != nil { + return fmt.Errorf("MYSQL_MAX_CONN_LIFETIME: %w", err) + } + db.SetConnMaxLifetime(d) + } + if c.cfg.MaxConnIdleTime != "" { + d, err := time.ParseDuration(c.cfg.MaxConnIdleTime) + if err != nil { + return fmt.Errorf("MYSQL_MAX_CONN_IDLE_TIME: %w", err) + } + db.SetConnMaxIdleTime(d) + } + c.mu.Lock() + c.db = db + c.mu.Unlock() + return nil +} + +func (c *mysqlComponent) OnStart() error { + ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) + defer cancel() + if err := c.Ping(ctx); err != nil { + return fmt.Errorf("mysql: ping failed: %w", err) + } + c.logger.Info("mysql: connected") + return nil +} + +func (c *mysqlComponent) OnStop() error { + c.mu.Lock() + defer c.mu.Unlock() + if c.db != nil { + c.logger.Info("mysql: closing pool") + _ = c.db.Close() + c.db = nil + } + return nil +} + +func (c *mysqlComponent) Ping(ctx context.Context) error { + c.mu.RLock() + db := c.db + c.mu.RUnlock() + if db == nil { + return fmt.Errorf("mysql: not initialized") + } + return db.PingContext(ctx) +} + +func (c *mysqlComponent) GetExecutor(ctx context.Context) Executor { + if tx, ok := ctx.Value(ctxTxKey{}).(Executor); ok { + return tx + } + c.mu.RLock() + db := c.db + c.mu.RUnlock() + return db +} + +func (c *mysqlComponent) Begin(ctx context.Context) (Tx, error) { + c.mu.RLock() + db := c.db + c.mu.RUnlock() + if db == nil { + return nil, fmt.Errorf("mysql: not initialized") + } + tx, err := db.BeginTx(ctx, nil) + if err != nil { + return nil, err + } + return &mysqlTx{Tx: tx}, nil +} + +func (c *mysqlComponent) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) { + c.mu.RLock() + db := c.db + c.mu.RUnlock() + return db.ExecContext(ctx, query, args...) +} + +func (c *mysqlComponent) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) { + c.mu.RLock() + db := c.db + c.mu.RUnlock() + return db.QueryContext(ctx, query, args...) +} + +func (c *mysqlComponent) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row { + c.mu.RLock() + db := c.db + c.mu.RUnlock() + return db.QueryRowContext(ctx, query, args...) +} + +func (c *mysqlComponent) HandleError(err error) error { return HandleError(err) } + +// health.Checkable +func (c *mysqlComponent) HealthCheck(ctx context.Context) error { return c.Ping(ctx) } +func (c *mysqlComponent) Name() string { return "mysql" } +func (c *mysqlComponent) Priority() health.Level { return health.LevelCritical } + +// --- mysqlTx --- + +type mysqlTx struct{ *sql.Tx } + +func (t *mysqlTx) ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) { + return t.Tx.ExecContext(ctx, query, args...) +} +func (t *mysqlTx) QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error) { + return t.Tx.QueryContext(ctx, query, args...) +} +func (t *mysqlTx) QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row { + return t.Tx.QueryRowContext(ctx, query, args...) +} +func (t *mysqlTx) Commit() error { return t.Tx.Commit() } +func (t *mysqlTx) Rollback() error { return t.Tx.Rollback() } + +// --- UnitOfWork --- + +type unitOfWork struct { + logger logz.Logger + client Client +} + +// NewUnitOfWork returns a UnitOfWork backed by the given client. +func NewUnitOfWork(logger logz.Logger, client Client) UnitOfWork { + return &unitOfWork{logger: logger, client: client} +} + +func (u *unitOfWork) Do(ctx context.Context, fn func(ctx context.Context) error) error { + tx, err := u.client.Begin(ctx) + if err != nil { + return fmt.Errorf("mysql: begin transaction: %w", err) + } + ctx = context.WithValue(ctx, ctxTxKey{}, tx) + if err := fn(ctx); err != nil { + if rbErr := tx.Rollback(); rbErr != nil { + u.logger.Error("mysql: rollback failed", rbErr) + } + return err + } + return tx.Commit() +} diff --git a/mysql_test.go b/mysql_test.go new file mode 100644 index 0000000..3159f44 --- /dev/null +++ b/mysql_test.go @@ -0,0 +1,166 @@ +package mysql + +import ( + "context" + "database/sql" + "errors" + "testing" + + mysqldrv "github.com/go-sql-driver/mysql" + + "code.nochebuena.dev/go/health" + "code.nochebuena.dev/go/logz" + "code.nochebuena.dev/go/xerrors" +) + +func newLogger() logz.Logger { return logz.New(logz.Options{}) } + +// --- New / name / priority --- + +func TestNew(t *testing.T) { + if New(newLogger(), Config{}) == nil { + t.Fatal("New returned nil") + } +} + +func TestComponent_Name(t *testing.T) { + c := New(newLogger(), Config{}).(health.Checkable) + if c.Name() != "mysql" { + t.Errorf("want mysql, got %s", c.Name()) + } +} + +func TestComponent_Priority(t *testing.T) { + c := New(newLogger(), Config{}).(health.Checkable) + if c.Priority() != health.LevelCritical { + t.Error("Priority() != LevelCritical") + } +} + +func TestComponent_OnStop_NilDB(t *testing.T) { + c := &mysqlComponent{logger: newLogger()} + if err := c.OnStop(); err != nil { + t.Errorf("OnStop with nil db: %v", err) + } +} + +// --- Config.DSN --- + +func TestConfig_DSN(t *testing.T) { + cfg := Config{Host: "localhost", Port: 3306, User: "root", Password: "pass", Name: "mydb"} + dsn := cfg.DSN() + if dsn == "" { + t.Fatal("DSN empty") + } + for _, want := range []string{"root", "localhost", "3306", "mydb"} { + if !strContains(dsn, want) { + t.Errorf("DSN %q missing %q", dsn, want) + } + } +} + +// --- HandleError --- + +func TestHandleError_Nil(t *testing.T) { + if err := HandleError(nil); err != nil { + t.Errorf("want nil, got %v", err) + } +} + +func TestHandleError_DuplicateEntry(t *testing.T) { + assertCode(t, HandleError(&mysqldrv.MySQLError{Number: 1062}), xerrors.ErrAlreadyExists) +} + +func TestHandleError_ForeignKey(t *testing.T) { + assertCode(t, HandleError(&mysqldrv.MySQLError{Number: 1452}), xerrors.ErrInvalidInput) +} + +func TestHandleError_NoRows(t *testing.T) { + assertCode(t, HandleError(sql.ErrNoRows), xerrors.ErrNotFound) +} + +func TestHandleError_Generic(t *testing.T) { + assertCode(t, HandleError(errors.New("boom")), xerrors.ErrInternal) +} + +// --- UnitOfWork --- + +type mockTx struct{ committed, rolledBack bool } + +func (m *mockTx) ExecContext(ctx context.Context, q string, args ...any) (sql.Result, error) { + return nil, nil +} +func (m *mockTx) QueryContext(ctx context.Context, q string, args ...any) (*sql.Rows, error) { + return nil, nil +} +func (m *mockTx) QueryRowContext(ctx context.Context, q string, args ...any) *sql.Row { return nil } +func (m *mockTx) Commit() error { m.committed = true; return nil } +func (m *mockTx) Rollback() error { m.rolledBack = true; return nil } + +type mockClient struct{ tx *mockTx } + +func (m *mockClient) Begin(ctx context.Context) (Tx, error) { return m.tx, nil } +func (m *mockClient) Ping(ctx context.Context) error { return nil } +func (m *mockClient) HandleError(err error) error { return HandleError(err) } +func (m *mockClient) GetExecutor(ctx context.Context) Executor { + if tx, ok := ctx.Value(ctxTxKey{}).(Executor); ok { + return tx + } + return nil +} + +func TestUnitOfWork_Commit(t *testing.T) { + tx := &mockTx{} + uow := NewUnitOfWork(newLogger(), &mockClient{tx: tx}) + if err := uow.Do(context.Background(), func(ctx context.Context) error { return nil }); err != nil { + t.Fatalf("unexpected error: %v", err) + } + if !tx.committed { + t.Error("expected Commit") + } +} + +func TestUnitOfWork_Rollback(t *testing.T) { + tx := &mockTx{} + uow := NewUnitOfWork(newLogger(), &mockClient{tx: tx}) + _ = uow.Do(context.Background(), func(ctx context.Context) error { return errors.New("fail") }) + if !tx.rolledBack { + t.Error("expected Rollback") + } +} + +func TestUnitOfWork_InjectsExecutor(t *testing.T) { + tx := &mockTx{} + client := &mockClient{tx: tx} + uow := NewUnitOfWork(newLogger(), client) + var got Executor + _ = uow.Do(context.Background(), func(ctx context.Context) error { + got = client.GetExecutor(ctx) + return nil + }) + if got != tx { + t.Error("GetExecutor should return the injected Tx") + } +} + +// --- helpers --- + +func assertCode(t *testing.T, err error, want xerrors.Code) { + t.Helper() + var xe *xerrors.Err + if !errors.As(err, &xe) { + t.Fatalf("expected *xerrors.Err, got %T: %v", err, err) + } + if xe.Code() != want { + t.Errorf("want %s, got %s", want, xe.Code()) + } +} + +func strContains(s, sub string) bool { + for i := 0; i <= len(s)-len(sub); i++ { + if s[i:i+len(sub)] == sub { + return true + } + } + return false +}