Binary cache sql backend

[pnikolic-amd]

Motivation

Adds a SQLite storage backend to the GPU binary cache introduced in #5100, as an alternative to the
directory of .mxr files. A single database file is easier to copy between machines and to share,
needs no per-entry files or renames, and records each kernel's operator name, problem and solution
in queryable columns so a cache can be inspected and pruned with the sqlite3 shell.

Setting MIGRAPHX_BINARY_CACHE (or the binary_cache option) to a path ending in .db or
.sqlite selects the database; any other path keeps the existing directory cache. There is no new
configuration.

Technical Details

• Prepared statements in migraphx::sqlite. The existing wrapper was sqlite3_exec-based,
  text-only and had no parameter binding, so it could not carry BLOBs. Added sqlite_stmt, created
  by sqlite::prepare: calling it with arguments resets the statement, binds them and returns a
  range of rows, each converted to a value (BLOB columns become binary values). Binding, stepping
  and resetting are private. Also added sqlite::try_write, which does not throw, plus
  set_busy_timeout and read_only, and value::pair for building keyed values. Existing
  sqlite users are unchanged, and sqlite3.h stays out of the GPU target.
• Storage backend abstraction. A type-erased binary_cache_backend, generated from
  tools/include/gpu/binary_cache_backend.hpp like problem_cache_backend, with
  load(version, device, key) and store(version, device, vector<binary_cache_entry>).
  binary_cache::entry moved into binary_cache_entry.hpp, and the existing directory code moved
  unchanged into file_binary_cache. Each backend serializes entries its own way and checks the
  full key on load, so a hash collision is a miss rather than a wrong kernel.
• Batched inserts. binary_cache::insert takes a vector of entries, and compile_ops stores
  every result of a compile round in one call, so the database commits them in a single
  transaction instead of one commit per kernel.
• sqlite_binary_cache. One cache_v1 table with primary key (version, device, key_hash)
  and columns key, op_name, problem/solution (JSON), code (msgpack BLOB) and timestamp.
  version holds the full version id (format, HIP compiler, kernel-header digest, rocMLIR), so
  rows from different builds can share a file and old builds can be pruned with one range delete.
  The schema version is in the table name, so an incompatible change becomes a new table rather
  than a migration. Statements are prepared once and reused. Stores run in one
  BEGIN IMMEDIATE transaction using INSERT OR REPLACE, which plays the role of the file
  backend's publish-by-rename. Cross-process safety relies on busy_timeout(5000).
• Failures fall back to recompiling. A database that cannot be opened, or whose table has an
  unexpected layout, disables persistence with a warning. A read-only database (write-protected
  file or read-only mount) still serves lookups. A failed store is rolled back and makes the cache
  read-only for the rest of the process instead of retrying against a busy or broken database.
  Missing parent directories are created, so a .db path behaves like a directory path on a fresh
  machine.
• Backend chosen by file extension, mirroring make_problem_cache_backend. Storage opens on
  the first lookup or insert, not in the constructor, so a context that never compiles never
  touches the disk or probes the compiler.
• Docs: docs/dev/triage-migraphx.rst covers the database mode, inspecting and pruning with
  sqlite3, and read-only behaviour. The CHANGELOG binary-cache entry is updated.

[Copilot]

Copilot review overview

🟡 Changes recommended

Release-mode validation holes, statement cleanup issues, and the missing promised provenance table remain unresolved.

Review effort: Balanced
Findings: 3 · 3

Open (6)

• Reset statement before rethrowing initial step exception · New
• Reject empty SQL when sqlite3_prepare returns no statement · New
• A failed write leaves store_stmt valid, so every later kernel retries the same unusable database.…
• Implement or revise missing cache_info_v1 provenance table · New
• This removes the directory-backed disk-hit, corruption, compile-twice, and verified-reuse…
• The new extension-based backend selection is not reflected in the binary-cache documentation:…

Resolved since last review (2)

• Opening exclusively through try_write() makes the documented read-only fallback unreachable for…
• The constructor now computes version_dir() even when persistence is disabled. Since every GPU…

[Copilot]

🟡 Changes recommended

Prepared statements mishandle underbinding and empty BLOBs, while existing database schemas are insufficiently validated.

7 open findings

• Release builds allow statement argument-count mismatches · New
• Empty BLOB conversion performs pointer arithmetic on null · New
• Existing cache table schema is not validated · New
• A failed write leaves store_stmt valid, so every later kernel retries the same unusable database.…
• Implement or revise missing cache_info_v1 provenance table
• This removes the directory-backed disk-hit, corruption, compile-twice, and verified-reuse…
• The new extension-based backend selection is not reflected in the binary-cache documentation:…

2 resolved since last review

• Reject empty SQL when sqlite3_prepare returns no statement
• Reset statement before rethrowing initial step exception

🧠 Review effort: Balanced

[codecov]

Codecov Report

❌ Patch coverage is 95.61404% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/sqlite.cpp	94.19%	5 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #5232      +/-   ##
===========================================
+ Coverage    92.72%   92.73%   +0.02%     
===========================================
  Files          635      635              
  Lines        36203    36314     +111     
===========================================
+ Hits         33566    33675     +109     
- Misses        2637     2639       +2     

Files with missing lines	Coverage Δ
src/include/migraphx/sqlite.hpp	100.00% <100.00%> (ø)
src/sqlite.cpp	92.62% <94.19%> (+10.57%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.