max_notify_queue_pages

Definition PG 18 manual

Specifies the maximum amount of allocated pages for NOTIFY / LISTEN queue. The default value is 1048576. For 8 KB pages it allows to consume up to 8 GB of disk space. This parameter can only be set at server start.

How it works

max_notify_queue_pages caps the number of database pages that the disk-backed LISTEN/NOTIFY queue may allocate. At the usual 8kB BLCKSZ, the PG18 default permits up to 8GB.

Notifications remain queued until all listening sessions have consumed or no longer need them. A listener that stays inside a long transaction can prevent cleanup and let queue usage grow.

This is disk capacity, not notify_buffers memory and not a limit on one payload. When the queue is full, transactions attempting NOTIFY can fail at commit. Its postmaster context fixes the value at server start; changing it requires a restart.

Operational considerations

Increasing queue capacity instead of fixing a listener that stays inside a long transaction.

Confusing max_notify_queue_pages disk capacity with notify_buffers shared-memory cache.

Forgetting that, with 8kB pages, the default 1048576 pages permits up to about 8GB.

Assuming a larger queue changes an individual NOTIFY payload limit or delivery semantics.

Workload guidance

OLAP: An OLAP label does not justify a larger queue. Long analytical transactions in listening sessions can delay cleanup, so separate listeners from long transactions and measure notification production versus consumption.

OLTP: Monitor pg_notification_queue_usage() and identify listeners that remain in long transactions before increasing capacity. Size the disk-backed queue from the maximum tolerated notification backlog and available database volume, not query scan throughput.

SMALL: Keep the default unless the application has a verified LISTEN/NOTIFY backlog requirement. More pages permit more disk consumption and postpone failure; they do not fix a stalled listener.