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

   1 '\" t
   2 .\"     Title: ALTER FOREIGN TABLE
   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 FOREIGN TABLE" "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_FOREIGN_TABLE \- change the definition of a foreign table
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ]
  36     \fIaction\fR [, \&.\&.\&. ]
  37 ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ]
  38     RENAME [ COLUMN ] \fIcolumn_name\fR TO \fInew_column_name\fR
  39 ALTER FOREIGN TABLE [ IF EXISTS ] \fIname\fR
  40     RENAME TO \fInew_name\fR
  41 ALTER FOREIGN TABLE [ IF EXISTS ] \fIname\fR
  42     SET SCHEMA \fInew_schema\fR
  43
  44 where \fIaction\fR is one of:
  45
  46     ADD [ COLUMN ] \fIcolumn_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ]
  47     DROP [ COLUMN ] [ IF EXISTS ] \fIcolumn_name\fR [ RESTRICT | CASCADE ]
  48     ALTER [ COLUMN ] \fIcolumn_name\fR [ SET DATA ] TYPE \fIdata_type\fR [ COLLATE \fIcollation\fR ]
  49     ALTER [ COLUMN ] \fIcolumn_name\fR SET DEFAULT \fIexpression\fR
  50     ALTER [ COLUMN ] \fIcolumn_name\fR DROP DEFAULT
  51     ALTER [ COLUMN ] \fIcolumn_name\fR { SET | DROP } NOT NULL
  52     ALTER [ COLUMN ] \fIcolumn_name\fR SET STATISTICS \fIinteger\fR
  53     ALTER [ COLUMN ] \fIcolumn_name\fR SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] )
  54     ALTER [ COLUMN ] \fIcolumn_name\fR RESET ( \fIattribute_option\fR [, \&.\&.\&. ] )
  55     ALTER [ COLUMN ] \fIcolumn_name\fR SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT }
  56     ALTER [ COLUMN ] \fIcolumn_name\fR OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ])
  57     ADD \fItable_constraint\fR [ NOT VALID ]
  58     VALIDATE CONSTRAINT \fIconstraint_name\fR
  59     DROP CONSTRAINT [ IF EXISTS ]  \fIconstraint_name\fR [ RESTRICT | CASCADE ]
  60     DISABLE TRIGGER [ \fItrigger_name\fR | ALL | USER ]
  61     ENABLE TRIGGER [ \fItrigger_name\fR | ALL | USER ]
  62     ENABLE REPLICA TRIGGER \fItrigger_name\fR
  63     ENABLE ALWAYS TRIGGER \fItrigger_name\fR
  64     SET WITHOUT OIDS
  65     INHERIT \fIparent_table\fR
  66     NO INHERIT \fIparent_table\fR
  67     OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  68     OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ])
  69 .fi
  70 .SH "DESCRIPTION"
  71 .PP
  72 \fBALTER FOREIGN TABLE\fR
  73 changes the definition of an existing foreign table\&. There are several subforms:
  74 .PP
  75 ADD COLUMN
  76 .RS 4
  77 This form adds a new column to the foreign table, using the same syntax as
  78 \fBCREATE FOREIGN TABLE\fR\&. Unlike the case when adding a column to a regular table, nothing happens to the underlying storage: this action simply declares that some new column is now accessible through the foreign table\&.
  79 .RE
  80 .PP
  81 DROP COLUMN [ IF EXISTS ]
  82 .RS 4
  83 This form drops a column from a foreign table\&. You will need to say
  84 CASCADE
  85 if anything outside the table depends on the column; for example, views\&. If
  86 IF EXISTS
  87 is specified and the column does not exist, no error is thrown\&. In this case a notice is issued instead\&.
  88 .RE
  89 .PP
  90 SET DATA TYPE
  91 .RS 4
  92 This form changes the type of a column of a foreign table\&. Again, this has no effect on any underlying storage: this action simply changes the type that
  93 PostgreSQL
  94 believes the column to have\&.
  95 .RE
  96 .PP
  97 SET/DROP DEFAULT
  98 .RS 4
  99 These forms set or remove the default value for a column\&. Default values only apply in subsequent
 100 \fBINSERT\fR
 101 or
 102 \fBUPDATE\fR
 103 commands; they do not cause rows already in the table to change\&.
 104 .RE
 105 .PP
 106 SET/DROP NOT NULL
 107 .RS 4
 108 Mark a column as allowing, or not allowing, null values\&.
 109 .RE
 110 .PP
 111 SET STATISTICS
 112 .RS 4
 113 This form sets the per\-column statistics\-gathering target for subsequent
 114 \fBANALYZE\fR
 115 operations\&. See the similar form of
 116 \fBALTER TABLE\fR
 117 for more details\&.
 118 .RE
 119 .PP
 120 SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] )
 121 .br
 122 RESET ( \fIattribute_option\fR [, \&.\&.\&. ] )
 123 .RS 4
 124 This form sets or resets per\-attribute options\&. See the similar form of
 125 \fBALTER TABLE\fR
 126 for more details\&.
 127 .RE
 128 .PP
 129 SET STORAGE
 130 .RS 4
 131 This form sets the storage mode for a column\&. See the similar form of
 132 \fBALTER TABLE\fR
 133 for more details\&. Note that the storage mode has no effect unless the table\*(Aqs foreign\-data wrapper chooses to pay attention to it\&.
 134 .RE
 135 .PP
 136 ADD \fItable_constraint\fR [ NOT VALID ]
 137 .RS 4
 138 This form adds a new constraint to a foreign table, using the same syntax as
 139 \fBCREATE FOREIGN TABLE\fR\&. Currently only
 140 CHECK
 141 and
 142 NOT NULL
 143 constraints are supported\&.
 144 .sp
 145 Unlike the case when adding a constraint to a regular table, nothing is done to verify the constraint is correct; rather, this action simply declares that some new condition should be assumed to hold for all rows in the foreign table\&. (See the discussion in
 146 \fBCREATE FOREIGN TABLE\fR\&.) If the constraint is marked
 147 NOT VALID
 148 (allowed only for the
 149 CHECK
 150 case), then it isn\*(Aqt assumed to hold, but is only recorded for possible future use\&.
 151 .RE
 152 .PP
 153 VALIDATE CONSTRAINT
 154 .RS 4
 155 This form marks as valid a constraint that was previously marked as
 156 NOT VALID\&. No action is taken to verify the constraint, but future queries will assume that it holds\&.
 157 .RE
 158 .PP
 159 DROP CONSTRAINT [ IF EXISTS ]
 160 .RS 4
 161 This form drops the specified constraint on a foreign table\&. If
 162 IF EXISTS
 163 is specified and the constraint does not exist, no error is thrown\&. In this case a notice is issued instead\&.
 164 .RE
 165 .PP
 166 DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER
 167 .RS 4
 168 These forms configure the firing of trigger(s) belonging to the foreign table\&. See the similar form of
 169 \fBALTER TABLE\fR
 170 for more details\&.
 171 .RE
 172 .PP
 173 SET WITHOUT OIDS
 174 .RS 4
 175 Backward compatibility syntax for removing the
 176 oid
 177 system column\&. As
 178 oid
 179 system columns cannot be added anymore, this never has an effect\&.
 180 .RE
 181 .PP
 182 INHERIT \fIparent_table\fR
 183 .RS 4
 184 This form adds the target foreign table as a new child of the specified parent table\&. See the similar form of
 185 \fBALTER TABLE\fR
 186 for more details\&.
 187 .RE
 188 .PP
 189 NO INHERIT \fIparent_table\fR
 190 .RS 4
 191 This form removes the target foreign table from the list of children of the specified parent table\&.
 192 .RE
 193 .PP
 194 OWNER
 195 .RS 4
 196 This form changes the owner of the foreign table to the specified user\&.
 197 .RE
 198 .PP
 199 OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] )
 200 .RS 4
 201 Change options for the foreign table or one of its columns\&.
 202 ADD,
 203 SET, and
 204 DROP
 205 specify the action to be performed\&.
 206 ADD
 207 is assumed if no operation is explicitly specified\&. Duplicate option names are not allowed (although it\*(Aqs OK for a table option and a column option to have the same name)\&. Option names and values are also validated using the foreign data wrapper library\&.
 208 .RE
 209 .PP
 210 RENAME
 211 .RS 4
 212 The
 213 RENAME
 214 forms change the name of a foreign table or the name of an individual column in a foreign table\&.
 215 .RE
 216 .PP
 217 SET SCHEMA
 218 .RS 4
 219 This form moves the foreign table into another schema\&.
 220 .RE
 221 .PP
 222 All the actions except
 223 RENAME
 224 and
 225 SET SCHEMA
 226 can be combined into a list of multiple alterations to apply in parallel\&. For example, it is possible to add several columns and/or alter the type of several columns in a single command\&.
 227 .PP
 228 If the command is written as
 229 ALTER FOREIGN TABLE IF EXISTS \&.\&.\&.
 230 and the foreign table does not exist, no error is thrown\&. A notice is issued in this case\&.
 231 .PP
 232 You must own the table to use
 233 \fBALTER FOREIGN TABLE\fR\&. To change the schema of a foreign table, you must also have
 234 CREATE
 235 privilege on the new schema\&. To alter the owner, you must be able to
 236 SET ROLE
 237 to the new owning role, and that role must have
 238 CREATE
 239 privilege on the table\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the table\&. However, a superuser can alter ownership of any table anyway\&.) To add a column or alter a column type, you must also have
 240 USAGE
 241 privilege on the data type\&.
 242 .SH "PARAMETERS"
 243 .PP
 244 \fIname\fR
 245 .RS 4
 246 The name (possibly schema\-qualified) of an existing foreign table to alter\&. If
 247 ONLY
 248 is specified before the table name, only that table is altered\&. If
 249 ONLY
 250 is not specified, the table and all its descendant tables (if any) are altered\&. Optionally,
 251 *
 252 can be specified after the table name to explicitly indicate that descendant tables are included\&.
 253 .RE
 254 .PP
 255 \fIcolumn_name\fR
 256 .RS 4
 257 Name of a new or existing column\&.
 258 .RE
 259 .PP
 260 \fInew_column_name\fR
 261 .RS 4
 262 New name for an existing column\&.
 263 .RE
 264 .PP
 265 \fInew_name\fR
 266 .RS 4
 267 New name for the table\&.
 268 .RE
 269 .PP
 270 \fIdata_type\fR
 271 .RS 4
 272 Data type of the new column, or new data type for an existing column\&.
 273 .RE
 274 .PP
 275 \fItable_constraint\fR
 276 .RS 4
 277 New table constraint for the foreign table\&.
 278 .RE
 279 .PP
 280 \fIconstraint_name\fR
 281 .RS 4
 282 Name of an existing constraint to drop\&.
 283 .RE
 284 .PP
 285 CASCADE
 286 .RS 4
 287 Automatically drop objects that depend on the dropped column or constraint (for example, views referencing the column), and in turn all objects that depend on those objects (see
 288 Section\ \&5.15)\&.
 289 .RE
 290 .PP
 291 RESTRICT
 292 .RS 4
 293 Refuse to drop the column or constraint if there are any dependent objects\&. This is the default behavior\&.
 294 .RE
 295 .PP
 296 \fItrigger_name\fR
 297 .RS 4
 298 Name of a single trigger to disable or enable\&.
 299 .RE
 300 .PP
 301 ALL
 302 .RS 4
 303 Disable or enable all triggers belonging to the foreign table\&. (This requires superuser privilege if any of the triggers are internally generated triggers\&. The core system does not add such triggers to foreign tables, but add\-on code could do so\&.)
 304 .RE
 305 .PP
 306 USER
 307 .RS 4
 308 Disable or enable all triggers belonging to the foreign table except for internally generated triggers\&.
 309 .RE
 310 .PP
 311 \fIparent_table\fR
 312 .RS 4
 313 A parent table to associate or de\-associate with this foreign table\&.
 314 .RE
 315 .PP
 316 \fInew_owner\fR
 317 .RS 4
 318 The user name of the new owner of the table\&.
 319 .RE
 320 .PP
 321 \fInew_schema\fR
 322 .RS 4
 323 The name of the schema to which the table will be moved\&.
 324 .RE
 325 .SH "NOTES"
 326 .PP
 327 The key word
 328 COLUMN
 329 is noise and can be omitted\&.
 330 .PP
 331 Consistency with the foreign server is not checked when a column is added or removed with
 332 ADD COLUMN
 333 or
 334 DROP COLUMN, a
 335 NOT NULL
 336 or
 337 CHECK
 338 constraint is added, or a column type is changed with
 339 SET DATA TYPE\&. It is the user\*(Aqs responsibility to ensure that the table definition matches the remote side\&.
 340 .PP
 341 Refer to
 342 \fBCREATE FOREIGN TABLE\fR
 343 for a further description of valid parameters\&.
 344 .SH "EXAMPLES"
 345 .PP
 346 To mark a column as not\-null:
 347 .sp
 348 .if n \{\
 349 .RS 4
 350 .\}
 351 .nf
 352 ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
 353 .fi
 354 .if n \{\
 355 .RE
 356 .\}
 357 .PP
 358 To change options of a foreign table:
 359 .sp
 360 .if n \{\
 361 .RS 4
 362 .\}
 363 .nf
 364 ALTER FOREIGN TABLE myschema\&.distributors OPTIONS (ADD opt1 \*(Aqvalue\*(Aq, SET opt2 \*(Aqvalue2\*(Aq, DROP opt3);
 365 .fi
 366 .if n \{\
 367 .RE
 368 .\}
 369 .SH "COMPATIBILITY"
 370 .PP
 371 The forms
 372 ADD,
 373 DROP, and
 374 SET DATA TYPE
 375 conform with the SQL standard\&. The other forms are
 376 PostgreSQL
 377 extensions of the SQL standard\&. Also, the ability to specify more than one manipulation in a single
 378 \fBALTER FOREIGN TABLE\fR
 379 command is an extension\&.
 380 .PP
 381 \fBALTER FOREIGN TABLE DROP COLUMN\fR
 382 can be used to drop the only column of a foreign table, leaving a zero\-column table\&. This is an extension of SQL, which disallows zero\-column foreign tables\&.
 383 .SH "SEE ALSO"
 384 CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)), DROP FOREIGN TABLE (\fBDROP_FOREIGN_TABLE\fR(7))