How nikolays/pgque works
PgQue is a PostgreSQL-native durable event queue: producers publish to a shared event log, consumers independently receive batches and acknowledge or retry them, and scheduled ticks make new events visible. Client libraries expose the SQL API and consumer loops in several languages; cooperative subconsumers are an additional consumption mode. The README describes the product’s snapshot batching, table rotation, retries, dead-letter handling, and optional scheduler integrations. SQL internals are represented at the documented API and feature level because their implementation was not sampled.
Main entry points: pgque.sql SQL queue API · client.ts TypeScript client · client.py Python client · pgque.go Go client
Components 21
Client libraries
- TypeScript client
clients/typescript/src/client.ts - Python client
clients/python/pgque/client.py - Go client
clients/go/pgque.go - Ruby client
clients/ruby/lib/pgque/client.rb - TypeScript consumer
clients/typescript/src/consumer.ts - Python consumer
clients/python/pgque/consumer.py - Go consumer
clients/go/consumer.go - Ruby consumer
clients/ruby/lib/pgque/consumer.rb
Queue SQL
- SQL queue API
sql/pgque.sql - Event log
sql/pgque.sql - Batching and rotation
sql/pgque.sql - Retry and DLQ
devel/sql/pgque-additions/dlq.sql - Delayed delivery
devel/sql/experimental/delayed.sql - Cooperative API
devel/sql/pgque-api/cooperative_consumers.sql - Wakeup notifications
devel/sql/pgque-additions/notify.sql
Scheduling
- External scheduler
- pg_cron
- pg_timetable
Other components
- Application producer
- Application consumer
- PostgreSQL
Connections 36
- Application producer → TypeScript client: publishes through
- Application producer → Python client: publishes through
- Application producer → Go client: publishes through
- Application producer → Ruby client: publishes through
- TypeScript client → SQL queue API: calls SQL
- Python client → SQL queue API: calls SQL
- Go client → SQL queue API: calls SQL
- Ruby client → SQL queue API: calls SQL
- SQL queue API → Event log: writes events
- SQL queue API → Batching and rotation: batches and rotates
- Batching and rotation → Event log: manages storage
- Application consumer → TypeScript consumer: runs
- Application consumer → Python consumer: runs
- Application consumer → Go consumer: runs
- Application consumer → Ruby consumer: runs
- TypeScript consumer → TypeScript client: receives and settles
- Python consumer → Python client: receives and settles
- Go consumer → Go client: receives and settles
- Ruby consumer → Ruby client: receives and settles
- TypeScript consumer → Wakeup notifications: listens for wakeups
- Python consumer → Wakeup notifications: listens for wakeups
- Ruby consumer → Wakeup notifications: listens for wakeups
- SQL queue API → Retry and DLQ: routes failures
- SQL queue API → Delayed delivery: supports scheduled delivery
- TypeScript client → Cooperative API: calls cooperative API
- Python client → Cooperative API: calls cooperative API
- Go client → Cooperative API: calls cooperative API
- Ruby client → Cooperative API: calls cooperative API
- TypeScript client → PostgreSQL: executes SQL
- Python client → PostgreSQL: executes SQL
- Go client → PostgreSQL: executes SQL
- Ruby client → PostgreSQL: executes SQL
- SQL queue API → PostgreSQL: runs within
- External scheduler → SQL queue API: invokes ticker
- pg_cron → External scheduler: provides scheduling
- pg_timetable → External scheduler: provides scheduling