doc: Add info about replication slot management

Add some more information about managing replication slots associated
with logical replication subscriptions.

diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index e7526905f8c37459c20d07ed433ce4b904399cc6..e87e3dcd36dfe300dbbda0df350ec82cb5815fe4 100644 (file)
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -204,6 +204,66 @@
    target table can have additional columns not provided by the published
    table.  Those will be filled with their default values.
   
+
+  
+   Replication Slot Management
+
+   
+    As mentioned earlier, each (active) subscription receives changes from a
+    replication slot on the remote (publishing) side.  Normally, the remote
+    replication slot is created automatically when the subscription is created
+    using CREATE SUBSCRIPTION and it is dropped
+    automatically when the subscription is dropped using DROP
+    SUBSCRIPTION.  In some situations, however, it can be useful or
+    necessary to manipulate the subscription and the underlying replication
+    slot separately.  Here are some scenarios:
+
+    
+     
+      
+       When creating a subscription, the replication slot already exists.  In
+       that case, the subscription can be created using the NOCREATE
+       SLOT option to associate with the existing slot.
+      
+     
+
+     
+      
+       When creating a subscription, the remote host is not reachable or in an
+       unclear state.  In that case, the subscription can be created using
+       the NOCONNECT option.  The remote host will then not
+       be contacted at all.  This is what pg_dump
+       uses.  The remote replication slot will then have to be created
+       manually before the subscription can be activated.
+      
+     
+
+     
+      
+       When dropping a subscription, the replication slot should be kept.
+       This could be useful when the subscriber database is being moved to a
+       different host and will be activated from there.  In that case,
+       disassociate the slot from the subscription using ALTER
+       SUBSCRIPTION before attempting to drop the subscription.
+      
+     
+
+     
+      
+       When dropping a subscription, the remote host is not reachable.  In
+       that case, disassociate the slot from the subscription
+       using ALTER SUBSCRIPTION before attempting to drop
+       the subscription.  If the remote database instance no longer exists, no
+       further action is then necessary.  If, however, the remote database
+       instance is just unreachable, the replication slot should then be
+       dropped manually; otherwise it would continue to reserve WAL and might
+       eventually cause the disk to fill up.  Such cases should be carefully
+       investigated.
+      
+     
+    
+   
+