From cc3d78f23f102d6fe509befb213f453fc1eec508 Mon Sep 17 00:00:00 2001
From: Dan Draper <dan@cipherstash.com>
Date: Thu, 21 May 2026 18:19:28 +1000
Subject: [PATCH 1/3] fix: pin EQL install scripts to eql-2.2.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stack installed the EQL SQL bundle from an unpinned releases/latest URL. EQL's Latest GitHub release moved to the 2.3 line, so CI (and the CLI installer / Drizzle generator) started pulling EQL 2.3 while the code emits EQL 2.2 payloads (protect-ffi 0.21.4) — breaking STE-vec containment queries. Pin local/Dockerfile, the CLI installer, and the Drizzle migration generator to eql-2.2.1. The move to 2.3 happens with the protect-ffi 0.22.0 upgrade.
---
 local/Dockerfile                                   | 6 ++++--
 packages/cli/src/installer/index.ts                | 7 +++++--
 packages/drizzle/src/bin/generate-eql-migration.ts | 5 ++++-
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/local/Dockerfile b/local/Dockerfile
index 23bee926..1bac5828 100644
--- a/local/Dockerfile
+++ b/local/Dockerfile
@@ -2,8 +2,10 @@ FROM postgres:latest
 
 RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*
 
-# Download latest EQL install script
-RUN curl -sLo /tmp/cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql
+# EQL install script, pinned to match the EQL payload format the code emits
+# (protect-ffi 0.21.x -> EQL 2.2). Bump in lockstep with protect-ffi.
+ARG EQL_VERSION=eql-2.2.1
+RUN curl -sLo /tmp/cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/download/${EQL_VERSION}/cipherstash-encrypt.sql
 
 # Copy the custom entrypoint script and SQL files
 COPY postgres-entrypoint.sh /usr/local/bin/postgres-entrypoint.sh
diff --git a/packages/cli/src/installer/index.ts b/packages/cli/src/installer/index.ts
index 54f31679..7c44bdd6 100644
--- a/packages/cli/src/installer/index.ts
+++ b/packages/cli/src/installer/index.ts
@@ -2,10 +2,13 @@ import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import pg from 'pg'
 
+// EQL release, pinned to match the EQL payload format this package emits.
+// Bump in lockstep with @cipherstash/protect-ffi.
+const EQL_VERSION = 'eql-2.2.1'
 const EQL_INSTALL_URL =
-  'https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql'
+  `https://github.com/cipherstash/encrypt-query-language/releases/download/${EQL_VERSION}/cipherstash-encrypt.sql`
 const EQL_INSTALL_NO_OPERATOR_FAMILY_URL =
-  'https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt-supabase.sql'
+  `https://github.com/cipherstash/encrypt-query-language/releases/download/${EQL_VERSION}/cipherstash-encrypt-supabase.sql`
 const EQL_SCHEMA_NAME = 'eql_v2'
 
 /**
diff --git a/packages/drizzle/src/bin/generate-eql-migration.ts b/packages/drizzle/src/bin/generate-eql-migration.ts
index d9c77020..d0a136db 100644
--- a/packages/drizzle/src/bin/generate-eql-migration.ts
+++ b/packages/drizzle/src/bin/generate-eql-migration.ts
@@ -4,8 +4,11 @@ import { readdir } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import { detectRunner } from './runner.js'
 
+// EQL release, pinned to match the EQL payload format this package emits.
+// Bump in lockstep with @cipherstash/protect-ffi.
+const EQL_VERSION = 'eql-2.2.1'
 const EQL_INSTALL_URL =
-  'https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql'
+  `https://github.com/cipherstash/encrypt-query-language/releases/download/${EQL_VERSION}/cipherstash-encrypt.sql`
 
 type CliArgs = {
   migrationName: string

From 15a28a07372f2a76da2b91afea9063a26f5d7456 Mon Sep 17 00:00:00 2001
From: Dan Draper <dan@cipherstash.com>
Date: Thu, 21 May 2026 18:23:01 +1000
Subject: [PATCH 2/3] docs: pin EQL install URLs to eql-2.2.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Match the code pins in c666853 — install docs told users to curl releases/latest, which now serves EQL 2.3 against 2.2-emitting code.
---
 packages/drizzle/GENERATE_EQL_MIGRATION_CLI.md | 2 +-
 packages/drizzle/README.md                     | 2 +-
 packages/protect/README.md                     | 8 ++++----
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/drizzle/GENERATE_EQL_MIGRATION_CLI.md b/packages/drizzle/GENERATE_EQL_MIGRATION_CLI.md
index 76093563..3dfd3e3b 100644
--- a/packages/drizzle/GENERATE_EQL_MIGRATION_CLI.md
+++ b/packages/drizzle/GENERATE_EQL_MIGRATION_CLI.md
@@ -98,7 +98,7 @@ Or use your custom migration workflow.
 ### Before (manual):
 ```bash
 npx drizzle-kit generate --custom --name=install-eql
-curl -sL https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql > drizzle/0001_install-eql.sql
+curl -sL https://github.com/cipherstash/encrypt-query-language/releases/download/eql-2.2.1/cipherstash-encrypt.sql > drizzle/0001_install-eql.sql
 npx drizzle-kit migrate
 ```
 
diff --git a/packages/drizzle/README.md b/packages/drizzle/README.md
index 245503a5..071cdd92 100644
--- a/packages/drizzle/README.md
+++ b/packages/drizzle/README.md
@@ -64,7 +64,7 @@ If you prefer to install EQL manually:
 
 ```bash
 npx drizzle-kit generate --custom --name=install-eql
-curl -sL https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql > drizzle/0001_install-eql.sql
+curl -sL https://github.com/cipherstash/encrypt-query-language/releases/download/eql-2.2.1/cipherstash-encrypt.sql > drizzle/0001_install-eql.sql
 npx drizzle-kit migrate
 ```
 
diff --git a/packages/protect/README.md b/packages/protect/README.md
index 558d106f..d436e087 100644
--- a/packages/protect/README.md
+++ b/packages/protect/README.md
@@ -814,17 +814,17 @@ CREATE TABLE users (
 
 To enable searchable encryption in PostgreSQL, [install the EQL custom types and functions](https://github.com/cipherstash/encrypt-query-language?tab=readme-ov-file#installation).
 
-1. Download the latest EQL install script:
+1. Download the EQL install script. The version is pinned to match this release of Protect.js — install exactly this version:
 
    ```sh
-   curl -sLo cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt.sql
+   curl -sLo cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/download/eql-2.2.1/cipherstash-encrypt.sql
    ```
 
    Using [Supabase](https://supabase.com/)? We ship an EQL release specifically for Supabase.
-   Download the latest EQL install script:
+   Download the matching Supabase EQL install script:
 
    ```sh
-   curl -sLo cipherstash-encrypt-supabase.sql https://github.com/cipherstash/encrypt-query-language/releases/latest/download/cipherstash-encrypt-supabase.sql
+   curl -sLo cipherstash-encrypt-supabase.sql https://github.com/cipherstash/encrypt-query-language/releases/download/eql-2.2.1/cipherstash-encrypt-supabase.sql
    ```
 
 2. Run this command to install the custom types and functions:

From c8622e99b64d7df4ca2a63ab1e591fd3748bfa33 Mon Sep 17 00:00:00 2001
From: Dan Draper <dan@cipherstash.com>
Date: Thu, 21 May 2026 21:35:16 +1000
Subject: [PATCH 3/3] ci: migrate bench Postgres to the pinned postgres-eql
 image
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tests-bench.yml built a hand-rolled EQL Postgres from local/Dockerfile (FROM postgres:latest + curl EQL + a custom entrypoint with no ON_ERROR_STOP). A failed install exited 0, the container went healthy anyway, and the bench failed confusingly — broken on main for days. Replace it with EQL's official postgres-eql:17-2.2.1 image via local/docker-compose.yml (same image tests.yml uses since #477). Keep local/docker-compose.yml (repurposed to image:) for local dev; delete local/Dockerfile, local/postgres-entrypoint.sh, and the orphaned local/create-ci-table.sql.
---
 .github/workflows/tests-bench.yml |  4 ++--
 local/Dockerfile                  | 19 -------------------
 local/create-ci-table.sql         |  9 ---------
 local/docker-compose.yml          |  6 +++---
 local/postgres-entrypoint.sh      | 24 ------------------------
 5 files changed, 5 insertions(+), 57 deletions(-)
 delete mode 100644 local/Dockerfile
 delete mode 100644 local/create-ci-table.sql
 delete mode 100644 local/postgres-entrypoint.sh

diff --git a/.github/workflows/tests-bench.yml b/.github/workflows/tests-bench.yml
index cce2d4f3..c38b1828 100644
--- a/.github/workflows/tests-bench.yml
+++ b/.github/workflows/tests-bench.yml
@@ -52,8 +52,8 @@ jobs:
       - name: Build @cipherstash/stack
         run: pnpm exec turbo run build --filter @cipherstash/stack
 
-      # Builds the local EQL-enabled Postgres image (local/Dockerfile),
-      # starts it, and waits for the pg_isready healthcheck to pass.
+      # Starts the pinned postgres-eql container (PostgreSQL 17 + EQL
+      # pre-installed) via local/docker-compose.yml; waits for healthcheck.
       - name: Start local Postgres (EQL)
         working-directory: local
         run: docker compose up --wait --wait-timeout 60
diff --git a/local/Dockerfile b/local/Dockerfile
deleted file mode 100644
index 1bac5828..00000000
--- a/local/Dockerfile
+++ /dev/null
@@ -1,19 +0,0 @@
-FROM postgres:latest
-
-RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*
-
-# EQL install script, pinned to match the EQL payload format the code emits
-# (protect-ffi 0.21.x -> EQL 2.2). Bump in lockstep with protect-ffi.
-ARG EQL_VERSION=eql-2.2.1
-RUN curl -sLo /tmp/cipherstash-encrypt.sql https://github.com/cipherstash/encrypt-query-language/releases/download/${EQL_VERSION}/cipherstash-encrypt.sql
-
-# Copy the custom entrypoint script and SQL files
-COPY postgres-entrypoint.sh /usr/local/bin/postgres-entrypoint.sh
-COPY create-ci-table.sql /tmp/create-ci-table.sql
-
-# Make the entrypoint script executable
-RUN chmod +x /usr/local/bin/postgres-entrypoint.sh
-
-# Use the custom entrypoint
-ENTRYPOINT ["/usr/local/bin/postgres-entrypoint.sh"]
-
diff --git a/local/create-ci-table.sql b/local/create-ci-table.sql
deleted file mode 100644
index 842f37ec..00000000
--- a/local/create-ci-table.sql
+++ /dev/null
@@ -1,9 +0,0 @@
-CREATE TABLE "protect-ci" (
-  id INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
-  email eql_v2_encrypted,
-  age eql_v2_encrypted,
-  score eql_v2_encrypted,
-  profile eql_v2_encrypted,
-  created_at TIMESTAMP DEFAULT NOW(),
-  test_run_id TEXT
-);
\ No newline at end of file
diff --git a/local/docker-compose.yml b/local/docker-compose.yml
index 0af01fdd..1ad0f256 100644
--- a/local/docker-compose.yml
+++ b/local/docker-compose.yml
@@ -1,8 +1,8 @@
 services:
   postgres: &postgres
-    build:
-      context: .
-      dockerfile: Dockerfile
+    # PostgreSQL 17 with CipherStash EQL pre-installed (official image).
+    # Pinned by tag — bump in lockstep with the EQL version the code targets.
+    image: ghcr.io/cipherstash/postgres-eql:17-2.2.1
     environment:
       PGPORT: 5432
       POSTGRES_DB: "cipherstash"
diff --git a/local/postgres-entrypoint.sh b/local/postgres-entrypoint.sh
deleted file mode 100644
index 6f771a21..00000000
--- a/local/postgres-entrypoint.sh
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/bin/bash
-set -e
-
-# Start PostgreSQL in the background
-echo "Starting PostgreSQL..."
-docker-entrypoint.sh postgres &
-
-# Wait for PostgreSQL to be ready
-echo "Waiting for PostgreSQL to be ready..."
-until pg_isready -U cipherstash -d cipherstash; do
-  echo "Waiting for PostgreSQL to be ready..."
-  sleep 2
-done
-
-echo "PostgreSQL is ready. Running CipherStash SQL initialization..."
-
-# Run the SQL file
-psql -U cipherstash -d cipherstash -f /tmp/cipherstash-encrypt.sql
-psql -U cipherstash -d cipherstash -f /tmp/create-ci-table.sql
-
-echo "CipherStash SQL initialization completed."
-
-# Wait for the PostgreSQL process
-wait $!