NikolayS/pgque v0.2.0-rc.1

v0.2.0-rc.1 — first public dev distribution

on GitHub

First release candidate for PgQue v0.2.0. RC1 stamps the source tree at v0.2.0-rc.1 and invites real-world testing before GA.

What rc.1 actually ships

• Go client is live: go get github.com/NikolayS/pgque-go@v0.2.0-rc.1 works today via the NikolayS/pgque-go mirror.
• PyPI and npm still pending. pip install pgque-py and npm install pgque will 404 today: registry-side trusted-publisher binding hasn't been done. Workflows are wired and dry-runs are green; first real publishes pending the one-time setup tracked at #229.
• SQL schema: install with \i sql/pgque.sql from this tag (or \i sql/pgque-tle.sql for pg_tle).
• Source layout: each client lives at clients/python/ (pgque-py), clients/typescript/ (pgque), clients/go/ (mirrored to github.com/NikolayS/pgque-go).

Highlights

• API parity across three client libraries. Python (pgque-py), TypeScript (pgque), and Go (pgque-go) all expose send / send_batch, receive, ack, nack with typed errors, force_next_tick/force_tick, subscribe/unsubscribe, plus a high-level Consumer and the experimental cooperative-consumer API.
• Set-based send_batch() — 3-5× producer throughput. pgque.send_batch() is now a single set-based insert. Local-Postgres microbenchmarks at N=10 000 (full numbers in #160):
  • send_batch(jsonb[]): 24,822 → 85,683 ev/s (~3.5×)
  • send_batch(text[]): 27,457 → 133,717 ev/s (~4.9×)
  • vs single send() loop, set-based send_batch is ~26× the throughput on JSON.
• Experimental cooperative consumers. A single logical consumer split across multiple workers via subconsumers, with the SQL core handling batch allocation and lease tracking. SQL + all three clients.
• Sub-second tick rate. Default ticker cadence drops from 1/s to 10/s; tunable via pgque.set_tick_period_ms().
• Scheduler choice. A new pg_timetable backend can drive the ticker on managed Postgres deployments where pg_cron is unavailable.
• Optional pg_tle install path alongside the default \i sql/pgque.sql.
• Hardened roles, security definer pinning, validation tightening. PgQ's producer/consumer role split is restored; every SECURITY DEFINER function pins search_path = pgque, pg_catalog; queue-name and max_return validation tightened.
• DLQ refinements: dlq_replay_all, idempotent nack terminal handling, harder dlq_purge validation.

Upgrade from v0.1.0

The supported upgrade path is to re-run the install on top of an existing v0.1.0 schema:

psql -d <db> -f sql/pgque.sql

The install is idempotent (every create table is if not exists, every function is create or replace, new columns added via guarded alter table … add column). Existing data, queues, consumers, and pending batches are preserved.

A CI test that proves "install v0.1.0, then re-install HEAD on top, everything still works" is tracked at #226 and is a blocker for v0.2.0 GA — not for rc.1.

Behavior changes vs v0.1.0 — please read before upgrading: documented in the release-notes draft at #227 under "Behavior changes vs v0.1.0". Notable: pgque_writer no longer inherits pgque_reader (apps that produce and consume must hold both); default tick cadence is 10/s; pgque.maint() no longer issues VACUUM.

Audit and provenance

• Pre-release audit (Python / TypeScript / Go / cross-client smoke matrix): #211
• Running release-notes draft (will grow into the v0.2.0 GA notes): #227
• v0.1.0 → HEAD upgrade-test tracking issue (GA blocker): #226

Known limitations / experimental APIs

These ship under v0.2.0 but are experimental and may change shape in subsequent releases:

• Cooperative consumers / subconsumers
• Delayed delivery (pgque.send_at + maint_deliver_delayed)
• Observability views (queue_stats, otel_metrics, etc.) — not loaded by default; opt in via \i sql/experimental/observability.sql

What's next

• Configure trusted publishers (PyPI / TestPyPI / npm / Go mirror token) and run the actual first publish
• Land the v0.1.0 → HEAD upgrade test (#226)
• Stabilise the cooperative consumer API
• v0.2.0 GA