Skip to content

Document raw-SQL EQL v3 querying: encryptQuery term + ::eql_v3.query_<domain> cast (no-ORM surfaces) #664

Description

@coderdan

Summary

EQL v3 search works fine from raw SQL — the Drizzle v3 adapter is sugar over exactly two steps any pg user can do:

  1. client.encryptQuery(...) mints a ciphertext-free query term (works for scalar/match/ORE on rc.1 / protect-ffi 0.29);
  2. the term is passed as a parameter cast to the column's query domain: $1::eql_v3.query_<domain> (e.g. eql_v3.query_text_search, eql_v3.query_numeric_ord; irregular: eql_v3_json → query_jsonb), which reaches the bundle's (domain, query_<domain>) operator overloads.

(See packages/stack-drizzle/src/v3/operators.ts — "the client capability this factory consumes: encryptQuery… the operator layer casts to the column's eql_v3.query_<domain> type".)

But no skill or doc shows this. In the 2026-07-16 skilltester eval, both no-ORM surfaces (raw pg/Hono, and the Deno edge function's SQL layer) had to reverse-engineer the cast from pg_operator/pg_cast and adapter source. Worse, when the (dist-tag-delivered, #661) stale 0.19.0 threw EQL_V3_QUERY_UNSUPPORTED, agents concluded "v3 can't be searched without an adapter" and downgraded to EQL v2 — a wrong conclusion a single documented example would have prevented.

Fix

  • Add a raw-SQL v3 querying section to skills/stash-encryption/SKILL.md (and the docs site): one worked example per query shape (eq / match / ORE range with the signed-range abs() decomposition), showing encryptQuery → parameterized ::eql_v3.query_<domain> cast.
  • Include the domain→query-type mapping table (incl. the query_jsonb irregular).

Related: #601 (raw-pg gap in the Supabase skill, v2-era). This issue is the v3/core-skill counterpart.

Evidence: cipherstash/skilltester branch 20260716-01-claude — docs/evals/hono-pg/2026-07-16-* and docs/evals/supabase-edge/2026-07-16-bug-no-guidance-for-deno-wasm-raw-sql.md.

Activity

  1. tobyhede commented on Sep 17, 2026

    @tobyhede
    Contributor

    Closing as Completed for this repository's documentation surface. stash-postgres is now the canonical raw-SQL EQL v3 guide, including encryptQuery terms, query-domain casts, the domain mapping, and worked equality, match, and range forms. The stash-encryption and stash-supabase entry points link to that guide.

    The public documentation website is maintained in a separate repository; any remaining website work should be tracked there rather than keeping this repository issue open.

  2. tobyhede commented on Sep 17, 2026

    @tobyhede
    Contributor

    Completion addendum: the signed-range abs() decomposition requested by this issue was missing when the issue was closed. It is now included in the pending stash patch changeset stash-postgres-signed-range, with a worked EQL v3 example that encrypts all four bounds.

    This corrects the closure record; the remaining raw-SQL guidance was already present as described.

  3. tobyhede commented on Sep 17, 2026

    @tobyhede
    Contributor

    The signed-range documentation fix is now publicly reviewable in #975. That PR is on its own branch from main and carries the stash patch changeset referenced above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions