From ab7e739d8f7b6ac4072dcf02cf688ce2753972cc Mon Sep 17 00:00:00 2001 From: Peter Smith Date: Mon, 17 Oct 2022 12:43:03 +1100 Subject: [PATCH v5] create subscriptipon - pgdocs for deferred slot creation. New documentation describing how to activate a subscription which was originally created in a disconnected mode. The new docs/examples are added as part of "Logical Replication - Subscription" section 31.2. The CREATE SUBSCRIPTION reference page is also updated to include links to it. --- doc/src/sgml/logical-replication.sgml | 163 ++++++++++++++++++++++++++++++ doc/src/sgml/ref/create_subscription.sgml | 34 ++++--- 2 files changed, 184 insertions(+), 13 deletions(-) diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml index e98538e..a2b952c 100644 --- a/doc/src/sgml/logical-replication.sgml +++ b/doc/src/sgml/logical-replication.sgml @@ -319,6 +319,169 @@ + + Deferred Replication Slot Creation + + + Sometimes, either by choice (e.g. create_slot = false), + or by necessity (e.g. connect = false), the remote + replication slot is not created automatically during + CREATE SUBSCRIPTION. In these cases the user will have + to create the slot manually before the subscription can be activated. + + + The following examples demonstrate the steps required to activate such + subscriptions. The 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 +-----------+----------- + sub1 | 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); +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 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 + + + + + + + Examples diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index bd12e71..43b32e8 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. -- 1.8.3.1