# nikolays/pgque architecture

> Architecture diagram of the GitHub repository nikolays/pgque, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikolays/pgque
- Repository: https://github.com/nikolays/pgque

## Overview

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: [`sql/pgque.sql`](https://github.com/nikolays/pgque/blob/main/sql/pgque.sql) (SQL queue API), [`clients/typescript/src/client.ts`](https://github.com/nikolays/pgque/blob/main/clients/typescript/src/client.ts) (TypeScript client), [`clients/python/pgque/client.py`](https://github.com/nikolays/pgque/blob/main/clients/python/pgque/client.py) (Python client), [`clients/go/pgque.go`](https://github.com/nikolays/pgque/blob/main/clients/go/pgque.go) (Go client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client libraries"]
  node_ts_client["TypeScript client<br/>[client.ts]"]
  node_py_client["Python client<br/>[client.py]"]
  node_go_client["Go client<br/>[pgque.go]"]
  node_ruby_client["Ruby client<br/>[client.rb]"]
  node_ts_consumer["TypeScript consumer<br/>[consumer.ts]"]
  node_py_consumer["Python consumer<br/>[consumer.py]"]
  node_go_consumer["Go consumer<br/>[consumer.go]"]
  node_ruby_consumer["Ruby consumer<br/>[consumer.rb]"]
end

subgraph group_sql["Queue SQL"]
  node_sql_api["SQL queue API<br/>[pgque.sql]"]
  node_event_log[("Event log<br/>[pgque.sql]")]
  node_batching_rotation["Batching and rotation<br/>[pgque.sql]"]
  node_retry_dlq["Retry and DLQ<br/>[dlq.sql]"]
  node_delayed["Delayed delivery<br/>[delayed.sql]"]
  node_coop_api["Cooperative API"]
  node_notify["Wakeup notifications<br/>[notify.sql]"]
end

subgraph group_consumption["Consumption"]
end

subgraph group_integrations["Scheduling"]
  node_scheduler(("External scheduler"))
  node_pgcron(("pg_cron"))
  node_timetable(("pg_timetable"))
end

node_producer(("Application producer"))
node_consumer_actor(("Application consumer"))
node_postgres[("PostgreSQL")]

node_producer -->|"publishes through"| node_ts_client
node_producer -->|"publishes through"| node_py_client
node_producer -->|"publishes through"| node_go_client
node_producer -->|"publishes through"| node_ruby_client
node_ts_client -->|"calls SQL"| node_sql_api
node_py_client -->|"calls SQL"| node_sql_api
node_go_client -->|"calls SQL"| node_sql_api
node_ruby_client -->|"calls SQL"| node_sql_api
node_sql_api -->|"writes events"| node_event_log
node_sql_api -->|"batches and rotates"| node_batching_rotation
node_batching_rotation -->|"manages storage"| node_event_log
node_consumer_actor -->|"runs"| node_ts_consumer
node_consumer_actor -->|"runs"| node_py_consumer
node_consumer_actor -->|"runs"| node_go_consumer
node_consumer_actor -->|"runs"| node_ruby_consumer
node_ts_consumer -->|"receives and settles"| node_ts_client
node_py_consumer -->|"receives and settles"| node_py_client
node_go_consumer -->|"receives and settles"| node_go_client
node_ruby_consumer -->|"receives and settles"| node_ruby_client
node_ts_consumer -->|"listens for wakeups"| node_notify
node_py_consumer -->|"listens for wakeups"| node_notify
node_ruby_consumer -->|"listens for wakeups"| node_notify
node_sql_api -->|"routes failures"| node_retry_dlq
node_sql_api -.->|"supports scheduled delivery"| node_delayed
node_ts_client -->|"calls cooperative API"| node_coop_api
node_py_client -->|"calls cooperative API"| node_coop_api
node_go_client -->|"calls cooperative API"| node_coop_api
node_ruby_client -->|"calls cooperative API"| node_coop_api
node_ts_client -->|"executes SQL"| node_postgres
node_py_client -->|"executes SQL"| node_postgres
node_go_client -->|"executes SQL"| node_postgres
node_ruby_client -->|"executes SQL"| node_postgres
node_sql_api -->|"runs within"| node_postgres
node_scheduler -->|"invokes ticker"| node_sql_api
node_pgcron -.->|"provides scheduling"| node_scheduler
node_timetable -.->|"provides scheduling"| node_scheduler

click node_ts_client "https://github.com/nikolays/pgque/blob/main/clients/typescript/src/client.ts"
click node_py_client "https://github.com/nikolays/pgque/blob/main/clients/python/pgque/client.py"
click node_go_client "https://github.com/nikolays/pgque/blob/main/clients/go/pgque.go"
click node_ruby_client "https://github.com/nikolays/pgque/blob/main/clients/ruby/lib/pgque/client.rb"
click node_ts_consumer "https://github.com/nikolays/pgque/blob/main/clients/typescript/src/consumer.ts"
click node_py_consumer "https://github.com/nikolays/pgque/blob/main/clients/python/pgque/consumer.py"
click node_go_consumer "https://github.com/nikolays/pgque/blob/main/clients/go/consumer.go"
click node_ruby_consumer "https://github.com/nikolays/pgque/blob/main/clients/ruby/lib/pgque/consumer.rb"
click node_sql_api "https://github.com/nikolays/pgque/blob/main/sql/pgque.sql"
click node_event_log "https://github.com/nikolays/pgque/blob/main/sql/pgque.sql"
click node_batching_rotation "https://github.com/nikolays/pgque/blob/main/sql/pgque.sql"
click node_retry_dlq "https://github.com/nikolays/pgque/blob/main/devel/sql/pgque-additions/dlq.sql"
click node_delayed "https://github.com/nikolays/pgque/blob/main/devel/sql/experimental/delayed.sql"
click node_coop_api "https://github.com/nikolays/pgque/blob/main/devel/sql/pgque-api/cooperative_consumers.sql"
click node_notify "https://github.com/nikolays/pgque/blob/main/devel/sql/pgque-additions/notify.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ts_client,node_py_client,node_go_client,node_ruby_client,node_ts_consumer,node_py_consumer,node_go_consumer,node_ruby_consumer toneBlue
class node_sql_api,node_event_log,node_batching_rotation,node_retry_dlq,node_delayed,node_coop_api,node_notify,node_postgres toneAmber
class node_scheduler,node_pgcron,node_timetable toneRose
class node_producer,node_consumer_actor toneIndigo
```

## Components

### Client libraries

- [TypeScript client](https://github.com/nikolays/pgque/blob/main/clients/typescript/src/client.ts): `clients/typescript/src/client.ts`
- [Python client](https://github.com/nikolays/pgque/blob/main/clients/python/pgque/client.py): `clients/python/pgque/client.py`
- [Go client](https://github.com/nikolays/pgque/blob/main/clients/go/pgque.go): `clients/go/pgque.go`
- [Ruby client](https://github.com/nikolays/pgque/blob/main/clients/ruby/lib/pgque/client.rb): `clients/ruby/lib/pgque/client.rb`
- [TypeScript consumer](https://github.com/nikolays/pgque/blob/main/clients/typescript/src/consumer.ts): `clients/typescript/src/consumer.ts`
- [Python consumer](https://github.com/nikolays/pgque/blob/main/clients/python/pgque/consumer.py): `clients/python/pgque/consumer.py`
- [Go consumer](https://github.com/nikolays/pgque/blob/main/clients/go/consumer.go): `clients/go/consumer.go`
- [Ruby consumer](https://github.com/nikolays/pgque/blob/main/clients/ruby/lib/pgque/consumer.rb): `clients/ruby/lib/pgque/consumer.rb`

### Queue SQL

- [SQL queue API](https://github.com/nikolays/pgque/blob/main/sql/pgque.sql): `sql/pgque.sql`
- [Event log](https://github.com/nikolays/pgque/blob/main/sql/pgque.sql): `sql/pgque.sql`
- [Batching and rotation](https://github.com/nikolays/pgque/blob/main/sql/pgque.sql): `sql/pgque.sql`
- [Retry and DLQ](https://github.com/nikolays/pgque/blob/main/devel/sql/pgque-additions/dlq.sql): `devel/sql/pgque-additions/dlq.sql`
- [Delayed delivery](https://github.com/nikolays/pgque/blob/main/devel/sql/experimental/delayed.sql): `devel/sql/experimental/delayed.sql`
- [Cooperative API](https://github.com/nikolays/pgque/blob/main/devel/sql/pgque-api/cooperative_consumers.sql): `devel/sql/pgque-api/cooperative_consumers.sql`
- [Wakeup notifications](https://github.com/nikolays/pgque/blob/main/devel/sql/pgque-additions/notify.sql): `devel/sql/pgque-additions/notify.sql`

### Scheduling

- **External scheduler**
- **pg_cron**
- **pg_timetable**

### Other components

- **Application producer**
- **Application consumer**
- **PostgreSQL**

## Connections

- 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