driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index

[os-sam]

Found while measuring #10792 (driver parity). Filed unassigned.

What

Booting a stack whose default datasource is MySQL (client mysql2) fails schema-sync for every platform object that carries an indexed string field. driver-sql maps a string/text field with no maxLength to a MySQL TEXT column, and MySQL refuses a TEXT/BLOB column in a key without a prefix length:

alter table `sys_user` add unique `uniq_sys_user_phone_number`(`phone_number`)
 -> BLOB/TEXT column 'phone_number' used in key specification without a key length

The base CREATE TABLE may succeed, but the ALTER TABLE ... ADD [UNIQUE] INDEX fails, so the table lands without its indexes and the object stays registered-but-broken (the driver logs Schema sync FAILED for object ... its table/columns were NOT created or altered). Downstream effect: the dev-admin seed never lands, and the first sign-in returns 401 INVALID_EMAIL_OR_PASSWORD on a fresh MySQL database.

Evidence

Measured against a real MySQL 8.0.46 server (a minimal ObjectQL + DefaultDatasourcePlugin(driver: 'mysql') + PlatformObjects + Auth boot). ~30 platform objects failed schema-sync. A sample of the offending columns (all in a unique or ordinary index):

• sys_user.phone_number (unique)
• sys_session.token (unique)
• sys_organization.slug (unique)
• sys_api_key.key (unique), sys_device_code.device_code (unique)
• sys_metadata unique (type, name, organization_id, package_id)
• sys_user_preference unique (organization_id, user_id, key)
• sys_oauth_* client_id / token / provider_id, sys_scim_provider, sys_team.name, etc.

The identical schema syncs cleanly on Postgres 16 (Postgres indexes text freely) and on SQLite (no such restriction). driver-sql stores string/text/textarea/html as TEXT (see the createColumn comment in sql-driver.ts, "Everything else createColumn stores as TEXT").

Why it matters (declared ≠ enforced)

MySQL is a declared-supported driver — createDefaultDatasourceDriverFactory maps mysql / mysql2 → @objectstack/driver-sql. But the CI Temporal Conformance (live PG + MySQL) job exercises only driver-sql's own suites, which build their tables with explicit knex .string() (VARCHAR); it never runs the platform-objects metadata syncSchema on MySQL. So this path is untested there and is currently broken end-to-end: a MySQL deployment cannot stand up its own platform schema.

Direction (for triage — not prescribing a fix)

Two shapes, contract-first:

• an indexed string column should be emitted as VARCHAR(n) on MySQL (a bounded length MySQL can index), rather than TEXT; and/or
• the platform objects' indexed string fields should declare a maxLength so the driver has a bound to emit.

Repro

Branch claude/issue-10792-remove-user-txn-driver-parity carries the boot probe packages/verify/src/issue-10792-driver-parity.probe.test.ts; run it with PROBE_DIALECT=mysql and OS_TEST_MYSQL_URL pointed at a MySQL 8.0 server. The schema-sync errors appear during beforeAll.

Generated by Claude Code

[claude]

Triage: pm:queue, domain:engine, Bug. Landing: packages/drivers/driver-sql schema-sync (unbounded string → TEXT on MySQL, index refused without key length) — ~30 platform objects fail to sync, so an auth stack cannot boot on a supported driver at all. Found during the #10792 second-round measurement (its ruling is recorded there). ⚠️ P0 suspicion flagged to the maintainer in the round report — today no CI leg runs platform-objects syncSchema on MySQL, so this is invisible to gates; the fix should add that leg or a targeted pin. Serial note: same driver package as #11324/#11321 (different files/defects) — answer fold-or-serial at dispatch.

---

Generated by Claude Code

[os-zhuang]

Claim — engine seat, session session_01RfyXxZ2WPjcjhuXpiQQc3y, branch claude/issue-11374-mysql-unbounded-string-index. pm:queue → pm:dispatched in one label write, read back.

Why this goes out first in the batch

Triage flagged p0 suspicion to the maintainer. Taking it at the head of the batch on the card's own measurement rather than on the suspicion: MySQL is a declared-supported driver (createDefaultDatasourceDriverFactory maps mysql / mysql2 → @objectstack/driver-sql), and on a fresh MySQL database ~30 platform objects fail schema-sync, the dev-admin seed never lands, and first sign-in returns 401 INVALID_EMAIL_OR_PASSWORD. That is not a degraded mode — the stack does not come up. declared ≠ enforced at the widest setting.

The part that decides the fix's shape

The card names the reason this was invisible: CI's required Temporal Conformance (live PG + MySQL) job exercises driver-sql's own suites, which build their tables with explicit knex.string() (VARCHAR), so it never runs platform-objects syncSchema on MySQL. A fix that repairs the column mapping without closing that hole leaves the next instance of this class equally invisible.

So the dispatch order asks for both, and asks the coverage question to be answered before the mapping is changed — because what the pin should assert depends on what the fix decides an unbounded indexed string is. ⛔ The dev is instructed not to reach for a prefix-length index as a first move without pricing the alternative (a bounded VARCHAR for indexed string fields), and to bring back the measurement rather than a preference if the two diverge.

Serialization

sql-driver.ts is this seat's hot file, but it is currently free: #11396 and #11401 merged (80f1dcd8f, 5dd3bc96c), #11270 merged at 13:17:43Z, and all 10 currently-open PRs are in spec / docs / rest / qa — none touches driver-sql. Measured, not assumed.

Dispatched alongside #11230 (objectql / metadata-core update-dispatch), which shares no file with this card.

Duplicate probe, both legs positive-controlled: repo-scoped PR search returns no open PR for this number, and git ls-remote origin 'refs/heads/*issue-11374*' is empty while the *issue-* pattern returns 98 live branches — so that zero is a reading.

---

Generated by Claude Code