qbit-document-generation/docs/MYSQL.md

Native MySQL qualification

The full foundation clean install passed 109 tests, zero failures/errors/skips, Checkstyle and coverage at 2026-10-31 00:45:47 CDT. Forty tests use actual disposable MySQL 8.4.13; the remaining69 use H2/memory and build guardrails. Evidence: mysql-full-verification.log. JAR SHA256: 9BCB0FA1A0CFDA44389BD3D0934215EEB2DDF9806DE604D09D1A5AD0BC4AA2C7. These checks qualify the implemented database contract, not a production volume or deployment.

Actual-engine testing exposed and fixed a concurrent draft overwrite under MySQL's default repeatable-read semantics. The original exactly-one-editor assertion passes with native READ COMMITTED established before any transaction read. An explicit one-connection C3P0 fixture proves the same physical server connection restores its original isolation/autocommit after commit and rollback.

DocumentGenerationSchema.mysqlScript(config) generates the twelve owned tables from native metadata. Operators apply it through migration tooling; registration never creates tables. It uses InnoDB, utf8mb4_0900_bin, complete unique idempotency indexes, DATETIME(6) and LONGTEXT for bounded template/context bodies. CREATE TABLE IF NOT EXISTS is a bootstrap convenience, not an upgrade mechanism; it does not repair a mismatched existing table. Historical H2 fixture bootstrap remains compatible.

GenerationJdbc is a package-owned policy shared by the independent audit writer, queue and native MySQL write transactions. It checks current physical server and schema state instead of caching a configuration claim:

• Configured native mysql backend, actual MySQL 8.4 product/version and matching catalog/JDBC endpoint.
• Fresh writable independent connections for queue/audit. Definitions use their own native READ COMMITTED transaction and preserve rollback behavior. The actual JDBC pool tracks the isolation setter; restoration is verified on the same server connection after commit and rollback.
• innodb_flush_log_at_trx_commit=1, sync_binlog=1, binary logging enabled, recovering doublewrite (ON or DETECT_AND_RECOVER), and a writable server/session.
• A strict session mode and UTC session timezone.
• All owned tables on the configured backend, actual InnoDB engines and binary/no-pad text columns, immutable primary keys and complete unique indexes without prefix truncation.
• Actual native table/column/type/primary-key metadata matches the owned schema. Remapping is refused before native reads/writes and SQL qualification, so a qualified table cannot mask a different mutation target.
• Session row-lock and metadata-lock waits are each 1–5 seconds. Owned prepared statements have a five-second JDBC query deadline, including the template row lock. A real held-row regression verifies bounded refusal without changing the draft.

Weak settings, missing tables/indexes, conflicting backend names, read-only connections and unsupported vendors fail before protected mutation. Existing file-H2 checks still inspect actual WRITE_DELAY=0; memory remains a volatile test fixture. Aurora is not implicitly qualified by being MySQL-compatible.

The selected collation preserves exact case and trailing-space identity; MySQL documents its NO PAD behavior. MySQL binary collations. The commit flags are prerequisites for the intended crash-recovery behavior, not a guarantee about storage hardware or backup recovery. MySQL binary-log durability. JDBC configuration should explicitly set connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true; the runtime verifies the resulting session. Connector/J datetime properties.

A row lock does not refresh an earlier repeatable-read snapshot used by a subsequent normal query. Owned draft transactions therefore establish READ COMMITTED before any read, retain their explicit template row lock through commit, and compare the current fingerprint through native QQQ reads. Ambient caller transactions are still refused. MySQL consistent reads.

DETECT_ONLY doublewrite mode lacks repair page copies and is refused; startup OFF is also refused. This complements redo/binlog synchronization instead of treating it as complete torn-page recovery. MySQL doublewrite buffer.

The real-engine suites use only disposable MySQL 8.4.13 containers pinned to sha256:a0225d1ea6631c8bc2385dc4c2faba17bbf1834ecf369e1659a9a382bd8d5dd7, loopback dynamic ports and generated test credentials. Application connections have only SELECT/INSERT/UPDATE/DELETE; fixture DDL and faults use a separate migration identity. Existing native queue, audit and publication tests are inherited without weakening their behavioral assertions. Additional cases cover actual engine/collation/index drift, weakened commit flags, UTC/strict sessions, denied application DDL, case/trailing-space keys, larger Unicode templates and server restart with refreshed endpoint discovery.

A container process restart test exercises database process recovery. It does not simulate host power loss, disk corruption, external-volume restoration or a production topology. Those deployment checks and a measured end-to-end workload remain separate release requirements.