NikolayS/pgque v0.2.2

PgQue 0.2.2

on GitHub

Receive overflow handling

PgQue 0.2.2 is a maintenance release. It does not include 0.3 development features.

The Go, Python, and TypeScript clients expose a typed error when a complete batch exceeds the configured receive limit. High-level consumers stop on this error. They do not run handlers, acknowledge the batch, or retry with the same limit. Other errors keep each client's existing policy.

Client changes

• Go: use errors.Is(err, pgque.ErrReceiveOverflow) or errors.As with *pgque.ReceiveOverflowError. The error chain still exposes *SQLError and the driver error.
• Python: catch PgqueReceiveOverflowError. Copy, deepcopy, and pickle preserve its fields, notes, and custom diagnostic data.
• TypeScript: catch PgqueReceiveOverflowError. It remains a PgqueSqlError and retains the driver error as its cause.
• Each error includes the operation, configured limit, SQLSTATE, and server hint. It does not include the actual batch size.
• Go row-read errors now use the operation labels receive and receive coop, without the rows suffix. Update code that compares these labels.

Recovery

The limit is a safety ceiling, not a page size. On overflow:

1. Do not acknowledge the failed receive.
2. Roll back a failed explicit transaction.
3. Choose a larger limit within the process memory budget.
4. Receive and process the complete batch. Then acknowledge it.

The SQL default remains 100. High-level consumers still default to the PostgreSQL integer maximum. This does not guarantee bounded memory use. A ticker threshold does not cap batch size or split an existing batch.

The server must have the complete-batch guard from 0.2.1 or later. Older servers can return a partial batch without an overflow error.

Install the clients

A database-only update does not install the client fixes. Upgrade the client package used by each application:

pip install --upgrade pgque-py==0.2.2
npm install pgque@0.2.2
go get github.com/NikolayS/pgque-go@v0.2.2

Install or update plain SQL

Run the installer as the schema owner or a superuser:

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

From 0.2.1, the database update changes only the version function. It does not change the SQL API or stored queue state. From 0.2.0, it also installs the complete-batch guard from 0.2.1.

Update pg_tle

Register the update paths, then update the extension:

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

The installer supports fresh installations and updates from 0.2.0 or 0.2.1. Do not uninstall a populated extension.

Verify the database version:

select pgque.version(); -- 0.2.2

Thanks

Thanks to Jobin Augustine for reporting that the default receive limit of 100 can be lower than a batch produced at the ticker’s 500-event threshold, leaving consumers stuck on repeated overflow errors. This report led to the receive overflow handling improvements in this release.