From 36e1f1e641c871781be264a665081dd52a6d77d9 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" Date: Mon, 10 Mar 2025 13:55:55 -0700 Subject: [PATCH 2/2] doc: editorial pass over pg_createsubscriber --- doc/src/sgml/ref/pg_createsubscriber.sgml | 105 ++++++++++------------ 1 file changed, 49 insertions(+), 56 deletions(-) diff --git a/doc/src/sgml/ref/pg_createsubscriber.sgml b/doc/src/sgml/ref/pg_createsubscriber.sgml index d39ec44297..cffc9cfc42 100644 --- a/doc/src/sgml/ref/pg_createsubscriber.sgml +++ b/doc/src/sgml/ref/pg_createsubscriber.sgml @@ -23,23 +23,10 @@ PostgreSQL documentation pg_createsubscriber option - - - - - - dbname - - - - - datadir - - - - - connstr - + + datadir + + connstr @@ -50,32 +37,26 @@ PostgreSQL documentation pg_createsubscriber creates a new logical replica from a physical standby server. All tables in the specified database are included in the logical - replication setup. A pair of - publication and subscription objects are created for each database. It - must be run at the target server. + replication setup. It must be run at the target server. - After a successful run, the state of the target server is analogous to a - fresh logical replication setup. The main difference between the logical - replication setup and pg_createsubscriber is how - the data synchronization is done. pg_createsubscriber - does not copy the initial table data. It does only the synchronization phase, - which ensures each table is brought up to a synchronized state. + The minimal command shown above replicates only a single database: the + one named in the connection string pointing to the source server. More + commonly, you would use the () + option one or more times to specify which databases in the source to replicate. + The corresponding publications, subscriptions, and replication slots are + then created using auto-generated names, which can be overriden + using the corresponding long-form command-line options, once each per database. - pg_createsubscriber targets large database - systems because in logical replication setup, most of the time is spent - doing the initial data copy. Furthermore, a side effect of this long time - spent synchronizing data is usually a large amount of changes to be applied - (that were produced during the initial data copy), which increases even - more the time when the logical replica will be unavailable. For smaller - databases, it is recommended to set up logical replication with initial data - synchronization. For details, see the CREATE SUBSCRIPTION - - copy_data option. - + After a successful run, the state of the target server is analogous to a + fresh logical replication setup. The main difference compared the logical + replication setup is that pg_createsubscriber + does not perform an initial data copy. Instead it relies on a LSN-based + point-in-time recovery of physical backup to coincide with the LSN-based + starting point of the subscription(s) it creates. @@ -92,12 +73,12 @@ PostgreSQL documentation - The name of the database in which to create a subscription. Multiple + The name of the database for which to create a subscription. Multiple databases can be selected by writing multiple - options. If option is not provided, the database - name will be obtained from option. If the database - name is not specified in either the option or - option, an error will be reported. + options. If no option is provided, the database + name will be obtained from the option. If the database + name is not specified in either the or + options, an error will be reported. @@ -107,7 +88,7 @@ PostgreSQL documentation - The target directory that contains a cluster directory from a physical + The target directory that contains a cluster directory of a physical replica. @@ -143,6 +124,11 @@ PostgreSQL documentation The connection string to the publisher. For details see . + + If the option is not provided, the database name + of the single database to replicate is obtained from here. If a database + name is also not specified in this connection string, an error will be reported. + @@ -162,8 +148,8 @@ PostgreSQL documentation - The maximum number of seconds to wait for recovery to end. Setting to - 0 disables. The default is 0. + The maximum number of seconds to wait for recovery to end. + A value of 0 (the default) disables. @@ -186,7 +172,7 @@ PostgreSQL documentation - The user name to connect as on target server. Defaults to the current + The user name to connect as on the target server. Defaults to the current operating system user name. @@ -210,12 +196,18 @@ PostgreSQL documentation - Use the specified main server configuration file for the target data - directory. pg_createsubscriber internally uses + Use the specified main server configuration file for the target service. + pg_createsubscriber internally uses the pg_ctl command to start and - stop the target server. It allows you to specify the actual - postgresql.conf configuration file if it is stored - outside the data directory. + stop the target server; which by default expects a postgresql.conf + configuration file to exist in the data directory. Pass the actual file location via this option + if that is not the case. + + + Note, the configuration setting port in this file is effectively ignored + as pg_createsubscriber always specifies the target listening port + on the pg_ctl command-line. + Use the option to specify which port the target server should listen on. @@ -310,7 +302,7 @@ PostgreSQL documentation - The target server must be used as a physical standby. The target server + The target server must be setup as a physical standby. The target server must have and configured to a value greater than or equal to the number of specified databases. The target @@ -344,16 +336,17 @@ PostgreSQL documentation - pg_createsubscriber usually starts the target - server with different connection settings during transformation. Hence, - connections to the target server should fail. + pg_createsubscriber is designed have full and + exclusive control over the target server. Plan for downtime or migration + of any applications or users of the target server in its soon-to-be converted + physical standby mode. Since DDL commands are not replicated by logical replication, avoid executing DDL commands that change the database schema while running pg_createsubscriber. If the target server has - already been converted to logical replica, the DDL commands might not be + already been converted to a logical replica, the DDL commands might not be replicated, which might cause an error. -- 2.34.1