doc: clarify when physical/logical replication is used

The imprecision caused some text to be only partially accurate.

Reported-by: Paul A Jungwirth
Author: Robert Treat

Discussion: https://postgr.es/m/CA%2BrenyULt3VBS1cRFKUfT2%3D5dr61xBOZdAZ-CqX3XLGXqY-aTQ%40mail.gmail.com

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 405c9689bd09ce042a0b52251465155119f24964..1c23538d3c5d2667eca9c088dbcb38e8288b5521 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -2075,7 +2075,7 @@ include_dir 'conf.d'
        <para>
         Specifies the maximum amount of memory to be used by logical decoding,
         before some of the decoded changes are written to local disk. This
-        limits the amount of memory used by logical streaming replication
+        limits the amount of memory used by streaming logical replication
         connections. It defaults to 64 megabytes (<literal>64MB</literal>).
         Since each replication connection only uses a single buffer of this size,
         and an installation normally doesn't have many such connections
@@ -3800,7 +3800,7 @@ include_dir 'conf.d'
         difference between the two modes, but when set to <literal>always</literal>
         the WAL archiver is enabled also during archive recovery or standby
         mode. In <literal>always</literal> mode, all files restored from the archive
-        or streamed with streaming replication will be archived (again). See
+        or streamed with streaming physical replication will be archived (again). See
         <xref linkend="continuous-archiving-in-standby"/> for details.
        </para>
        <para>
@@ -3906,7 +3906,7 @@ include_dir 'conf.d'
         full files.  Therefore, it is unwise to use a very short
         <varname>archive_timeout</varname> &mdash; it will bloat your archive
         storage.  <varname>archive_timeout</varname> settings of a minute or so are
-        usually reasonable.  You should consider using streaming replication,
+        usually reasonable.  You should consider using streaming physical replication,
         instead of archiving, if you want data to be copied off the primary
         server more quickly than that.
         If this value is specified without units, it is taken as seconds.
@@ -3931,7 +3931,7 @@ include_dir 'conf.d'
 
     <para>
      This section describes the settings that apply to recovery in general,
-     affecting crash recovery, streaming replication and archive-based
+     affecting crash recovery, streaming physical replication and archive-based
      replication.
     </para>
 
@@ -4042,7 +4042,7 @@ include_dir 'conf.d'
        <para>
         The local shell command to execute to retrieve an archived segment of
         the WAL file series. This parameter is required for archive recovery,
-        but optional for streaming replication.
+        but optional for streaming physical replication.
         Any <literal>%f</literal> in the string is
         replaced by the name of the file to retrieve from the archive,
         and any <literal>%p</literal> is replaced by the copy destination path name
@@ -4468,15 +4468,16 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
     <title>Replication</title>
 
     <para>
-     These settings control the behavior of the built-in
-     <firstterm>streaming replication</firstterm> feature (see
-     <xref linkend="streaming-replication"/>), and the built-in
-     <firstterm>logical replication</firstterm> feature (see
+     These settings control the behavior of
+     <firstterm>streaming replication</firstterm>,
+     both <firstterm>physical replication</firstterm>
+     (see <xref linkend="streaming-replication"/>) and
+     <firstterm>logical replication</firstterm> (see
      <xref linkend="logical-replication"/>).
     </para>
 
     <para>
-     For <emphasis>streaming replication</emphasis>, servers will be either a
+     For <emphasis>physical 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
@@ -4907,7 +4908,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
       These settings control the behavior of a
       <link linkend="standby-server-operation">standby server</link>
       that is
-      to receive replication data.  Their values on the primary server
+      to receive physical replication data.  Their values on the primary server
       are irrelevant.
      </para>
 
@@ -5047,7 +5048,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
         conflict with about-to-be-applied WAL entries, as described in
         <xref linkend="hot-standby-conflict"/>.
         <varname>max_standby_streaming_delay</varname> applies when WAL data is
-        being received via streaming replication.
+        being received via streaming physical replication.
         If this value is specified without units, it is taken as milliseconds.
         The default is 30 seconds.
         A value of -1 allows the standby to wait forever for conflicting
@@ -5183,7 +5184,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
       <listitem>
        <para>
         Specifies how long the standby server should wait when WAL data is not
-        available from any sources (streaming replication,
+        available from any sources (streaming physical replication,
         local <filename>pg_wal</filename> or WAL archive) before trying
         again to retrieve WAL data.
         If this value is specified without units, it is taken as milliseconds.
@@ -5260,7 +5261,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
         <filename>pg_wal</filename> directory.
        </para>
        <para>
-        This parameter is intended for use with streaming replication deployments;
+        This parameter is intended for use with streaming physical replication deployments;
         however, if the parameter is specified it will be honored in all cases
         except crash recovery.
 

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 81eeadd6c47597d9293db29f16a8edb1824f1671..33ca3f0286c17ec3cbc8508c7f1e2cebf6be8eea 100644 (file)
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -151,7 +151,7 @@ protocol to make nodes agree on a serializable transactional order.
     </para>
     <para>
      A standby server can be implemented using file-based log shipping
-     (<xref linkend="warm-standby"/>) or streaming replication (see
+     (<xref linkend="warm-standby"/>) or streaming physical replication (see
      <xref linkend="streaming-replication"/>), or a combination of both. For
      information on hot standby, see <xref linkend="hot-standby"/>.
     </para>
@@ -628,7 +628,7 @@ protocol to make nodes agree on a serializable transactional order.
     In standby mode, the server continuously applies WAL received from the
     primary server. The standby server can read WAL from a WAL archive
     (see <xref linkend="guc-restore-command"/>) or directly from the primary
-    over a TCP connection (streaming replication). The standby server will
+    over a TCP connection (streaming physical replication). The standby server will
     also attempt to restore any WAL found in the standby cluster's
     <filename>pg_wal</filename> directory. That typically happens after a server
     restart, when the standby replays again WAL that was streamed from the
@@ -772,6 +772,14 @@ archive_cleanup_command = 'pg_archivecleanup /path/to/archive "%r"'
     generated, without waiting for the WAL file to be filled.
    </para>
 
+   <note>
+    <para>
+     This discussion of streaming replication assumes physical replication.
+     Although you could treat a logical replication subscriber as a warm standby,
+     it would require some differences to what is described here.
+    </para>
+   </note>
+
    <para>
     Streaming replication is asynchronous by default
     (see <xref linkend="synchronous-replication"/>), in which case there is

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index aa013f348d4d1768fad7576c9b0ac25c1d1af97c..b3faaa675ef33b7f4053e6cc8b49614d8e225944 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -6,7 +6,7 @@
  <para>
   Logical replication is a method of replicating data objects and their
   changes, based upon their replication identity (usually a primary key).  We
-  use the term logical in contrast to physical replication, which uses exact
+  use the term logical replication in contrast to physical replication, which uses exact
   block addresses and byte-by-byte replication.  PostgreSQL supports both
   mechanisms concurrently, see <xref linkend="high-availability"/>.  Logical
   replication allows fine-grained control over both data replication and
@@ -2496,8 +2496,8 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
   <title>Monitoring</title>
 
   <para>
-   Because logical replication is based on a similar architecture as
-   <link linkend="streaming-replication">physical streaming replication</link>,
+   Because streaming logical replication is based on a similar architecture as
+   <link linkend="streaming-replication">streaming physical replication</link>,
    the monitoring on a publication node is similar to monitoring of a
    physical replication primary
    (see <xref linkend="streaming-replication-monitoring"/>).

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index cae8a376c3ba769cf8c6f9dd443053dc383fcbb6..6368e46ce932f39aebd7cdbf6b78e18486e5aa3f 100644 (file)
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -275,9 +275,9 @@ postgres=# SELECT * from pg_logical_slot_get_changes('regression_slot', NULL, NU
     </para>
 
     <note>
-     <para><productname>PostgreSQL</productname> also has streaming replication slots
-     (see <xref linkend="streaming-replication"/>), but they are used somewhat
-     differently there.
+     <para><productname>PostgreSQL</productname> can also use streaming replication slots
+     to maintain a standby server (see <xref linkend="streaming-replication"/>), but
+     typically those use physical replication, not logical.
      </para>
     </note>