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 
Reviewed-by: vignesh C 
Reviewed-by: samay sharma 
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
     
      These settings control the behavior of the built-in
      streaming replication feature (see
-     ).  Servers will be either a
+     ), and the built-in
+     logical replication feature (see
+     ).
+    
+
+    
+     For streaming replication, 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 ) 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.
     
 
+    
+     For logical replication, publishers
+     (servers that do CREATE PUBLICATION)
+     replicate data to subscribers
+     (servers that do CREATE SUBSCRIPTION).
+     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
+     .
+    
+
     
      Sending Servers
 
@@ -4213,6 +4230,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
        max_replication_slots (integer)
        
         max_replication_slots configuration parameter
+        in a sending server
        
        
        
@@ -4229,14 +4247,8 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         
 
         
-         On the subscriber side, specifies how many replication origins (see
-         ) 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
-         pg_replication_origin_status,
-         not pg_replication_origin)
-         will prevent the server from starting.
+         Note that this parameter also applies on the subscriber side, but with
+         a different meaning.
         
        
       
@@ -4914,17 +4926,39 @@ ANY num_sync ( 
      
       These settings control the behavior of a logical replication subscriber.
       Their values on the publisher are irrelevant.
-     
-
-     
-      Note that wal_receiver_timeout,
-      wal_receiver_status_interval and
-      wal_retrieve_retry_interval configuration parameters
-      affect the logical replication workers as well.
+      See  for more details.
      
 
      
 
+     
+      max_replication_slots (integer)
+       
+        max_replication_slots configuration parameter
+        in a subscriber
+       
+      
+      
+       
+        Specifies how many replication origins (see
+        ) 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
+        pg_replication_origin_status)
+        will prevent the server from starting.
+        max_replication_slots must be set to at least the
+        number of subscriptions that will be added to the subscriber, plus some
+        reserve for table synchronization.
+       
+
+       
+        Note that this parameter also applies on a sending server, but with
+        a different meaning.
+       
+      
+     
+
      
       max_logical_replication_workers (integer)
       

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
   Configuration Settings
 
   
-   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,
+   max_replication_slots is used on both the publisher and
+   the subscriber, but it has a different meaning for each.
   
 
-  
-   On the publisher side, wal_level must be set to
-   logical, and max_replication_slots
-   must be set to at least the number of subscriptions expected to connect,
-   plus some reserve for table synchronization.  And
-   max_wal_senders should be set to at least the same as
-   max_replication_slots plus the number of physical
-   replicas that are connected at the same time.
-  
+  
+   Publishers
+
+   
+    wal_level must be
+    set to logical.
+   
+
+   
+    max_replication_slots
+    must be set to at least the number of subscriptions expected to connect,
+    plus some reserve for table synchronization.
+   
+
+   
+    max_wal_senders
+    should be set to at least the same as
+    max_replication_slots, plus the number of physical
+    replicas that are connected at the same time.
+   
+
+  
+
+  
+   Subscribers
+
+   
+    max_replication_slots
+    must be set to at least the number of subscriptions that will be added to
+    the subscriber, plus some reserve for table synchronization.
+   
+
+   
+    max_logical_replication_workers
+    must be set to at least the number of subscriptions (for apply workers), plus
+    some reserve for the table synchronization workers.
+   
+
+   
+    max_worker_processes
+    may need to be adjusted to accommodate for replication workers, at least
+    (max_logical_replication_workers
+    + 1). Note, some extensions and parallel queries also
+    take worker slots from max_worker_processes.
+   
+
+   
+    max_sync_workers_per_subscription
+     controls the amount of parallelism of the initial data copy during the
+     subscription initialization or when new tables are added.
+   
+
+   
+    Logical replication workers are also affected by
+    wal_receiver_timeout,
+    wal_receiver_status_interval and
+    wal_receiver_retry_interval.
+   
+
+  
 
-  
-   max_replication_slots 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.
-   max_logical_replication_workers must be set to at least
-   the number of subscriptions, again plus some reserve for the table
-   synchronization.  Additionally the max_worker_processes
-   may need to be adjusted to accommodate for replication workers, at least
-   (max_logical_replication_workers
-   + 1).  Note that some extensions and parallel queries
-   also take worker slots from max_worker_processes.
-