0001-fixup-Create-a-new-logical-replica-from-a-base-backu.patch

From a0ad5fdaddc17ef74594bfd3c65c777649d1544b Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 15 Mar 2022 14:39:19 +0100
Subject: [PATCH] fixup! Create a new logical replica from a base backup or
 standby server.

---
 doc/src/sgml/ref/pg_subscriber.sgml | 172 ++++++++++++++++------------
 1 file changed, 99 insertions(+), 73 deletions(-)

diff --git a/doc/src/sgml/ref/pg_subscriber.sgml b/doc/src/sgml/ref/pg_subscriber.sgml
index e68a19092e..df63c6a993 100644
--- a/doc/src/sgml/ref/pg_subscriber.sgml
+++ b/doc/src/sgml/ref/pg_subscriber.sgml
@@ -43,79 +43,6 @@ <title>Description</title>
    replication connections from the target server (known as subscriber server).
    The target server should accept local logical replication connection.
   </para>
-
-  <para>
-   The transformation proceeds in eight steps. First,
-   <application>pg_subscriber</application> checks if the given target data
-   directory has the same system identifier than the source data directory.
-   Since it uses the recovery process as one of the steps, it starts the target
-   server as a replica from the source server. If the system identifier is not
-   the same, <application>pg_subscriber</application> will terminate with an
-   error.
-  </para>
-
-  <para>
-   Second, <application>pg_subscriber</application> checks if the target data
-   directory is used by a standby server. Stop the standby server if it is
-   running. One of the next steps is to add some recovery parameters that
-   requires a server start. This step avoids an error.
-  </para>
-
-  <para>
-   Next, <application>pg_subscriber</application> creates one replication slot
-   for each specified database on the source server. The replication slot name
-   contains a <literal>pg_subscriber</literal> prefix. These replication slots
-   will be used by the subscriptions in a future step.  Another replication
-   slot is used to get a consistent start location. This consistent LSN will be
-   used (a) as a stopping point in the <xref
-   linkend="guc-recovery-target-lsn"/> parameter and (b) by the subscriptions
-   as a replication starting point. It guarantees that no transaction will be
-   lost.
-  </para>
-
-  <para>
-   Next, write recovery parameters into the target data directory and start the
-   target server. It specifies a LSN (consistent LSN that was obtained in the
-   previous step) of write-ahead log location up to which recovery will
-   proceed. It also specifies <literal>promote</literal> as the action that the
-   server should take once the recovery target is reached. This step finishes
-   once the server ends standby mode and is accepting read-write operations.
-  </para>
-
-  <para>
-   Next, <application>pg_subscriber</application> creates one publication for
-   each specified database on the source server. Each publication replicates
-   changes for all tables in the database. The publication name contains a
-   <literal>pg_subscriber</literal> prefix. These publication will be used by a
-   corresponding subscription in a next step.
-  </para>
-
-  <para>
-   Next, <application>pg_subscriber</application> creates one subscription for
-   each specified database on the target server. Each subscription name
-   contains a <literal>pg_subscriber</literal> prefix. The replication slot
-   name is identical to the subscription name. It also does not copy existing
-   data from the source server. It does not create a replication slot. Instead,
-   it uses the replication slot that was created in a previous step. The
-   subscription is created but it is not enabled yet. The reason is the
-   replication progress must be set to the consistent LSN but replication
-   origin name contains the subscription oid in its name. Hence, the
-   subscription will be enabled in a separate step.
-  </para>
-
-  <para>
-   Next, <application>pg_subscriber</application> sets the replication progress
-   to the consistent LSN that was obtained in a previous step. When the target
-   server started the recovery process, it caught up to the consistent LSN.
-   This is the exact LSN to be used as a initial location for the logical
-   replication.
-  </para>
-
-  <para>
-   Finally, <application>pg_subscriber</application> enables the subscription
-   for each specified database on the target server. The subscription starts
-   streaming from the consistent LSN.
-  </para>
  </refsect1>
 
  <refsect1>
@@ -209,6 +136,105 @@ <title>Options</title>
 
  </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   The transformation proceeds in the following steps:
+  </para>
+
+  <procedure>
+   <step>
+    <para>
+     <application>pg_subscriber</application> checks if the given target data
+     directory has the same system identifier than the source data directory.
+     Since it uses the recovery process as one of the steps, it starts the
+     target server as a replica from the source server. If the system
+     identifier is not the same, <application>pg_subscriber</application> will
+     terminate with an error.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     <application>pg_subscriber</application> checks if the target data
+     directory is used by a standby server. Stop the standby server if it is
+     running. One of the next steps is to add some recovery parameters that
+     requires a server start. This step avoids an error.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     <application>pg_subscriber</application> creates one replication slot for
+     each specified database on the source server. The replication slot name
+     contains a <literal>pg_subscriber</literal> prefix. These replication
+     slots will be used by the subscriptions in a future step.  Another
+     replication slot is used to get a consistent start location. This
+     consistent LSN will be used (a) as a stopping point in the <xref
+     linkend="guc-recovery-target-lsn"/> parameter and (b) by the
+     subscriptions as a replication starting point. It guarantees that no
+     transaction will be lost.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     <application>pg_subscriber</application> writes recovery parameters into
+     the target data directory and start the target server. It specifies a LSN
+     (consistent LSN that was obtained in the previous step) of write-ahead
+     log location up to which recovery will proceed. It also specifies
+     <literal>promote</literal> as the action that the server should take once
+     the recovery target is reached. This step finishes once the server ends
+     standby mode and is accepting read-write operations.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Next, <application>pg_subscriber</application> creates one publication
+     for each specified database on the source server. Each publication
+     replicates changes for all tables in the database. The publication name
+     contains a <literal>pg_subscriber</literal> prefix. These publication
+     will be used by a corresponding subscription in a next step.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     <application>pg_subscriber</application> creates one subscription for
+     each specified database on the target server. Each subscription name
+     contains a <literal>pg_subscriber</literal> prefix. The replication slot
+     name is identical to the subscription name. It also does not copy
+     existing data from the source server. It does not create a replication
+     slot. Instead, it uses the replication slot that was created in a
+     previous step. The subscription is created but it is not enabled yet. The
+     reason is the replication progress must be set to the consistent LSN but
+     replication origin name contains the subscription oid in its name. Hence,
+     the subscription will be enabled in a separate step.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     <application>pg_subscriber</application> sets the replication progress to
+     the consistent LSN that was obtained in a previous step. When the target
+     server started the recovery process, it caught up to the consistent LSN.
+     This is the exact LSN to be used as a initial location for the logical
+     replication.
+    </para>
+   </step>
+
+   <step>
+    <para>
+     Finally, <application>pg_subscriber</application> enables the subscription
+     for each specified database on the target server. The subscription starts
+     streaming from the consistent LSN.
+    </para>
+   </step>
+  </procedure>
+ </refsect1>
+
  <refsect1>
   <title>Examples</title>
 
-- 
2.35.1