Skip to content

Fix pg_durable documentation examples#257

Merged
pinodeca merged 2 commits into
mainfrom
tjgreen42/fix-readme-batch-example
Jun 22, 2026
Merged

Fix pg_durable documentation examples#257
pinodeca merged 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!

@pinodeca pinodeca merged commit e0d5707 into main Jun 22, 2026
5 checks passed
@pinodeca pinodeca deleted the tjgreen42/fix-readme-batch-example branch June 22, 2026 15:17
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