begriffs open source - ai-pg/blob - full-docs/man7/ALTER_SUBSCRIPTION.7

   1 '\" t
   2 .\"     Title: ALTER SUBSCRIPTION
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "ALTER SUBSCRIPTION" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 ALTER_SUBSCRIPTION \- change the definition of a subscription
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER SUBSCRIPTION \fIname\fR CONNECTION \*(Aq\fIconninfo\fR\*(Aq
  36 ALTER SUBSCRIPTION \fIname\fR SET PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] [ WITH ( \fIpublication_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ]
  37 ALTER SUBSCRIPTION \fIname\fR ADD PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] [ WITH ( \fIpublication_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ]
  38 ALTER SUBSCRIPTION \fIname\fR DROP PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] [ WITH ( \fIpublication_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ]
  39 ALTER SUBSCRIPTION \fIname\fR REFRESH PUBLICATION [ WITH ( \fIrefresh_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ]
  40 ALTER SUBSCRIPTION \fIname\fR ENABLE
  41 ALTER SUBSCRIPTION \fIname\fR DISABLE
  42 ALTER SUBSCRIPTION \fIname\fR SET ( \fIsubscription_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
  43 ALTER SUBSCRIPTION \fIname\fR SKIP ( \fIskip_option\fR = \fIvalue\fR )
  44 ALTER SUBSCRIPTION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  45 ALTER SUBSCRIPTION \fIname\fR RENAME TO \fInew_name\fR
  46 .fi
  47 .SH "DESCRIPTION"
  48 .PP
  49 \fBALTER SUBSCRIPTION\fR
  50 can change most of the subscription properties that can be specified in
  51 CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))\&.
  52 .PP
  53 You must own the subscription to use
  54 \fBALTER SUBSCRIPTION\fR\&. To rename a subscription or alter the owner, you must have
  55 CREATE
  56 permission on the database\&. In addition, to alter the owner, you must be able to
  57 SET ROLE
  58 to the new owning role\&. If the subscription has
  59 password_required=false, only superusers can modify it\&.
  60 .PP
  61 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,
  62 PostgreSQL
  63 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
  64 DROP SUBSCRIPTION (\fBDROP_SUBSCRIPTION\fR(7))\&.
  65 .PP
  66 Commands
  67 \fBALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION\fR,
  68 \fBALTER SUBSCRIPTION \&.\&.\&. {SET|ADD|DROP} PUBLICATION \&.\&.\&.\fR
  69 with
  70 refresh
  71 option as
  72 true,
  73 \fBALTER SUBSCRIPTION \&.\&.\&. SET (failover = true|false)\fR
  74 and
  75 \fBALTER SUBSCRIPTION \&.\&.\&. SET (two_phase = false)\fR
  76 cannot be executed inside a transaction block\&.
  77 .PP
  78 Commands
  79 \fBALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION\fR
  80 and
  81 \fBALTER SUBSCRIPTION \&.\&.\&. {SET|ADD|DROP} PUBLICATION \&.\&.\&.\fR
  82 with
  83 refresh
  84 option as
  85 true
  86 also cannot be executed when the subscription has
  87 two_phase
  88 commit enabled, unless
  89 copy_data
  90 is
  91 false\&. See column
  92 subtwophasestate
  93 of
  94 pg_subscription
  95 to know the actual two\-phase state\&.
  96 .SH "PARAMETERS"
  97 .PP
  98 \fIname\fR
  99 .RS 4
 100 The name of a subscription whose properties are to be altered\&.
 101 .RE
 102 .PP
 103 CONNECTION \*(Aq\fIconninfo\fR\*(Aq
 104 .RS 4
 105 This clause replaces the connection string originally set by
 106 CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))\&. See there for more information\&.
 107 .RE
 108 .PP
 109 SET PUBLICATION \fIpublication_name\fR
 110 .br
 111 ADD PUBLICATION \fIpublication_name\fR
 112 .br
 113 DROP PUBLICATION \fIpublication_name\fR
 114 .RS 4
 115 These forms change the list of subscribed publications\&.
 116 SET
 117 replaces the entire list of publications with a new list,
 118 ADD
 119 adds additional publications to the list of publications, and
 120 DROP
 121 removes the publications from the list of publications\&. We allow non\-existent publications to be specified in
 122 ADD
 123 and
 124 SET
 125 variants so that users can add those later\&. See
 126 CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))
 127 for more information\&. By default, this command will also act like
 128 REFRESH PUBLICATION\&.
 129 .sp
 130 \fIpublication_option\fR
 131 specifies additional options for this operation\&. The supported options are:
 132 .PP
 133 refresh (boolean)
 134 .RS 4
 135 When false, the command will not try to refresh table information\&.
 136 REFRESH PUBLICATION
 137 should then be executed separately\&. The default is
 138 true\&.
 139 .RE
 140 .sp
 141 Additionally, the options described under
 142 REFRESH PUBLICATION
 143 may be specified, to control the implicit refresh operation\&.
 144 .RE
 145 .PP
 146 REFRESH PUBLICATION
 147 .RS 4
 148 Fetch missing table information from publisher\&. This will start replication of tables that were added to the subscribed\-to publications since
 149 \fBCREATE SUBSCRIPTION\fR
 150 or the last invocation of
 151 \fBREFRESH PUBLICATION\fR\&.
 152 .sp
 153 \fIrefresh_option\fR
 154 specifies additional options for the refresh operation\&. The supported options are:
 155 .PP
 156 copy_data (boolean)
 157 .RS 4
 158 Specifies whether to copy pre\-existing data in the publications that are being subscribed to when the replication starts\&. The default is
 159 true\&.
 160 .sp
 161 Previously subscribed tables are not copied, even if a table\*(Aqs row filter
 162 WHERE
 163 clause has since been modified\&.
 164 .sp
 165 See
 166 Notes
 167 for details of how
 168 copy_data = true
 169 can interact with the
 170 origin
 171 parameter\&.
 172 .sp
 173 See the
 174 binary
 175 parameter of
 176 \fBCREATE SUBSCRIPTION\fR
 177 for details about copying pre\-existing data in binary format\&.
 178 .RE
 179 .RE
 180 .PP
 181 ENABLE
 182 .RS 4
 183 Enables a previously disabled subscription, starting the logical replication worker at the end of the transaction\&.
 184 .RE
 185 .PP
 186 DISABLE
 187 .RS 4
 188 Disables a running subscription, stopping the logical replication worker at the end of the transaction\&.
 189 .RE
 190 .PP
 191 SET ( \fIsubscription_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
 192 .RS 4
 193 This clause alters parameters originally set by
 194 CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))\&. See there for more information\&. The parameters that can be altered are
 195 slot_name,
 196 synchronous_commit,
 197 binary,
 198 streaming,
 199 disable_on_error,
 200 password_required,
 201 run_as_owner,
 202 origin,
 203 failover, and
 204 two_phase\&. Only a superuser can set
 205 password_required = false\&.
 206 .sp
 207 When altering the
 208 slot_name, the
 209 failover
 210 and
 211 two_phase
 212 property values of the named slot may differ from the counterpart
 213 failover
 214 and
 215 two_phase
 216 parameters specified in the subscription\&. When creating the slot, ensure the slot properties
 217 failover
 218 and
 219 two_phase
 220 match their counterpart parameters of the subscription\&. Otherwise, the slot on the publisher may behave differently from what these subscription options say: for example, the slot on the publisher could either be synced to the standbys even when the subscription\*(Aqs
 221 failover
 222 option is disabled or could be disabled for sync even when the subscription\*(Aqs
 223 failover
 224 option is enabled\&.
 225 .sp
 226 The
 227 failover
 228 and
 229 two_phase
 230 parameters can only be altered when the subscription is disabled\&.
 231 .sp
 232 When altering
 233 two_phase
 234 from
 235 true
 236 to
 237 false, the backend process reports an error if any prepared transactions done by the logical replication worker (from when
 238 two_phase
 239 parameter was still
 240 true) are found\&. You can resolve prepared transactions on the publisher node, or manually roll back them on the subscriber, and then try again\&. The transactions prepared by logical replication worker corresponding to a particular subscription have the following pattern:
 241 \(lqpg_gid_%u_%u\(rq
 242 (parameters: subscription
 243 \fIoid\fR, remote transaction id
 244 \fIxid\fR)\&. To resolve such transactions manually, you need to roll back all the prepared transactions with corresponding subscription IDs in their names\&. Applications can check
 245 pg_prepared_xacts
 246 to find the required prepared transactions\&. After the
 247 two_phase
 248 option is changed from
 249 true
 250 to
 251 false, the publisher will replicate the transactions again when they are committed\&.
 252 .RE
 253 .PP
 254 SKIP ( \fIskip_option\fR = \fIvalue\fR )
 255 .RS 4
 256 Skips applying all changes of the remote transaction\&. If incoming data violates any constraints, logical replication will stop until it is resolved\&. By using the
 257 \fBALTER SUBSCRIPTION \&.\&.\&. SKIP\fR
 258 command, the logical replication worker skips all data modification changes within the transaction\&. This option has no effect on the transactions that are already prepared by enabling
 259 two_phase
 260 on the subscriber\&. After the logical replication worker successfully skips the transaction or finishes a transaction, the LSN (stored in
 261 pg_subscription\&.subskiplsn) is cleared\&. See
 262 Section\ \&29.7
 263 for the details of logical replication conflicts\&.
 264 .sp
 265 \fIskip_option\fR
 266 specifies options for this operation\&. The supported option is:
 267 .PP
 268 lsn (pg_lsn)
 269 .RS 4
 270 Specifies the finish LSN of the remote transaction whose changes are to be skipped by the logical replication worker\&. The finish LSN is the LSN at which the transaction is either committed or prepared\&. Skipping individual subtransactions is not supported\&. Setting
 271 NONE
 272 resets the LSN\&.
 273 .RE
 274 .RE
 275 .PP
 276 \fInew_owner\fR
 277 .RS 4
 278 The user name of the new owner of the subscription\&.
 279 .RE
 280 .PP
 281 \fInew_name\fR
 282 .RS 4
 283 The new name for the subscription\&.
 284 .RE
 285 .PP
 286 When specifying a parameter of type
 287 boolean, the
 288 =
 289 \fIvalue\fR
 290 part can be omitted, which is equivalent to specifying
 291 TRUE\&.
 292 .SH "EXAMPLES"
 293 .PP
 294 Change the publication subscribed by a subscription to
 295 insert_only:
 296 .sp
 297 .if n \{\
 298 .RS 4
 299 .\}
 300 .nf
 301 ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only;
 302 .fi
 303 .if n \{\
 304 .RE
 305 .\}
 306 .PP
 307 Disable (stop) the subscription:
 308 .sp
 309 .if n \{\
 310 .RS 4
 311 .\}
 312 .nf
 313 ALTER SUBSCRIPTION mysub DISABLE;
 314 .fi
 315 .if n \{\
 316 .RE
 317 .\}
 318 .SH "COMPATIBILITY"
 319 .PP
 320 \fBALTER SUBSCRIPTION\fR
 321 is a
 322 PostgreSQL
 323 extension\&.
 324 .SH "SEE ALSO"
 325 CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)), DROP SUBSCRIPTION (\fBDROP_SUBSCRIPTION\fR(7)), CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)), ALTER PUBLICATION (\fBALTER_PUBLICATION\fR(7))