fix(pg-cursor): settle read() when rowCount exceeds remaining rows

[dyk1454683243-sudo]

Fixes brianc#2949

Upstream PR: brianc#3786

Problem

cursor.read(rowCount) never called its callback when rowCount was larger than the remaining (or total) rows. A table with 100 rows and read(1000) hung instead of returning the leftover rows.

PostgreSQL reports portal exhaustion with CommandComplete, not PortalSuspended. pg-cursor only delivered the current batch from PortalSuspended or ReadyForQuery. After CommandComplete the cursor closed the portal and sent Sync, then waited for ReadyForQuery. If that message was never dispatched to the cursor, read() never settled.

A late RowDescription could also reset a busy cursor to idle and start a queued execute, overwriting the in-flight callback. Queued read() calls were never drained when the portal was exhausted.

Fix

In packages/pg-cursor:

• Deliver the in-flight read() as soon as CommandComplete arrives (shorter or empty batch).
• Resolve any queued reads with [] once the portal is exhausted.
• Do not start a queued execute from RowDescription / noData while a read is already in flight.
• Clear the current callback synchronously so a later ReadyForQuery cannot deliver the same batch twice.

Tests

packages/pg-cursor/test/read-exhaustion.js:

• Unit: oversized read() settles on CommandComplete without ReadyForQuery.
• Unit: leftover rows after a partial page, then an oversized read().
• Unit: queued reads settle with [] after exhaustion.
• Unit: late RowDescription does not overwrite an in-flight oversized read.
• Integration: 100 rows, read(1000) returns 100, then [].
• Integration: read(40) then read(1000) returns the remaining 60.

Verification

• packages/pg-cursor: 49 passing (including the new cases)
• packages/pg-query-stream: 40 passing
• eslint on the changed files: clean

  

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-20T17:07:07.197938Z	d9e4e43	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d9e4e430ac

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not execute queued reads while handling ReadyForQuery

When an empty query such as a comment has two reads issued before the first completes, handleEmptyQuery() leads directly to handleReadyForQuery() without a preceding CommandComplete. This call therefore changes the busy cursor to idle and promotes the second read here, sending another Execute; handleReadyForQuery() then immediately marks the cursor done and removes it as the client's active query. The promoted callback has already been removed from _queue, so it hangs, and its eventual backend response is handled as an unexpected message. Terminal calls to _sendRows() must not shift queued work, or the cursor must be marked done before calling it.

Useful? React with 👍 / 👎.