test(drizzle): v3 DB integration suite (provisioning, round-trip, domain matrix)

DB-gated suites (describe.skipIf without DATABASE_URL): advisory-lock
installer, text_eq round-trip, and the text domain matrix with an in-memory
oracle and negative assertions (domain CHECK, blocker RAISE, wrong-domain).

Author: tobyhede

packages/drizzle/__tests__/eql-v3.test.ts

@@ -0,0 +1,269 @@
+import 'dotenv/config'
+import { protect } from '@cipherstash/protect'
+import { sql as dsql } from 'drizzle-orm'
+import { pgTable } from 'drizzle-orm/pg-core'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import {
+  createProtectOperators,
+  eqlV3Type,
+  extractProtectSchema,
+} from '../src/pg/v3/index'
+import {
+  oracleAscLabels,
+  oracleContains,
+  oracleEq,
+  oracleLt,
+  oracleNe,
+  v3SeedData,
+} from './fixtures/eql-v3-seed-data'
+import { installEqlV3 } from './v3/helpers/install-v3'
+
+// DB-gated suite: skipped (not failed) without DATABASE_URL — see provisioning.test.ts.
+const HAS_DB = !!process.env.DATABASE_URL
+
+const SKIP_ORDER_BY = true // shared CI DB, mirrors drizzle.test.ts:61
+const TABLE = `v3_matrix_${Date.now()}`
+
+const table = pgTable(TABLE, {
+  t_storage: eqlV3Type<string>('t_storage', { dataType: 'text' }),
+  t_eq: eqlV3Type<string>('t_eq', { dataType: 'text', index: 'equality' }),
+  t_match: eqlV3Type<string>('t_match', {
+    dataType: 'text',
+    index: 'freeTextSearch',
+  }),
+  t_ord: eqlV3Type<string>('t_ord', {
+    dataType: 'text',
+    index: 'orderAndRange',
+  }),
+})
+const schema = extractProtectSchema(table)
+
+let sql: ReturnType<typeof postgres>
+let db: ReturnType<typeof drizzle>
+let pc: Awaited<ReturnType<typeof protect>>
+let ops: ReturnType<typeof createProtectOperators>
+
+// biome-ignore lint/suspicious/noExplicitAny: test unwrap
+function unwrap(r: any) {
+  if (r.failure) {
+    throw new Error(
+      `[protect] ${r.failure.message ?? JSON.stringify(r.failure)}`,
+    )
+  }
+  return r.data
+}
+
+beforeAll(async () => {
+  if (!HAS_DB) return
+  // { prepare: false } is required for the pooled CI DB (PgBouncer transaction
+  // mode) — mirrors packages/protect/__tests__/searchable-json-pg.test.ts:12.
+  sql = postgres(process.env.DATABASE_URL as string, { prepare: false })
+  await installEqlV3(sql)
+  await sql.unsafe(`CREATE TABLE IF NOT EXISTS "${TABLE}" (
+    t_storage eql_v3.text,
+    t_eq eql_v3.text_eq,
+    t_match eql_v3.text_match,
+    t_ord eql_v3.text_ord
+  )`)
+  await sql.unsafe(
+    `CREATE INDEX IF NOT EXISTS "${TABLE}_eq_idx" ON "${TABLE}" (eql_v3.eq_term(t_eq))`,
+  )
+  await sql.unsafe(
+    `CREATE INDEX IF NOT EXISTS "${TABLE}_match_idx" ON "${TABLE}" USING gin (eql_v3.match_term(t_match))`,
+  )
+  await sql.unsafe(
+    `CREATE INDEX IF NOT EXISTS "${TABLE}_ord_idx" ON "${TABLE}" (eql_v3.ord_term(t_ord))`,
+  )
+
+  db = drizzle({ client: sql })
+  pc = await protect({ schemas: [schema] })
+  ops = createProtectOperators(pc)
+
+  const models = v3SeedData.map((r) => ({
+    t_storage: r.label,
+    t_eq: r.label,
+    t_match: r.label,
+    t_ord: r.label,
+  }))
+  const enc = unwrap(await pc.bulkEncryptModels(models, schema))
+  await db.insert(table).values(enc as never[])
+}, 180000)
+
+afterAll(async () => {
+  await sql?.unsafe(`DROP TABLE IF EXISTS "${TABLE}"`)
+  await sql?.end()
+})
+
+async function decryptLabels(
+  rows: unknown[],
+  col: 't_storage' | 't_eq' | 't_match' | 't_ord',
+) {
+  const dec = unwrap(await pc.bulkDecryptModels(rows as never[]))
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic col access
+  return dec.map((d: any) => d[col]).sort()
+}
+
+describe.skipIf(!HAS_DB)('EQL v3 text domain matrix', () => {
+  it('t_storage: insert + decrypt round-trip', async () => {
+    const rows = await db.select().from(table)
+    expect(rows.length).toBe(v3SeedData.length)
+    const labels = await decryptLabels(rows, 't_storage')
+    expect(labels).toEqual(v3SeedData.map((r) => r.label).sort())
+  })
+
+  it('t_storage: NULL round-trips through the adapter codec (not just raw IS NULL)', async () => {
+    await sql.unsafe(`INSERT INTO "${TABLE}" (t_storage) VALUES (NULL)`)
+    // Read the NULL row back THROUGH the Drizzle typed column so v3FromDriver's
+    // null branch is exercised, then decrypt through the codec — proving the
+    // adapter maps a DB NULL to a JS null end-to-end, not just that a NULL exists.
+    const nullRows = await db
+      .select()
+      .from(table)
+      .where(dsql`${table.t_storage} IS NULL`)
+    expect(nullRows.length).toBeGreaterThanOrEqual(1)
+    // biome-ignore lint/suspicious/noExplicitAny: reading the typed column value
+    expect((nullRows[0] as any).t_storage).toBeNull()
+    const dec = unwrap(await pc.bulkDecryptModels(nullRows as never[]))
+    expect(dec[0].t_storage).toBeNull()
+  })
+
+  it('t_eq: = returns exactly the matching row(s)', async () => {
+    const rows = await db
+      .select()
+      .from(table)
+      .where(await ops.eq(table.t_eq, 'banana'))
+    expect(await decryptLabels(rows, 't_eq')).toEqual(
+      oracleEq('banana').map((r) => r.label),
+    )
+  })
+
+  it('t_eq: <> returns the exact complement', async () => {
+    const rows = await db
+      .select()
+      .from(table)
+      .where(await ops.ne(table.t_eq, 'banana'))
+    expect(await decryptLabels(rows, 't_eq')).toEqual(
+      oracleNe('banana')
+        .map((r) => r.label)
+        .sort(),
+    )
+  })
+
+  it('t_eq: HMAC determinism — duplicate plaintext, = returns both', async () => {
+    const enc = unwrap(await pc.bulkEncryptModels([{ t_eq: 'banana' }], schema))
+    await db.insert(table).values(enc[0] as never)
+    const rows = await db
+      .select()
+      .from(table)
+      .where(await ops.eq(table.t_eq, 'banana'))
+    expect(rows.length).toBe(2)
+  })
+
+  it('t_match: containment returns matches and excludes non-matching', async () => {
+    const rows = await db
+      .select()
+      .from(table)
+      .where(await ops.ilike(table.t_match, 'aard'))
+    const got = await decryptLabels(rows, 't_match')
+    expect(got).toEqual(
+      oracleContains('aard')
+        .map((r) => r.label)
+        .sort(),
+    )
+    expect(got).not.toContain('banana')
+  })
+
+  it('t_ord: < returns the lexicographic prefix set', async () => {
+    const rows = await db
+      .select()
+      .from(table)
+      .where(await ops.lt(table.t_ord, 'cherry'))
+    expect(await decryptLabels(rows, 't_ord')).toEqual(
+      oracleLt('cherry')
+        .map((r) => r.label)
+        .sort(),
+    )
+  })
+
+  const ordByIt = SKIP_ORDER_BY ? it.skip : it
+  ordByIt('t_ord: ORDER BY returns the exact decrypted sequence', async () => {
+    const rows = await db.select().from(table).orderBy(ops.asc(table.t_ord))
+    const dec = unwrap(await pc.bulkDecryptModels(rows as never[]))
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic col
+    expect(dec.map((d: any) => d.t_ord)).toEqual(oracleAscLabels())
+  })
+
+  // §7 min/max coverage. Skipped under the same shared-CI ORDER BY constraint
+  // (MIN/MAX over an encrypted ord domain relies on the same ORE ordering the
+  // CI DB declines). Present as a stub so the gap is visible, not omitted.
+  ordByIt('t_ord: MIN()/MAX() return the lexicographic extremes', async () => {
+    const rows = await sql.unsafe(
+      `SELECT eql_v3.min(t_ord) AS lo, eql_v3.max(t_ord) AS hi FROM "${TABLE}"`,
+    )
+    expect(rows.length).toBe(1)
+  })
+})
+
+describe.skipIf(!HAS_DB)('v3 negative assertions', () => {
+  it('CHECK rejects a match payload (bf, no hm) inserted into text_eq', async () => {
+    // A match payload carries {c,i,v,bf} but no hm; text_eq_check requires hm, so
+    // coercing it into text_eq fails with the domain CHECK (SQLSTATE 23514).
+    const matchEnc = unwrap(
+      await pc.bulkEncryptModels([{ t_match: 'banana' }], schema),
+    )
+    const badPayload = JSON.stringify(
+      (matchEnc[0] as Record<string, unknown>).t_match,
+    )
+    await expect(
+      sql.unsafe(
+        `INSERT INTO "${TABLE}" (t_eq) VALUES ('${badPayload}'::jsonb::eql_v3.text_eq)`,
+      ),
+    ).rejects.toThrow(/text_eq_check|23514/i)
+  })
+
+  it('blocker RAISEs for an unsupported ordering operator on text_eq', async () => {
+    // text_eq is equality-only: eql_v3.lt(text_eq, …) is a blocker that RAISEs
+    // 'operator < is not supported for eql_v3.text_eq' — NOT a bare Postgres 42883
+    // "operator does not exist". The operator EXISTS and binds the blocker fn.
+    await expect(
+      sql.unsafe(`SELECT * FROM "${TABLE}" WHERE t_eq < t_eq`),
+    ).rejects.toThrow(/not supported for .*eql_v3\.text_eq/i)
+  })
+
+  it('wrong-domain: an eq-shaped term used as text_ord is rejected, not silently coerced', async () => {
+    // An eq value has {c,i,v,hm} but no ob. The text_ord `=` operator extracts the
+    // ord term via eql_v3.ord_term → eql_v3.ore_block_u64_8_256(jsonb), which RAISEs
+    // 'Expected an ore index (ob) value in json' for the missing ob. (text_ord_check
+    // would also reject it; either is an intentional v3 guard, never silent coercion.)
+    const eqEnc = unwrap(
+      await pc.bulkEncryptModels([{ t_eq: 'banana' }], schema),
+    )
+    const eqTerm = JSON.stringify((eqEnc[0] as Record<string, unknown>).t_eq)
+    await expect(
+      sql.unsafe(
+        `SELECT * FROM "${TABLE}" WHERE t_ord = '${eqTerm}'::jsonb::eql_v3.text_ord`,
+      ),
+    ).rejects.toThrow(/ore index \(ob\)|text_ord_check|23514/i)
+  })
+
+  it('mapping gaps are loud (pure function rejects out-of-scope tuples)', async () => {
+    const { eqlV3Domain } = await import('../src/pg/v3/domain-map')
+    // @ts-expect-error number has no v3 domain in this milestone
+    expect(() => eqlV3Domain('number', 'equality')).toThrow(/unsupported/i)
+  })
+})
+
+describe.skipIf(!HAS_DB)('v3 functional index definitions', () => {
+  it('eq_term / match_term / ord_term functional indexes exist on the table', async () => {
+    const rows = await sql`
+      SELECT indexname, indexdef FROM pg_indexes
+      WHERE tablename = ${TABLE}
+    `
+    const defs = rows.map((r) => r.indexdef as string).join('\n')
+    expect(defs).toContain('eq_term')
+    expect(defs).toContain('match_term')
+    expect(defs).toContain('ord_term')
+  })
+})

packages/drizzle/__tests__/fixtures/eql-v3-seed-data.ts

@@ -0,0 +1,28 @@
+export type V3SeedRow = { label: string }
+
+/** Lexicographic spread for ord; shared-trigram pair (aardvark/aard) for match. */
+export const v3SeedData: V3SeedRow[] = [
+  { label: 'aardvark' },
+  { label: 'aard' },
+  { label: 'banana' },
+  { label: 'cherry' },
+  { label: 'date' },
+]
+
+export function oracleEq(target: string): V3SeedRow[] {
+  return v3SeedData.filter((r) => r.label === target)
+}
+export function oracleNe(target: string): V3SeedRow[] {
+  return v3SeedData.filter((r) => r.label !== target)
+}
+export function oracleContains(sub: string): V3SeedRow[] {
+  return v3SeedData.filter((r) => r.label.includes(sub))
+}
+export function oracleLt(target: string): V3SeedRow[] {
+  return v3SeedData.filter((r) => r.label < target)
+}
+export function oracleAscLabels(): string[] {
+  return [...v3SeedData]
+    .sort((a, b) => a.label.localeCompare(b.label))
+    .map((r) => r.label)
+}

packages/drizzle/__tests__/v3/helpers/install-v3.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import type postgres from 'postgres'
+
+const SQL_PATH = fileURLToPath(
+  new URL('../../fixtures/cipherstash-encrypt-v3.sql', import.meta.url),
+)
+
+/**
+ * Installs the v3 SQL. Multi-statement DDL requires sql.unsafe (tagged-template
+ * sql`` runs a single statement).
+ *
+ * Idempotency is GUARDED, not via CREATE OR REPLACE: the EQL v3 SQL hardcodes the
+ * `eql_v3` schema and its `CREATE DOMAIN`/`CREATE OPERATOR` have no OR REPLACE, so a
+ * blind re-install errors on the second run. We therefore probe for `eql_v3.text_eq`
+ * and skip the install if it already exists.
+ *
+ * The probe-then-install runs inside ONE transaction holding a transaction-scoped
+ * advisory lock, so it is also concurrency-safe: the `eql_v3` schema is global and
+ * shared across the protect/stack/drizzle suites Turbo runs, and without the lock
+ * two suites could both pass the probe before either installs, then race on
+ * `CREATE DOMAIN` (which has no OR REPLACE). A `pg_advisory_xact_lock` serialises
+ * that window — the first holder installs, the rest see `text_eq` present and
+ * no-op (§9b). It MUST be a transaction (not a bare session lock): `sql` is a
+ * connection pool, so a session lock and its unlock could land on different pooled
+ * connections (and would not survive PgBouncer transaction mode). A single
+ * `sql.begin` keeps the lock, probe, and install on one connection and auto-releases
+ * the lock at commit.
+ */
+const INSTALL_LOCK_KEY = 'eql_v3_install'
+
+export async function installEqlV3(sql: postgres.Sql): Promise<void> {
+  const ddl = readFileSync(SQL_PATH, 'utf-8')
+  await sql.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtext(${INSTALL_LOCK_KEY}))`
+    const [present] = await tx`
+      SELECT 1 FROM pg_type t
+      JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname = 'eql_v3' AND t.typname = 'text_eq'
+    `
+    if (present) return // already installed by an earlier run / sibling suite
+    await tx.unsafe(ddl)
+  })
+}

packages/drizzle/__tests__/v3/provisioning.test.ts

@@ -0,0 +1,45 @@
+import 'dotenv/config'
+import postgres from 'postgres'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { installEqlV3 } from './helpers/install-v3'
+
+// DB-gated suite: without DATABASE_URL the whole describe is skipped (not failed),
+// so a bare `pnpm test` reports skips rather than a hard import-time throw.
+const HAS_DB = !!process.env.DATABASE_URL
+
+let sql: ReturnType<typeof postgres>
+
+beforeAll(async () => {
+  if (!HAS_DB) return
+  // { prepare: false } is required for the pooled CI DB (PgBouncer transaction
+  // mode) — mirrors packages/protect/__tests__/searchable-json-pg.test.ts:12.
+  sql = postgres(process.env.DATABASE_URL as string, { prepare: false })
+  await installEqlV3(sql)
+}, 120000)
+
+afterAll(async () => {
+  await sql?.end()
+})
+
+describe.skipIf(!HAS_DB)('v3 DB provisioning', () => {
+  it('installs the eql_v3 schema and its text_eq domain', async () => {
+    const rows = await sql`
+      SELECT 1 FROM pg_type t
+      JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname = 'eql_v3' AND t.typname = 'text_eq'
+    `
+    expect(rows.length).toBe(1)
+  })
+
+  it('the v3 extractor functions were installed (eq_term, ord_term, match_term)', async () => {
+    const fns = await sql`
+      SELECT proname FROM pg_proc p
+      JOIN pg_namespace n ON n.oid = p.pronamespace
+      WHERE n.nspname = 'eql_v3' AND p.proname IN ('eq_term','ord_term','match_term')
+    `
+    // >= 3, not == 3: each extractor is overloaded per scalar (text/int2/int4/int8/
+    // date/timestamptz/…), so there are many rows. At least one per name proves the
+    // DDL executed rather than silently no-op'ing.
+    expect(fns.length).toBeGreaterThanOrEqual(3)
+  })
+})