|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * #15479 — the HASH-SHADOW arm of `syncDeclaredIndexes`'s `catch`, on a PLAIN |
| 5 | + * unique over rows that already violate it. |
| 6 | + * |
| 7 | + * ## The defect |
| 8 | + * |
| 9 | + * #14902 (PR #15477) brought the DIRECT arm to parity: a plain unique over |
| 10 | + * existing duplicates logs on the durability channel and lets the boot |
| 11 | + * continue, instead of throwing the database's raw error. The hash-shadow arm |
| 12 | + * — one branch above it in the SAME `catch`, taken when MySQL refuses to key |
| 13 | + * the column directly — still asked `nullSafe.size > 0 && isUniqueViolation…`, |
| 14 | + * so with no organization key part the branch did not fire, the code fell |
| 15 | + * through to `logDurabilityFailure(unkeyable, msg)` + `throw`, and the boot |
| 16 | + * died carrying a message about an UNKEYABLE TEXT COLUMN while the actual |
| 17 | + * cause was duplicate rows — naming neither the conflicting rows nor a remedy. |
| 18 | + * |
| 19 | + * ## Why this file is a live cell and could not be a SQLite one |
| 20 | + * |
| 21 | + * The shadow route exists only because MySQL refuses a key part over the |
| 22 | + * 768-char utf8mb4 ceiling; SQLite and Postgres never refuse, so they never |
| 23 | + * reach this arm. `maxLength: 1024` is what selects it. The card that filed |
| 24 | + * this said the branch was unreachable in the dispatch container — measured |
| 25 | + * false: MySQL 8.0 installs from the distro archive and this suite drives it. |
| 26 | + * |
| 27 | + * ## The two-arm message split, which is the half that is NOT a guard widening |
| 28 | + * |
| 29 | + * The surviving branch's message said "existing rows violate the NULL-safe key |
| 30 | + * (duplicates the previous void constraint admitted, #5030)". Neither clause is |
| 31 | + * true of a plain unique: nothing admitted those rows, and there is no NULL-safe |
| 32 | + * key. Widening the guard and leaving one message would ship a FACTUALLY FALSE |
| 33 | + * durability log — worse than the throw it replaces, because it sends the |
| 34 | + * operator hunting for a NULL-distinct index that was never there. So the |
| 35 | + * NULL-safe branch keeps its wording (asserted below as the CONTROL) and the |
| 36 | + * plain branch gets the direct arm's reviewed sentence. |
| 37 | + * |
| 38 | + * Opt-in, like every live cell in this package: |
| 39 | + * |
| 40 | + * OS_TEST_MYSQL_URL=mysql://root:root@127.0.0.1:3306/conformance \ |
| 41 | + * pnpm --filter @objectstack/driver-sql test |
| 42 | + */ |
| 43 | + |
| 44 | +import { describe, it, expect, afterEach } from 'vitest'; |
| 45 | +import { SqlDriver } from '../src/index.js'; |
| 46 | +import { isHashShadowColumn } from './schema-drift.js'; |
| 47 | +import { MYSQL_CELL, declareDialectCell } from './live-dialect-matrix.testkit.js'; |
| 48 | + |
| 49 | +/** 900 chars — comfortably over the 768-char keyable ceiling, so `v` is TEXT. */ |
| 50 | +const LONG = 'p'.repeat(900); |
| 51 | + |
| 52 | +/** |
| 53 | + * A tenancy-DISABLED object whose one long text field carries a PLAIN unique. |
| 54 | + * `maxLength: 1024` exceeds the keyable ceiling, so MySQL refuses the direct |
| 55 | + * index and the sync takes the shadow route; `tenancy: { enabled: false }` is |
| 56 | + * one of the two shapes #14902 identified as reaching the plain path (the other |
| 57 | + * is an explicit `unique: 'global'`, exercised by `globalUniqueOn` below). |
| 58 | + */ |
| 59 | +const plainUniqueOn = (name: string) => ({ |
| 60 | + name, |
| 61 | + tenancy: { enabled: false }, |
| 62 | + fields: { v: { type: 'text', maxLength: 1024 } }, |
| 63 | + indexes: [{ fields: ['v'], unique: true as const, name: `uniq_${name}_v` }], |
| 64 | +}); |
| 65 | + |
| 66 | +/** The second shape of the same path: tenanted object, explicit global scope. */ |
| 67 | +const globalUniqueOn = (name: string) => ({ |
| 68 | + name, |
| 69 | + fields: { |
| 70 | + organization_id: { type: 'string' }, |
| 71 | + v: { type: 'text', maxLength: 1024 }, |
| 72 | + }, |
| 73 | + indexes: [{ fields: ['v'], unique: 'global' as const, name: `uniq_${name}_v` }], |
| 74 | +}); |
| 75 | + |
| 76 | +/** The CONTROL shape: an organization-scoped unique, i.e. the NULL-safe arm. */ |
| 77 | +const orgUniqueOn = (name: string) => ({ |
| 78 | + name, |
| 79 | + fields: { |
| 80 | + organization_id: { type: 'string' }, |
| 81 | + v: { type: 'text', maxLength: 1024 }, |
| 82 | + }, |
| 83 | + indexes: [{ fields: ['v'], unique: 'organization' as const, name: `uniq_${name}_v` }], |
| 84 | +}); |
| 85 | + |
| 86 | +declareDialectCell(MYSQL_CELL, 'hash-shadow plain unique over duplicates (#15479)', (cell) => { |
| 87 | + describe('hash-shadow arm, plain unique over duplicate rows on live MySQL (#15479)', () => { |
| 88 | + let driver: SqlDriver; |
| 89 | + afterEach(async () => { |
| 90 | + await driver?.disconnect().catch(() => {}); |
| 91 | + }); |
| 92 | + |
| 93 | + /** Physical truth, read back from the catalog rather than from our DDL. */ |
| 94 | + const catalog = async (table: string) => { |
| 95 | + const knex = (driver as any).knex; |
| 96 | + const cols = await knex |
| 97 | + .select('COLUMN_NAME', 'DATA_TYPE', 'GENERATION_EXPRESSION') |
| 98 | + .from('information_schema.COLUMNS') |
| 99 | + .where({ TABLE_SCHEMA: knex.client.database(), TABLE_NAME: table }); |
| 100 | + const idx = await knex |
| 101 | + .select('INDEX_NAME', 'NON_UNIQUE', 'COLUMN_NAME', 'SUB_PART') |
| 102 | + .from('information_schema.STATISTICS') |
| 103 | + .where({ TABLE_SCHEMA: knex.client.database(), TABLE_NAME: table }); |
| 104 | + return { cols, idx }; |
| 105 | + }; |
| 106 | + |
| 107 | + /** Collect this driver's log lines rather than letting them reach stdout. */ |
| 108 | + const spy = (): string[] => { |
| 109 | + const logs: string[] = []; |
| 110 | + (driver as any).logger = { |
| 111 | + warn: (msg: string) => logs.push(String(msg)), |
| 112 | + info: (msg: string) => logs.push(String(msg)), |
| 113 | + error: (msg: string) => logs.push(String(msg)), |
| 114 | + }; |
| 115 | + return logs; |
| 116 | + }; |
| 117 | + |
| 118 | + /** |
| 119 | + * Boot the object WITHOUT its unique index, accumulate two rows that |
| 120 | + * violate it, then re-register WITH the index — the legacy-upgrade shape. |
| 121 | + */ |
| 122 | + const seedDuplicatesThenDeclare = async ( |
| 123 | + meta: { name: string; indexes: unknown[] }, |
| 124 | + row: Record<string, unknown>, |
| 125 | + ): Promise<{ logs: string[]; err: unknown }> => { |
| 126 | + driver = new SqlDriver(cell.config()); |
| 127 | + const logs = spy(); |
| 128 | + await driver.initObjects([{ ...meta, indexes: [] }] as any); |
| 129 | + const knex = (driver as any).knex; |
| 130 | + await knex(meta.name).insert([ |
| 131 | + { id: 'a', ...row }, |
| 132 | + { id: 'b', ...row }, |
| 133 | + ]); |
| 134 | + const err: unknown = await driver.initObjects([meta] as any).then( |
| 135 | + () => null, |
| 136 | + (e) => e, |
| 137 | + ); |
| 138 | + return { logs, err }; |
| 139 | + }; |
| 140 | + |
| 141 | + // ── Why each it() carries an explicit 60_000 budget (#13902) ── |
| 142 | + // Each block constructs a FRESH `new SqlDriver(...)` against this cell's |
| 143 | + // live server inside its own body, so the connect cycle plus the schema-sync |
| 144 | + // DDL and catalog read-back are paid PER TEST rather than once in a |
| 145 | + // beforeAll. Sized like this package's siblings; not a claim that these are |
| 146 | + // normally anywhere near that slow. |
| 147 | + |
| 148 | + /** |
| 149 | + * THE CARD'S THREE ACCEPTANCE CONDITIONS, on the `tenancy: { enabled: false }` |
| 150 | + * shape: the boot survives, the durability log names the conflicting group |
| 151 | + * and the remedy, and the index is absent afterwards. |
| 152 | + */ |
| 153 | + it('survives the boot and diagnoses duplicates under a tenancy-disabled plain unique', async () => { |
| 154 | + const { logs, err } = await seedDuplicatesThenDeclare(plainUniqueOn('os15479_plain'), { |
| 155 | + v: LONG, |
| 156 | + }); |
| 157 | + |
| 158 | + expect(err, 'the boot must NOT die: this is a degradation, not a fatal').toBeNull(); |
| 159 | + |
| 160 | + const diagnosis = logs.find((l) => l.includes("cannot create hash-shadow unique index 'uniq_os15479_plain_v'")); |
| 161 | + expect(diagnosis, 'the degradation must reach the durability channel').toBeTruthy(); |
| 162 | + expect(diagnosis).toMatch(/Conflicting group\(s\): \(v="p+"\) × 2 rows/); |
| 163 | + expect(diagnosis).toMatch(/os migrate plan/); |
| 164 | + expect(diagnosis).toContain("The constraint 'v' is NOT enforced"); |
| 165 | + |
| 166 | + // ⛔ And it must NOT carry the NULL-safe arm's framing, which is false |
| 167 | + // here: nothing admitted these rows and there is no NULL-safe key. |
| 168 | + expect(diagnosis).not.toContain('#5030'); |
| 169 | + expect(diagnosis).not.toContain('NULL-safe'); |
| 170 | + expect(diagnosis).not.toContain('COALESCE'); |
| 171 | + |
| 172 | + // The constraint is honestly ABSENT, and the atomic ALTER left no |
| 173 | + // orphaned shadow column behind. |
| 174 | + const { cols, idx } = await catalog('os15479_plain'); |
| 175 | + expect(idx.some((i: any) => i.INDEX_NAME === 'uniq_os15479_plain_v')).toBe(false); |
| 176 | + expect(cols.filter((c: any) => isHashShadowColumn(c.COLUMN_NAME))).toEqual([]); |
| 177 | + }, 60_000); |
| 178 | + |
| 179 | + /** |
| 180 | + * The same disposition on the OTHER shape that reaches the plain path — an |
| 181 | + * explicit `unique: 'global'` on a tenanted object. Two shapes because |
| 182 | + * #14902 measured both, and a guard keyed on the wrong one would pass here |
| 183 | + * and fail in production. |
| 184 | + */ |
| 185 | + it("survives the boot under an explicit unique: 'global' on a tenanted object", async () => { |
| 186 | + const { logs, err } = await seedDuplicatesThenDeclare(globalUniqueOn('os15479_global'), { |
| 187 | + v: LONG, |
| 188 | + organization_id: 'org_a', |
| 189 | + }); |
| 190 | + |
| 191 | + expect(err, 'the boot must NOT die').toBeNull(); |
| 192 | + const diagnosis = logs.find((l) => l.includes("cannot create hash-shadow unique index 'uniq_os15479_global_v'")); |
| 193 | + expect(diagnosis, 'the degradation must reach the durability channel').toBeTruthy(); |
| 194 | + expect(diagnosis).toMatch(/Conflicting group\(s\):/); |
| 195 | + expect(diagnosis).not.toContain('#5030'); |
| 196 | + expect(diagnosis).not.toContain('COALESCE'); |
| 197 | + |
| 198 | + const { idx } = await catalog('os15479_global'); |
| 199 | + expect(idx.some((i: any) => i.INDEX_NAME === 'uniq_os15479_global_v')).toBe(false); |
| 200 | + }, 60_000); |
| 201 | + |
| 202 | + /** |
| 203 | + * ⛔ THE CONTROL for the message split: the NULL-safe arm keeps its OWN |
| 204 | + * wording. A one-character fix that widened the guard and left a single |
| 205 | + * message would pass the two blocks above and fail exactly here — and the |
| 206 | + * inverse mistake, rewriting both arms into the plain sentence, fails here |
| 207 | + * too. |
| 208 | + */ |
| 209 | + it('leaves the NULL-safe arm saying the NULL-safe thing', async () => { |
| 210 | + const { logs, err } = await seedDuplicatesThenDeclare(orgUniqueOn('os15479_org'), { |
| 211 | + v: LONG, |
| 212 | + organization_id: null, |
| 213 | + }); |
| 214 | + |
| 215 | + expect(err, 'the NULL-safe arm already survived the boot').toBeNull(); |
| 216 | + const diagnosis = logs.find((l) => l.includes("cannot create hash-shadow unique index 'uniq_os15479_org_v'")); |
| 217 | + expect(diagnosis, 'the NULL-safe degradation must still be logged').toBeTruthy(); |
| 218 | + expect(diagnosis).toContain('#5030'); |
| 219 | + expect(diagnosis).toContain('NULL-safe'); |
| 220 | + expect(diagnosis).toContain("COALESCE(organization_id, '__global__')"); |
| 221 | + }, 60_000); |
| 222 | + |
| 223 | + /** |
| 224 | + * The positive control that the widened guard did not turn the shadow route |
| 225 | + * off: over CLEAN data the plain unique is still CREATED, on the shadow |
| 226 | + * column, and still enforces. |
| 227 | + */ |
| 228 | + it('still creates and enforces the plain shadow unique over clean data', async () => { |
| 229 | + driver = new SqlDriver(cell.config()); |
| 230 | + spy(); |
| 231 | + await driver.initObjects([plainUniqueOn('os15479_clean')] as any); |
| 232 | + |
| 233 | + const { cols, idx } = await catalog('os15479_clean'); |
| 234 | + const shadow = cols.find((c: any) => isHashShadowColumn(c.COLUMN_NAME)); |
| 235 | + expect(shadow, 'a shadow column must exist').toBeTruthy(); |
| 236 | + const carried = idx.filter((i: any) => isHashShadowColumn(i.COLUMN_NAME)); |
| 237 | + expect(carried.length).toBe(1); |
| 238 | + expect(Number(carried[0].NON_UNIQUE)).toBe(0); |
| 239 | + |
| 240 | + const knex = (driver as any).knex; |
| 241 | + await knex('os15479_clean').insert({ id: 'a', v: LONG }); |
| 242 | + await expect(knex('os15479_clean').insert({ id: 'b', v: LONG })).rejects.toThrow(/duplicate/i); |
| 243 | + await knex('os15479_clean').insert({ id: 'c', v: 'q'.repeat(900) }); |
| 244 | + }, 60_000); |
| 245 | + }); |
| 246 | +}); |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?v=4&size=40){kind=avatar}
0 commit comments