qbit-record-files/docs/MYSQL.md

MySQL 8.4 qualification

Current delta caveat (2026-11-01): the historical qualified167-test artifact below is not qualification of the latest collection/adoption source. The later212-test full run failed on one fixture setup connection reset; its unchanged two-case control passed that case but failed later on a fresh parent-lookup TCP connection timeout after exercising collection migration/correction SQL. These transport failures are unclassified and retained. No timeout increase, skipped test, assertion weakening or blind full rerun closes them. Current required follow-up is an owned provider transport/readiness diagnosis and then an exact-source full gate. See V1-REMAINING.md.

Status: actual MySQL8.4 integration acceptance passed. Parent run67747 passed36 selected tests, including11 real MySQL cases and11 existing H2 archive cases. The subsequent clean MySQL-enabled full verification/install16807 passed167 tests and Checkstyle. File-backed H2 with WRITE_DELAY=0 retains its qualification. This is the pinned disposable provider/native service fixture acceptance described below, not production deployment, hardware durability or object-store qualification. Aurora, MariaDB and PostgreSQL are not covered.

The host applies RecordFilesSchema.mysqlScript(config) once through its migration tooling after the Collaboration owner schema/journal migration. It generates the current native fields, full unique keys, restrictive references, InnoDB tables and exact utf8mb4_0900_bin identities. Native datetime fields use DATETIME(6) to avoid the TIMESTAMP 2038 limit. This initial schema is not an upgrade/rollback migration system. Never give end users direct SQL or DDL privileges.

RecordFilesMySql checks the actual native connection target and catalog, MySQL 8.4 product, JDBC and session writable state, active transaction state when required, and all owned table/column/index identities. It requires innodb_flush_log_at_trx_commit=1, sync_binlog=1 when binary logging is enabled, innodb_doublewrite=ON or DETECT_AND_RECOVER, UTC session time and a 1–5 second session lock wait. Qualification never changes pooled-session or global settings. Use explicit driver UTC conversion (connectionTimeZone=UTC&preserveInstants=true, with the session configured UTC), or a fixed UTC JVM. The fixture additionally configures forceConnectionTimeZoneToSession=true in its host-owned driver URL.

One qualification issues one current-settings query and three catalog queries covering all owned tables together. Native JDBC observations also issue queries: the real provider reported six counted questions and23 ms for one probe (including the measurement query). This is a single fixture measurement, not a capacity claim. Actual operations may qualify several transactions; the native fixture also reports end-to-end synthetic intake/replay/read cost once those paths pass. There is no cached claim that remains valid after settings/schema changes. Trusted administrators control DDL and storage durability; probes cannot prevent concurrent privileged DDL, prove hardware honors fsync, or establish WORM retention. Actual committed audit writes remain mandatory before storage or delivery effects, and mutation outcomes share the native transaction with their changes.

MySqlRecordFilesTest is explicitly enabled with -DmysqlRecordFilesTests=true. It uses Testcontainers 2.0.3 and official mysql@sha256:a0225d1ea6631c8bc2385dc4c2faba17bbf1834ecf369e1659a9a382bd8d5dd7, random synthetic credentials, dynamic ports and a private disposable volume. It preserves the native source/tenant/owner services and uses only the public owner journal DDL. Planned evidence covers exact-byte intake/replay/read and tenant denial, independent attempt versus rolled-back outcome, audit failure before storage, settings/schema/target refusal, native timestamps across JVM zones beyond 2038, concurrent row locking, and physical server restart with refreshed mapped port. Canonical object bytes remain synthetic; this is database qualification, not object-store qualification.

Primary references: MySQL ACID, InnoDB parameters, doublewrite buffer, Connector/J instant preservation, and datetime conversion options.

The first actual provider run failed all eight MySQL cases during fixture schema setup; the thirteen selected existing H2 cases passed. The fixture had synthesized every unrelated Collaboration feature table. Its personal favorite/recent key permits 785 utf8mb4 characters across four fields, exceeding MySQL's 3072-byte index limit. Full Collaboration schema portability remains a separate owner task; its full generated schema currently targets PostgreSQL. The corrected RF fixture initializes only the native source tables plus participating owner attachment, feature-setting and activity tables, retains their required/default fields and exact intake unique index, and uses the public journal migration. It changes no identity lengths and creates no truncated or digest substitute keys. Actual native owner intake/activity/read calls exercise this scope; the next provider run remains pending.

Driver-option parsing rejects duplicates (including encoded duplicates), conflicting timezone aliases, unknown casing for relevant options, and explicit non-UTC/non-preserving overrides even on a UTC JVM. Runtime current-session checks remain separate from this configuration validation.

Qualification compares live metadata with newly generated owner definitions, then validates physical full keys, column mappings/types/nullability and identity generation against those definitions. Removing a native unique key and its physical index cannot redefine the expected schema. It also requires a1–5 second metadata lock_wait_timeout; row and archive-source locking statements have five-second JDBC query deadlines. The host configures these limits; request qualification never mutates them.

The second real run passed14 existing cases and two of eight MySQL cases. It exposed a required isolation contract: source-incarnation creation commits independently, so an enclosing REPEATABLE READ snapshot cannot see that new association on its later ordinary read even though a locking read sees it. Qualification now requires actual @@SESSION.transaction_isolation=READ-COMMITTED; the host must configure this before request admission. The disposable fixture uses --transaction-isolation=READ-COMMITTED, with a negative test that restores and refuses REPEATABLE READ. No production connection settings are changed by qualification. The engine-negative fixture now alters the small-index upload-chunk table, avoiding MyISAM's smaller unrelated index limit. Native document insertion assertions additionally verify successful exact IDs before service tests. Provider rerun is pending.

The third provider run passed14 existing cases and four of eight MySQL cases, advancing through the source-incarnation path. Four cases exposed another participating fixture table, collaboration_user, required by the real PeopleService.touch() call before owner upload. The fixture now includes its complete native identity key and fields. All eleven MySQL cases subsequently passed, including metadata/schema weakening refusal, a real competing row-lock timeout, and coordinated archive deletion followed by standard owner Get/list/content and revoked-current-rights refusal. Archive source locking uses MySQL backticks or H2 quotes under the already qualified backend. Earlier pending statements above describe intermediate runs; final acceptance is the167-test clean build stated at the top.

Verified RF main JAR SHA256: DF128995A3C8D5BCCC5D433E17BBEF63CAAF38F768B3D8FFB66B18EADEAE9563; test classifier: 29FB7477C91F18255D085FFCD633B28DEAFDF1CA24878D03B6A6AB5494C13F9A. The owner dependency is the215-test development artifact 2C5B01640520624E67F538F79A01AF14DE2D46690A7753654A54029A341AC254. No frozen previous consumer bundle was modified.