From 863d1c9e9bd287875ece3807855c0496a16069d5 Mon Sep 17 00:00:00 2001
From: "postgrest-ci[bot]"
 <239778017+postgrest-ci[bot]@users.noreply.github.com>
Date: Thu, 26 Mar 2026 11:00:40 +0500
Subject: [PATCH] docs: explain schema cache reload behavior with NOTIFY
 debouncing

---
 docs/postgrest.dict              |  2 ++
 docs/references/schema_cache.rst | 13 +++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/docs/postgrest.dict b/docs/postgrest.dict
index 9105565a1..ae8ea41ae 100644
--- a/docs/postgrest.dict
+++ b/docs/postgrest.dict
@@ -194,3 +194,5 @@ Websockets
 webuser
 wfts
 www
+debouncing
+deduplicates
\ No newline at end of file
diff --git a/docs/references/schema_cache.rst b/docs/references/schema_cache.rst
index 86f49bae0..4d5a1f3af 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 of 100 milliseconds. The reload function is executed once immediately when the first notification is received and once more after the burst of events settles, resulting in at most two executions within that time window.
+
 .. _auto_schema_reloading:
 
 Automatic Schema Cache Reloading