perf(stack/drizzle): wrap eq/ne/inArray/notInArray in eql_v2.hmac_256(...)

[coderdan]

Summary

Stacked on #424.

Fixes #421. Bare col = value (and <>, IN, NOT IN) only engages the eql_v2.encrypted_operator_class btree index, which doesn't exist on Supabase or any --exclude-operator-family install. Customers there silently seq-scan every encrypted equality lookup at any scale.

This change wraps both sides of the comparison in eql_v2.hmac_256(...) so the canonical hmac_256 functional hash index engages on every install.

What changed

packages/stack/src/drizzle/operators.ts:

• eq / ne (around line 728): emitted SQL goes from col = $1 to eql_v2.hmac_256(col) = eql_v2.hmac_256($1) (and <> for ne).
• inArray / notInArray (around lines 1486 / 1532): each comparison in the OR/AND chain wraps both sides in eql_v2.hmac_256(...). Postgres can BitmapOr several hash-index scans, so the OR-of-eq stays as fast as a single equality lookup per value.

Plan-shape verification

EXPLAIN on the same 10k-row fixture (from #424's bench), before vs after:

Operator	Before fix	After fix
eq	Seq Scan	Index Scan on bench_text_hmac_idx
inArray	Seq Scan	Bitmap Heap Scan
ne	Seq Scan	Seq Scan (low-selectivity, expected)
notInArray	Seq Scan	Seq Scan (low-selectivity, expected)

ne and notInArray continue to seq-scan post-fix, but for the right reason: <> against a single value matches ~all rows, so the planner correctly avoids the index. The SQL form is now correct on Supabase and the planner makes the right call regardless.

Wall-clock benchmark

pnpm -F @cipherstash/bench bench:local against the same 10k-row fixture, vitest --bench (tinybench under the hood). Higher hz is better; lower mean is better.

Operator	Before (hz)	After (hz)	Before mean (ms)	After mean (ms)	Speedup
eq (string match)	5.53	1,910.73	180.7	0.52	~345×
inArray (3 string matches)	1.46	1,696.64	686.4	0.59	~1163×
like (prefix)	1.33	1.38	754.6	724.8	— (#422)
gt (int)	2.03	1.95	493.0	513.4	— (#422)
between (int)	1.25	1.27	798.1	787.0	— (#422)
orderBy desc + limit 10	2.99	3.09	334.8	323.2	— (#422)

Operators outside the scope of this fix (like, gt, between, orderBy) are unchanged within noise — those still seq-scan because their call-shaped forms aren't being inlined by the planner. Tracked separately in #422.

What's NOT in this PR

• The legacy packages/drizzle/src/pg/operators.ts:731 has the identical bug. Tracked in perf: legacy @cipherstash/drizzle has the same bare-equality bug as @cipherstash/stack/drizzle #426.
• investigate: do Drizzle's call-shaped forms (like/ilike/gt/order_by/jsonb_*) actually engage functional indexes? #422 (call-shaped operators not engaging functional indexes) is broader and likely needs an EQL-side fix to function inlinability. Tracked separately.
• Drizzle jsonbPathQueryFirst / jsonbGet typed as predicates but return eql_v2_encrypted #423 (jsonbPathQueryFirst / jsonbGet typed as predicates but return eql_v2_encrypted) is an API-shape bug surfaced by the same bench. Tracked separately.

Test plan

• On this branch, in packages/bench: pnpm db:setup && pnpm test:local. Expect 9/9 green on __tests__/drizzle/operators.explain.test.ts.
• Inspect packages/bench/results/explain-shape.json — eq should report Index Scan on bench_text_hmac_idx; inArray should report Bitmap Heap Scan.
• Existing @cipherstash/stack unit tests still pass: pnpm -F @cipherstash/stack test.

Summary by CodeRabbit

• Performance
  • Improved query performance for encrypted columns. Equality checks, inequality comparisons, and array filtering operations now execute significantly faster, reducing database query latency and improving overall application responsiveness. This enhancement delivers consistent performance benefits when filtering or searching encrypted data, resulting in a noticeably faster user experience.

[coderabbitai]

Warning

Rate limit exceeded

@coderdan has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 21 minutes and 22 seconds before requesting another review.

To continue reviewing without waiting, purchase usage credits in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b9cb0f7a-e487-4fc8-b1ae-2e9141401e05

📥 Commits

Reviewing files that changed from the base of the PR and between bbe8431 and 2d21c39.

📒 Files selected for processing (2)

• packages/bench/README.md
• packages/stack/src/drizzle/operators.ts

📝 Walkthrough

Walkthrough

This PR wraps Drizzle's equality operators (eq, ne, inArray, notInArray) with eql_v2.hmac_256(...) to enable functional hash index engagement on encrypted columns, preventing fallback to sequential scans. A changeset documents the performance improvement.

Changes

Equality Operators with Functional Hash Index

Layer / File(s)	Summary
Operator Implementation packages/stack/src/drizzle/operators.ts	Equality (eq/ne) operators wrap both operands with eql_v2.hmac_256(...) and use a hashed operator (= or <>). InArray and NotInArray build per-value conditions using eql_v2.hmac_256(${left}) = eql_v2.hmac_256(${value}) and eql_v2.hmac_256(${left}) <> eql_v2.hmac_256(${value}) respectively, replacing direct Drizzle operators.
Documentation .changeset/drizzle-hmac-256-equality.md	Changeset entry documents the perf improvement: hmac_256 wrapping engages functional hash indexes on Supabase and --exclude-operator-family installs, avoiding sequential scans.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• perf: legacy @cipherstash/drizzle has the same bare-equality bug as @cipherstash/stack/drizzle #426: Directly related; same operator wrapping pattern applied to equality and array comparisons to use hmac_256 functional indexes.
• investigate: do Drizzle's call-shaped forms (like/ilike/gt/order_by/jsonb_*) actually engage functional indexes? #422: Related inspection of Drizzle operator forms (eq/ne/inArray/notInArray) to ensure they match functional index extractor forms.
• perf: encryptedSupabase emits bare-column query forms that don't engage Supabase functional indexes #420: Implements the same hmac_256 wrapping solution to engage Supabase functional indexes instead of falling back to sequential scans.

Suggested reviewers

• auxesis

Poem

🐰 A whisper through the hash—
Where hmac_256 takes the clash,
No more sequential crawl,
Indexes answer the call! ✨
Performance leaps, equality's thrash.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: wrapping equality and membership operators in eql_v2.hmac_256() for performance improvement.
Linked Issues check	✅ Passed	The PR successfully addresses #421 by wrapping eq/ne/inArray/notInArray operators in eql_v2.hmac_256() to engage functional hash indexes and avoid sequential scans.
Out of Scope Changes check	✅ Passed	All changes are scoped to the stated objectives: only equality/membership operators are modified, with no unrelated alterations to other operator families or APIs.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dan/fix-bare-equality-supabase

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 2d21c39

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@cipherstash/stack	Patch
@cipherstash/bench	Patch
@cipherstash/basic-example	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/stack/src/drizzle/operators.ts`:
- Around line 1490-1495: The current code filters out undefined entries from
encryptedValues causing silent predicate changes; instead, check for missing
encryption results and throw an error (fail fast) when any encrypted value is
undefined so callers like inArray() and notInArray() don't get altered
predicates; update the logic around encryptedValues in operators.ts (the block
that builds conditions using eql_v2.hmac_256 and bindIfParam) to validate and
throw on undefined entries, and apply the same guard in encryptedNotInArray, or
alternatively enforce one-result-per-input inside encryptValues() so all callers
receive complete results.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: db7911e8-b9de-4522-9ef2-b691c4f4654d

📥 Commits

Reviewing files that changed from the base of the PR and between e57b53f and bbe8431.

📒 Files selected for processing (2)

• .changeset/drizzle-hmac-256-equality.md
• packages/stack/src/drizzle/operators.ts