Better document logical replication parameters

Add some cross-links between chapter "20. Server Parameters" and
"31. Logical Replication" regarding the available configuration
parameters, for easier navigation; and some more explanatory text too.

I (Álvaro) chose to duplicate max_replication_slots in Chapter 20,
because it has completely different meanings at each side of the
replication link.

Author: Peter Smith <smithpb2250@gmail.com>
Reviewed-by: vignesh C <vignesh21@gmail.com>
Reviewed-by: samay sharma <smilingsamay@gmail.com>
Discussion: https://postgr.es/m/CAHut+PsESqpy7w3Y6cX98c255ZuCjvipkhKjy6hZBjOv4E6iJA@mail.gmail.com

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index ff6fcd902a8982dcc02e613523a37b46f183a02d..8e4145979dc4bcfaeb75870b1317b82e6d511464 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4156,7 +4156,13 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
     <para>
      These settings control the behavior of the built-in
      <firstterm>streaming replication</firstterm> feature (see
-     <xref linkend="streaming-replication"/>).  Servers will be either a
+     <xref linkend="streaming-replication"/>), and the built-in
+     <firstterm>logical replication</firstterm> feature (see
+     <xref linkend="logical-replication"/>).
+    </para>
+
+    <para>
+     For <emphasis>streaming replication</emphasis>, servers will be either a
      primary or a standby server.  Primaries can send data, while standbys
      are always receivers of replicated data.  When cascading replication
      (see <xref linkend="cascading-replication"/>) is used, standby servers
@@ -4166,6 +4172,17 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
      across the cluster without problems if that is required.
     </para>
 
+    <para>
+     For <emphasis>logical replication</emphasis>, <firstterm>publishers</firstterm>
+     (servers that do <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>)
+     replicate data to <firstterm>subscribers</firstterm>
+     (servers that do <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>).
+     Servers can also be publishers and subscribers at the same time. Note,
+     the following sections refer to publishers as "senders". For more details
+     about logical replication configuration settings refer to
+     <xref linkend="logical-replication-config"/>.
+    </para>
+
     <sect2 id="runtime-config-replication-sender">
      <title>Sending Servers</title>
 
@@ -4213,6 +4230,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
        <term><varname>max_replication_slots</varname> (<type>integer</type>)
        <indexterm>
         <primary><varname>max_replication_slots</varname> configuration parameter</primary>
+        <secondary>in a sending server</secondary>
        </indexterm>
        </term>
        <listitem>
@@ -4229,14 +4247,8 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         </para>
 
         <para>
-         On the subscriber side, specifies how many replication origins (see
-         <xref linkend="replication-origins"/>) can be tracked simultaneously,
-         effectively limiting how many logical replication subscriptions can
-         be created on the server. Setting it to a lower value than the current
-         number of tracked replication origins (reflected in
-         <link linkend="view-pg-replication-origin-status">pg_replication_origin_status</link>,
-         not <link linkend="catalog-pg-replication-origin">pg_replication_origin</link>)
-         will prevent the server from starting.
+         Note that this parameter also applies on the subscriber side, but with
+         a different meaning.
         </para>
        </listitem>
       </varlistentry>
@@ -4914,17 +4926,39 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
      <para>
       These settings control the behavior of a logical replication subscriber.
       Their values on the publisher are irrelevant.
-     </para>
-
-     <para>
-      Note that <varname>wal_receiver_timeout</varname>,
-      <varname>wal_receiver_status_interval</varname> and
-      <varname>wal_retrieve_retry_interval</varname> configuration parameters
-      affect the logical replication workers as well.
+      See <xref linkend="logical-replication-config"/> for more details.
      </para>
 
      <variablelist>
 
+     <varlistentry id="guc-max-replication-slots-subscriber" xreflabel="max_replication_slots">
+      <term><varname>max_replication_slots</varname> (<type>integer</type>)
+       <indexterm>
+        <primary><varname>max_replication_slots</varname> configuration parameter</primary>
+        <secondary>in a subscriber</secondary>
+       </indexterm>
+      </term>
+      <listitem>
+       <para>
+        Specifies how many replication origins (see
+        <xref linkend="replication-origins"/>) can be tracked simultaneously,
+        effectively limiting how many logical replication subscriptions can
+        be created on the server. Setting it to a lower value than the current
+        number of tracked replication origins (reflected in
+        <link linkend="view-pg-replication-origin-status">pg_replication_origin_status</link>)
+        will prevent the server from starting.
+        <literal>max_replication_slots</literal> must be set to at least the
+        number of subscriptions that will be added to the subscriber, plus some
+        reserve for table synchronization.
+       </para>
+
+       <para>
+        Note that this parameter also applies on a sending server, but with
+        a different meaning.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-max-logical-replication-workers" xreflabel="max_logical_replication_workers">
       <term><varname>max_logical_replication_workers</varname> (<type>integer</type>)
       <indexterm>

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index f8756389a3bf6121ec86fddd119626faaafd72fa..7fdf08b59d0c817839973a64082f2e50df3ecff6 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -1765,31 +1765,73 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
   <title>Configuration Settings</title>
 
   <para>
-   Logical replication requires several configuration options to be set.
+   Logical replication requires several configuration options to be set. Most
+   options are relevant only on one side of the replication. However,
+   <varname>max_replication_slots</varname> is used on both the publisher and
+   the subscriber, but it has a different meaning for each.
   </para>
 
-  <para>
-   On the publisher side, <varname>wal_level</varname> must be set to
-   <literal>logical</literal>, and <varname>max_replication_slots</varname>
-   must be set to at least the number of subscriptions expected to connect,
-   plus some reserve for table synchronization.  And
-   <varname>max_wal_senders</varname> should be set to at least the same as
-   <varname>max_replication_slots</varname> plus the number of physical
-   replicas that are connected at the same time.
-  </para>
+  <sect2 id="logical-replication-config-publisher">
+   <title>Publishers</title>
+
+   <para>
+    <link linkend="guc-wal-level"><varname>wal_level</varname></link> must be
+    set to <literal>logical</literal>.
+   </para>
+
+   <para>
+    <link linkend="guc-max-replication-slots"><varname>max_replication_slots</varname></link>
+    must be set to at least the number of subscriptions expected to connect,
+    plus some reserve for table synchronization.
+   </para>
+
+   <para>
+    <link linkend="guc-max-wal-senders"><varname>max_wal_senders</varname></link>
+    should be set to at least the same as
+    <varname>max_replication_slots</varname>, plus the number of physical
+    replicas that are connected at the same time.
+   </para>
+
+  </sect2>
+
+  <sect2 id="logical-replication-config-subscriber">
+   <title>Subscribers</title>
+
+   <para>
+    <link linkend="guc-max-replication-slots-subscriber"><varname>max_replication_slots</varname></link>
+    must be set to at least the number of subscriptions that will be added to
+    the subscriber, plus some reserve for table synchronization.
+   </para>
+
+   <para>
+    <link linkend="guc-max-logical-replication-workers"><varname>max_logical_replication_workers</varname></link>
+    must be set to at least the number of subscriptions (for apply workers), plus
+    some reserve for the table synchronization workers.
+   </para>
+
+   <para>
+    <link linkend="guc-max-worker-processes"><varname>max_worker_processes</varname></link>
+    may need to be adjusted to accommodate for replication workers, at least
+    (<link linkend="guc-max-logical-replication-workers"><varname>max_logical_replication_workers</varname></link>
+    + <literal>1</literal>). Note, some extensions and parallel queries also
+    take worker slots from <varname>max_worker_processes</varname>.
+   </para>
+
+   <para>
+    <link linkend="guc-max-sync-workers-per-subscription"><varname>max_sync_workers_per_subscription</varname></link>
+     controls the amount of parallelism of the initial data copy during the
+     subscription initialization or when new tables are added.
+   </para>
+
+   <para>
+    Logical replication workers are also affected by
+    <link linkend="guc-wal-receiver-timeout"><varname>wal_receiver_timeout</varname></link>,
+    <link linkend="guc-wal-receiver-status-interval"><varname>wal_receiver_status_interval</varname></link> and
+    <link linkend="guc-wal-retrieve-retry-interval"><varname>wal_receiver_retry_interval</varname></link>.
+   </para>
+
+  </sect2>
 
-  <para>
-   <varname>max_replication_slots</varname> must also be set on the subscriber.
-   It should be set to at least the number of subscriptions that will be added
-   to the subscriber, plus some reserve for table synchronization.
-   <varname>max_logical_replication_workers</varname> must be set to at least
-   the number of subscriptions, again plus some reserve for the table
-   synchronization.  Additionally the <varname>max_worker_processes</varname>
-   may need to be adjusted to accommodate for replication workers, at least
-   (<varname>max_logical_replication_workers</varname>
-   + <literal>1</literal>).  Note that some extensions and parallel queries
-   also take worker slots from <varname>max_worker_processes</varname>.
-  </para>
  </sect1>
 
  <sect1 id="logical-replication-quick-setup">