|
| 1 | +import { writeFileSync, mkdirSync } from 'node:fs' |
| 2 | +import { resolve, dirname } from 'node:path' |
| 3 | +import { fileURLToPath } from 'node:url' |
| 4 | +import type { SQL } from 'drizzle-orm' |
| 5 | +import { afterAll, beforeAll, describe, expect, it } from 'vitest' |
| 6 | +import { buildDrizzleQueries } from '../../src/drizzle/queries.js' |
| 7 | +import { |
| 8 | + type BenchHandle, |
| 9 | + benchTable, |
| 10 | + buildBench, |
| 11 | + teardownBench, |
| 12 | +} from '../../src/drizzle/setup.js' |
| 13 | +import { applySchema } from '../../src/harness/db.js' |
| 14 | +import { |
| 15 | + type PlanNode, |
| 16 | + explain, |
| 17 | + hasSeqScan, |
| 18 | + summarize, |
| 19 | + topScan, |
| 20 | +} from '../../src/harness/explain.js' |
| 21 | +import { seed } from '../../src/harness/seed.js' |
| 22 | + |
| 23 | +const __dirname = dirname(fileURLToPath(import.meta.url)) |
| 24 | +const resultsDir = resolve(__dirname, '..', '..', 'results') |
| 25 | + |
| 26 | +let handle: BenchHandle |
| 27 | +let q: ReturnType<typeof buildDrizzleQueries> |
| 28 | +const investigationLog: Record<string, unknown> = { observations: {} } |
| 29 | + |
| 30 | +beforeAll(async () => { |
| 31 | + handle = await buildBench() |
| 32 | + await applySchema(handle.pgClient) |
| 33 | + await seed(handle) |
| 34 | + q = buildDrizzleQueries(handle.encryptionClient) |
| 35 | +}) |
| 36 | + |
| 37 | +afterAll(async () => { |
| 38 | + if (handle) await teardownBench(handle) |
| 39 | + |
| 40 | + // Persist #422 investigation outputs as a JSON artifact regardless of pass/fail. |
| 41 | + try { |
| 42 | + mkdirSync(resultsDir, { recursive: true }) |
| 43 | + writeFileSync( |
| 44 | + resolve(resultsDir, 'explain-shape.json'), |
| 45 | + `${JSON.stringify(investigationLog, null, 2)}\n`, |
| 46 | + ) |
| 47 | + } catch (err) { |
| 48 | + console.warn('[bench] failed to persist investigation log:', err) |
| 49 | + } |
| 50 | +}) |
| 51 | + |
| 52 | +/** |
| 53 | + * Compile a Drizzle WHERE expression to SQL+params and run EXPLAIN against it. |
| 54 | + * Wraps in a SELECT that touches the bench table so the planner has to make |
| 55 | + * a decision on the encrypted column. |
| 56 | + */ |
| 57 | +async function explainWhere(where: SQL): Promise<PlanNode> { |
| 58 | + const query = handle.db.select().from(benchTable).where(where) |
| 59 | + const compiled = query.toSQL() |
| 60 | + return explain(handle.pgClient, compiled.sql, compiled.params as unknown[]) |
| 61 | +} |
| 62 | + |
| 63 | +async function explainOrderBy(orderBy: SQL): Promise<PlanNode> { |
| 64 | + const query = handle.db.select().from(benchTable).orderBy(orderBy).limit(10) |
| 65 | + const compiled = query.toSQL() |
| 66 | + return explain(handle.pgClient, compiled.sql, compiled.params as unknown[]) |
| 67 | +} |
| 68 | + |
| 69 | +function recordObservation(name: string, plan: PlanNode): void { |
| 70 | + const scan = topScan(plan) |
| 71 | + investigationLog.observations = { |
| 72 | + ...(investigationLog.observations as Record<string, unknown>), |
| 73 | + [name]: { |
| 74 | + summary: summarize(plan), |
| 75 | + nodeType: scan?.['Node Type'], |
| 76 | + indexName: scan?.['Index Name'] ?? null, |
| 77 | + }, |
| 78 | + } |
| 79 | +} |
| 80 | + |
| 81 | +function recordError(name: string, err: unknown): void { |
| 82 | + investigationLog.observations = { |
| 83 | + ...(investigationLog.observations as Record<string, unknown>), |
| 84 | + [name]: { |
| 85 | + error: err instanceof Error ? err.message : String(err), |
| 86 | + }, |
| 87 | + } |
| 88 | +} |
| 89 | + |
| 90 | +/** |
| 91 | + * Run a Drizzle WHERE-shaped expression through EXPLAIN, but if compiling or |
| 92 | + * planning the query fails (e.g. the operator returns a non-boolean type), log |
| 93 | + * the error to the investigation artifact instead of bubbling it. #422 tests |
| 94 | + * must never block CI — they're observational. |
| 95 | + */ |
| 96 | +async function tryExplainWhere(name: string, where: SQL): Promise<void> { |
| 97 | + try { |
| 98 | + const plan = await explainWhere(where) |
| 99 | + recordObservation(name, plan) |
| 100 | + } catch (err) { |
| 101 | + recordError(name, err) |
| 102 | + } |
| 103 | +} |
| 104 | + |
| 105 | +// --- #421: equality + array operators ------------------------------------- |
| 106 | +// |
| 107 | +// `bench_text_hmac_idx` (functional hash on eql_v2.hmac_256) is the expected |
| 108 | +// fast path. Pre-fix Drizzle emits bare `=` / `<>` / `IN (...)` which falls |
| 109 | +// back to seq scan. Post-fix it emits `eql_v2.hmac_256(col) = |
| 110 | +// eql_v2.hmac_256(value)` and the index scan kicks in. |
| 111 | +// |
| 112 | +// `eq` and `inArray` are naturally high-selectivity (only a few rows match), |
| 113 | +// so the planner should pick the hmac index — assertion enforces it. |
| 114 | +// |
| 115 | +// `ne` and `notInArray` are naturally low-selectivity (almost all rows match); |
| 116 | +// even with the hmac index available the planner correctly chooses a seq |
| 117 | +// scan because it would re-touch nearly every row. We record their plans for |
| 118 | +// the investigation log but don't assert — the SQL shape is what matters, |
| 119 | +// and that's covered by the unit tests under packages/stack. |
| 120 | +describe('#421: equality and array operators', () => { |
| 121 | + it('eq engages the hmac functional index', async () => { |
| 122 | + const plan = await explainWhere(await q.eq('value-0000042')) |
| 123 | + recordObservation('eq', plan) |
| 124 | + expect(hasSeqScan(plan), summarize(plan)).toBe(false) |
| 125 | + }) |
| 126 | + |
| 127 | + it('inArray engages the hmac functional index', async () => { |
| 128 | + const plan = await explainWhere( |
| 129 | + await q.inArray(['value-0000042', 'value-0000123', 'value-0000999']), |
| 130 | + ) |
| 131 | + recordObservation('inArray', plan) |
| 132 | + expect(hasSeqScan(plan), summarize(plan)).toBe(false) |
| 133 | + }) |
| 134 | + |
| 135 | + it('records ne plan shape (low-selectivity, not asserted)', async () => { |
| 136 | + const plan = await explainWhere(await q.ne('value-0000042')) |
| 137 | + recordObservation('ne', plan) |
| 138 | + }) |
| 139 | + |
| 140 | + it('records notInArray plan shape (low-selectivity, not asserted)', async () => { |
| 141 | + const plan = await explainWhere( |
| 142 | + await q.notInArray(['value-0000042', 'value-0000123']), |
| 143 | + ) |
| 144 | + recordObservation('notInArray', plan) |
| 145 | + }) |
| 146 | +}) |
| 147 | + |
| 148 | +// --- #422: investigation operators ---------------------------------------- |
| 149 | +// |
| 150 | +// We don't yet know which call-shaped forms the planner inlines. Record plan |
| 151 | +// shape; assertions land in a follow-up once #422 closes. |
| 152 | +describe('#422: call-shaped operators (recorded, not asserted)', () => { |
| 153 | + it('records like / ilike plan shapes', async () => { |
| 154 | + await tryExplainWhere('like', (await q.like('%value-00000%')) as SQL) |
| 155 | + await tryExplainWhere('ilike', (await q.ilike('%VALUE-00000%')) as SQL) |
| 156 | + }) |
| 157 | + |
| 158 | + it('records gt / gte / lt / lte plan shapes', async () => { |
| 159 | + for (const [name, build] of [ |
| 160 | + ['gt', () => q.gt(5000)], |
| 161 | + ['gte', () => q.gte(5000)], |
| 162 | + ['lt', () => q.lt(5000)], |
| 163 | + ['lte', () => q.lte(5000)], |
| 164 | + ] as const) { |
| 165 | + await tryExplainWhere(name, (await build()) as SQL) |
| 166 | + } |
| 167 | + }) |
| 168 | + |
| 169 | + it('records between plan shape', async () => { |
| 170 | + await tryExplainWhere('between', (await q.between(2500, 7500)) as SQL) |
| 171 | + }) |
| 172 | + |
| 173 | + it('records jsonb operator plan shapes', async () => { |
| 174 | + for (const [name, build] of [ |
| 175 | + ['jsonbPathQueryFirst', () => q.jsonbPathQueryFirst('$.idx')], |
| 176 | + ['jsonbGet', () => q.jsonbGet('$.idx')], |
| 177 | + ['jsonbPathExists', () => q.jsonbPathExists('$.idx')], |
| 178 | + ] as const) { |
| 179 | + await tryExplainWhere(name, await build()) |
| 180 | + } |
| 181 | + }) |
| 182 | + |
| 183 | + it('records ORDER BY plan shape (asc / desc)', async () => { |
| 184 | + for (const [name, sql] of [ |
| 185 | + ['asc', q.asc()], |
| 186 | + ['desc', q.desc()], |
| 187 | + ] as const) { |
| 188 | + try { |
| 189 | + const plan = await explainOrderBy(sql) |
| 190 | + recordObservation(`orderBy_${name}`, plan) |
| 191 | + } catch (err) { |
| 192 | + recordError(`orderBy_${name}`, err) |
| 193 | + } |
| 194 | + } |
| 195 | + }) |
| 196 | +}) |
0 commit comments