docs(eql): lead the existing-database install with the stash CLI - #936
Draft
coderdan wants to merge 1 commit into
Draft
docs(eql): lead the existing-database install with the stash CLI#936coderdan wants to merge 1 commit into
coderdan wants to merge 1 commit into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
EQL is the SQL library that CipherStash installs into a Postgres database (as the
eql_v3schema) so encrypted values can be stored and queried. Its README told you to install it one way only: download a release SQL file and runpsql -fon it. That way breaks on real databases — the file is about 6,000 separate SQL statements, andpsql -fsends them one at a time over the network. On a pooled connection, a slow link, or a hosting platform that kills any command after a fixed time, the install stops halfway and leaves a broken, half-installed schema behind.This makes
npx stash eql install— thestashCLI command that installs EQL for you, in one connection, with a role-permission check first — the headline instruction, and moves the raw-SQL instructions into a collapsed section with a warning about the failure above.Changes
packages/eql/README.md, "Install into an existing database": leads withnpx stash eql install. Explains that it takes the database URL fromDATABASE_URLor--database-url(one run only, never written to disk), runs the same role-capability checks asnpx stash eql preflight, installs without needing a superuser, and reports the optional superuser-only statements it skipped instead of erroring. Points atnpx stash eql migration --supabase(or--drizzle) for platforms where schema changes have to go through a migration tool.<details>block, with a warning that names the per-statement round-trip hazard and its two workarounds: a direct (non-pooled) connection, or splitting the file at statement boundaries and applying one chunk per command.Verification
Docs-only; no code, no published-package surface, so no changeset. The EQL npm package's own README (
packages/eql/packages/eql/README.md) is a separate 13-line stub and is untouched — this file is the subtree root README and ships in no tarball.packages/cli/src/cli/registry.ts):eql preflight,eql install,eql migrationall exist,--supabase/--drizzleexist oneql migration, and--database-urlis the documented one-shot, highest-precedence source.psql -fover a pooled connection hit a managed platform's 600-second command ceiling mid-bundle and half-installed the schema; recovery was 27 statement-boundary chunks applied onepsql -ceach.Related
Ports cipherstash/encrypt-query-language#440, which was still open when the EQL code moved into this repo and so can no longer merge there. Refs #665. Companion skill update already merged as #929.