From 2b6688feb4be8253ada3efba4533450577dad6a3 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Fri, 21 Aug 2026 13:07:08 +0930 Subject: [PATCH] docs(eql): lead the existing-database install with the stash CLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's only instruction for installing EQL into an existing database was: download the release SQL, run `psql -f`. That path has a failure mode hit on a live run — the bundle is ~6,000 statements and `psql -f` sends one per protocol round trip, so over a pooled connection or under a platform command-time ceiling the install dies partway and leaves a half-installed schema. Make `npx stash eql install` the primary instruction and demote the raw-SQL path to a collapsible alternative carrying a warning about the round-trip hazard and its two mitigations. Ports cipherstash/encrypt-query-language#440, which was not merged before the EQL code moved into this repo. Refs #665. --- packages/eql/README.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/packages/eql/README.md b/packages/eql/README.md index bc9b33043..dda681e6f 100644 --- a/packages/eql/README.md +++ b/packages/eql/README.md @@ -52,7 +52,20 @@ EQL is installed automatically on first boot. Pin a specific version with `:17-< ### Install into an existing database -Execute the install SQL file directly: +Use the `stash` CLI (recommended): + +```sh +npx stash eql install +``` + +It connects using `DATABASE_URL` (or `--database-url` for a one-shot run), checks your role's +capabilities first (`npx stash eql preflight` runs the same checks standalone), installs as a +non-superuser, and prints any optional superuser-gated statements it skipped instead of failing +on them. On platforms where schema changes must go through a migration tool, generate a +migration instead: `npx stash eql migration --supabase` (or `--drizzle`). + +
+Alternative: apply the raw SQL yourself 1. Download the latest EQL install script: @@ -66,6 +79,15 @@ Execute the install SQL file directly: psql -f cipherstash-encrypt.sql ``` +> [!WARNING] +> The bundle is ~6,000 statements and `psql -f` sends one statement per protocol round trip. Over a +> pooled or high-latency connection — or under a platform command-time ceiling (some managed +> platforms kill commands after a fixed limit) — this can time out **partway**, leaving a +> half-installed schema. If you cannot use the CLI, apply the file over a direct (non-pooled) +> connection, or split it at statement boundaries and apply each chunk as a single command. + +
+ ## EQL Components