Skip to content

Fix pg_durable documentation examples#257

Open
tjgreen42 wants to merge 2 commits into
mainfrom
tjgreen42/fix-readme-batch-example
Open

Fix pg_durable documentation examples#257
tjgreen42 wants to merge 2 commits into
mainfrom
tjgreen42/fix-readme-batch-example

Conversation

@tjgreen42

@tjgreen42 tjgreen42 commented Jun 18, 2026

Copy link
Copy Markdown
Contributor

Problem

Testing the README and user-facing documentation examples found several result-substitution issues:

  • The README quick example used a captured multi-row result as a scalar in an array context. A bare $var capture substitutes only the first column of the first row, so the generated SQL was invalid.
  • USER_GUIDE.md had additional examples with the same scalar-vs-row-set issue, unqualified playground tables, duplicate unnamed substituted columns, and signal workflows that captured order/doc but referenced undefined $order_id/$doc_id.
  • docs/spec-signals.md duplicated the signal capture-reference mistakes.
  • The Azure HTTP domains smoke check comment claimed broader SQL validation than the script performs.

Fix

  • Use $batch.* row-set expansion where examples pass captured row sets between steps.
  • Keep runnable User Guide examples aligned with the playground schema from the appendix.
  • Alias substituted dot-notation columns in the dot-notation example.
  • Reference captured result columns with $order.id and $doc.id in signal examples.
  • Narrow the smoke-check comment to match its actual offline validation.

Verification

Tested against pgrx-managed PostgreSQL 17 and 18 instances built from this PR branch:

  • README quick example completed and updated all expected rows.
  • Corrected finite User Guide examples completed, including dot notation, df.if_rows(), configurable ETL, row-set expansion, and signal timeout flows.
  • docs/SCENARIOS.md copy-paste scenarios completed; the scheduled HTTP scenario was started, observed through its first insert, then cancelled.
  • Example smoke checks passed for azure-functions, azure-http-domains, and invoice-approval.
  • Local non-cloud portions of the Azure example SQL scripts ran successfully.
  • Patched signal snippets in docs/spec-signals.md completed with expected state changes.

The Quick Example used `id = ANY($batch)`, but a bare $var substitutes
only the first column of the first captured row as a scalar, so the
generated SQL was `id = ANY(1)` and failed with "op ANY/ALL (array)
requires array on right side".

Use the $batch.* row-set expansion instead, referencing the captured
result as a subquery: `id IN (SELECT id FROM $batch.*)`.

@pinodeca pinodeca left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching this!

@tjgreen42 tjgreen42 changed the title Fix README quick example: use $batch.* row-set expansion Fix pg_durable documentation examples Jun 19, 2026
@tjgreen42 tjgreen42 marked this pull request as ready for review June 19, 2026 20:29

@pinodeca pinodeca left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Thanks for QA-testing our docs!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants