|
3 | 3 | /** |
4 | 4 | * [#29520 codemod] The "Column creation helper" section of `SqlDriver`: the |
5 | 5 | * bodies of `declaredVarcharLength`, `keyableTextLength`, |
6 | | - * `hashShadowColumnFor`, `createHashShadowUniqueIndex`, |
7 | | - * `hashShadowColumnState`, `dropOrphanedHashShadowColumn`, |
| 6 | + * `explainUnkeyableTextColumn`, `hashShadowColumnFor`, |
| 7 | + * `createHashShadowUniqueIndex`, `hashShadowColumnState`, |
| 8 | + * `dropOrphanedHashShadowColumn`, `explainHashShadowDuplicate`, |
8 | 9 | * `decorateHashShadowDuplicate`, `hashShadowSourceColumns`, |
9 | 10 | * `varcharPackLength`, `rowWidthProfile`, `schemaBytesPerChar`, |
10 | 11 | * `explainRowSizeOverflow`, `rethrowWithRowSizeExplanation`, `jsonColumn` moved |
@@ -55,11 +56,14 @@ import type { SqlDriver as SqlDriverClass } from './sql-driver.js'; |
55 | 56 | * assigns. |
56 | 57 | */ |
57 | 58 | export interface ColumnCreationHost { |
| 59 | + declaredFieldsFor: SqlDriverClass['declaredFieldsFor']; |
58 | 60 | explainHashShadowDuplicate: SqlDriverClass['explainHashShadowDuplicate']; |
59 | 61 | explainRowSizeOverflow: SqlDriverClass['explainRowSizeOverflow']; |
60 | 62 | hashShadowColumnState: SqlDriverClass['hashShadowColumnState']; |
| 63 | + hashShadowSourceColumns: SqlDriverClass['hashShadowSourceColumns']; |
61 | 64 | readonly isMysql: SqlDriverClass['isMysql']; |
62 | 65 | readonly isSqlite: SqlDriverClass['isSqlite']; |
| 66 | + keyableTextLength: SqlDriverClass['keyableTextLength']; |
63 | 67 | readonly knex: SqlDriverClass['knex']; |
64 | 68 | logDurabilityFailure: SqlDriverClass['logDurabilityFailure']; |
65 | 69 | readonly logger: SqlDriverClass['logger']; |
@@ -89,6 +93,101 @@ export class ColumnCreationFacet { |
89 | 93 | return n; |
90 | 94 | } |
91 | 95 |
|
| 96 | + /** The body of `SqlDriver#explainUnkeyableTextColumn`; the method's docblock there is its contract. */ |
| 97 | + static async explainUnkeyableTextColumn(this: Pick<ColumnCreationHost, 'declaredFieldsFor' | 'keyableTextLength' | 'knex'>, tableName: string, indexName: string, columns: string[], cause: unknown): Promise<string | null> { |
| 98 | + const code = (cause as { code?: string } | undefined)?.code; |
| 99 | + if (code !== 'ER_BLOB_KEY_WITHOUT_LENGTH' && code !== 'ER_TOO_LONG_KEY') return null; |
| 100 | + let offenders: string[] = []; |
| 101 | + try { |
| 102 | + const info: Record<string, { type?: string }> = await this.knex(tableName).columnInfo(); |
| 103 | + offenders = columns.filter((c) => /text|blob/i.test(String(info?.[c]?.type ?? ''))); |
| 104 | + } catch { |
| 105 | + // Introspection is a nicety here; the advice below holds without it. |
| 106 | + } |
| 107 | + const named = |
| 108 | + offenders.length > 0 |
| 109 | + ? `Column(s) ${offenders.map((c) => `"${c}"`).join(', ')} are stored as TEXT` |
| 110 | + : 'One or more of its key columns is stored as TEXT'; |
| 111 | + |
| 112 | + // Commit ebcc34e89: the SAME refusal has two causes, and the message below is true of |
| 113 | + // only one of them. On CREATE the field really declares no usable bound, so |
| 114 | + // "declare `maxLength`" is the fix. On an UPGRADE the bound IS declared — |
| 115 | + // the additive sync never rewrites a column's type (#3728), so a column |
| 116 | + // created before the declaration stays TEXT forever — and that same sentence |
| 117 | + // tells the operator to do what they already did, once per boot, in |
| 118 | + // production, which reads as the release they just deployed being broken. |
| 119 | + // |
| 120 | + // The discriminator is per COLUMN and needs BOTH halves, which is why it is |
| 121 | + // computed here rather than inferred from the error code: a bounded |
| 122 | + // declaration alone does not imply a stale column, because `ER_TOO_LONG_KEY` |
| 123 | + // can refuse a COMPOSITE whose parts are each individually keyable (see |
| 124 | + // {@link MAX_KEYABLE_VARCHAR_CHARS} — the bound is per KEY, not per column). |
| 125 | + // So the branch fires only where the physical column is TEXT *and* |
| 126 | + // {@link keyableTextLength} says a fresh create would have emitted |
| 127 | + // `varchar(n)` for it. When `columnInfo()` fails, `offenders` is empty and |
| 128 | + // this map stays empty, so the CREATE-path message stands — the honest |
| 129 | + // reading, since without introspection the two causes are indistinguishable. |
| 130 | + // |
| 131 | + // `declaredFieldsFor` returns `undefined` for a table this driver does not |
| 132 | + // own the column set of, and misses a SHARD table (registered under the base |
| 133 | + // name). Both degrade to the message below rather than guessing. |
| 134 | + const declaredFields = this.declaredFieldsFor(tableName); |
| 135 | + const staleBounds = new Map<string, number>(); |
| 136 | + for (const c of offenders) { |
| 137 | + const field = declaredFields?.[c]; |
| 138 | + const bound = field ? this.keyableTextLength(field) : null; |
| 139 | + if (bound !== null) staleBounds.set(c, bound); |
| 140 | + } |
| 141 | + |
| 142 | + if (staleBounds.size > 0) { |
| 143 | + const staleNamed = [...staleBounds] |
| 144 | + .map(([c, n]) => `"${c}" (declares \`maxLength: ${n}\`)`) |
| 145 | + .join(', '); |
| 146 | + const [firstColumn, firstBound] = [...staleBounds][0]; |
| 147 | + // Named in full, deliberately. The mirror case in `schema-drift.ts` (the |
| 148 | + // unbounded field over a stale `varchar`) already had to derive this, and |
| 149 | + // the two MySQL `MODIFY` hazards it names are recorded twice more in this |
| 150 | + // file, on the datetime and time widenings: MODIFY does NOT repeat a |
| 151 | + // `NOT NULL`, and it DROPS a `DEFAULT` it does not restate. An operator |
| 152 | + // who follows an abbreviated version of this remedy ends up worse off than |
| 153 | + // the no-op they started with — a column that lost its default. |
| 154 | + const others = |
| 155 | + offenders.length > staleBounds.size |
| 156 | + ? ` Column(s) ${offenders |
| 157 | + .filter((c) => !staleBounds.has(c)) |
| 158 | + .map((c) => `"${c}"`) |
| 159 | + .join(', ')} in the same key declare no usable bound and DO need \`maxLength\` ` + |
| 160 | + `declared on the field.` |
| 161 | + : ''; |
| 162 | + return ( |
| 163 | + `[sql-driver] cannot create index '${indexName}' on "${tableName}" — MySQL refuses a TEXT/BLOB ` + |
| 164 | + `column in a key without a key length. Column(s) ${staleNamed} are stored as TEXT even though the ` + |
| 165 | + `field ALREADY declares a usable \`maxLength\` — the column was created before that bound was ` + |
| 166 | + `declared, and the additive sync never rewrites a column's type, so re-declaring \`maxLength\` ` + |
| 167 | + `changes nothing here. REMEDY: convert the column(s) to varchar(n) by hand, with a backup ` + |
| 168 | + `taken first, restating the FULL column definition on MySQL (MODIFY drops a NOT NULL or DEFAULT you ` + |
| 169 | + `do not repeat) — e.g. ALTER TABLE \`${tableName}\` MODIFY \`${firstColumn}\` ` + |
| 170 | + `varchar(${firstBound}) plus that column's existing NOT NULL / DEFAULT clauses, restated verbatim; ` + |
| 171 | + `— and let the next boot create this index. ObjectStack does NOT rewrite the column for you: that ` + |
| 172 | + `ALTER needs an exclusive metadata lock on the table, which makes it a destructive, hard-to-roll-back ` + |
| 173 | + `action and a deliberate manual floor rather than a boot-time one.${others} The table exists but this ` + |
| 174 | + `index does NOT, so any uniqueness it declared is currently unenforced. A prefix index is deliberately ` + |
| 175 | + `not substituted: on a UNIQUE index it constrains the prefix rather than the value, and rejects two ` + |
| 176 | + `different values that share one.` |
| 177 | + ); |
| 178 | + } |
| 179 | + |
| 180 | + return ( |
| 181 | + `[sql-driver] cannot create index '${indexName}' on "${tableName}" — MySQL refuses a TEXT/BLOB ` + |
| 182 | + `column in a key without a key length. ${named} because the field declares no \`maxLength\` (or one ` + |
| 183 | + `wider than ${SqlDriver.MAX_KEYABLE_VARCHAR_CHARS} characters, the most a utf8mb4 key part can hold). ` + |
| 184 | + `Declare \`maxLength\` on the field(s) so the column is emitted as varchar(n) and can be keyed. ` + |
| 185 | + `The table exists but this index does NOT, so any uniqueness it declared is currently ` + |
| 186 | + `unenforced. A prefix index is deliberately not substituted: on a UNIQUE index it constrains the ` + |
| 187 | + `prefix rather than the value, and rejects two different values that share one.` |
| 188 | + ); |
| 189 | + } |
| 190 | + |
92 | 191 | /** The body of `SqlDriver#hashShadowColumnFor`; the method's docblock there is its contract. */ |
93 | 192 | static hashShadowColumnFor(indexName: string): string { |
94 | 193 | // Commit cd1348802: DELEGATES rather than re-deriving. The differ has to look for |
@@ -277,6 +376,85 @@ export class ColumnCreationFacet { |
277 | 376 | return true; |
278 | 377 | } |
279 | 378 |
|
| 379 | + /** The body of `SqlDriver#explainHashShadowDuplicate`; the method's docblock there is its contract. */ |
| 380 | + static async explainHashShadowDuplicate(this: Pick<ColumnCreationHost, 'hashShadowSourceColumns' | 'isMysql' | 'knex'>, tableName: string, values: Record<string, unknown>, cause: unknown): Promise<string | null> { |
| 381 | + if (!this.isMysql) return null; |
| 382 | + if ((cause as { code?: string } | undefined)?.code !== 'ER_DUP_ENTRY') return null; |
| 383 | + const message = String((cause as { message?: string } | undefined)?.message ?? ''); |
| 384 | + // MySQL names the key as `table.index` (8.0) or `index` (5.7) — take the |
| 385 | + // last path segment either way. |
| 386 | + const keyed = /for key '([^']+)'/.exec(message); |
| 387 | + if (!keyed) return null; |
| 388 | + const indexName = keyed[1]!.split('.').pop()!; |
| 389 | + const shadow = SqlDriver.hashShadowColumnFor(indexName); |
| 390 | + let shadowExists = false; |
| 391 | + try { |
| 392 | + shadowExists = await this.knex.schema.hasColumn(tableName, shadow); |
| 393 | + } catch { |
| 394 | + return null; |
| 395 | + } |
| 396 | + if (!shadowExists) return null; |
| 397 | + const sources = await this.hashShadowSourceColumns(tableName, indexName); |
| 398 | + if (sources.length === 0) return null; |
| 399 | + // Only the source columns the failing write actually supplied; a partial |
| 400 | + // update cannot be re-selected on columns it never mentioned. A NULL-safe |
| 401 | + // key part (commit df1c75c4b) is exempt: the enforced key COALESCEs an absent or |
| 402 | + // NULL value into the '__global__' bucket, so its key part is knowable |
| 403 | + // without the write mentioning the column. |
| 404 | + if ( |
| 405 | + !sources.every( |
| 406 | + (s) => s.nullSafe || Object.prototype.hasOwnProperty.call(values, s.column), |
| 407 | + ) |
| 408 | + ) { |
| 409 | + return null; |
| 410 | + } |
| 411 | + let existing = 0; |
| 412 | + try { |
| 413 | + // Re-select by the key the index ENFORCES, not by raw equality (commit df1c75c4b): |
| 414 | + // a NULL-safe part compares through the same COALESCE the generation |
| 415 | + // expression carries (NULL and absent both land in the global bucket), |
| 416 | + // and plain parts use `<=>` — MySQL's NULL-safe equality; this whole |
| 417 | + // route is inside `isMysql`. A bare `.where({col: null})` would compare |
| 418 | + // `= NULL`, match nothing, and misreport a genuine NULL-organization |
| 419 | + // duplicate as a HASH COLLISION. |
| 420 | + let q = this.knex(tableName); |
| 421 | + for (const s of sources) { |
| 422 | + q = s.nullSafe |
| 423 | + ? q.whereRaw(`COALESCE(??, '${GLOBAL_TENANT}') = COALESCE(?, '${GLOBAL_TENANT}')`, [ |
| 424 | + s.column, |
| 425 | + (values[s.column] ?? null) as any, |
| 426 | + ]) |
| 427 | + : q.whereRaw('?? <=> ?', [s.column, (values[s.column] ?? null) as any]); |
| 428 | + } |
| 429 | + const rows = await q.limit(1); |
| 430 | + existing = rows.length; |
| 431 | + } catch { |
| 432 | + return null; |
| 433 | + } |
| 434 | + // Describe the key parts as enforced — NULL-safe parts in their COALESCE |
| 435 | + // spelling — so the message names the actual constraint (commit df1c75c4b). |
| 436 | + const described = sources |
| 437 | + .map((s) => (s.nullSafe ? `COALESCE(${s.column}, '${GLOBAL_TENANT}')` : s.column)) |
| 438 | + .join(', '); |
| 439 | + if (existing > 0) { |
| 440 | + // The ordinary case: a real duplicate. Say so in the declared terms |
| 441 | + // rather than leaving MySQL's binary digest as the only explanation. |
| 442 | + return ( |
| 443 | + `[sql-driver] duplicate value for the UNIQUE constraint '${indexName}' on "${tableName}" ` + |
| 444 | + `(${described}). The constraint is physically carried by a hash-shadow column, so the ` + |
| 445 | + `server's own message quotes a binary digest instead of the value.` |
| 446 | + ); |
| 447 | + } |
| 448 | + return ( |
| 449 | + `[sql-driver] HASH COLLISION on the shadow-carried UNIQUE index '${indexName}' on "${tableName}" ` + |
| 450 | + `(${described}): the write was rejected as a duplicate, but NO existing row carries these ` + |
| 451 | + `values. Uniqueness on this index is enforced over a SHA-256 of them, so two different ` + |
| 452 | + `values produced the same digest. This is expected at a rate near 10^-59 for a billion rows — if ` + |
| 453 | + `you are reading this, please report it with the values above; the write itself is legitimate and ` + |
| 454 | + `is being refused.` |
| 455 | + ); |
| 456 | + } |
| 457 | + |
280 | 458 | /** The body of `SqlDriver#decorateHashShadowDuplicate`; the method's docblock there is its contract. */ |
281 | 459 | static async decorateHashShadowDuplicate(this: Pick<ColumnCreationHost, 'explainHashShadowDuplicate' | 'logDurabilityFailure'>, tableName: string, values: Record<string, unknown>, error: unknown): Promise<unknown> { |
282 | 460 | let explanation: string | null = null; |
|
0 commit comments