From 5afa321e896fa1565bb8dc6ce15a89bd1cca580f Mon Sep 17 00:00:00 2001
From: Laurence Isla <lau.isla.c@gmail.com>
Date: Tue, 11 Jun 2024 20:24:55 -0500
Subject: [PATCH] docs: add "Listener" page

Co-authored-by: Steve Chavez <stevechavezast@gmail.com>
---
 docs/explanations/architecture.rst |  3 +--
 docs/references/configuration.rst  |  4 +--
 docs/references/listener.rst       | 41 ++++++++++++++++++++++++++++++
 docs/references/schema_cache.rst   |  6 +----
 4 files changed, 44 insertions(+), 10 deletions(-)
 create mode 100644 docs/references/listener.rst

diff --git a/docs/explanations/architecture.rst b/docs/explanations/architecture.rst
index ba5917ed5..ea4775238 100644
--- a/docs/explanations/architecture.rst
+++ b/docs/explanations/architecture.rst
@@ -77,5 +77,4 @@ The HTTP server is provided by `Warp <https://aosabook.org/en/posa/warp.html>`_.
 Listener
 --------
 
-`Listener.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Listener.hs>`_ is in charge of maintaining a `LISTEN session <https://www.postgresql.org/docs/current/sql-listen.html>`_
-that keeps the :ref:`schema_cache` and the :ref:`in_db_config` up to date.
+`Listener.hs <https://github.com/PostgREST/postgrest/blob/main/src/PostgREST/Listener.hs>`_ is in charge of the :ref:`listener`.
diff --git a/docs/references/configuration.rst b/docs/references/configuration.rst
index 2740e7053..b6f3d197e 100644
--- a/docs/references/configuration.rst
+++ b/docs/references/configuration.rst
@@ -135,14 +135,12 @@ To reload the configuration via signal, send a SIGUSR2 signal to the server proc
 Configuration Reload with NOTIFY
 --------------------------------
 
-To reload the configuration from within the database, you can use a NOTIFY command.
+To reload the configuration from within the database, you can use the ``NOTIFY`` command. See :ref:`listener`.
 
 .. code:: postgresql
 
    NOTIFY pgrst, 'reload config'
 
-The ``"pgrst"`` notification channel is enabled by default. You can name the channel with :ref:`db-channel` and enable or disable it with :ref:`db-channel-enabled`.
-
 .. _config_full_list:
 
 List of parameters
diff --git a/docs/references/listener.rst b/docs/references/listener.rst
new file mode 100644
index 000000000..7384cd611
--- /dev/null
+++ b/docs/references/listener.rst
@@ -0,0 +1,41 @@
+.. _listener:
+
+Listener
+########
+
+PostgREST uses `LISTEN <https://www.postgresql.org/docs/current/sql-listen.html>`_ to reload its :ref:`Schema Cache <schema_reloading_notify>` and :ref:`Configuration <config_reloading_notify>` via `NOTIFY <https://www.postgresql.org/docs/current/sql-notify.html>`_.
+This is useful in environments where you can’t send SIGUSR1 or SIGUSR2 Unix Signals.
+Like on cloud managed containers or on Windows systems.
+
+.. code:: postgresql
+
+  NOTIFY pgrst, 'reload schema'; -- reload schema cache
+  NOTIFY pgrst, 'reload config'; -- reload config
+  NOTIFY pgrst;                  -- reload both
+
+By default, the LISTEN channel is enabled (:ref:`db-channel-enabled`) and named ``pgrst`` (:ref:`db-channel`).
+
+Listener on Read Replicas
+=========================
+
+
+The ``LISTEN`` and ``NOTIFY`` commands do not work on PostgreSQL read replicas.
+Thus, if you connect PostgREST to a read replica the Listener will fail to start.
+
+.. code:: console
+
+  12/Jun/2024:15:19:57 -0500: Failed listening for notifications on the "pgrst" channel... connection to server... failed: session is read-only
+
+To work around this, you can connect the Listener to the primary while still using the :ref:`connection_pool` on the replica.
+
+This can be done by using the standard `libpq multiple hosts <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-MULTIPLE-HOSTS>`_ and `target_session_attrs <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS>`_ in your :ref:`connection string <db-uri>`.
+
+.. code:: bash
+
+  db-uri = "postgres://read_replica.host,primary.host/mydb?target_session_attrs=read-only"
+
+This will cause the :ref:`connection_pool` to connect to the read replica host and ``LISTEN`` on the fallback primary host.
+
+.. note::
+
+  Under the hood, PostgREST forces `target_session_attrs=read-write <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-TARGET-SESSION-ATTRS>`_ for the ``LISTEN`` session.
diff --git a/docs/references/schema_cache.rst b/docs/references/schema_cache.rst
index 68407ad3c..86f49bae0 100644
--- a/docs/references/schema_cache.rst
+++ b/docs/references/schema_cache.rst
@@ -47,16 +47,12 @@ For docker you can do:
 Schema Cache Reloading with NOTIFY
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-PostgREST also allows you to reload its schema cache through PostgreSQL `NOTIFY <https://www.postgresql.org/docs/current/sql-notify.html>`_.
+To reload the schema cache from within the database, you can use the ``NOTIFY`` command. See :ref:`listener`.
 
 .. code-block:: postgres
 
   NOTIFY pgrst, 'reload schema'
 
-This is useful in environments where you can’t send the SIGUSR1 Unix Signal. Like on cloud managed containers or on Windows systems.
-
-The ``pgrst`` notification channel is enabled by default. For configuring the channel, see :ref:`db-channel` and :ref:`db-channel-enabled`.
-
 .. _auto_schema_reloading:
 
 Automatic Schema Cache Reloading