docs(readme): lead the existing-database install with the stash CLI - #440
docs(readme): lead the existing-database install with the stash CLI#440coderdan wants to merge 1 commit into
Conversation
The README's only install path for an existing database was downloading the release SQL and replaying it with psql -f. That works on a direct connection, but the bundle is ~6,000 statements and psql -f sends one per protocol round trip — over a pooled connection or under a platform command-time ceiling the install dies partway and leaves a half-installed schema (observed live on a managed AI platform: statements timed out at the platform's 600s limit mid-bundle). The CLI path also preflights role capability and prints skipped optional statements instead of failing on them. stash eql install is now the primary instruction; the raw-SQL path stays as a collapsible alternative with a warning describing the round-trip hazard and the direct-connection / chunking mitigations. Refs cipherstash/stack#665.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📝 WalkthroughWalkthroughREADME.md now recommends the ChangesInstallation documentation
Estimated code review effort: 1 (Trivial) | ~3 minutes Merge Risk: ⚪ Minimal · up to This documentation-only change updates the recommended installation path and preserves the existing raw-SQL instructions; no actionable merge-blocking risk remains after normal checks and review. Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Closing unmerged: the EQL source moved into the cipherstash/stack monorepo ( Ported verbatim to cipherstash/stack#936 — same README change, same wording, applied to |
1 participant
Summary
The README's only instruction for installing EQL (the SQL library that becomes the
eql_v3schema) into an existing database was: download the release SQL, runpsql -f. That path has a real failure mode we hit live — the bundle is ~6,000 statements andpsql -fsends one per protocol round trip, so over a pooled connection or under a platform command-time ceiling (managed AI platforms kill commands at a fixed limit) the install dies partway and leaves a half-installed schema. This makesnpx stash eql installthe primary instruction and demotes the raw-SQL path to a collapsible alternative with a warning.Changes
npx stash eql install: connects viaDATABASE_URLor--database-url(one-shot), preflights role capability (stash eql preflight), installs as a non-superuser, prints skipped optional superuser-gated statements instead of failing. Points atstash eql migration --supabase|--drizzlefor migration-tool platforms.<details>block, plus a warning: the per-statement round-trip hazard, and the mitigations (direct non-pooled connection, or statement-boundary chunking applied one chunk per command).Verification
Docs-only. The hazard is from a live run: applying the 3.0.4 bundle with
psql -fover a pooled connection timed out at a managed platform's 600-second ceiling mid-bundle and half-installed the schema; recovery was 27 statement-boundary chunks applied onepsql -ceach (full record in cipherstash/skilltester branch20260819-01-lovable,apps/lovable-cloud/.cipherstash/bug-eql-bundle-psql-timeout.md). CLI flag claims verified against the publishedstash@1.1.0(shared--database-urlflag on every db/eql command; one-shot semantics). Commit signed.Related
Refs cipherstash/stack#665. Companion skill update: cipherstash/stack#929.
https://claude.ai/code/session_013d6Ni8tR7FfxPos9TdEuDs
Summary by CodeRabbit
stashCLI.psqltimeouts and partial installations on pooled or high-latency connections.