diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
index 434bc31180..f8756389a3 100644
--- a/doc/src/sgml/logical-replication.sgml
+++ b/doc/src/sgml/logical-replication.sgml
@@ -320,7 +320,7 @@
- Examples
+ Examples - Setup Logical Replication
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 bd12e71e33..f9a1776380 100644
--- 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
- 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
+
+ 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_namepg_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.