Supabase

Field-level encryption that works with your Supabase project out of the box.

Connect from the dashboard

You can connect Supabase from the CipherStash Dashboard instead of starting entirely from the CLI.

You can also install CipherStash from the Supabase Marketplace — the dashboard supports both simple and signed redirect install flows.

Full reference: Supabase dashboard integration

How this works

What is EQL?

EQL (Encrypted Query Language) is a Postgres extension CipherStash installs into your database. It provides the eql_v2_encrypted column type and the internal functions that make encrypted search possible. You don't write EQL directly. The SDK handles it.

Why your columns must be eql_v2_encrypted

Encrypted values aren't strings or plain JSONB. They're structured ciphertext objects that hold the ciphertext plus optional search indexes. Postgres needs the column type so the SDK and Postgres agree on which functions handle inserts and queries.

What the CLI installs on Supabase

db install --supabase uses a Supabase-compatible EQL variant. It omits CREATE OPERATOR FAMILY (which requires superuser), and grants USAGE, table, routine, and sequence permissions on the eql_v2 schema to anon, authenticated, and service_role.

Packages

CipherStash splits its functionality across two packages: a runtime SDK that your application imports, and a CLI for setup and schema management.

Setup

npm install @cipherstash/stack
npm install -D stash

npx stash init --supabase

npx stash db install --supabase --migration

supabase/migrations/00000000000000_cipherstash_eql.sql

npx stash db install --supabase --migration --migrations-dir ./db/migrations

npx stash db install --supabase --direct

Database schema

Encrypted columns must use the eql_v2_encrypted type. Define them in your Supabase SQL editor or a migration file.

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email eql_v2_encrypted NOT NULL,
  name eql_v2_encrypted NOT NULL
);

Choose your integration

Three paths. Same encryption, same key management, same searchable queries. Pick the one that fits your stack.

Encryption SDK (any Postgres client)

Works with any client that connects to your Supabase Postgres database. Define a schema, encrypt fields, store and query with raw SQL or any library.

import { Encryption, encryptedTable, encryptedColumn } from "@cipherstash/stack"

const users = encryptedTable("users", {
  email: encryptedColumn("email").equality().freeTextSearch(),
})

const enc = await Encryption({ schemas: [users] })

// Encrypt
const encrypted = await enc.encrypt("[email protected]", {
  column: users.email, table: users,
})

// Store with any client
await sql`INSERT INTO users (email) VALUES (${encrypted.data})`

// Query — search ciphertext without decrypting
const query = await enc.encryptQuery("[email protected]", {
  column: users.email, table: users,
})

This is the universal approach. It works regardless of which client library you use to connect to Supabase.

Full reference: Storing encrypted data

Supabase JS SDK

If you're using the Supabase JavaScript client, the encryptedSupabase wrapper gives you automatic encryption with the same API you already know.

import { encryptedSupabase } from "@cipherstash/stack/supabase"

const eSupabase = await encryptedSupabase(supabaseUrl, supabaseKey)

// Insert — automatically encrypted
await eSupabase.from("users").insert({
  email: "[email protected]",
})

// Query — automatically encrypts the search term
const { data } = await eSupabase
  .from("users")
  .select()
  .eq("email", "[email protected]")

The wrapper handles encryption, decryption, type casting, and search term formatting. Your queries look identical to standard Supabase queries.

Full reference: Supabase JS SDK integration

Drizzle ORM

If you're using Drizzle ORM with Supabase, define encrypted columns directly in your Drizzle schema.

import { encryptedType } from "@cipherstash/stack/drizzle"

export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  email: encryptedType<string>("email"),
})

Encrypted query operators work like standard Drizzle operators.

Full reference: Drizzle ORM integration

What you get

1. Searchable encryption. Equality, free-text search, range, ordering, and JSON queries over ciphertext. Your Postgres indexes work on encrypted data.
2. Works alongside Row Level Security. CipherStash encryption and Supabase RLS are complementary. RLS controls who can access rows. CipherStash controls who can decrypt values. Defense in depth.
3. Schema-first. Define encrypted columns once. Type-safe across your entire application.
4. Identity-bound keys. Tie encryption to a user's identity. Only that user can decrypt their data.
5. Zero-knowledge. CipherStash never sees your plaintext data. Keys are derived on your device and never stored.

Going to production

Local development uses device-based authentication. Production uses environment variables. See Going to production.

Next steps

• Supabase dashboard integration — OAuth connect, setup hub, Marketplace install, and production config
• Quickstart — Encrypt your first fields in 15 minutes
• Supabase JS SDK reference — Full API for the encryptedSupabase wrapper
• Drizzle ORM reference — Encrypted column types and operators
• Searchable encryption — How queries over ciphertext work
• Supabase db reset removes EQL — Fix for direct-push installs
• Dashboard — Manage keysets, clients, and access keys