NikolayS/pgque v0.2.1

PgQue v0.2.1

on GitHub

Complete-batch receive safety

PgQue v0.2.1 is a maintenance release backported to v0.2.0. It does not include the v0.3 alpha features.

pgque.receive() and pgque.receive_coop() now return the complete batch or raise an error when the batch exceeds max_return. Exactly max_return events succeeds; an additional event raises before the call can return a successful partial result. The failed statement rolls back its consumer allocation/ownership changes. Overflow uses SQLSTATE 54000 (program_limit_exceeded) and includes recovery guidance.

This fixes a data-loss footgun: earlier receives could return only part of a batch, while ack(batch_id) finished the entire batch and skipped unreturned events. ack() remains a whole-batch acknowledgment; applications must process every event before calling it.

Compatibility and recovery

Before upgrading: the default SQL ceiling is 100, below the default ticker event-count threshold of 500. Ordinary batches can exceed 100. Direct Python/TypeScript receives and Go ReceiveCoop also default to 100; callers relying on these defaults must pass a sufficient resource-safe ceiling before upgrading. Alert on SQLSTATE 54000 and growing consumer lag. High-level consumer loops default to the Postgres integer maximum.

Older servers can silently truncate receive results; install this server update before relying on overflow protection.

• Applications using a ceiling smaller than an actual batch will now receive an error. Roll back a failed transaction, then retry with a sufficient ceiling within your resource budget. Never acknowledge after the failed receive.
• ticker_max_count is a tick-trigger threshold, not a maximum batch size. Repeated receives with an undersized ceiling are not pagination. Monitor overflow errors and consumer lag.
• No client-library update is required for this server-side fix. Python, Go and TypeScript package versions remain unchanged.
• Reference documentation, examples and client guidance are corrected. A proper paged-batch protocol is tracked separately in #364.

Install or upgrade the plain SQL installation

Use the installer from this tag, as its schema owner or a superuser:

psql --single-transaction -v ON_ERROR_STOP=1 -d mydb -f sql/pgque.sql

For a v0.2.0 plain SQL installation, this replaces functions while preserving queues, consumer positions, active batches, retry/DLQ rows and queue configuration. Reapplication is supported.

select pgque.version(); -- 0.2.1

Upgrade a pg_tle installation

Register the new version and its non-destructive update path, then update the installed extension:

psql -v ON_ERROR_STOP=1 -d mydb -f sql/pgque-tle.sql
psql -v ON_ERROR_STOP=1 -d mydb -c "alter extension pgque update to '0.2.1';"

The update replaces only the receive functions and version function. Do not uninstall a populated extension to apply this fix. The wrapper also supports fresh installations.

Verification

Release-gate evidence and SamoRev review are posted on the maintenance PR. The tests cover N-1/N/N+1, integer-maximum ceilings, complete retry payloads, consumer-state rollback, cooperative stale-worker takeover, fresh installation and populated v0.2.0 upgrade/reapplication.

Fixes #365.