Declarative consumers
Annotate a method with @PgmqListener(queue = "...") and it receives messages, like Spring Kafka.
Spring Boot library
PGMQ Spring Boot Starter
Durable queues in PostgreSQL, the Spring way.
An idiomatic Spring Boot integration for the PGMQ PostgreSQL message queue. When your data already lives in PostgreSQL, it can replace a separate broker for application-scale asynchronous work, with the developer experience of Spring Kafka or Spring AMQP and the ACID guarantees of PostgreSQL.
- Java 17+
- Spring Boot 4
- PostgreSQL + PGMQ
- Micrometer
- Spring AOT
@PgmqListener(queue = "orders")
public void handle(OrderCreated event) {
shipping.schedule(event.orderId());
}
// Sent in the same transaction as your data
pgmqTemplate.send("orders", new OrderCreated(id));What it does
Transactional outbox
Send messages inside your normal @Transactional methods, so data and messages commit together.
Poison pill handling
Messages that keep failing move to a dead-letter queue after a configurable number of retries.
Exponential backoff
Visibility timeouts grow with each failure, relieving struggling downstream APIs.
Fast wake-ups
Durable PGMQ reads combined with PostgreSQL LISTEN/NOTIFY, with periodic polling as a safety net.
Production features
Batching with List<T> parameters, concurrent consumers, delayed messages, Micrometer metrics and native-image hints.
How it's built
A Spring Boot auto-configuration module between PGMQ and your application:
-
Producer
PgmqTemplate serialises your objects to JSONB with the application ObjectMapper.
-
Consumer
@PgmqListener containers with polling or notification mode, batching and concurrency.
-
Reliability
Outbox, transactional deduplication, retries, backoff and dead-letter routing.
-
Operations
Micrometer metrics (throughput, latency, queue depth), SpEL configuration and graceful shutdown.
Engineering highlights
- Notification wake-ups are coordinated with a short lease, so replicas do not stampede the same queue.
- Same-database work, message finalisation and processed-message tracking happen in one transaction.
- Tested against a real PostgreSQL with PGMQ via Testcontainers, covering race conditions and transaction boundaries.
- Configuration is plain Spring properties, ready for Kubernetes ConfigMaps.
- Honest status: tested by automated integration suites, not yet battle-tested at production scale.
Quick start
git clone https://github.com/esgaltur/pgmq-spring-boot-starter.git
cd pgmq-spring-boot-starter
mvn install # not on Maven Central yet
# then in your pom.xml:
# io.github.esgaltur:pgmq-spring-boot-starter:0.0.1-SNAPSHOTThe full documentation is in the repository on GitHub.