From 941c2f2d17811df5c306ebbe88b2e380a9595597 Mon Sep 17 00:00:00 2001
From: Artur Bento de Carvalho <142529798+arturbent0@users.noreply.github.com>
Date: Fri, 20 Mar 2026 19:16:11 -0300
Subject: [PATCH] docs: explain schema cache reload behavior with NOTIFY
 debouncing

Add a "debouncing" section to explain how PostgREST handles multiple NOTIFY events.
---
 docs/references/schema_cache.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/references/schema_cache.rst b/docs/references/schema_cache.rst
index 86f49bae0..b9d4e13e9 100644
--- a/docs/references/schema_cache.rst
+++ b/docs/references/schema_cache.rst
@@ -53,6 +53,19 @@ To reload the schema cache from within the database, you can use the ``NOTIFY``
 
   NOTIFY pgrst, 'reload schema'
 
+Debouncing
+~~~~~~~~~~
+
+PostgREST does not reload the schema cache for each notification when several ``NOTIFY pgrst`` events are generated quickly after one another.
+
+There are two cases to consider: when notifications are sent within a single transaction and when they are sent across multiple transactions.
+
+In the first case, PostgreSQL deduplicates identical ``NOTIFY`` events within the same transaction. This means that even if multiple ``NOTIFY pgrst`` statements are executed before a ``COMMIT``, only a single notification is delivered to PostgREST.
+
+In the second case, when notifications are sent from separate transactions in a short time span, PostgREST applies a debouncing mechanism to avoid excessive schema cache reloads.
+
+Instead of reloading the schema cache for each notification, events are grouped within a small time window. The reload function is executed once immediately when the first notification is received and once more after the burst of events settles.
+
 .. _auto_schema_reloading:
 
 Automatic Schema Cache Reloading