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

   1 '\" t
   2 .\"     Title: ALTER PUBLICATION
   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 PUBLICATION" "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_PUBLICATION \- change the definition of a publication
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER PUBLICATION \fIname\fR ADD \fIpublication_object\fR [, \&.\&.\&.]
  36 ALTER PUBLICATION \fIname\fR SET \fIpublication_object\fR [, \&.\&.\&.]
  37 ALTER PUBLICATION \fIname\fR DROP \fIpublication_object\fR [, \&.\&.\&.]
  38 ALTER PUBLICATION \fIname\fR SET ( \fIpublication_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
  39 ALTER PUBLICATION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  40 ALTER PUBLICATION \fIname\fR RENAME TO \fInew_name\fR
  41
  42 where \fIpublication_object\fR is one of:
  43
  44     TABLE [ ONLY ] \fItable_name\fR [ * ] [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] [ WHERE ( \fIexpression\fR ) ] [, \&.\&.\&. ]
  45     TABLES IN SCHEMA { \fIschema_name\fR | CURRENT_SCHEMA } [, \&.\&.\&. ]
  46 .fi
  47 .SH "DESCRIPTION"
  48 .PP
  49 The command
  50 \fBALTER PUBLICATION\fR
  51 can change the attributes of a publication\&.
  52 .PP
  53 The first three variants change which tables/schemas are part of the publication\&. The
  54 SET
  55 clause will replace the list of tables/schemas in the publication with the specified list; the existing tables/schemas that were present in the publication will be removed\&. The
  56 ADD
  57 and
  58 DROP
  59 clauses will add and remove one or more tables/schemas from the publication\&. Note that adding tables/schemas to a publication that is already subscribed to will require an
  60 ALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION
  61 action on the subscribing side in order to become effective\&. Note also that
  62 DROP TABLES IN SCHEMA
  63 will not drop any schema tables that were specified using
  64 FOR TABLE/
  65 ADD TABLE, and the combination of
  66 DROP
  67 with a
  68 WHERE
  69 clause is not allowed\&.
  70 .PP
  71 The fourth variant of this command listed in the synopsis can change all of the publication properties specified in
  72 CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7))\&. Properties not mentioned in the command retain their previous settings\&.
  73 .PP
  74 The remaining variants change the owner and the name of the publication\&.
  75 .PP
  76 You must own the publication to use
  77 \fBALTER PUBLICATION\fR\&. Adding a table to a publication additionally requires owning that table\&. The
  78 ADD TABLES IN SCHEMA
  79 and
  80 SET TABLES IN SCHEMA
  81 to a publication requires the invoking user to be a superuser\&. To alter the owner, you must be able to
  82 SET ROLE
  83 to the new owning role, and that role must have
  84 CREATE
  85 privilege on the database\&. Also, the new owner of a
  86 FOR ALL TABLES
  87 or
  88 FOR TABLES IN SCHEMA
  89 publication must be a superuser\&. However, a superuser can change the ownership of a publication regardless of these restrictions\&.
  90 .PP
  91 Adding/Setting any schema when the publication also publishes a table with a column list, and vice versa is not supported\&.
  92 .SH "PARAMETERS"
  93 .PP
  94 \fIname\fR
  95 .RS 4
  96 The name of an existing publication whose definition is to be altered\&.
  97 .RE
  98 .PP
  99 \fItable_name\fR
 100 .RS 4
 101 Name of an existing table\&. If
 102 ONLY
 103 is specified before the table name, only that table is affected\&. If
 104 ONLY
 105 is not specified, the table and all its descendant tables (if any) are affected\&. Optionally,
 106 *
 107 can be specified after the table name to explicitly indicate that descendant tables are included\&.
 108 .sp
 109 Optionally, a column list can be specified\&. See
 110 CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7))
 111 for details\&. Note that a subscription having several publications in which the same table has been published with different column lists is not supported\&. See
 112 Warning: Combining Column Lists from Multiple Publications
 113 for details of potential problems when altering column lists\&.
 114 .sp
 115 If the optional
 116 WHERE
 117 clause is specified, rows for which the
 118 \fIexpression\fR
 119 evaluates to false or null will not be published\&. Note that parentheses are required around the expression\&. The
 120 \fIexpression\fR
 121 is evaluated with the role used for the replication connection\&.
 122 .RE
 123 .PP
 124 \fIschema_name\fR
 125 .RS 4
 126 Name of an existing schema\&.
 127 .RE
 128 .PP
 129 SET ( \fIpublication_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] )
 130 .RS 4
 131 This clause alters publication parameters originally set by
 132 CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7))\&. See there for more information\&.
 133 .if n \{\
 134 .sp
 135 .\}
 136 .RS 4
 137 .it 1 an-trap
 138 .nr an-no-space-flag 1
 139 .nr an-break-flag 1
 140 .br
 141 .ps +1
 142 \fBCaution\fR
 143 .ps -1
 144 .br
 145 Altering the
 146 publish_via_partition_root
 147 parameter can lead to data loss or duplication at the subscriber because it changes the identity and schema of the published tables\&. Note this happens only when a partition root table is specified as the replication target\&.
 148 .sp
 149 This problem can be avoided by refraining from modifying partition leaf tables after the
 150 \fBALTER PUBLICATION \&.\&.\&. SET\fR
 151 until the
 152 \fBALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION\fR
 153 is executed and by only refreshing using the
 154 copy_data = off
 155 option\&.
 156 .sp .5v
 157 .RE
 158 .RE
 159 .PP
 160 \fInew_owner\fR
 161 .RS 4
 162 The user name of the new owner of the publication\&.
 163 .RE
 164 .PP
 165 \fInew_name\fR
 166 .RS 4
 167 The new name for the publication\&.
 168 .RE
 169 .SH "EXAMPLES"
 170 .PP
 171 Change the publication to publish only deletes and updates:
 172 .sp
 173 .if n \{\
 174 .RS 4
 175 .\}
 176 .nf
 177 ALTER PUBLICATION noinsert SET (publish = \*(Aqupdate, delete\*(Aq);
 178 .fi
 179 .if n \{\
 180 .RE
 181 .\}
 182 .PP
 183 Add some tables to the publication:
 184 .sp
 185 .if n \{\
 186 .RS 4
 187 .\}
 188 .nf
 189 ALTER PUBLICATION mypublication ADD TABLE users (user_id, firstname), departments;
 190 .fi
 191 .if n \{\
 192 .RE
 193 .\}
 194 .PP
 195 Change the set of columns published for a table:
 196 .sp
 197 .if n \{\
 198 .RS 4
 199 .\}
 200 .nf
 201 ALTER PUBLICATION mypublication SET TABLE users (user_id, firstname, lastname), TABLE departments;
 202 .fi
 203 .if n \{\
 204 .RE
 205 .\}
 206 .PP
 207 Add schemas
 208 marketing
 209 and
 210 sales
 211 to the publication
 212 sales_publication:
 213 .sp
 214 .if n \{\
 215 .RS 4
 216 .\}
 217 .nf
 218 ALTER PUBLICATION sales_publication ADD TABLES IN SCHEMA marketing, sales;
 219 .fi
 220 .if n \{\
 221 .RE
 222 .\}
 223 .PP
 224 Add tables
 225 users,
 226 departments
 227 and schema
 228 production
 229 to the publication
 230 production_publication:
 231 .sp
 232 .if n \{\
 233 .RS 4
 234 .\}
 235 .nf
 236 ALTER PUBLICATION production_publication ADD TABLE users, departments, TABLES IN SCHEMA production;
 237 .fi
 238 .if n \{\
 239 .RE
 240 .\}
 241 .SH "COMPATIBILITY"
 242 .PP
 243 \fBALTER PUBLICATION\fR
 244 is a
 245 PostgreSQL
 246 extension\&.
 247 .SH "SEE ALSO"
 248 CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)), DROP PUBLICATION (\fBDROP_PUBLICATION\fR(7)), CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)), ALTER SUBSCRIPTION (\fBALTER_SUBSCRIPTION\fR(7))