From 71db88dc65151bb0aa9b8d1ecdac4010bbf4272c Mon Sep 17 00:00:00 2001 From: Nikolay Samokhvalov Date: Thu, 10 Jul 2025 16:17:31 -0700 Subject: [PATCH] Add performance warnings to NOTIFY/LISTEN documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document serious performance limitations that affect production systems: - Global lock warning: NOTIFY uses AccessExclusiveLock during commit affecting entire cluster - Explains lock purpose: ensures notification ordering but creates cluster-wide bottleneck - O(N²) performance warning: Duplicate checking complexity with specific mitigation strategies - Architectural guidance: New subsection with high-concurrency recommendations - PostgreSQL-native alternative: Recommend logical decoding with proper cross-reference - Diagnostic guidance: Enable log_lock_waits with example log message to identify - Cross-reference: Add LISTEN → NOTIFY performance limitation reference - pg_notify() warning: Function has same performance limitations as NOTIFY command These warnings help developers make informed architectural decisions before encountering serious performance issues in production environments. --- doc/src/sgml/ref/listen.sgml | 4 +++ doc/src/sgml/ref/notify.sgml | 48 ++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index 6c1f09bd455..85f6784be80 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -95,6 +95,10 @@ LISTEN channel prepared for two-phase commit. + + See NOTIFY documentation for important performance limitations when using LISTEN/NOTIFY at scale. + + There is a race condition when first setting up a listening session: if concurrently-committing transactions are sending notify events, diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml index fd6ed54e8f9..19b75bc4795 100644 --- a/doc/src/sgml/ref/notify.sgml +++ b/doc/src/sgml/ref/notify.sgml @@ -153,6 +153,14 @@ NOTIFY channel [ , Notes + + Warning: NOTIFY uses a global lock during transaction commit that serializes all commits containing NOTIFY statements across the entire PostgreSQL cluster. This lock (AccessExclusiveLock) ensures notification ordering but affects all databases in the cluster, not just the one issuing NOTIFY. Under high concurrency, this can cause severe performance degradation with hundreds of processes queuing for commit. + + + + Performance Warning: Duplicate notification checking has O(N²) complexity. Transactions generating more than a few hundred distinct notifications may experience severe performance degradation. For example, 10,000 notifications in a single transaction can take several minutes just for duplicate checking. Consider using fewer distinct channel names or splitting notifications across multiple transactions if generating large volumes. + + There is a queue that holds notifications that have been sent but not yet processed by all listening sessions. If this queue becomes full, @@ -175,6 +183,42 @@ NOTIFY channel [ , + + Performance considerations for high-concurrency systems + + + For applications with high notification rates or many concurrent connections: + + + + + + Each NOTIFY acquires a global lock during commit, limiting total cluster commit throughput + + + + + Multiple databases on the same cluster share this bottleneck + + + + + Consider logical decoding for high-volume scenarios + + + + + Monitor commit wait times for AccessExclusiveLock waits during COMMIT operations + + + + + Enable to identify when transactions are waiting for notification locks. Look for messages like process X still waiting for AccessExclusiveLock on object 0 of class 1262 of database 0 + + + + + pg_notify @@ -190,6 +234,10 @@ NOTIFY channel [ , NOTIFY command if you need to work with non-constant channel names and payloads. + + + Note: pg_notify() is subject to the same performance limitations as the NOTIFY command. See the performance warnings above for important considerations about global locking and O(N²) duplicate checking performance. + -- 2.39.5 (Apple Git-154)