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

   1
   2 ALTER FOREIGN TABLE
   3
   4    ALTER FOREIGN TABLE — change the definition of a foreign table
   5
   6 Synopsis
   7
   8 ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] name [ * ]
   9     action [, ... ]
  10 ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] name [ * ]
  11     RENAME [ COLUMN ] column_name TO new_column_name
  12 ALTER FOREIGN TABLE [ IF EXISTS ] name
  13     RENAME TO new_name
  14 ALTER FOREIGN TABLE [ IF EXISTS ] name
  15     SET SCHEMA new_schema
  16
  17 where action is one of:
  18
  19     ADD [ COLUMN ] column_name data_type [ COLLATE collation ] [ column_constrai
  20 nt [ ... ] ]
  21     DROP [ COLUMN ] [ IF EXISTS ] column_name [ RESTRICT | CASCADE ]
  22     ALTER [ COLUMN ] column_name [ SET DATA ] TYPE data_type [ COLLATE collation
  23  ]
  24     ALTER [ COLUMN ] column_name SET DEFAULT expression
  25     ALTER [ COLUMN ] column_name DROP DEFAULT
  26     ALTER [ COLUMN ] column_name { SET | DROP } NOT NULL
  27     ALTER [ COLUMN ] column_name SET STATISTICS integer
  28     ALTER [ COLUMN ] column_name SET ( attribute_option = value [, ... ] )
  29     ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] )
  30     ALTER [ COLUMN ] column_name SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAI
  31 N | DEFAULT }
  32     ALTER [ COLUMN ] column_name OPTIONS ( [ ADD | SET | DROP ] option ['value']
  33  [, ... ])
  34     ADD table_constraint [ NOT VALID ]
  35     VALIDATE CONSTRAINT constraint_name
  36     DROP CONSTRAINT [ IF EXISTS ]  constraint_name [ RESTRICT | CASCADE ]
  37     DISABLE TRIGGER [ trigger_name | ALL | USER ]
  38     ENABLE TRIGGER [ trigger_name | ALL | USER ]
  39     ENABLE REPLICA TRIGGER trigger_name
  40     ENABLE ALWAYS TRIGGER trigger_name
  41     SET WITHOUT OIDS
  42     INHERIT parent_table
  43     NO INHERIT parent_table
  44     OWNER TO { new_owner | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  45     OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])
  46
  47 Description
  48
  49    ALTER FOREIGN TABLE changes the definition of an existing foreign
  50    table. There are several subforms:
  51
  52    ADD COLUMN
  53           This form adds a new column to the foreign table, using the same
  54           syntax as CREATE FOREIGN TABLE. Unlike the case when adding a
  55           column to a regular table, nothing happens to the underlying
  56           storage: this action simply declares that some new column is now
  57           accessible through the foreign table.
  58
  59    DROP COLUMN [ IF EXISTS ]
  60           This form drops a column from a foreign table. You will need to
  61           say CASCADE if anything outside the table depends on the column;
  62           for example, views. If IF EXISTS is specified and the column
  63           does not exist, no error is thrown. In this case a notice is
  64           issued instead.
  65
  66    SET DATA TYPE
  67           This form changes the type of a column of a foreign table.
  68           Again, this has no effect on any underlying storage: this action
  69           simply changes the type that PostgreSQL believes the column to
  70           have.
  71
  72    SET/DROP DEFAULT
  73           These forms set or remove the default value for a column.
  74           Default values only apply in subsequent INSERT or UPDATE
  75           commands; they do not cause rows already in the table to change.
  76
  77    SET/DROP NOT NULL
  78           Mark a column as allowing, or not allowing, null values.
  79
  80    SET STATISTICS
  81           This form sets the per-column statistics-gathering target for
  82           subsequent ANALYZE operations. See the similar form of ALTER
  83           TABLE for more details.
  84
  85    SET ( attribute_option = value [, ... ] )
  86           RESET ( attribute_option [, ... ] )
  87           This form sets or resets per-attribute options. See the similar
  88           form of ALTER TABLE for more details.
  89
  90    SET STORAGE
  91           This form sets the storage mode for a column. See the similar
  92           form of ALTER TABLE for more details. Note that the storage mode
  93           has no effect unless the table's foreign-data wrapper chooses to
  94           pay attention to it.
  95
  96    ADD table_constraint [ NOT VALID ]
  97           This form adds a new constraint to a foreign table, using the
  98           same syntax as CREATE FOREIGN TABLE. Currently only CHECK and
  99           NOT NULL constraints are supported.
 100
 101           Unlike the case when adding a constraint to a regular table,
 102           nothing is done to verify the constraint is correct; rather,
 103           this action simply declares that some new condition should be
 104           assumed to hold for all rows in the foreign table. (See the
 105           discussion in CREATE FOREIGN TABLE.) If the constraint is marked
 106           NOT VALID (allowed only for the CHECK case), then it isn't
 107           assumed to hold, but is only recorded for possible future use.
 108
 109    VALIDATE CONSTRAINT
 110           This form marks as valid a constraint that was previously marked
 111           as NOT VALID. No action is taken to verify the constraint, but
 112           future queries will assume that it holds.
 113
 114    DROP CONSTRAINT [ IF EXISTS ]
 115           This form drops the specified constraint on a foreign table. If
 116           IF EXISTS is specified and the constraint does not exist, no
 117           error is thrown. In this case a notice is issued instead.
 118
 119    DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER
 120           These forms configure the firing of trigger(s) belonging to the
 121           foreign table. See the similar form of ALTER TABLE for more
 122           details.
 123
 124    SET WITHOUT OIDS
 125           Backward compatibility syntax for removing the oid system
 126           column. As oid system columns cannot be added anymore, this
 127           never has an effect.
 128
 129    INHERIT parent_table
 130           This form adds the target foreign table as a new child of the
 131           specified parent table. See the similar form of ALTER TABLE for
 132           more details.
 133
 134    NO INHERIT parent_table
 135           This form removes the target foreign table from the list of
 136           children of the specified parent table.
 137
 138    OWNER
 139           This form changes the owner of the foreign table to the
 140           specified user.
 141
 142    OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] )
 143           Change options for the foreign table or one of its columns. ADD,
 144           SET, and DROP specify the action to be performed. ADD is assumed
 145           if no operation is explicitly specified. Duplicate option names
 146           are not allowed (although it's OK for a table option and a
 147           column option to have the same name). Option names and values
 148           are also validated using the foreign data wrapper library.
 149
 150    RENAME
 151           The RENAME forms change the name of a foreign table or the name
 152           of an individual column in a foreign table.
 153
 154    SET SCHEMA
 155           This form moves the foreign table into another schema.
 156
 157    All the actions except RENAME and SET SCHEMA can be combined into a
 158    list of multiple alterations to apply in parallel. For example, it is
 159    possible to add several columns and/or alter the type of several
 160    columns in a single command.
 161
 162    If the command is written as ALTER FOREIGN TABLE IF EXISTS ... and the
 163    foreign table does not exist, no error is thrown. A notice is issued in
 164    this case.
 165
 166    You must own the table to use ALTER FOREIGN TABLE. To change the schema
 167    of a foreign table, you must also have CREATE privilege on the new
 168    schema. To alter the owner, you must be able to SET ROLE to the new
 169    owning role, and that role must have CREATE privilege on the table's
 170    schema. (These restrictions enforce that altering the owner doesn't do
 171    anything you couldn't do by dropping and recreating the table. However,
 172    a superuser can alter ownership of any table anyway.) To add a column
 173    or alter a column type, you must also have USAGE privilege on the data
 174    type.
 175
 176 Parameters
 177
 178    name
 179           The name (possibly schema-qualified) of an existing foreign
 180           table to alter. If ONLY is specified before the table name, only
 181           that table is altered. If ONLY is not specified, the table and
 182           all its descendant tables (if any) are altered. Optionally, *
 183           can be specified after the table name to explicitly indicate
 184           that descendant tables are included.
 185
 186    column_name
 187           Name of a new or existing column.
 188
 189    new_column_name
 190           New name for an existing column.
 191
 192    new_name
 193           New name for the table.
 194
 195    data_type
 196           Data type of the new column, or new data type for an existing
 197           column.
 198
 199    table_constraint
 200           New table constraint for the foreign table.
 201
 202    constraint_name
 203           Name of an existing constraint to drop.
 204
 205    CASCADE
 206           Automatically drop objects that depend on the dropped column or
 207           constraint (for example, views referencing the column), and in
 208           turn all objects that depend on those objects (see
 209           Section 5.15).
 210
 211    RESTRICT
 212           Refuse to drop the column or constraint if there are any
 213           dependent objects. This is the default behavior.
 214
 215    trigger_name
 216           Name of a single trigger to disable or enable.
 217
 218    ALL
 219           Disable or enable all triggers belonging to the foreign table.
 220           (This requires superuser privilege if any of the triggers are
 221           internally generated triggers. The core system does not add such
 222           triggers to foreign tables, but add-on code could do so.)
 223
 224    USER
 225           Disable or enable all triggers belonging to the foreign table
 226           except for internally generated triggers.
 227
 228    parent_table
 229           A parent table to associate or de-associate with this foreign
 230           table.
 231
 232    new_owner
 233           The user name of the new owner of the table.
 234
 235    new_schema
 236           The name of the schema to which the table will be moved.
 237
 238 Notes
 239
 240    The key word COLUMN is noise and can be omitted.
 241
 242    Consistency with the foreign server is not checked when a column is
 243    added or removed with ADD COLUMN or DROP COLUMN, a NOT NULL or CHECK
 244    constraint is added, or a column type is changed with SET DATA TYPE. It
 245    is the user's responsibility to ensure that the table definition
 246    matches the remote side.
 247
 248    Refer to CREATE FOREIGN TABLE for a further description of valid
 249    parameters.
 250
 251 Examples
 252
 253    To mark a column as not-null:
 254 ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
 255
 256    To change options of a foreign table:
 257 ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'v
 258 alue2', DROP opt3);
 259
 260 Compatibility
 261
 262    The forms ADD, DROP, and SET DATA TYPE conform with the SQL standard.
 263    The other forms are PostgreSQL extensions of the SQL standard. Also,
 264    the ability to specify more than one manipulation in a single ALTER
 265    FOREIGN TABLE command is an extension.
 266
 267    ALTER FOREIGN TABLE DROP COLUMN can be used to drop the only column of
 268    a foreign table, leaving a zero-column table. This is an extension of
 269    SQL, which disallows zero-column foreign tables.
 270
 271 See Also
 272
 273    CREATE FOREIGN TABLE, DROP FOREIGN TABLE