CodeLogic.MySQL2 4.5.3-preview.58

• net10.0

  • CodeLogic (>= 3.2.0 && < 5.0.0)
  • MySqlConnector (>= 2.5.0)

# CL.MySQL2 — Changelog

All notable changes to **CodeLogic.MySQL2** are documented here. Versions follow
[Semantic Versioning](https://semver.org/). The version listed here matches the
NuGet package version of `CodeLogic.MySQL2`.

## [4.5.0] — 2026-05-24

### Added

- **`StorageType` enum on `ColumnAttribute`.** Per-column physical storage
 override that takes precedence over `DataType` for DDL generation.
 Available values: `Binary`, `VarBinary`, `TinyBlob`, `Blob`, `MediumBlob`,
 `LongBlob`. When set, the column is stored as the chosen binary type and
 values are automatically converted to/from binary on read and write.

- **Guid-as-BINARY(16) support.** Set `StorageType = StorageType.Binary` on a
 `Guid` property and CL.MySQL2 stores it as `BINARY(16)` using RFC 4122
 big-endian byte layout for correct lexicographic sort order. Conversion is
 automatic in all paths: insert, update, read, WHERE clauses, and IN queries.

 ```csharp
 [Column(StorageType = StorageType.Binary, Primary = true, NotNull = true)]
 public Guid Id { get; set; }
 ```

- **Automatic binary conversion for all CLR types.** Any property can be
 stored as binary by setting `StorageType`. Supported types and their binary
 sizes (auto-detected when `Size` is not explicit):

 | CLR type | Binary size | Byte order |
 |---|---|---|
 | `Guid` | 16 | RFC 4122 big-endian |
 | `long` / `ulong` | 8 | big-endian |
 | `int` / `uint` | 4 | big-endian |
 | `short` / `ushort` | 2 | big-endian |
 | `double` | 8 | big-endian |
 | `float` | 4 | big-endian |
 | `decimal` | 16 | big-endian |
 | `DateTime` / `DateTimeOffset` | 8 | ticks, big-endian |
 | `bool` / `byte` / `sbyte` | 1 | — |
 | `string` | explicit | UTF-8 |
 | `byte[]` | passthrough | as-is |

- **LINQ WHERE support for binary-stored columns.** Expressions like
 `repo.Where(x => x.Id == someGuid)` and `list.Contains(x.Id)` correctly
 convert parameter values to binary when the column uses `StorageType`.

- **`SequentialGuid.NewId()` helper.** Generates time-ordered UUIDv7 values
 optimized for `BINARY(16)` primary keys. Sequential inserts append to the
 B-tree instead of causing random page splits — dramatically reducing index
 fragmentation compared to random UUIDv4.

 ```csharp
 [Column(StorageType = StorageType.Binary, Primary = true, NotNull = true)]
 public Guid Id { get; set; } = SequentialGuid.NewId();
 ```

- **Unified versioning.** All CodeLogic.Libs now share a single version line
 controlled by `version.txt`. AssemblyVersion is derived automatically.

### Notes

- **No breaking changes.** `StorageType` defaults to `StorageType.Default`
 (the zero-value), so all existing entities and schemas are unaffected.
 Guid inference still returns `Char(36)` unless you explicitly opt in.

## [4.2.3] — 2026-05-15

### Fixed

- **Cache orphan accumulation on mutations.** `QueryCache.Invalidate(tableName)`
 previously only bumped the per-table version counter — old cache entries
 (now unreachable via the read path because the cache key changed) lingered
 in the underlying store until TTL or LRU swept them. On a busy app this
 produced unbounded memory growth. Invalidate now also calls
 `ICacheStore.EvictByTableAsync` to sweep matching entries in the same step.
- **SmartCachePool orphan tracking.** Each pool entry now remembers the
 cache key it last wrote. If the next tick computes a different key
 (because a mutation bumped the table version between ticks), the
 previous key is evicted explicitly. Works on any `ICacheStore`
 implementation including ones that can't enumerate (Redis without
 SCAN, memcached).

### Added

- `ICacheStore.EvictByTableAsync(tableName)` — bulk eviction by table.
 Default in-process implementation is an O(n) scan over current entries.
 Distributed adapters can override (e.g. Redis tag-set or key prefix).
- `ICacheStore.CountByTable()` — entries grouped by tableName for diagnostics.
- `QueryCache.GetStats()` → `QueryCacheStats(TotalEntries, EntriesByTable,
 TableVersions)`. Surfaced on the library API via `MySQL2Library.GetCacheStats()`
 so admin tools can render "what's in the cache right now" without
 dumping values.

## [4.2.2] — 2026-05-15

### Fixed

- **SmartCache pool no longer corrupts `ToListAsync` results.** The pool's
 refresh factory stored the unwrapped `List<T>` instead of the
 `Result<List<T>>` that the cache-aside read path expects. After the first
 background refresh tick, every subsequent read failed the `(Result<List<T>>)`
 cast inside `GetOrSetAsync`, the outer try/catch turned it into a Failure
 Result, and callers saw an empty list (manifested as "No servers configured"
 / empty leaderboards roughly one refresh interval after warm-up). `FirstOrDefaultAsync`
 and `CountAsync` already cached the full Result and were unaffected; only
 `ToListAsync` was wrong.

## [4.2.1] — 2026-05-15

### Fixed

- **Failure Results no longer poison the cache.** Previously, a query that
 failed (e.g. transient connection error during a cold warm-up) had its
 `Result<T>.Failure` value cached just like a successful one — subsequent
 reads served the failure until the entry's TTL expired or a pool refresh
 overwrote it. Now `QueryCache.GetOrSetAsync` skips writing failure Results,
 evicts any pre-existing failure entry on read, and `SetDirectAsync` (the
 smart-cache pool's refresh path) refuses to write failures too. Empty
 server lists / leaderboards on first request after a deploy are gone.

## [4.2.0] — 2026-05-15

### Added

- **Smart-cache pool warm-up on registration.** `RegisterCachePool` now
 accepts an optional `warmUp: Func<Task>` callback that fires as a
 fire-and-forget task right after the pool starts. The callback just
 calls the queries that should be warm — they auto-register with the
 pool via their normal `.SmartCache(name)` decoration — so the cache
 is hot before the first user request hits it. Exceptions are caught
 and logged; the pool stays lazy if warm-up fails.
- `SmartCachePool.WarmUp(Func<Task>)` — public method exposing the same
 behaviour for callers that want to warm a pool independently of
 registration.

## [4.1.2] — 2026-05-15

### Added

- **Smart cache pools** — named groups of cached queries kept warm by a
 background timer (`mysql.RegisterCachePool("dashboard", refreshEvery: 30s)`,
 opt in per-query with `.SmartCache("dashboard")`). Reads after the first
 populate the cache never block on the DB — the pool's timer re-runs every
 registered query in the background and overwrites the entry.
- `SmartCachePool.RefreshNowAsync()` — out-of-schedule refresh, useful right
 after a deploy to prime the cache before the first user hits the page.
- `MySQL2Library.GetCachePoolStats()` — diagnostic snapshot per pool
 (entry count, ticks fired, ticks failed, last tick UTC).
- `QueryCache.SetDirectAsync(...)` — internal cache write API used by pools.

### Notes

- Smart cache is mutually exclusive with `.WithCache(TimeSpan)` — if both are
 set, the pool wins and the TTL comes from `refreshEvery * 2`.
- Unknown pool name on `.SmartCache(name)` logs a warning and falls back to
 non-cached execution (no exception).
- Per-pool eviction policy: an entry that has not been read for
 `MaxIdleFires` (default 3) consecutive ticks is dropped from the refresh
 list. Bounds cardinality on parameterized queries.
- Smart cache is disabled inside a transaction scope (same as `.WithCache`).
- Single-node only in v4.2. Multi-node coordination is on the roadmap.

## [4.1.1] — 2026-04-17

### Fixed

- Qualify LHS columns in upsert SET clauses so `UpsertAsync` no longer
 generates ambiguous column references when the table has columns whose
 names clash with parameter placeholders.

## [4.1.0] — 2026-04-17

### Added

- **Typed upsert** — `UpsertAsync` + `UpsertWithIncrementsAsync` on the
 repository. Compiles to `INSERT ... ON DUPLICATE KEY UPDATE ...` with
 full LINQ-shaped value/increment expressions on the update side.

### Changed

- `LibraryManifest.Version` now reads from the assembly's `AssemblyVersion`
 attribute at runtime instead of being a hard-coded string. Keeps the
 manifest honest across rebuilds.

## [4.0.4] — 2026-04-16

### Changed

- README + manifest refresh across every CodeLogic library for the v4 baseline.
- No functional changes vs 4.0.3.

## [4.0.1] — 2026-04-09

### Fixed

- Drop the `Expression.Compile().DynamicInvoke()` fast-path inside the SQL
 expression visitor — it broke on closures over generic types. The visitor
 now always walks the tree.

## [4.0.0] — 2026-04-09

Major rewrite. Breaking.

### Added

- **Projection pushdown** — `.Select<TResult>(x => new { ... })` emits a
 real `SELECT col1, col2, ...` column list instead of `SELECT *`. Combined
 with compiled materializers this often cuts row-transfer bandwidth by 80%+.
- **SQL-side aggregation** — `.GroupBy(...).Select(g => new { g.Key,
 g.Sum(...), g.Average(...), ... })` translates to real `GROUP BY` +
 aggregate functions. No client-side row materialization.
- **`SqlFn` helpers** — server-side function markers (`SqlFn.DayOfWeek`,
 `SqlFn.Hour`, `SqlFn.BucketUtc`, `SqlFn.Coalesce`, `SqlFn.Round`, etc.)
 recognized by the translator — mirrors EF's `EF.Functions` pattern.
- **`[Index]` attribute** — declare named, unique, and covering indexes
 (with `Include = new[] { ... }`) at the column level.
- **`[RetainDays]` attribute** — opt entities into a daily background purge
 worker that runs batched `DELETE` until drained.
- **Working result cache** — `.WithCache(TimeSpan)` with two correctness
 fixes from prior versions:
 - DateTime closures near `UtcNow` are time-quantized to a configurable
   window (default 60s) so `.Where(x => x.At >= UtcNow.AddDays(-30))`
   stops producing a unique cache key per call.
 - Mutations bump a per-table version that participates in the cache
   key — invalidation is free (old keys become un-hittable, no eviction
   loop).
- **`EntityMetadata<T>` + compiled `Materializer<T>`** — reflection runs
 once per entity at first use; subsequent reads use a compiled
 reader-to-entity function.
- **Observability events** — `QueryExecutedEvent`, `SlowQueryEvent`,
 `CacheHitEvent`, `CacheMissEvent`, `N1QueryDetectedEvent`,
 `TableSyncedEvent` publish to the CodeLogic event bus.
- **`MaxBatchInsertSize`, `MaxInClauseValues`, `PreparedStatementCacheSize`,
 `N1DetectorThreshold`, `CaptureExplainOnSlowQuery`, `DefaultStringSize`,
 `CacheEnabledOverride`** — per-database config knobs.
- **`CacheConfiguration`** — global cache settings (`Enabled`,
 `MaxEntries`, `DefaultTtlSeconds`, `TimeQuantizeSeconds`,
 `PublishEvents`).

### Changed

- Republished as v4.0.0 to reset the version line with the new package shape.
- All public APIs refreshed under the v4 baseline.

## Earlier releases

Pre-4.0 history is retained in the
[git log](https://github.com/Media2A/CodeLogic.Libs/commits/main/CL.MySQL2)
but is not documented in detail here — the library shape changed
significantly in the v4 rewrite.