@cipherstash/stack-drizzle

@cipherstash/stack-drizzle

Classes

EqlV3CodecError

Defined in: codec.ts:11

Thrown when a driver value cannot be read back as an EQL v3 envelope.

Extends

• Error

Constructors

Constructor

new EqlV3CodecError(message, options?): EqlV3CodecError;

Defined in: codec.ts:12

Parameters

message

string

options?

ErrorOptions

Returns

EqlV3CodecError

Overrides

Error.constructor

Properties

stackTraceLimit

static stackTraceLimit: number;

Defined in: ../../../node_modules/.bun/@[email protected]/node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

cause?

optional cause: unknown;

Defined in: ../../../../node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

Error.cause

name

name: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.name

message

message: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

stack?

optional stack: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: ../../../node_modules/.bun/@[email protected]/node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: ../../../node_modules/.bun/@[email protected]/node_modules/@types/node/globals.d.ts:56

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

isError()

static isError(error): error is Error;

Defined in: ../../../../node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters

error

unknown

Returns

error is Error

Inherited from

Error.isError

EncryptionOperatorError

Defined in: operators.ts:95

A dedicated error for v3 operator gating and operand-encryption failures, carrying the offending column/table/operator for diagnostics.

INTENTIONAL FORK: this mirrors the v2 adapter's EncryptionOperatorError rather than sharing it. Unifying the two would couple ./drizzle and ./eql/v3/drizzle — two independently-versioned public entry points — so the duplication is deliberate, not an oversight.

Extends

• Error

Constructors

Constructor

new EncryptionOperatorError(message, context?): EncryptionOperatorError;

Defined in: operators.ts:96

Parameters

message

string

context?

columnName?

string

tableName?

string

operator?

string

Returns

EncryptionOperatorError

Overrides

Error.constructor

Properties

context?

readonly optional context: {
  columnName?: string;
  tableName?: string;
  operator?: string;
};

Defined in: operators.ts:98

columnName?

optional columnName: string;

tableName?

optional tableName: string;

operator?

optional operator: string;

stackTraceLimit

static stackTraceLimit: number;

Defined in: ../../../node_modules/.bun/@[email protected]/node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

cause?

optional cause: unknown;

Defined in: ../../../../node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

Error.cause

name

name: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.name

message

message: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

stack?

optional stack: string;

Defined in: ../../../../node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: ../../../node_modules/.bun/@[email protected]/node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: ../../../node_modules/.bun/@[email protected]/node_modules/@types/node/globals.d.ts:56

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

isError()

static isError(error): error is Error;

Defined in: ../../../../node_modules/typescript/lib/lib.esnext.error.d.ts:23

Indicates whether the argument provided is a built-in Error instance or not.

Parameters

error

unknown

Returns

error is Error

Inherited from

Error.isError

Variables

types

const types: {
  Integer: (name) => EqlV3Column<EncryptedIntegerColumn>;
  IntegerEq: (name) => EqlV3Column<EncryptedIntegerEqColumn>;
  IntegerOrdOre: (name) => EqlV3Column<EncryptedIntegerOrdOreColumn>;
  IntegerOrd: (name) => EqlV3Column<EncryptedIntegerOrdColumn>;
  Smallint: (name) => EqlV3Column<EncryptedSmallintColumn>;
  SmallintEq: (name) => EqlV3Column<EncryptedSmallintEqColumn>;
  SmallintOrdOre: (name) => EqlV3Column<EncryptedSmallintOrdOreColumn>;
  SmallintOrd: (name) => EqlV3Column<EncryptedSmallintOrdColumn>;
  Bigint: (name) => EqlV3Column<EncryptedBigintColumn>;
  BigintEq: (name) => EqlV3Column<EncryptedBigintEqColumn>;
  BigintOrdOre: (name) => EqlV3Column<EncryptedBigintOrdOreColumn>;
  BigintOrd: (name) => EqlV3Column<EncryptedBigintOrdColumn>;
  Date: (name) => EqlV3Column<EncryptedDateColumn>;
  DateEq: (name) => EqlV3Column<EncryptedDateEqColumn>;
  DateOrdOre: (name) => EqlV3Column<EncryptedDateOrdOreColumn>;
  DateOrd: (name) => EqlV3Column<EncryptedDateOrdColumn>;
  Timestamp: (name) => EqlV3Column<EncryptedTimestampColumn>;
  TimestampEq: (name) => EqlV3Column<EncryptedTimestampEqColumn>;
  TimestampOrdOre: (name) => EqlV3Column<EncryptedTimestampOrdOreColumn>;
  TimestampOrd: (name) => EqlV3Column<EncryptedTimestampOrdColumn>;
  Numeric: (name) => EqlV3Column<EncryptedNumericColumn>;
  NumericEq: (name) => EqlV3Column<EncryptedNumericEqColumn>;
  NumericOrdOre: (name) => EqlV3Column<EncryptedNumericOrdOreColumn>;
  NumericOrd: (name) => EqlV3Column<EncryptedNumericOrdColumn>;
  Text: (name) => EqlV3Column<EncryptedTextColumn>;
  TextEq: (name) => EqlV3Column<EncryptedTextEqColumn>;
  TextMatch: (name) => EqlV3Column<EncryptedTextMatchColumn>;
  TextOrdOre: (name) => EqlV3Column<EncryptedTextOrdOreColumn>;
  TextOrd: (name) => EqlV3Column<EncryptedTextOrdColumn>;
  TextSearch: (name) => EqlV3Column<EncryptedTextSearchColumn>;
  Boolean: (name) => EqlV3Column<EncryptedBooleanColumn>;
  Real: (name) => EqlV3Column<EncryptedRealColumn>;
  RealEq: (name) => EqlV3Column<EncryptedRealEqColumn>;
  RealOrdOre: (name) => EqlV3Column<EncryptedRealOrdOreColumn>;
  RealOrd: (name) => EqlV3Column<EncryptedRealOrdColumn>;
  Double: (name) => EqlV3Column<EncryptedDoubleColumn>;
  DoubleEq: (name) => EqlV3Column<EncryptedDoubleEqColumn>;
  DoubleOrdOre: (name) => EqlV3Column<EncryptedDoubleOrdOreColumn>;
  DoubleOrd: (name) => EqlV3Column<EncryptedDoubleOrdColumn>;
  Json: (name) => EqlV3Column<EncryptedJsonColumn>;
};

Defined in: types.ts:10

Drizzle-native mirror of @/eql/v3's types namespace. Each PascalCase factory returns a Drizzle column wrapping the matching concrete v3 builder.

Type Declaration

Integer()

readonly Integer: (name) => EqlV3Column<EncryptedIntegerColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedIntegerColumn>

IntegerEq()

readonly IntegerEq: (name) => EqlV3Column<EncryptedIntegerEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedIntegerEqColumn>

IntegerOrdOre()

readonly IntegerOrdOre: (name) => EqlV3Column<EncryptedIntegerOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedIntegerOrdOreColumn>

IntegerOrd()

readonly IntegerOrd: (name) => EqlV3Column<EncryptedIntegerOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedIntegerOrdColumn>

Smallint()

readonly Smallint: (name) => EqlV3Column<EncryptedSmallintColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedSmallintColumn>

SmallintEq()

readonly SmallintEq: (name) => EqlV3Column<EncryptedSmallintEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedSmallintEqColumn>

SmallintOrdOre()

readonly SmallintOrdOre: (name) => EqlV3Column<EncryptedSmallintOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedSmallintOrdOreColumn>

SmallintOrd()

readonly SmallintOrd: (name) => EqlV3Column<EncryptedSmallintOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedSmallintOrdColumn>

Bigint()

readonly Bigint: (name) => EqlV3Column<EncryptedBigintColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedBigintColumn>

BigintEq()

readonly BigintEq: (name) => EqlV3Column<EncryptedBigintEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedBigintEqColumn>

BigintOrdOre()

readonly BigintOrdOre: (name) => EqlV3Column<EncryptedBigintOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedBigintOrdOreColumn>

BigintOrd()

readonly BigintOrd: (name) => EqlV3Column<EncryptedBigintOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedBigintOrdColumn>

Date()

readonly Date: (name) => EqlV3Column<EncryptedDateColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDateColumn>

DateEq()

readonly DateEq: (name) => EqlV3Column<EncryptedDateEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDateEqColumn>

DateOrdOre()

readonly DateOrdOre: (name) => EqlV3Column<EncryptedDateOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDateOrdOreColumn>

DateOrd()

readonly DateOrd: (name) => EqlV3Column<EncryptedDateOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDateOrdColumn>

Timestamp()

readonly Timestamp: (name) => EqlV3Column<EncryptedTimestampColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTimestampColumn>

TimestampEq()

readonly TimestampEq: (name) => EqlV3Column<EncryptedTimestampEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTimestampEqColumn>

TimestampOrdOre()

readonly TimestampOrdOre: (name) => EqlV3Column<EncryptedTimestampOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTimestampOrdOreColumn>

TimestampOrd()

readonly TimestampOrd: (name) => EqlV3Column<EncryptedTimestampOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTimestampOrdColumn>

Numeric()

readonly Numeric: (name) => EqlV3Column<EncryptedNumericColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedNumericColumn>

NumericEq()

readonly NumericEq: (name) => EqlV3Column<EncryptedNumericEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedNumericEqColumn>

NumericOrdOre()

readonly NumericOrdOre: (name) => EqlV3Column<EncryptedNumericOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedNumericOrdOreColumn>

NumericOrd()

readonly NumericOrd: (name) => EqlV3Column<EncryptedNumericOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedNumericOrdColumn>

Text()

readonly Text: (name) => EqlV3Column<EncryptedTextColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTextColumn>

TextEq()

readonly TextEq: (name) => EqlV3Column<EncryptedTextEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTextEqColumn>

TextMatch()

readonly TextMatch: (name) => EqlV3Column<EncryptedTextMatchColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTextMatchColumn>

TextOrdOre()

readonly TextOrdOre: (name) => EqlV3Column<EncryptedTextOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTextOrdOreColumn>

TextOrd()

readonly TextOrd: (name) => EqlV3Column<EncryptedTextOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTextOrdColumn>

TextSearch()

readonly TextSearch: (name) => EqlV3Column<EncryptedTextSearchColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedTextSearchColumn>

Boolean()

readonly Boolean: (name) => EqlV3Column<EncryptedBooleanColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedBooleanColumn>

Real()

readonly Real: (name) => EqlV3Column<EncryptedRealColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedRealColumn>

RealEq()

readonly RealEq: (name) => EqlV3Column<EncryptedRealEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedRealEqColumn>

RealOrdOre()

readonly RealOrdOre: (name) => EqlV3Column<EncryptedRealOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedRealOrdOreColumn>

RealOrd()

readonly RealOrd: (name) => EqlV3Column<EncryptedRealOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedRealOrdColumn>

Double()

readonly Double: (name) => EqlV3Column<EncryptedDoubleColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDoubleColumn>

DoubleEq()

readonly DoubleEq: (name) => EqlV3Column<EncryptedDoubleEqColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDoubleEqColumn>

DoubleOrdOre()

readonly DoubleOrdOre: (name) => EqlV3Column<EncryptedDoubleOrdOreColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDoubleOrdOreColumn>

DoubleOrd()

readonly DoubleOrd: (name) => EqlV3Column<EncryptedDoubleOrdColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedDoubleOrdColumn>

Json()

readonly Json: (name) => EqlV3Column<EncryptedJsonColumn>;

Parameters

name

string

Returns

EqlV3Column<EncryptedJsonColumn>

Functions

v3ToDriver()

function v3ToDriver(value): string | null;

Defined in: codec.ts:67

Serialise an encrypted envelope to a jsonb string for the driver. Null and undefined map to SQL NULL (JS null), never the JSON null literal.

Parameters

value

EncryptedPayload | null | undefined

Returns

string | null

v3FromDriver()

function v3FromDriver(value): EncryptedPayload | null;

Defined in: codec.ts:81

Parse a driver jsonb value back into an encrypted envelope. postgres hands back an already-parsed object for jsonb; a string is parsed. Null and undefined normalise to null (SQL NULL).

Malformed and non-envelope payloads throw EqlV3CodecError rather than surfacing a raw SyntaxError or passing a bare scalar through as though it were an envelope — a wrong value here reaches decrypt as garbage.

Parameters

value

string | object | null | undefined

Returns

EncryptedPayload | null

makeEqlV3Column()

function makeEqlV3Column<C>(builder): EqlV3Column<C>;

Defined in: column.ts:221

Type Parameters

C

C extends AnyEncryptedV3Column

Parameters

builder

C

Returns

EqlV3Column<C>

getEqlV3Column()

function getEqlV3Column(columnName, column): AnyEncryptedV3Column | undefined;

Defined in: column.ts:265

Parameters

columnName

string

column

unknown

Returns

AnyEncryptedV3Column | undefined

isEqlV3Column()

function isEqlV3Column(column): boolean;

Defined in: column.ts:277

Parameters

column

unknown

Returns

boolean

encryptedIndexes()

function encryptedIndexes(columns): IndexBuilder[];

Defined in: indexes.ts:56

Derive the recommended functional indexes for every encrypted column in a table, from the same per-domain capability record the operator layer gates on (builder.build().indexes) — so the emitted indexes and the operators that engage them cannot drift.

Call it inside pgTable's third-argument callback and spread the result:

import { integer, pgTable } from 'drizzle-orm/pg-core'
import { encryptedIndexes, types } from '@cipherstash/stack-drizzle'

export const users = pgTable(
  'users',
  {
    id: integer('id').primaryKey(),
    email: types.TextEq('email'),
    bio: types.TextSearch('bio'),
  },
  (t) => [...encryptedIndexes(t)],
)

Emitted per capability, named <table>_&lt;column&gt;_&lt;capability&gt;:

• equality (hm term) → USING btree (eql_v3.eq_term(col))
• ordering (op term) → USING btree (eql_v3.ord_term(col))
• ORE ordering (ob) → USING btree (eql_v3.ord_term_ore(col))
• free-text match (bf) → USING gin (eql_v3.match_term(col))
• encrypted JSON → USING gin ((eql_v3.to_ste_vec_query(col)::jsonb) jsonb_path_ops)

A types.TextSearch column therefore yields three indexes. Ordering columns differ by type: a numeric, date, or timestamp *Ord / *OrdOre column yields a single ordering index that also serves = (EQL compares those columns by their ordering term directly), while types.TextOrd / TextOrdOre yield an equality index alongside the ordering one (text equality runs on a separate term). A storage-only column (bare types.Text, types.Boolean, …) yields none — it has no queryable term — and non-encrypted columns are ignored. Field-level selector indexes on encrypted JSON cannot be derived here (the selector hash is data the crypto layer emits, not schema) — declare those by hand; see the stash-indexing skill for the recipe.

Existing tables adopt these through a normal drizzle-kit generate migration; run ANALYZE <table> after it applies — an expression index gathers no statistics at CREATE INDEX time. The gap this closes (#753): the integration emitted operators but no index DDL, so encrypted predicates sequential-scanned by default.

Parameters

columns

Record<string, unknown>

Returns

IndexBuilder[]

createEncryptionOperators()

function createEncryptionOperators(client, defaults?): {
  eq: (l, r, opts?) => Promise<SQL<unknown>>;
  ne: (l, r, opts?) => Promise<SQL<unknown>>;
  gt: (l, r, opts?) => Promise<SQL<unknown>>;
  gte: (l, r, opts?) => Promise<SQL<unknown>>;
  lt: (l, r, opts?) => Promise<SQL<unknown>>;
  lte: (l, r, opts?) => Promise<SQL<unknown>>;
  between: (l, min, max, opts?) => Promise<SQL<unknown>>;
  notBetween: (l, min, max, opts?) => Promise<SQL<unknown>>;
  matches: (l, r, opts?) => Promise<SQL<unknown>>;
  contains: (l, r, opts?) => Promise<SQL<unknown>>;
  selector: (l, path) => {
     eq: (value, opts?) => Promise<SQL<unknown>>;
     ne: (value, opts?) => Promise<SQL<unknown>>;
     gt: (value, opts?) => Promise<SQL<unknown>>;
     gte: (value, opts?) => Promise<SQL<unknown>>;
     lt: (value, opts?) => Promise<SQL<unknown>>;
     lte: (value, opts?) => Promise<SQL<unknown>>;
     asc: (opts?) => Promise<SQL<unknown>>;
     desc: (opts?) => Promise<SQL<unknown>>;
  };
  inArray: (l, values, opts?) => Promise<SQL<unknown>>;
  notInArray: (l, values, opts?) => Promise<SQL<unknown>>;
  asc: (c) => SQL<unknown>;
  desc: (c) => SQL<unknown>;
  and: (...conds) => Promise<SQL<unknown>>;
  or: (...conds) => Promise<SQL<unknown>>;
  isNull: (value) => SQL;
  isNotNull: (value) => SQL;
  not: (condition) => SQL;
  exists: (subquery) => SQL;
  notExists: (subquery) => SQL;
};

Defined in: operators.ts:204

Build v3-aware query operators (eq, gte, matches, contains, asc, …) bound to an encryption client. Each comparison/containment operator AUTO-ENCRYPTS its plaintext operand into an EQL v3 query term before handing it to Drizzle, so callers pass plaintext and the emitted SQL compares encrypted values. Every operator also gates on the target column's capabilities and throws EncryptionOperatorError when the column can't answer the operator (e.g. ordering a non-ore column).

Parameters

client

OperandEncryptionClient

anything that can encryptQuery: an EncryptionClient at any schema-tuple instantiation, including the narrowed one Encryption({ schemas }) returns, or a partial client supplying just that capability. No cast needed in either case.

defaults?

EncryptionOperatorCallOpts = {}

lock context / audit applied to every operand encryption unless a per-call override is supplied.

Returns

eq()

eq: (l, r, opts?) => Promise<SQL<unknown>>;

Equality: column = value. Encrypts r and emits eql_v3.eq. Requires a unique or ore index on the column.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

ne()

ne: (l, r, opts?) => Promise<SQL<unknown>>;

Inequality: column <> value. Encrypts r and emits eql_v3.neq. Requires a unique or ore index on the column.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

gt()

gt: (l, r, opts?) => Promise<SQL<unknown>>;

Greater-than: column > value. Encrypts r and emits eql_v3.gt. Requires an ore (order/range) index.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

gte()

gte: (l, r, opts?) => Promise<SQL<unknown>>;

Greater-than-or-equal: column >= value. Encrypts r and emits eql_v3.gte. Requires an ore (order/range) index.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

lt()

lt: (l, r, opts?) => Promise<SQL<unknown>>;

Less-than: column < value. Encrypts r and emits eql_v3.lt. Requires an ore (order/range) index.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

lte()

lte: (l, r, opts?) => Promise<SQL<unknown>>;

Less-than-or-equal: column <= value. Encrypts r and emits eql_v3.lte. Requires an ore (order/range) index.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

between()

between: (l, min, max, opts?) => Promise<SQL<unknown>>;

Inclusive range min <= column <= max. Encrypts both bounds concurrently. Requires an ore (order/range) index.

Parameters

l

SQLWrapper

min

unknown

max

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

notBetween()

notBetween: (l, min, max, opts?) => Promise<SQL<unknown>>;

Negated inclusive range NOT (min <= column <= max). Encrypts both bounds concurrently. Requires an ore (order/range) index.

Parameters

l

SQLWrapper

min

unknown

max

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

matches()

matches: (l, r, opts?) => Promise<SQL<unknown>>;

Fuzzy free-text token match — the needle's 3-gram set is (bloom-)tested as a subset of the column's. NOT containment: order/multiplicity- insensitive and one-sided (a true may be a false positive). Encrypts r. Requires a match (free-text search) index.

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

contains()

contains: (l, r, opts?) => Promise<SQL<unknown>>;

Exact encrypted-JSONB containment (@>): matches rows whose document contains the given sub-object. No false positives. Encrypts r. Requires a ste_vec index (a types.Json column).

Parameters

l

SQLWrapper

r

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

selector()

selector: (l, path) => {
  eq: (value, opts?) => Promise<SQL<unknown>>;
  ne: (value, opts?) => Promise<SQL<unknown>>;
  gt: (value, opts?) => Promise<SQL<unknown>>;
  gte: (value, opts?) => Promise<SQL<unknown>>;
  lt: (value, opts?) => Promise<SQL<unknown>>;
  lte: (value, opts?) => Promise<SQL<unknown>>;
  asc: (opts?) => Promise<SQL<unknown>>;
  desc: (opts?) => Promise<SQL<unknown>>;
};

JSONPath selector-with-constraint on a types.Json (ste_vec) column. Returns comparison and ordering methods bound to col->'path' — e.g. await ops.selector(users.doc, '$.age').gt(21) emits col->'<sel>' > <entry>, while .asc() emits ORDER BY eql_v3.ord_term(col->'<sel>'). Its unique power over contains is ordering at a path (gt/gte/lt/lte and asc/desc); eq/ne are also provided. Dot-notation object paths only in v1.

Parameters

l

SQLWrapper

path

string

Returns

eq()

eq: (value, opts?) => Promise<SQL<unknown>>;

col->'path' = value (encrypted equality at the selector). A row whose document lacks path is excluded (it is not equal to value).

Parameters

value

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

ne()

ne: (value, opts?) => Promise<SQL<unknown>>;

col->'path' <> value, INCLUDING rows whose document lacks path ("not equal to value" covers "has no value").

Parameters

value

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

gt()

gt: (value, opts?) => Promise<SQL<unknown>>;

col->'path' > value (encrypted ordering at the selector).

Parameters

value

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

gte()

gte: (value, opts?) => Promise<SQL<unknown>>;

col->'path' >= value.

Parameters

value

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

lt()

lt: (value, opts?) => Promise<SQL<unknown>>;

col->'path' < value.

Parameters

value

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

lte()

lte: (value, opts?) => Promise<SQL<unknown>>;

col->'path' <= value.

Parameters

value

unknown

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

asc()

asc: (opts?) => Promise<SQL<unknown>>;

Order rows ascending by the encrypted scalar at path. Missing paths produce SQL NULL and follow PostgreSQL's normal NULL ordering.

Parameters

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

desc()

desc: (opts?) => Promise<SQL<unknown>>;

Order rows descending by the encrypted scalar at path. Missing paths produce SQL NULL and follow PostgreSQL's normal NULL ordering.

Parameters

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

inArray()

inArray: (l, values, opts?) => Promise<SQL<unknown>>;

Membership: ORs one encrypted eq term per value. The whole list is encrypted in one encryptQuery batch crossing. Rejects an empty list; requires a unique or ore index.

Parameters

l

SQLWrapper

values

unknown[]

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

notInArray()

notInArray: (l, values, opts?) => Promise<SQL<unknown>>;

Non-membership: ANDs one encrypted ne term per value. The whole list is encrypted in one encryptQuery batch crossing. Rejects an empty list; requires a unique or ore index.

Parameters

l

SQLWrapper

values

unknown[]

opts?

EncryptionOperatorCallOpts

Returns

Promise<SQL<unknown>>

asc()

asc: (c) => SQL<unknown>;

Ascending order by the encrypted order term (eql_v3.ord_term / eql_v3.ord_term_ore, by the column's ordering flavour). Synchronous (no operand to encrypt). Requires an ordering index.

Parameters

c

SQLWrapper

Returns

SQL<unknown>

desc()

desc: (c) => SQL<unknown>;

Descending order by the encrypted order term (eql_v3.ord_term / eql_v3.ord_term_ore, by the column's ordering flavour). Synchronous (no operand to encrypt). Requires an ordering index.

Parameters

c

SQLWrapper

Returns

SQL<unknown>

and()

and: (...conds) => Promise<SQL<unknown>>;

Conjunction of the given conditions, awaiting any async operands and dropping undefined. Empty input resolves to true.

Parameters

conds

...( | SQLWrapper | SQL<unknown> | Promise<SQL<unknown>> | undefined)[]

Returns

Promise<SQL<unknown>>

or()

or: (...conds) => Promise<SQL<unknown>>;

Disjunction of the given conditions, awaiting any async operands and dropping undefined. Empty input resolves to false.

Parameters

conds

...( | SQLWrapper | SQL<unknown> | Promise<SQL<unknown>> | undefined)[]

Returns

Promise<SQL<unknown>>

isNull()

isNull: (value) => SQL;

Drizzle's isNull, re-exported unchanged — column IS NULL needs no encryption and works on any (nullable) encrypted column.

Test whether an expression is NULL. By the SQL standard, NULL is neither equal nor not equal to itself, so it's recommended to use isNull and notIsNull for comparisons to NULL.

Examples

// Select cars that have no discontinuedAt date.
db.select().from(cars)
  .where(isNull(cars.discontinuedAt))

Parameters

value

SQLWrapper

Returns

SQL

See

isNotNull for the inverse of this test

isNotNull()

isNotNull: (value) => SQL;

Drizzle's isNotNull, re-exported unchanged — column IS NOT NULL needs no encryption.

Test whether an expression is not NULL. By the SQL standard, NULL is neither equal nor not equal to itself, so it's recommended to use isNull and notIsNull for comparisons to NULL.

Examples

// Select cars that have been discontinued.
db.select().from(cars)
  .where(isNotNull(cars.discontinuedAt))

Parameters

value

SQLWrapper

Returns

SQL

See

isNull for the inverse of this test

not()

not: (condition) => SQL;

Drizzle's not, re-exported unchanged — negates an already-built (encrypted) predicate. Safe over any operator here, including between, whose fragment is self-parenthesising.

Negate the meaning of an expression using the not keyword.

Examples

// Select cars _not_ made by GM or Ford.
db.select().from(cars)
  .where(not(inArray(cars.make, ['GM', 'Ford'])))

Parameters

condition

SQLWrapper

Returns

SQL

exists()

exists: (subquery) => SQL;

Drizzle's exists, re-exported unchanged — for correlated subqueries.

Test whether a subquery evaluates to have any rows.

Examples

// Users whose `homeCity` column has a match in a cities
// table.
db
  .select()
  .from(users)
  .where(
    exists(db.select()
      .from(cities)
      .where(eq(users.homeCity, cities.id))),
  );

Parameters

subquery

SQLWrapper

Returns

SQL

See

notExists for the inverse of this test

notExists()

notExists: (subquery) => SQL;

Drizzle's notExists, re-exported unchanged — for correlated subqueries.

Test whether a subquery doesn't include any result rows.

Examples

// Users whose `homeCity` column doesn't match
// a row in the cities table.
db
  .select()
  .from(users)
  .where(
    notExists(db.select()
      .from(cities)
      .where(eq(users.homeCity, cities.id))),
  );

Parameters

subquery

SQLWrapper

Returns

SQL

See

exists for the inverse of this test

Example

const ops = createEncryptionOperators(await Encryption({ schemas: [users] }))
await db.select().from(users).where(await ops.eq(users.email, '[email protected]'))

extractEncryptionSchema()

function extractEncryptionSchema<T>(table): ExtractedEncryptionSchema<T>;

Defined in: schema-extraction.ts:81

Rebuild a Drizzle table's encrypted columns as an eql/v3 EncryptedTable.

The return type mirrors what encryptedTable() itself returns — EncryptedTable<Cols> & Cols — so the result is both a schema for Encryption({ schemas }) and a column accessor (schema.email), with each column's concrete domain preserved. That is what keeps InferPlaintext / encryptModel / bulkEncryptModels precisely typed against an extracted schema.

Type Parameters

T

T extends PgTable<TableConfig>

Parameters

table

T

Returns

ExtractedEncryptionSchema<T>