CipherStash extension: searchable encrypted columns

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt

Use this file to discover all available pages before exploring further.

​

What the extension provides

• Six encrypted column types: EncryptedString, EncryptedDouble, EncryptedBigInt, EncryptedDate, EncryptedBoolean, EncryptedJson. Each maps a plain JS type to an EQL ciphertext stored in a single eql_v2_encrypted Postgres column.
• Per-codec search-mode flags (equality, freeTextSearch, orderAndRange, searchableJson) that drive which EQL search-config indices are emitted at migration time. All flags default to true.
• 13 predicate operators surfaced as column methods (e.g. m.email.cipherstashEq(...), m.salary.cipherstashGt(...)).
• 4 free-standing helpers for sort and JSON projection: cipherstashAsc, cipherstashDesc, cipherstashJsonbPathQueryFirst, cipherstashJsonbGet.
• bulkEncryptMiddleware(sdk) — coalesces cipherstash parameters across rows into one bulkEncrypt SDK round-trip per (table, column) group before wire encoding.
• decryptAll(rows) — reads a result set and coalesces every cipherstash envelope into one bulkDecrypt SDK round-trip per (table, column) group.
• EQL contract space — the extension ships the eql_v2_configuration table, eql_v2_encrypted composite types, eql_v2 domains, and the EQL bundle SQL as a Prisma Next contract space so the framework manages it alongside your own schema.

​

The six encrypted column types

​

Setup

pnpm add @prisma-next/extension-cipherstash

import { defineConfig } from '@prisma-next/cli/config-types';
import postgresAdapter from '@prisma-next/adapter-postgres/control';
import sql from '@prisma-next/family-sql/control';
import postgres from '@prisma-next/target-postgres/control';
import cipherstash from '@prisma-next/extension-cipherstash/control';

export default defineConfig({
  family: sql,
  target: postgres,
  adapter: postgresAdapter,
  extensionPacks: [cipherstash],
});

model User {
  id              Int @id @default(autoincrement())

  email           cipherstash.EncryptedString({ orderAndRange: true })
  searchableEmail cipherstash.EncryptedString({ freeTextSearch: true })
  salary          cipherstash.EncryptedDouble()
  accountId       cipherstash.EncryptedBigInt() @map("accountid")
  birthday        cipherstash.EncryptedDate()
  emailVerified   cipherstash.EncryptedBoolean() @map("emailverified")
  profile         cipherstash.EncryptedJson()
}

pnpm prisma-next contract emit
pnpm prisma-next db init

import { bulkEncryptMiddleware } from '@prisma-next/extension-cipherstash/middleware';
import { createCipherstashRuntimeDescriptor } from '@prisma-next/extension-cipherstash/runtime';
import postgres from '@prisma-next/postgres/runtime';
import type { Contract } from './prisma/contract.d';
import contractJson from './prisma/contract.json' with { type: 'json' };

const sdk = /* your CipherstashSdk implementation */;

export const db = postgres<Contract>({
  contractJson,
  extensions: [createCipherstashRuntimeDescriptor({ sdk })],
  middleware: [bulkEncryptMiddleware(sdk)],
});

​

Writing and reading encrypted data

import {
  cipherstashAsc,
  decryptAll,
  EncryptedBigInt,
  EncryptedDate,
  EncryptedDouble,
  EncryptedString,
} from '@prisma-next/extension-cipherstash/runtime';
import { and } from '@prisma-next/sql-orm-client';
import { db } from './prisma/db';

// Write — bulkEncryptMiddleware coalesces columns into one bulkEncrypt call per (table, column) group.
await db.orm.User.create({
  id: 1,
  email: EncryptedString.from('alice@example.com'),
  salary: EncryptedDouble.from(75_000.50),
  accountId: EncryptedBigInt.from(1_000_000_000_001n),
  birthday: EncryptedDate.from(new Date('1985-03-15')),
});

// Read — predicate operators on column accessors; cipherstashAsc as a free-standing helper.
const rows = await db.orm.User
  .where((u) => and(
    u.email.cipherstashIlike('%@example.com'),
    u.salary.cipherstashGt(50_000),
    u.birthday.cipherstashLt(new Date('1990-01-01')),
  ))
  .orderBy((u) => [cipherstashAsc(u.salary)])
  .all();

// Decrypt — one bulkDecrypt per (table, column) group.
await decryptAll(rows);
console.log(await rows[0]?.email.decrypt());

​

Operator reference

​

Predicate operators (column methods)

​

Free-standing helpers (non-predicate)

import {
  cipherstashAsc,
  cipherstashDesc,
  cipherstashJsonbPathQueryFirst,
  cipherstashJsonbGet,
} from '@prisma-next/extension-cipherstash/runtime';

​

EQL search-config index types

​

Choosing the right codec

​

Subpath exports

​

Security model

• Plaintext lifetime — the write-side envelope retains its plaintext slot post-encrypt. Treat envelope objects as plaintext-equivalent for the lifetime of the variable.
• Ciphertext routing — every read-side envelope carries the (table, column) it was decoded from. decrypt and decryptAll route bulk SDK calls by that key so the SDK can select the correct key material per column.
• Plaintext redaction — toJSON, toString, valueOf, Symbol.toPrimitive, and Symbol.for('nodejs.util.inspect.custom') all return [REDACTED]. Accidental console.log, JSON.stringify, template-literal interpolation, and util.inspect cannot leak plaintext. Explicit access is via envelope.expose().
• Cancellation — every internal SDK call accepts an AbortSignal.

​

Known limitations

• cipherstashJsonbPathExists against the live EQL bundle — the framework currently binds the JSONpath as a plain text ParamRef rather than the hashed selector the EQL bundle expects. Predicate queries return zero rows against rows that should match. The non-predicate helpers (cipherstashJsonbPathQueryFirst, cipherstashJsonbGet) work correctly. Workaround: project all rows with the SELECT-expression helpers and filter client-side.
• EncryptedBigInt capped at Number.MAX_SAFE_INTEGER — the CipherStash SDK’s JsPlaintext union does not include bigint. Values beyond Number.MAX_SAFE_INTEGER cannot be encrypted and will throw on overflow.
• No encrypted timestamp / datetime — CipherStash offers only calendar-date encryption (EncryptedDate). Encrypted timestamp support is deferred.
• No re-encryption migration primitive — adopting cipherstash for an existing populated column requires re-encrypting row data. The codec lifecycle hook emits the correct search-config DDL but does not touch row data. Work around it with a hand-authored dataTransform migration.