feat(config): expose charset, loc, and parseTime as configurable DSN parameters

- add Config.Charset (MYSQL_CHARSET, default "utf8mb4"): connection character set
  sent as SET NAMES during handshake; previously hardcoded
- add Config.Loc (MYSQL_LOC, default "UTC"): IANA timezone for time.Time ↔
  DATE/DATETIME conversion; previously hardcoded
- add Config.ParseTime (MYSQL_PARSE_TIME, default "true"): driver-level DATE/DATETIME
  → time.Time mapping; valid values "true"/"false"; previously hardcoded
- update DSN() to derive parameters from Config fields with empty-means-default
  semantics; existing Config literals produce identical DSN output (backward compatible)
- remove unused url.URL construction from DSN(); params now built directly via url.Values
- document collation DSN limitation in Config godoc, CLAUDE.md, RELEASE.md, CHANGELOG.md:
  go-sql-driver v1.8.x uses 1-byte handshake collation IDs (max 255); MariaDB 11.4+
  collations such as utf8mb4_uca1400_as_cs exceed that range — set collation at the
  database/table level in schema migrations instead
This commit is contained in:
2026-03-20 14:12:24 -06:00
parent d9d07bcb70
commit 9d8762458c
3 changed files with 59 additions and 9 deletions

View File

@@ -22,6 +22,8 @@ Provides a `Component` that manages a `*sql.DB` connection pool, satisfies the `
- **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`.
- **Configurable DSN parameters (v0.9.1)**: `Config.Charset`, `Config.Loc`, and `Config.ParseTime` are optional string fields that control the corresponding DSN parameters. Empty value means "use the safe default" (`utf8mb4`, `UTC`, `true`). Existing `Config` literals that do not set these fields behave identically to v0.9.0.
- **Collation DSN limitation**: `go-sql-driver` v1.8.x negotiates the connection collation via a 1-byte handshake ID (max 255). MariaDB 11.4+ collations such as `utf8mb4_uca1400_as_cs` exceed that range and cannot be specified in the DSN. Set collation at the schema level (database/table DDL) instead.
## Patterns
@@ -62,6 +64,7 @@ defer rows.Close()
- 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.
- Do not pass a MariaDB 11.4+ collation (e.g. `utf8mb4_uca1400_as_cs`) as `Config.Collation` or any DSN parameter — the driver will fail at connect time with "unknown collation". Set collation in schema migrations at the database/table level instead.
## Testing Notes