Add Drizzle ORM integration #197

calvinbrewer · 2025-10-30T14:29:59Z

Change Summary:
Added: The Cipherstash Drizzle package along with its initial interface utilizing protect operators.
Enhanced: Enabled users to extend the Encrypted type, a custom type from Drizzle, allowing for the definition of custom protect schemas.

This update aims to improve data protection capabilities and flexibility when working with encrypted data types in Drizzle.

…query examples

docs/how-to/drizzle-orm-integration.md

packages/protect/__tests__/supabase.test.ts

- Create new @cipherstash/drizzle package with Protect.js operators - Move Drizzle integration tests from protect package to drizzle package - Add schema extraction utilities for automatic Protect.js schema generation - Update documentation with new API using createProtectOperators - Export schema types needed by Drizzle package - Add encryptedType helper for Drizzle table definitions

Co-authored-by: Dan Draper <[email protected]>

- Implement LazyOperatorPromise class to support deferred encryption - Update all operators (eq, ne, gt, gte, lt, lte, between, notBetween, like, ilike, notIlike) to return LazyOperatorPromise when encryption is needed - Override protectOps.and() to batch collect and encrypt all operator values in a single createSearchTerms call - Update TypeScript types to reflect operators can return Promise<SQL> | SQL - Update documentation and tests to demonstrate batched and() usage pattern This significantly improves performance when using multiple operators in a query by batching all encryption operations into a single call instead of multiple separate calls.

…into drizzle-orm

- Add type parameter examples to all encryptedType usage in schema definitions - Add TIP box explaining importance of type parameters for type safety - Update Select + Decrypt example to demonstrate type inference after decryption - Update test file to use type parameters for consistency - Remove outdated WARNING about TypeScript support work in progress - Update TODO list to reflect current state This ensures developers understand that encryptedType<T> maintains type safety throughout the encryption/decryption flow, with TypeScript knowing the correct types of decrypted data.

- Refactor LazyOperatorPromise to implement Promise<SQL> instead of extending it - Add auto-execution logic so operators work when awaited directly - Store encryption context (protectClient, defaultProtectTable, protectTableCache) in LazyOperatorPromise - Implement then/catch/finally to delegate to internal promise - Add _execute() method to handle encryption when awaited outside of and() - Update all operator constructors to pass encryption context This fixes the 'Promise resolve or reject function is not callable' error that occurred when operators were used standalone (not in protectOps.and()). Operators now work both standalone and batched in and() for maximum flexibility.

…ors in and() - Add example showing regular Drizzle operators (eq, ne, gt, etc.) can be mixed with Protect operators in protectOps.and() - Add note explaining that protectOps.and() automatically handles both encrypted and non-encrypted column operators - Update test comments to clarify mixing of operator types - Import eq from drizzle-orm in test file for clarity The implementation already supported this capability - protectOps.and() correctly separates lazy operators (for encrypted columns) from regular SQL conditions (for non-encrypted columns) and combines them appropriately.

- Add workflow step to create .env file for drizzle package with database URL - Add SQL script to create protect-ci table for integration tests - Update postgres entrypoint to run CI table creation script

- Add SKIP_ORDER_BY_TEST flag to drizzle and supabase test suites - CI database doesn't support order by on encrypted columns - Skip order by tests gracefully with console log message

…ndencies

coderdan · 2025-11-05T23:18:57Z

packages/drizzle/src/pg/index.ts

+export type EncryptedColumnConfig = {
+  /**
+   * Data type for the column (default: 'string')
+   */
+  dataType?: CastAs
+  /**
+   * Enable free text search. Can be a boolean for default options, or an object for custom configuration.
+   */
+  freeTextSearch?: boolean | MatchIndexOpts
+  /**
+   * Enable equality index. Can be a boolean for default options, or an array of token filters.
+   */
+  equality?: boolean | TokenFilter[]
+  /**
+   * Enable order and range index for sorting and range queries.
+   */
+  orderAndRange?: boolean
+}


Is this type different to the ones used in protect itself?

Those types are the same pulled from @cipherstash/schema package 🚀

coderdan · 2025-11-06T00:25:39Z

examples/drizzle/src/db/schema.ts

+  amount: encryptedType<number>('amount', {
+    dataType: 'number',
+    equality: true,
+    orderAndRange: true,
+  }),


Not a blocker but this is slightly duplicative. Given that the generic type is number, maybe the dataType can be inferred?

Good call - we can probably infer the dataType from the type interface provided to encrytpedType.

coderdan · 2025-11-06T00:27:52Z

examples/drizzle/README.md

+# Database connection
 DATABASE_URL="postgresql://[username]:[password]@[host]:5432/[database]"
+
+# CipherStash credentials


Can we link to some docs or just the sign-up page for how to get these creds?

coderdan · 2025-11-06T00:30:42Z

examples/drizzle/README.md

+# Get all transactions
+curl http://localhost:3000/transactions
+
+# Filter by account number
+curl "http://localhost:3000/transactions?accountNumber=1234"
+
+# Filter by amount range
+curl "http://localhost:3000/transactions?minAmount=100&maxAmount=1000"
+
+# Filter by status
+curl "http://localhost:3000/transactions?status=completed"
+```


Fine for demo but maybe add a comment that params should usually be done via POST if they are sensitive so that they don't appear in logs.

coderdan · 2025-11-06T00:40:06Z

packages/drizzle/src/pg/operators.ts

+    isNull,
+    isNotNull,
+    not,
+    and: protectAnd,


Move this up to above the comment.

coderdan · 2025-11-06T00:43:33Z

packages/drizzle/README.md

+})
+```
+
+> 💡 **Type Safety Tip**: Always specify the type parameter (`encryptedType<string>`, `encryptedType<number>`, etc.) to maintain type safety after decryption. Without it, decrypted values will be typed as `unknown`.


Worth explaining in a note below that this is because the database doesn't know what type that was encrypted.

Suggested (outside of the quote):

This is because the database only sees encrypted data and doesn't know the underlying type. It must be specified in the ORM.

coderdan · 2025-11-06T00:45:39Z

packages/drizzle/README.md

+const results = await db
+  .select()
+  .from(usersTable)
+  .where(await protectOps.eq(usersTable.email, '[email protected]'))


It's slightly annoying that we need the await here. I wonder if the Drizzle team have any suggestions about how we could avoid it.

Since it requires a call to ZeroKMS to create the encrypted search term we'd need for the core Drizzle interface to be aware of promises in the filter clauses

Do the underlying FFI calls have to be async?
Would it be possible to expose an (optional) sync interface for some use cases?

coderdan · 2025-11-06T00:46:25Z

packages/drizzle/README.md

+const decrypted = await protectClient.bulkDecryptModels(results)
+```
+
+> ⚠️ **Note**: Sorting with ORE on Supabase and other databases that don't support operator families may not work as expected.


Sorting won't work on Supabase. Period.

coderdan · 2025-11-06T00:47:09Z

packages/drizzle/README.md

+  )
+```
+
+> 💡 **Performance Tip**: Using `protectOps.and()` batches all encryption operations into a single `createSearchTerms` call, which is more efficient than awaiting each operator individually.


coderdan · 2025-11-06T00:50:10Z

docs/how-to/drizzle-orm-integration.md

@@ -0,0 +1,426 @@
+# Drizzle ORM Integration with Protect.js


Is this doc superseded by the README? Seems like its saying the same stuff

Yeah it's pretty much a duplicate. I'll just remove it and we can add better how tos later

calvinbrewer added 5 commits October 30, 2025 08:28

docs: 📝 add Drizzle ORM integration guide

de69cf4

test: ✅ add Drizzle ORM integration test and update Supabase tests

08933a1

fix: 🚨 replace isNaN with Number.isNaN and fix test any type

55dd990

chore: 📦️ update package.json and lockfile

86e9fda

docs: 📝 update Drizzle ORM integration guide with encrypted type and …

701f716

…query examples