begriffs open source - ai-pg/blob - full-docs/txt/app-pgcreatesubscriber.txt

   1
   2 pg_createsubscriber
   3
   4    pg_createsubscriber — convert a physical replica into a new logical
   5    replica
   6
   7 Synopsis
   8
   9    pg_createsubscriber [option...] { -d | --database }dbname { -D |
  10    --pgdata }datadir { -P | --publisher-server }connstr
  11
  12 Description
  13
  14    pg_createsubscriber creates a new logical replica from a physical
  15    standby server. All tables in the specified database are included in
  16    the logical replication setup. A pair of publication and subscription
  17    objects are created for each database. It must be run at the target
  18    server.
  19
  20    After a successful run, the state of the target server is analogous to
  21    a fresh logical replication setup. The main difference between the
  22    logical replication setup and pg_createsubscriber is how the data
  23    synchronization is done. pg_createsubscriber does not copy the initial
  24    table data. It does only the synchronization phase, which ensures each
  25    table is brought up to a synchronized state.
  26
  27    pg_createsubscriber targets large database systems because in logical
  28    replication setup, most of the time is spent doing the initial data
  29    copy. Furthermore, a side effect of this long time spent synchronizing
  30    data is usually a large amount of changes to be applied (that were
  31    produced during the initial data copy), which increases even more the
  32    time when the logical replica will be available. For smaller databases,
  33    it is recommended to set up logical replication with initial data
  34    synchronization. For details, see the CREATE SUBSCRIPTION copy_data
  35    option.
  36
  37 Options
  38
  39    pg_createsubscriber accepts the following command-line arguments:
  40
  41    -a
  42           --all
  43           Create one subscription per database on the target server.
  44           Exceptions are template databases and databases that don't allow
  45           connections. To discover the list of all databases, connect to
  46           the source server using the database name specified in the
  47           --publisher-server connection string, or if not specified, the
  48           postgres database will be used, or if that does not exist,
  49           template1 will be used. Automatically generated names for
  50           subscriptions, publications, and replication slots are used when
  51           this option is specified. This option cannot be used along with
  52           --database, --publication, --replication-slot, or
  53           --subscription.
  54
  55    -d dbname
  56           --database=dbname
  57           The name of the database in which to create a subscription.
  58           Multiple databases can be selected by writing multiple -d
  59           switches. This option cannot be used together with -a. If -d
  60           option is not provided, the database name will be obtained from
  61           -P option. If the database name is not specified in either the
  62           -d option, or the -P option, and -a option is not specified, an
  63           error will be reported.
  64
  65    -D directory
  66           --pgdata=directory
  67           The target directory that contains a cluster directory from a
  68           physical replica.
  69
  70    -n
  71           --dry-run
  72           Do everything except actually modifying the target directory.
  73
  74    -p port
  75           --subscriber-port=port
  76           The port number on which the target server is listening for
  77           connections. Defaults to running the target server on port 50432
  78           to avoid unintended client connections.
  79
  80    -P connstr
  81           --publisher-server=connstr
  82           The connection string to the publisher. For details see
  83           Section 32.1.1.
  84
  85    -s dir
  86           --socketdir=dir
  87           The directory to use for postmaster sockets on target server.
  88           The default is current directory.
  89
  90    -t seconds
  91           --recovery-timeout=seconds
  92           The maximum number of seconds to wait for recovery to end.
  93           Setting to 0 disables. The default is 0.
  94
  95    -T
  96           --enable-two-phase
  97           Enables two_phase commit for the subscription. When multiple
  98           databases are specified, this option applies uniformly to all
  99           subscriptions created on those databases. The default is false.
 100
 101    -U username
 102           --subscriber-username=username
 103           The user name to connect as on target server. Defaults to the
 104           current operating system user name.
 105
 106    -v
 107           --verbose
 108           Enables verbose mode. This will cause pg_createsubscriber to
 109           output progress messages and detailed information about each
 110           step to standard error. Repeating the option causes additional
 111           debug-level messages to appear on standard error.
 112
 113    --clean=objtype
 114           Drop all objects of the specified type from specified databases
 115           on the target server.
 116
 117           + publications: The FOR ALL TABLES publications established for
 118             this subscriber are always dropped; specifying this object
 119             type causes all other publications replicated from the source
 120             server to be dropped as well.
 121
 122           The objects selected to be dropped are individually logged,
 123           including during a --dry-run. There is no opportunity to affect
 124           or stop the dropping of the selected objects, so consider taking
 125           a backup of them using pg_dump.
 126
 127    --config-file=filename
 128           Use the specified main server configuration file for the target
 129           data directory. pg_createsubscriber internally uses the pg_ctl
 130           command to start and stop the target server. It allows you to
 131           specify the actual postgresql.conf configuration file if it is
 132           stored outside the data directory.
 133
 134    --publication=name
 135           The publication name to set up the logical replication. Multiple
 136           publications can be specified by writing multiple --publication
 137           switches. The number of publication names must match the number
 138           of specified databases, otherwise an error is reported. The
 139           order of the multiple publication name switches must match the
 140           order of database switches. If this option is not specified, a
 141           generated name is assigned to the publication name. This option
 142           cannot be used together with --all.
 143
 144    --replication-slot=name
 145           The replication slot name to set up the logical replication.
 146           Multiple replication slots can be specified by writing multiple
 147           --replication-slot switches. The number of replication slot
 148           names must match the number of specified databases, otherwise an
 149           error is reported. The order of the multiple replication slot
 150           name switches must match the order of database switches. If this
 151           option is not specified, the subscription name is assigned to
 152           the replication slot name. This option cannot be used together
 153           with --all.
 154
 155    --subscription=name
 156           The subscription name to set up the logical replication.
 157           Multiple subscriptions can be specified by writing multiple
 158           --subscription switches. The number of subscription names must
 159           match the number of specified databases, otherwise an error is
 160           reported. The order of the multiple subscription name switches
 161           must match the order of database switches. If this option is not
 162           specified, a generated name is assigned to the subscription
 163           name. This option cannot be used together with --all.
 164
 165    -V
 166           --version
 167           Print the pg_createsubscriber version and exit.
 168
 169    -?
 170           --help
 171           Show help about pg_createsubscriber command line arguments, and
 172           exit.
 173
 174 Notes
 175
 176 Prerequisites
 177
 178    There are some prerequisites for pg_createsubscriber to convert the
 179    target server into a logical replica. If these are not met, an error
 180    will be reported. The source and target servers must have the same
 181    major version as the pg_createsubscriber. The given target data
 182    directory must have the same system identifier as the source data
 183    directory. The given database user for the target data directory must
 184    have privileges for creating subscriptions and using
 185    pg_replication_origin_advance().
 186
 187    The target server must be used as a physical standby. The target server
 188    must have max_active_replication_origins and
 189    max_logical_replication_workers configured to a value greater than or
 190    equal to the number of specified databases. The target server must have
 191    max_worker_processes configured to a value greater than the number of
 192    specified databases. The target server must accept local connections.
 193    If you are planning to use the --enable-two-phase switch then you will
 194    also need to set the max_prepared_transactions appropriately.
 195
 196    The source server must accept connections from the target server. The
 197    source server must not be in recovery. The source server must have
 198    wal_level as logical. The source server must have max_replication_slots
 199    configured to a value greater than or equal to the number of specified
 200    databases plus existing replication slots. The source server must have
 201    max_wal_senders configured to a value greater than or equal to the
 202    number of specified databases and existing WAL sender processes.
 203
 204 Warnings
 205
 206    If pg_createsubscriber fails after the target server was promoted, then
 207    the data directory is likely not in a state that can be recovered. In
 208    such case, creating a new standby server is recommended.
 209
 210    pg_createsubscriber usually starts the target server with different
 211    connection settings during transformation. Hence, connections to the
 212    target server should fail.
 213
 214    Since DDL commands are not replicated by logical replication, avoid
 215    executing DDL commands that change the database schema while running
 216    pg_createsubscriber. If the target server has already been converted to
 217    logical replica, the DDL commands might not be replicated, which might
 218    cause an error.
 219
 220    If pg_createsubscriber fails while processing, objects (publications,
 221    replication slots) created on the source server are removed. The
 222    removal might fail if the target server cannot connect to the source
 223    server. In such a case, a warning message will inform the objects left.
 224    If the target server is running, it will be stopped.
 225
 226    If the replication is using primary_slot_name, it will be removed from
 227    the source server after the logical replication setup.
 228
 229    If the target server is a synchronous replica, transaction commits on
 230    the primary might wait for replication while running
 231    pg_createsubscriber.
 232
 233    Unless the --enable-two-phase switch is specified, pg_createsubscriber
 234    sets up logical replication with two-phase commit disabled. This means
 235    that any prepared transactions will be replicated at the time of COMMIT
 236    PREPARED, without advance preparation. Once setup is complete, you can
 237    manually drop and re-create the subscription(s) with the two_phase
 238    option enabled.
 239
 240    pg_createsubscriber changes the system identifier using pg_resetwal. It
 241    would avoid situations in which the target server might use WAL files
 242    from the source server. If the target server has a standby, replication
 243    will break and a fresh standby should be created.
 244
 245    Replication failures can occur if required WAL files are missing. To
 246    prevent this, the source server must set max_slot_wal_keep_size to -1
 247    to ensure that required WAL files are not prematurely removed.
 248
 249 How It Works
 250
 251    The basic idea is to have a replication start point from the source
 252    server and set up a logical replication to start from this point:
 253     1. Start the target server with the specified command-line options. If
 254        the target server is already running, pg_createsubscriber will
 255        terminate with an error.
 256     2. Check if the target server can be converted. There are also a few
 257        checks on the source server. If any of the prerequisites are not
 258        met, pg_createsubscriber will terminate with an error.
 259     3. Create a publication and replication slot for each specified
 260        database on the source server. Each publication is created using
 261        FOR ALL TABLES. If the --publication option is not specified, the
 262        publication has the following name pattern:
 263        “pg_createsubscriber_%u_%x” (parameter: database oid, random int).
 264        If the --replication-slot option is not specified, the replication
 265        slot has the following name pattern: “pg_createsubscriber_%u_%x”
 266        (parameters: database oid, random int). These replication slots
 267        will be used by the subscriptions in a future step. The last
 268        replication slot LSN is used as a stopping point in the
 269        recovery_target_lsn parameter and by the subscriptions as a
 270        replication start point. It guarantees that no transaction will be
 271        lost.
 272     4. Write recovery parameters into the target data directory and
 273        restart the target server. It specifies an LSN
 274        (recovery_target_lsn) of the write-ahead log location up to which
 275        recovery will proceed. It also specifies promote as the action that
 276        the server should take once the recovery target is reached.
 277        Additional recovery parameters are added to avoid unexpected
 278        behavior during the recovery process such as end of the recovery as
 279        soon as a consistent state is reached (WAL should be applied until
 280        the replication start location) and multiple recovery targets that
 281        can cause a failure. This step finishes once the server ends
 282        standby mode and is accepting read-write transactions. If
 283        --recovery-timeout option is set, pg_createsubscriber terminates if
 284        recovery does not end until the given number of seconds.
 285     5. Create a subscription for each specified database on the target
 286        server. If the --subscription option is not specified, the
 287        subscription has the following name pattern:
 288        “pg_createsubscriber_%u_%x” (parameters: database oid, random int).
 289        It does not copy existing data from the source server. It does not
 290        create a replication slot. Instead, it uses the replication slot
 291        that was created in a previous step. The subscription is created
 292        but it is not enabled yet. The reason is the replication progress
 293        must be set to the replication start point before starting the
 294        replication.
 295     6. Drop publications on the target server that were replicated because
 296        they were created before the replication start location. It has no
 297        use on the subscriber.
 298     7. Set the replication progress to the replication start point for
 299        each subscription. When the target server starts the recovery
 300        process, it catches up to the replication start point. This is the
 301        exact LSN to be used as a initial replication location for each
 302        subscription. The replication origin name is obtained since the
 303        subscription was created. The replication origin name and the
 304        replication start point are used in pg_replication_origin_advance()
 305        to set up the initial replication location.
 306     8. Enable the subscription for each specified database on the target
 307        server. The subscription starts applying transactions from the
 308        replication start point.
 309     9. If the standby server was using primary_slot_name, it has no use
 310        from now on so drop it.
 311    10. If the standby server contains failover replication slots, they
 312        cannot be synchronized anymore, so drop them.
 313    11. Update the system identifier on the target server. The pg_resetwal
 314        is run to modify the system identifier. The target server is
 315        stopped as a pg_resetwal requirement.
 316
 317 Examples
 318
 319    To create a logical replica for databases hr and finance from a
 320    physical replica at foo:
 321 $ pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance
 322
 323 See Also
 324
 325    pg_basebackup