From 1882d6cca161dcf9fa05ecab5abeb1a027a5cfd2 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 13 Sep 2021 14:27:02 -0400 Subject: [PATCH] Doc: improve documentation of CREATE/ALTER SUBSCRIPTION. Improve the descriptions of some options. Fix sloppy grammar and markup. Peter Smith and Tom Lane Discussion: https://postgr.es/m/CAHut+PtPJDSOxtuMGpO2yDrRPKxcYGL4n7HqJP9HernZE=Cj+g@mail.gmail.com --- doc/src/sgml/ref/alter_subscription.sgml | 35 +++---- doc/src/sgml/ref/create_subscription.sgml | 107 ++++++++++++---------- 2 files changed, 76 insertions(+), 66 deletions(-) diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml index 835be0d2a4..9e51395a61 100644 --- a/doc/src/sgml/ref/alter_subscription.sgml +++ b/doc/src/sgml/ref/alter_subscription.sgml @@ -50,14 +50,14 @@ ALTER SUBSCRIPTION name RENAME TO < (Currently, all subscription owners must be superusers, so the owner checks will be bypassed in practice. But this might change in the future.) - + When refreshing a publication we remove the relations that are no longer part of the publication and we also remove the table synchronization slots if there are any. It is necessary to remove these slots so that the resources allocated for the subscription on the remote host are released. If due to network breakdown or some other error, PostgreSQL - is unable to remove the slots, an ERROR will be reported. To proceed in this + is unable to remove the slots, an error will be reported. To proceed in this situation, the user either needs to retry the operation or disassociate the slot from the subscription and drop the subscription as explained in . @@ -69,9 +69,11 @@ ALTER SUBSCRIPTION name RENAME TO < option as true cannot be executed inside a transaction block. These commands also cannot be executed when the subscription has - two_phase commit enabled, unless copy_data = false. - See column subtwophasestate of - to know the actual two-phase state. + two_phase commit enabled, + unless copy_data is false. + See column subtwophasestate of + pg_subscription + to know the actual two-phase state. @@ -92,7 +94,7 @@ ALTER SUBSCRIPTION name RENAME TO < CONNECTION 'conninfo' - This clause alters the connection property originally set by + This clause replaces the connection string originally set by . See there for more information. @@ -105,7 +107,8 @@ ALTER SUBSCRIPTION name RENAME TO < DROP PUBLICATION publication_name - Changes the list of subscribed publications. SET + These forms change the list of subscribed publications. + SET replaces the entire list of publications with a new list, ADD adds additional publications to the list of publications, and DROP removes the publications from @@ -143,8 +146,8 @@ ALTER SUBSCRIPTION name RENAME TO < Fetch missing table information from publisher. This will start replication of tables that were added to the subscribed-to publications - since the last invocation of REFRESH PUBLICATION or - since CREATE SUBSCRIPTION. + since CREATE SUBSCRIPTION or + the last invocation of REFRESH PUBLICATION. @@ -156,9 +159,9 @@ ALTER SUBSCRIPTION name RENAME TO < copy_data (boolean) - Specifies whether the existing data in the publications that are - being subscribed to should be copied once the replication starts. - The default is true. (Previously subscribed + Specifies whether to copy pre-existing data in the publications + that are being subscribed to when the replication starts. + The default is true. (Previously-subscribed tables are not copied.) @@ -171,8 +174,8 @@ ALTER SUBSCRIPTION name RENAME TO < ENABLE - Enables the previously disabled subscription, starting the logical - replication worker at the end of transaction. + Enables a previously disabled subscription, starting the logical + replication worker at the end of the transaction. @@ -181,8 +184,8 @@ ALTER SUBSCRIPTION name RENAME TO < DISABLE - Disables the running subscription, stopping the logical replication - worker at the end of transaction. + Disables a running subscription, stopping the logical replication + worker at the end of the transaction. diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index 04a0fd7fba..990a41f1a1 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -32,20 +32,21 @@ CREATE SUBSCRIPTION subscription_nameDescription - CREATE SUBSCRIPTION adds a new subscription for the - current database. The subscription name must be distinct from the name of - any existing subscription in the database. + CREATE SUBSCRIPTION adds a new logical-replication + subscription. The subscription name must be distinct from the name of + any existing subscription in the current database. - The subscription represents a replication connection to the publisher. As - such this command does not only add definitions in the local catalogs but - also creates a replication slot on the publisher. + A subscription represents a replication connection to the publisher. + Hence, in addition to adding definitions in the local catalogs, this + command normally creates a replication slot on the publisher. A logical replication worker will be started to replicate data for the new - subscription at the commit of the transaction where this command is run. + subscription at the commit of the transaction where this command is run, + unless the subscription is initially disabled. @@ -73,14 +74,15 @@ CREATE SUBSCRIPTION subscription_nameCONNECTION 'conninfo' - The connection string to the publisher. For details - see . + The libpq connection string defining how + to connect to the publisher database. For details see + . - PUBLICATION publication_name + PUBLICATION publication_name [, ...] Names of the publications on the publisher to subscribe to. @@ -105,25 +107,23 @@ CREATE SUBSCRIPTION subscription_name Specifies whether the CREATE SUBSCRIPTION - should connect to the publisher at all. Setting this to - false will change default values of - enabled, create_slot and + command should connect to the publisher at all. The default + is true. Setting this to + false will force the values of + create_slot, enabled and copy_data to false. + (You cannot combine setting connect + to false with + setting create_slot, enabled, + or copy_data to true.) - It is not allowed to combine connect set to - false and enabled, - create_slot, or copy_data - set to true. - - - - Since no connection is made when this option is set - to false, the tables are not subscribed, and so + 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. - It is required to run - ALTER SUBSCRIPTION ... REFRESH PUBLICATION in order + You will need to then run + ALTER SUBSCRIPTION ... REFRESH PUBLICATION for tables to be subscribed. @@ -135,6 +135,8 @@ 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. @@ -143,8 +145,8 @@ CREATE SUBSCRIPTION subscription_nameenabled (boolean) - Specifies whether the subscription should be actively replicating, - or whether it should be just setup but not started yet. The default + Specifies whether the subscription should be actively replicating + or whether it should just be set up but not started yet. The default is true. @@ -154,15 +156,15 @@ CREATE SUBSCRIPTION subscription_nameslot_name (string) - Name of the replication slot to use. The default behavior is to - use the name of the subscription for the slot name. + Name of the publisher's replication slot to use. The default is + to use the name of the subscription for the slot name. - When slot_name is set to - NONE, there will be no replication slot - associated with the subscription. This can be used if the - replication slot will be created later manually. Such + 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. @@ -172,7 +174,8 @@ CREATE SUBSCRIPTION subscription_name - The following parameters control the replication behavior: + The following parameters control the subscription's replication + behavior after it has been created: @@ -183,14 +186,14 @@ CREATE SUBSCRIPTION subscription_namefalse. - Even when this option is enabled, only data types that have + Even when this option is enabled, only data types having binary send and receive functions will be transferred in binary. - When doing cross-version replication, it could happen that the + When doing cross-version replication, it could be that the publisher has a binary send function for some data type, but the - subscriber lacks a binary receive function for the type. In + subscriber lacks a binary receive function for that type. In such a case, data transfer will fail, and the binary option cannot be used. @@ -201,8 +204,8 @@ CREATE SUBSCRIPTION subscription_namecopy_data (boolean) - Specifies whether the existing data in the publications that are - being subscribed to should be copied once the replication starts. + Specifies whether to copy pre-existing data in the publications + that are being subscribed to when the replication starts. The default is true. @@ -212,9 +215,9 @@ CREATE SUBSCRIPTION subscription_namestreaming (boolean) - Specifies whether streaming of in-progress transactions should - be enabled for this subscription. By default, all transactions - are fully decoded on the publisher, and only then sent to the + Specifies whether to enable streaming of in-progress transactions + for this subscription. By default, all transactions + are fully decoded on the publisher and only then sent to the subscriber as a whole. @@ -261,18 +264,22 @@ CREATE SUBSCRIPTION subscription_name - When two-phase commit is enabled then the decoded transactions are sent - to the subscriber on the PREPARE TRANSACTION. By default, the transaction - prepared on the publisher is decoded as a normal transaction at commit. + When two-phase commit is enabled, prepared transactions are sent + to the subscriber at the time of PREPARE + TRANSACTION, and are processed as two-phase + transactions on the subscriber too. Otherwise, prepared + transactions are sent to the subscriber only when committed, and + are then processed immediately by the subscriber. - The two-phase commit implementation requires that the replication has - successfully passed the initial table synchronization phase. This means - even when two_phase is enabled for the subscription, the internal - two-phase state remains temporarily "pending" until the initialization - phase is completed. See column - subtwophasestate of + The implementation of two-phase commit requires that replication + has successfully finished the initial table synchronization + phase. So even when two_phase is enabled for a + subscription, the internal two-phase state remains + temporarily pending until the initialization phase + completes. See column subtwophasestate + of pg_subscription to know the actual two-phase state.