Doc: Update information about manually creating slots.

There are some cases (e.g. when the subscription is created using the
connect = false option) where the remote replication slot was not created
automatically and the user must create it manually before the subscription
can be activated. There was not enough information in the docs for users
to do this easily.

Author: Peter Smith
Reviewd by: Shi yu, Amit Kapila
Discussion: https://postgr.es/m/CAHut+PvqdqOanheWSHDyhQiF+Z-7w=-+k4U+bwbT=b6YQ_hrXQ@mail.gmail.com

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 434bc3118054b828f78ee764d99e78f4f1d6a3fe..f8756389a3bf6121ec86fddd119626faaafd72fa 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -320,7 +320,7 @@
   
 
   
-    Examples
+    Examples<span class="marked"> - Setup Logical Replication</span>
 
     
      Create some test tables on the publisher.
@@ -512,6 +512,163 @@ test_sub=# SELECT * FROM t3;
 
   
 
+  
+   Examples - Deferred Replication Slot Creation
+
+   
+    There are some cases (e.g.
+    ) where, if the
+    remote replication slot was not created automatically, the user must create
+    it manually before the subscription can be activated. The steps to create
+    the slot and activate the subscription are shown in the following examples.
+    These examples specify the standard logical decoding plugin
+    (pgoutput), which is what the built-in logical
+    replication uses.
+   
+   
+    First, create a publication for the examples to use.
+
+test_pub=# CREATE PUBLICATION pub1 FOR ALL TABLES;
+CREATE PUBLICATION
+
+   
+    Example 1: Where the subscription says connect = false
+   
+   
+    
+     
+      
+       Create the subscription.
+
+test_sub=# CREATE SUBSCRIPTION sub1
+test_sub-# CONNECTION 'host=localhost dbname=test_pub'
+test_sub-# PUBLICATION pub1
+test_sub-# WITH (connect=false);
+WARNING:  subscription was created, but is not connected
+HINT:  To initiate replication, you must manually create the replication slot, enable the subscription, and refresh the subscription.
+CREATE SUBSCRIPTION
+
+     
+     
+      
+       On the publisher, manually create a slot. Because the name was not
+       specified during CREATE SUBSCRIPTION, the name of the
+       slot to create is same as the subscription name, e.g. "sub1".
+
+test_pub=# SELECT * FROM pg_create_logical_replication_slot('sub1', 'pgoutput');
+ slot_name |    lsn
+-----------+-----------
+ sub1      | 0/19404D0
+(1 row)
+
+     
+     
+      
+       On the subscriber, complete the activation of the subscription. After
+       this the tables of pub1 will start replicating.
+
+test_sub=# ALTER SUBSCRIPTION sub1 ENABLE;
+ALTER SUBSCRIPTION
+test_sub=# ALTER SUBSCRIPTION sub1 REFRESH PUBLICATION;
+ALTER SUBSCRIPTION
+
+     
+    
+   
+
+   
+    Example 2: Where the subscription says connect = false,
+    but also specifies the slot_name
+    
+     
+      
+       Create the subscription.
+
+test_sub=# CREATE SUBSCRIPTION sub1
+test_sub-# CONNECTION 'host=localhost dbname=test_pub'
+test_sub-# PUBLICATION pub1
+test_sub-# WITH (connect=false, slot_name='myslot');
+WARNING:  subscription was created, but is not connected
+HINT:  To initiate replication, you must manually create the replication slot, enable the subscription, and refresh the subscription.
+CREATE SUBSCRIPTION
+
+     
+     
+      
+       On the publisher, manually create a slot using the same name that was
+       specified during CREATE SUBSCRIPTION, e.g. "myslot".
+
+test_pub=# SELECT * FROM pg_create_logical_replication_slot('myslot', 'pgoutput');
+ slot_name |    lsn
+-----------+-----------
+ myslot    | 0/19059A0
+(1 row)
+
+     
+     
+      
+       On the subscriber, the remaining subscription activation steps are the
+       same as before.
+
+test_sub=# ALTER SUBSCRIPTION sub1 ENABLE;
+ALTER SUBSCRIPTION
+test_sub=# ALTER SUBSCRIPTION sub1 REFRESH PUBLICATION;
+ALTER SUBSCRIPTION
+
+     
+    
+   
+
+   
+    Example 3: Where the subscription specifies slot_name = NONE
+    
+     
+      
+       Create the subscription. When slot_name = NONE then
+       enabled = false, and
+       create_slot = false are also needed.
+
+test_sub=# CREATE SUBSCRIPTION sub1
+test_sub-# CONNECTION 'host=localhost dbname=test_pub'
+test_sub-# PUBLICATION pub1
+test_sub-# WITH (slot_name=NONE, enabled=false, create_slot=false);
+CREATE SUBSCRIPTION
+
+     
+     
+      
+       On the publisher, manually create a slot using any name, e.g. "myslot".
+
+test_pub=# SELECT * FROM pg_create_logical_replication_slot('myslot', 'pgoutput');
+ slot_name |    lsn
+-----------+-----------
+ myslot    | 0/1905930
+(1 row)
+
+     
+     
+      
+       On the subscriber, associate the subscription with the slot name just
+       created.
+
+test_sub=# ALTER SUBSCRIPTION sub1 SET (slot_name='myslot');
+ALTER SUBSCRIPTION
+
+     
+     
+      
+       The remaining subscription activation steps are same as before.
+
+test_sub=# ALTER SUBSCRIPTION sub1 ENABLE;
+ALTER SUBSCRIPTION
+test_sub=# ALTER SUBSCRIPTION sub1 REFRESH PUBLICATION;
+ALTER SUBSCRIPTION
+
+     
+    
+   
+  
+
  
 
  

diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index bd12e71e33603eec5c4b55e8c1537b2cc0cc438e..f9a1776380bfc6058cdf7a1331bcf3c1d77228fa 100644 (file)
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -120,11 +120,11 @@ CREATE SUBSCRIPTION subscription_name
 
          
           Since no connection is made when this option is
-          false, no tables are subscribed, and so
-          after you enable the subscription nothing will be replicated.
-          You will need to then run
-          <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION>
-          for tables to be subscribed.
+          false, no tables are subscribed. To initiate
+          replication, you must manually create the replication slot, enable
+          the subscription, and refresh the subscription. See
+          <xref linkend="logical-replication-subscription-examples-deferred-slot"/>
+          for examples.
          
         
        
@@ -135,8 +135,12 @@ CREATE SUBSCRIPTION subscription_name
          
           Specifies whether the command should create the replication slot on
           the publisher.  The default is true.
+         
+         
           If set to false, you are responsible for
-          creating the publisher's slot in some other way.
+          creating the publisher's slot in some other way. See
+          
+          for examples.
          
         
        
@@ -162,11 +166,13 @@ CREATE SUBSCRIPTION subscription_name
 
          
           Setting slot_name to NONE
-          means there will be no replication slot
-          associated with the subscription.  Use this when you will be
-          creating the replication slot later manually.  Such
-          subscriptions must also have both enabled and
-          create_slot set to false.
+          means there will be no replication slot associated with the
+          subscription. Such subscriptions must also have both
+          enabled and create_slot set to
+          false.  Use this when you will be creating the
+          replication slot later manually. See
+          
+          for examples.
          
         
        
@@ -357,8 +363,10 @@ CREATE SUBSCRIPTION subscription_name
    replication slot separately (using the
    function pg_create_logical_replication_slot with the
    plugin name pgoutput) and create the subscription using
-   the parameter create_slot = false.  This is an
-   implementation restriction that might be lifted in a future release.
+   the parameter create_slot = false.  See
+   
+   for examples. This is an implementation restriction that might be lifted in a
+   future release.