# pgmq/pgmq architecture

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

- Interactive diagram: https://gitdiagram.com/pgmq/pgmq
- Repository: https://github.com/pgmq/pgmq

## Overview

PGMQ is a PostgreSQL-backed message queue exposed as SQL functions and a Rust client library. The main workflow is producer sends a message to a queue; a consumer reads it under a visibility timeout, then deletes or archives it. The SQL API also documents FIFO/grouped queues and topic routing; Rust offers multiple database-client adapters and installation/migration helpers. The SQL implementation was not sampled, so SQL capability links rely on README evidence; Rust links use the shown excerpts or SOURCE INDEX references.

Main entry points: [`pgmq-extension/sql/pgmq.sql`](https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql) (SQL Queue API), [`pgmq-rs/src/queue/mod.rs`](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/mod.rs) (Queue Interface), [`pgmq-rs/src/install/mod.rs`](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/mod.rs) (Install Orchestrator), [`pgmq-rs/src/queue/sqlx/mod.rs`](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/sqlx/mod.rs) (SQLx Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sql["PostgreSQL Queue"]
  node_sqlapi["SQL Queue API<br/>[pgmq.sql]"]
  node_queuestore[("Queue Tables<br/>[pgmq.sql]")]
  node_archivestore[("Archive Tables<br/>[pgmq.sql]")]
  node_fifo["FIFO Groups<br/>[fifo-queues.md]"]
  node_topics["Topic Routing<br/>[topics.md]"]
end

subgraph group_rust["Rust Client"]
  node_clientapi["Queue Interface<br/>[mod.rs]"]
  node_pgext["SQLx Extension Client<br/>[mod.rs]"]
  node_sqlxadapter["SQLx Adapter<br/>[mod.rs]"]
  node_dieseladapter["Diesel Adapter<br/>[mod.rs]"]
  node_rustpostgres["Postgres Adapters<br/>[mod.rs]"]
  node_sqlqueries["Queue SQL<br/>[sql.rs]"]
  node_querybuilder["Diesel Queries<br/>[query.rs]"]
end

subgraph group_install["Installation"]
  node_installer["Install Orchestrator<br/>[mod.rs]"]
  node_migration["Migration Scripts<br/>[script.rs]"]
  node_migrationstate[("Applied Migrations<br/>[applied.rs]")]
  node_version["Version Parsing<br/>[version.rs]"]
end

subgraph group_types["Shared Types"]
  node_models["Message Models<br/>[mod.rs]"]
  node_queuevalidation["Queue Name Validation<br/>[queue_name.rs]"]
  node_duration["Timeout Types<br/>[duration.rs]"]
end

node_producer(("Producer"))
node_consumer(("Consumer"))
node_postgres[("PostgreSQL")]

node_producer -->|"sends messages"| node_sqlapi
node_sqlapi -->|"stores messages"| node_queuestore
node_consumer -->|"reads messages"| node_sqlapi
node_sqlapi -->|"reads messages"| node_queuestore
node_sqlapi -->|"deletes messages"| node_queuestore
node_sqlapi -->|"archives messages"| node_archivestore
node_sqlapi -->|"supports ordering"| node_fifo
node_sqlapi -->|"routes topics"| node_topics
node_clientapi -->|"implements interface"| node_sqlxadapter
node_clientapi -->|"implements interface"| node_dieseladapter
node_clientapi -->|"implements interface"| node_rustpostgres
node_pgext -->|"delegates queries"| node_sqlxadapter
node_sqlxadapter -->|"uses statements"| node_sqlqueries
node_dieseladapter -->|"builds queries"| node_querybuilder
node_querybuilder -->|"uses statements"| node_sqlqueries
node_rustpostgres -->|"uses statements"| node_sqlqueries
node_clientapi -->|"returns messages"| node_models
node_clientapi -->|"validates names"| node_queuevalidation
node_clientapi -->|"uses timeouts"| node_duration
node_installer -->|"loads applied state"| node_migrationstate
node_installer -->|"runs migrations"| node_migration
node_migration -->|"records versions"| node_migrationstate
node_installer -->|"orders versions"| node_version
node_sqlapi -->|"runs on"| node_postgres
node_installer -->|"installs extension"| node_postgres

click node_sqlapi "https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql"
click node_queuestore "https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql"
click node_archivestore "https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql"
click node_fifo "https://github.com/pgmq/pgmq/blob/main/docs/fifo-queues.md"
click node_topics "https://github.com/pgmq/pgmq/blob/main/docs/topics.md"
click node_clientapi "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/mod.rs"
click node_pgext "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/pg_ext/mod.rs"
click node_sqlxadapter "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/sqlx/mod.rs"
click node_dieseladapter "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/diesel/mod.rs"
click node_rustpostgres "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/rust_postgres/mod.rs"
click node_sqlqueries "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/sql.rs"
click node_querybuilder "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/diesel/query.rs"
click node_models "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/types/mod.rs"
click node_queuevalidation "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/types/queue_name.rs"
click node_duration "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/types/duration.rs"
click node_installer "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/mod.rs"
click node_migration "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/script.rs"
click node_migrationstate "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/applied.rs"
click node_version "https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/version.rs"

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_sqlapi,node_queuestore,node_archivestore,node_fifo,node_topics toneBlue
class node_clientapi,node_pgext,node_sqlxadapter,node_dieseladapter,node_rustpostgres,node_sqlqueries,node_querybuilder,node_postgres toneAmber
class node_installer,node_migration,node_migrationstate,node_version toneMint
class node_models,node_queuevalidation,node_duration toneRose
class node_producer,node_consumer toneIndigo
```

## Components

### PostgreSQL Queue

- [SQL Queue API](https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql): `pgmq-extension/sql/pgmq.sql`
- [Queue Tables](https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql): `pgmq-extension/sql/pgmq.sql`
- [Archive Tables](https://github.com/pgmq/pgmq/blob/main/pgmq-extension/sql/pgmq.sql): `pgmq-extension/sql/pgmq.sql`
- [FIFO Groups](https://github.com/pgmq/pgmq/blob/main/docs/fifo-queues.md): `docs/fifo-queues.md`
- [Topic Routing](https://github.com/pgmq/pgmq/blob/main/docs/topics.md): `docs/topics.md`

### Rust Client

- [Queue Interface](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/mod.rs): `pgmq-rs/src/queue/mod.rs`
- [SQLx Extension Client](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/pg_ext/mod.rs): `pgmq-rs/src/pg_ext/mod.rs`
- [SQLx Adapter](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/sqlx/mod.rs): `pgmq-rs/src/queue/sqlx/mod.rs`
- [Diesel Adapter](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/diesel/mod.rs): `pgmq-rs/src/queue/diesel/mod.rs`
- [Postgres Adapters](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/rust_postgres/mod.rs): `pgmq-rs/src/queue/rust_postgres/mod.rs`
- [Queue SQL](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/sql.rs): `pgmq-rs/src/queue/sql.rs`
- [Diesel Queries](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/queue/diesel/query.rs): `pgmq-rs/src/queue/diesel/query.rs`

### Installation

- [Install Orchestrator](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/mod.rs): `pgmq-rs/src/install/mod.rs`
- [Migration Scripts](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/script.rs): `pgmq-rs/src/install/script.rs`
- [Applied Migrations](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/applied.rs): `pgmq-rs/src/install/applied.rs`
- [Version Parsing](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/install/version.rs): `pgmq-rs/src/install/version.rs`

### Shared Types

- [Message Models](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/types/mod.rs): `pgmq-rs/src/types/mod.rs`
- [Queue Name Validation](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/types/queue_name.rs): `pgmq-rs/src/types/queue_name.rs`
- [Timeout Types](https://github.com/pgmq/pgmq/blob/main/pgmq-rs/src/types/duration.rs): `pgmq-rs/src/types/duration.rs`

### Other components

- **Producer**
- **Consumer**
- **PostgreSQL**

## Connections

- Producer → SQL Queue API: sends messages (evidence: `README.md`)
- SQL Queue API → Queue Tables: stores messages (evidence: `README.md`)
- Consumer → SQL Queue API: reads messages (evidence: `README.md`)
- SQL Queue API → Queue Tables: reads messages (evidence: `README.md`)
- SQL Queue API → Queue Tables: deletes messages (evidence: `README.md`)
- SQL Queue API → Archive Tables: archives messages (evidence: `README.md`)
- SQL Queue API → FIFO Groups: supports ordering (evidence: `README.md`)
- SQL Queue API → Topic Routing: routes topics (evidence: `README.md`)
- Queue Interface → SQLx Adapter: implements interface (evidence: `pgmq-rs/src/queue/mod.rs`)
- Queue Interface → Diesel Adapter: implements interface (evidence: `pgmq-rs/src/queue/mod.rs`)
- Queue Interface → Postgres Adapters: implements interface (evidence: `pgmq-rs/src/queue/mod.rs`)
- SQLx Extension Client → SQLx Adapter: delegates queries (evidence: `pgmq-rs/src/pg_ext/mod.rs`)
- SQLx Adapter → Queue SQL: uses statements (evidence: `pgmq-rs/src/queue/sqlx/mod.rs`)
- Diesel Adapter → Diesel Queries: builds queries (evidence: `pgmq-rs/src/queue/diesel/mod.rs`)
- Diesel Queries → Queue SQL: uses statements (evidence: `pgmq-rs/src/queue/diesel/query.rs`)
- Postgres Adapters → Queue SQL: uses statements (evidence: `pgmq-rs/src/queue/rust_postgres/mod.rs`)
- Queue Interface → Message Models: returns messages (evidence: `pgmq-rs/src/queue/mod.rs`)
- Queue Interface → Queue Name Validation: validates names (evidence: `pgmq-rs/src/queue/macros.rs`)
- Queue Interface → Timeout Types: uses timeouts
- Install Orchestrator → Applied Migrations: loads applied state (evidence: `pgmq-rs/src/install/mod.rs`)
- Install Orchestrator → Migration Scripts: runs migrations (evidence: `pgmq-rs/src/install/mod.rs`)
- Migration Scripts → Applied Migrations: records versions (evidence: `pgmq-rs/src/install/script.rs`)
- Install Orchestrator → Version Parsing: orders versions (evidence: `pgmq-rs/src/install/mod.rs`)
- SQL Queue API → PostgreSQL: runs on (evidence: `README.md`)
- Install Orchestrator → PostgreSQL: installs extension (evidence: `pgmq-rs/src/install/mod.rs`)
