docs: fix stale identity model, incorrect examples, and missing documentation#219
Merged
pinodeca merged 2 commits intoJun 11, 2026
Conversation
…entation
Fixes found during a reliability audit of the documentation:
Critical:
- Rewrite 'How Identity Is Captured' section to describe the current v0.2.0+
model (direct connection as submitted_by) instead of the removed v0.1.1
login_role/SET ROLE model
- Fix df.join(a,b,c) → df.join3(a,b,c) in multi-party approval examples
(USER_GUIDE.md and spec-signals.md)
High:
- Add df.wait_for_completion() to DSL Reference table
- Mark df.run() as stub in manual grants list
- Add 'Superuser Cannot Start Workflows' troubleshooting entry
- Add 'current_user lacks LOGIN attribute' troubleshooting entry
- Document the result JSON shape ({rows, row_count})
- Update security review docs to remove all login_role references and
reflect the current identity model
Medium:
- Fix CHANGELOG: $name? substitutes NULL, not empty string
- Fix grammar.md: use {sku} syntax for setvars, not $sku
- Fix df.list_instances() examples to use lowercase status values
- Fix broken JSON accessor in scheduled API polling example
The redirect test hit httpbin.org without an explicit HTTP timeout and used the default 30s wait_for_completion. When httpbin.org is slow, the wait races the HTTP timeout causing flaky CI failures. Add 10s HTTP timeout and 60s wait_for_completion to give headroom.
There was a problem hiding this comment.
Pull request overview
This PR updates pg_durable’s documentation to reflect the current v0.2.0+ identity/privilege model, corrects several stale or incorrect DSL examples (notably df.join3() usage and JSON access patterns), and adds missing reference/troubleshooting content. It also tightens one E2E HTTP/SSRF test by making timeouts explicit.
Changes:
- Update USER_GUIDE DSL reference, examples, result-format documentation, identity model explanation, and troubleshooting entries.
- Fix stale/incorrect signal/join docs and variable-substitution grammar examples; correct CHANGELOG semantics for
$name?. - Refresh security-review docs to remove
login_rolereferences and describe the current per-user connection model.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| USER_GUIDE.md | Adds/updates DSL reference and multiple examples; rewrites identity model and troubleshooting; documents result JSON shape. |
| tests/e2e/sql/06_http_and_ssrf.sql | Makes HTTP timeout explicit and increases wait_for_completion timeout for redirect test stability. |
| docs/spec-signals.md | Fixes multi-party approval example to use df.join3() for 3 branches. |
| docs/security-review/workbook-data.md | Updates identity inventory, activity inventory, and schema tables to remove login_role and reflect current columns. |
| docs/security-review/ThreatModelDFD.md | Updates threat model diagrams/tables to the new identity and per-user connection model. |
| docs/security-review/security-review.md | Updates security review findings to the new identity and per-user connection model. |
| docs/grammar.md | Corrects variable substitution syntax to {name} and clarifies $name result binding usage. |
| CHANGELOG.md | Fixes $name? semantics to state it substitutes NULL (not empty string). |
Contributor
|
@iemejia Thanks for your PR! The docs do need a lot of love. I kicked off the Copilot review but I haven't read its findings yet. I also want to take a look myself - and will post my own review. |
pinodeca
approved these changes
Jun 11, 2026
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
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
Fixes 12 documentation issues found during a deep reliability audit.
Critical Fixes
login_role+SET ROLE). Rewrote to describe the current v0.2.0+ model where the worker connects directly assubmitted_by(which must haveLOGIN).df.join()arity (C3): Multi-party approval examples calleddf.join(a, b, c)with 3 arguments — the correct function isdf.join3(a, b, c). Fixed in USER_GUIDE.md and spec-signals.md.High-Severity Fixes
df.wait_for_completion()to the DSL Reference table (H9)df.run()as a stub in the manual grants list (H8){"rows": [...], "row_count": N}(H13)login_rolereferences and reflect the current model (H14)Medium-Severity Fixes
$name?substitutesNULL, not "empty string" (M15){sku}syntax for setvars, not$sku(M16)df.list_instances()examples to use lowercase status values (M17)Files Changed
USER_GUIDE.md— Identity model rewrite, new troubleshooting entries, result format docs, example fixesCHANGELOG.md— Fix $name? wordingdocs/grammar.md— Fix variable substitution syntaxdocs/spec-signals.md— Fix join3 exampledocs/security-review/ThreatModelDFD.md— Remove login_role referencesdocs/security-review/security-review.md— Remove login_role referencesdocs/security-review/workbook-data.md— Remove login_role references