begriffs open source - ai-pg/blob - full-docs/txt/sql-altersubscription.txt

   1
   2 ALTER SUBSCRIPTION
   3
   4    ALTER SUBSCRIPTION — change the definition of a subscription
   5
   6 Synopsis
   7
   8 ALTER SUBSCRIPTION name CONNECTION 'conninfo'
   9 ALTER SUBSCRIPTION name SET PUBLICATION publication_name [, ...] [ WITH ( public
  10 ation_option [= value] [, ... ] ) ]
  11 ALTER SUBSCRIPTION name ADD PUBLICATION publication_name [, ...] [ WITH ( public
  12 ation_option [= value] [, ... ] ) ]
  13 ALTER SUBSCRIPTION name DROP PUBLICATION publication_name [, ...] [ WITH ( publi
  14 cation_option [= value] [, ... ] ) ]
  15 ALTER SUBSCRIPTION name REFRESH PUBLICATION [ WITH ( refresh_option [= value] [,
  16  ... ] ) ]
  17 ALTER SUBSCRIPTION name ENABLE
  18 ALTER SUBSCRIPTION name DISABLE
  19 ALTER SUBSCRIPTION name SET ( subscription_parameter [= value] [, ... ] )
  20 ALTER SUBSCRIPTION name SKIP ( skip_option = value )
  21 ALTER SUBSCRIPTION name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SES
  22 SION_USER }
  23 ALTER SUBSCRIPTION name RENAME TO new_name
  24
  25 Description
  26
  27    ALTER SUBSCRIPTION can change most of the subscription properties that
  28    can be specified in CREATE SUBSCRIPTION.
  29
  30    You must own the subscription to use ALTER SUBSCRIPTION. To rename a
  31    subscription or alter the owner, you must have CREATE permission on the
  32    database. In addition, to alter the owner, you must be able to SET ROLE
  33    to the new owning role. If the subscription has
  34    password_required=false, only superusers can modify it.
  35
  36    When refreshing a publication we remove the relations that are no
  37    longer part of the publication and we also remove the table
  38    synchronization slots if there are any. It is necessary to remove these
  39    slots so that the resources allocated for the subscription on the
  40    remote host are released. If due to network breakdown or some other
  41    error, PostgreSQL is unable to remove the slots, an error will be
  42    reported. To proceed in this situation, the user either needs to retry
  43    the operation or disassociate the slot from the subscription and drop
  44    the subscription as explained in DROP SUBSCRIPTION.
  45
  46    Commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION, ALTER SUBSCRIPTION
  47    ... {SET|ADD|DROP} PUBLICATION ... with refresh option as true, ALTER
  48    SUBSCRIPTION ... SET (failover = true|false) and ALTER SUBSCRIPTION ...
  49    SET (two_phase = false) cannot be executed inside a transaction block.
  50
  51    Commands ALTER SUBSCRIPTION ... REFRESH PUBLICATION and ALTER
  52    SUBSCRIPTION ... {SET|ADD|DROP} PUBLICATION ... with refresh option as
  53    true also cannot be executed when the subscription has two_phase commit
  54    enabled, unless copy_data is false. See column subtwophasestate of
  55    pg_subscription to know the actual two-phase state.
  56
  57 Parameters
  58
  59    name #
  60           The name of a subscription whose properties are to be altered.
  61
  62    CONNECTION 'conninfo' #
  63           This clause replaces the connection string originally set by
  64           CREATE SUBSCRIPTION. See there for more information.
  65
  66    SET PUBLICATION publication_name
  67           ADD PUBLICATION publication_name
  68           DROP PUBLICATION publication_name #
  69           These forms change the list of subscribed publications. SET
  70           replaces the entire list of publications with a new list, ADD
  71           adds additional publications to the list of publications, and
  72           DROP removes the publications from the list of publications. We
  73           allow non-existent publications to be specified in ADD and SET
  74           variants so that users can add those later. See CREATE
  75           SUBSCRIPTION for more information. By default, this command will
  76           also act like REFRESH PUBLICATION.
  77
  78           publication_option specifies additional options for this
  79           operation. The supported options are:
  80
  81         refresh (boolean)
  82                 When false, the command will not try to refresh table
  83                 information. REFRESH PUBLICATION should then be executed
  84                 separately. The default is true.
  85
  86           Additionally, the options described under REFRESH PUBLICATION
  87           may be specified, to control the implicit refresh operation.
  88
  89    REFRESH PUBLICATION #
  90           Fetch missing table information from publisher. This will start
  91           replication of tables that were added to the subscribed-to
  92           publications since CREATE SUBSCRIPTION or the last invocation of
  93           REFRESH PUBLICATION.
  94
  95           refresh_option specifies additional options for the refresh
  96           operation. The supported options are:
  97
  98         copy_data (boolean)
  99                 Specifies whether to copy pre-existing data in the
 100                 publications that are being subscribed to when the
 101                 replication starts. The default is true.
 102
 103                 Previously subscribed tables are not copied, even if a
 104                 table's row filter WHERE clause has since been modified.
 105
 106                 See Notes for details of how copy_data = true can interact
 107                 with the origin parameter.
 108
 109                 See the binary parameter of CREATE SUBSCRIPTION for
 110                 details about copying pre-existing data in binary format.
 111
 112    ENABLE #
 113           Enables a previously disabled subscription, starting the logical
 114           replication worker at the end of the transaction.
 115
 116    DISABLE #
 117           Disables a running subscription, stopping the logical
 118           replication worker at the end of the transaction.
 119
 120    SET ( subscription_parameter [= value] [, ... ] ) #
 121           This clause alters parameters originally set by CREATE
 122           SUBSCRIPTION. See there for more information. The parameters
 123           that can be altered are slot_name, synchronous_commit, binary,
 124           streaming, disable_on_error, password_required, run_as_owner,
 125           origin, failover, and two_phase. Only a superuser can set
 126           password_required = false.
 127
 128           When altering the slot_name, the failover and two_phase property
 129           values of the named slot may differ from the counterpart
 130           failover and two_phase parameters specified in the subscription.
 131           When creating the slot, ensure the slot properties failover and
 132           two_phase match their counterpart parameters of the
 133           subscription. Otherwise, the slot on the publisher may behave
 134           differently from what these subscription options say: for
 135           example, the slot on the publisher could either be synced to the
 136           standbys even when the subscription's failover option is
 137           disabled or could be disabled for sync even when the
 138           subscription's failover option is enabled.
 139
 140           The failover and two_phase parameters can only be altered when
 141           the subscription is disabled.
 142
 143           When altering two_phase from true to false, the backend process
 144           reports an error if any prepared transactions done by the
 145           logical replication worker (from when two_phase parameter was
 146           still true) are found. You can resolve prepared transactions on
 147           the publisher node, or manually roll back them on the
 148           subscriber, and then try again. The transactions prepared by
 149           logical replication worker corresponding to a particular
 150           subscription have the following pattern: “pg_gid_%u_%u”
 151           (parameters: subscription oid, remote transaction id xid). To
 152           resolve such transactions manually, you need to roll back all
 153           the prepared transactions with corresponding subscription IDs in
 154           their names. Applications can check pg_prepared_xacts to find
 155           the required prepared transactions. After the two_phase option
 156           is changed from true to false, the publisher will replicate the
 157           transactions again when they are committed.
 158
 159    SKIP ( skip_option = value ) #
 160           Skips applying all changes of the remote transaction. If
 161           incoming data violates any constraints, logical replication will
 162           stop until it is resolved. By using the ALTER SUBSCRIPTION ...
 163           SKIP command, the logical replication worker skips all data
 164           modification changes within the transaction. This option has no
 165           effect on the transactions that are already prepared by enabling
 166           two_phase on the subscriber. After the logical replication
 167           worker successfully skips the transaction or finishes a
 168           transaction, the LSN (stored in pg_subscription.subskiplsn) is
 169           cleared. See Section 29.7 for the details of logical replication
 170           conflicts.
 171
 172           skip_option specifies options for this operation. The supported
 173           option is:
 174
 175         lsn (pg_lsn)
 176                 Specifies the finish LSN of the remote transaction whose
 177                 changes are to be skipped by the logical replication
 178                 worker. The finish LSN is the LSN at which the transaction
 179                 is either committed or prepared. Skipping individual
 180                 subtransactions is not supported. Setting NONE resets the
 181                 LSN.
 182
 183    new_owner #
 184           The user name of the new owner of the subscription.
 185
 186    new_name #
 187           The new name for the subscription.
 188
 189    When specifying a parameter of type boolean, the = value part can be
 190    omitted, which is equivalent to specifying TRUE.
 191
 192 Examples
 193
 194    Change the publication subscribed by a subscription to insert_only:
 195 ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only;
 196
 197    Disable (stop) the subscription:
 198 ALTER SUBSCRIPTION mysub DISABLE;
 199
 200 Compatibility
 201
 202    ALTER SUBSCRIPTION is a PostgreSQL extension.
 203
 204 See Also
 205
 206    CREATE SUBSCRIPTION, DROP SUBSCRIPTION, CREATE PUBLICATION, ALTER
 207    PUBLICATION