pgmq

A lightweight message queue. Like AWS SQS and RSMQ but on Postgres.

Overview

PackageVersionCategoryLicenseLanguage
pgmq1.11.0FEATPostgreSQLSQL
IDExtensionBinLibLoadCreateTrustRelocSchema
2880pgmqNoYesNoYesYesNopgmq
Relatedkafka_fdw pg_cron pg_task pg_net pg_background pgagent pg_jobmon
Depended Bypg_later vectorize

Version

TypeRepoVersionPG VerPackageDeps
EXTPIGSTY1.11.01817161514pgmq-
RPMPIGSTY1.11.01817161514pgmq_$v-
DEBPIGSTY1.11.01817161514postgresql-$v-pgmq-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64
el8.aarch64
el9.x86_64
el9.aarch64
el10.x86_64
el10.aarch64
d12.x86_64
d12.aarch64
d13.x86_64
d13.aarch64
u22.x86_64
u22.aarch64
u24.x86_64
u24.aarch64

Build

You can build the RPM / DEB packages for pgmq using pig build:

pig build pkg pgmq         # build RPM / DEB packages

Install

You can install pgmq directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pgmq;          # Install for current active PG version
pig ext install -y pgmq -v 18  # PG 18
pig ext install -y pgmq -v 17  # PG 17
pig ext install -y pgmq -v 16  # PG 16
pig ext install -y pgmq -v 15  # PG 15
pig ext install -y pgmq -v 14  # PG 14
dnf install -y pgmq_18       # PG 18
dnf install -y pgmq_17       # PG 17
dnf install -y pgmq_16       # PG 16
dnf install -y pgmq_15       # PG 15
dnf install -y pgmq_14       # PG 14
apt install -y postgresql-18-pgmq   # PG 18
apt install -y postgresql-17-pgmq   # PG 17
apt install -y postgresql-16-pgmq   # PG 16
apt install -y postgresql-15-pgmq   # PG 15
apt install -y postgresql-14-pgmq   # PG 14

Create Extension:

CREATE EXTENSION pgmq;

Usage

pgmq: A lightweight message queue for PostgreSQL

PGMQ is a lightweight message queue built on PostgreSQL, providing guaranteed “exactly once” delivery within a visibility timeout, FIFO queues, topic-based routing, and message archival.

CREATE EXTENSION pgmq;

Create a Queue

SELECT pgmq.create('my_queue');

Send Messages

-- Send a single message (returns msg_id)
SELECT * FROM pgmq.send(
  queue_name => 'my_queue',
  msg        => '{"foo": "bar"}'
);

-- Send with delay (invisible for 5 seconds)
SELECT * FROM pgmq.send(
  queue_name => 'my_queue',
  msg        => '{"foo": "bar"}',
  delay      => 5
);

-- Send a batch of messages
SELECT pgmq.send_batch(
  queue_name => 'my_queue',
  msgs       => ARRAY['{"a":1}','{"b":2}','{"c":3}']::jsonb[]
);

Read Messages

Read messages and make them invisible for a visibility timeout (in seconds):

SELECT * FROM pgmq.read(
  queue_name => 'my_queue',
  vt         => 30,    -- visibility timeout in seconds
  qty        => 2      -- number of messages to read
);

Pop a Message

Read and immediately delete a message:

SELECT * FROM pgmq.pop('my_queue');

Delete a Message

SELECT pgmq.delete('my_queue', 6);

Archive a Message

Move a message from the queue to the archive table for long-term retention:

SELECT pgmq.archive(queue_name => 'my_queue', msg_id => 2);

-- Archive multiple messages
SELECT pgmq.archive(queue_name => 'my_queue', msg_ids => ARRAY[3, 4, 5]);

Inspect archived messages:

SELECT * FROM pgmq.a_my_queue;

Drop a Queue

SELECT pgmq.drop_queue('my_queue');

Visibility Timeout

Messages become invisible after being read for the duration of the visibility timeout (vt). If not deleted or archived within that time, they become visible again for other consumers. Set vt greater than the expected processing time.

Key Functions

FunctionDescription
pgmq.create(queue_name)Create a new queue
pgmq.send(queue_name, msg, [delay])Send a message
pgmq.send_batch(queue_name, msgs)Send multiple messages
pgmq.read(queue_name, vt, qty)Read messages with visibility timeout
pgmq.pop(queue_name)Read and delete a message atomically
pgmq.delete(queue_name, msg_id)Delete a message
pgmq.archive(queue_name, msg_id/msg_ids)Archive message(s)
pgmq.drop_queue(queue_name)Delete a queue

Last Modified 2026-03-12: add pg extension catalog (95749bf)