begriffs open source - ai-pg/blob - full-docs/src/sgml/html/sql-alterforeigntable.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER FOREIGN TABLE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER" /><link rel="next" href="sql-alterfunction.html" title="ALTER FUNCTION" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER FOREIGN TABLE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alterfunction.html" title="ALTER FUNCTION">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERFOREIGNTABLE"><div class="titlepage"></div><a id="id-1.9.3.13.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER FOREIGN TABLE</span></h2><p>ALTER FOREIGN TABLE — change the definition of a foreign table</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
   4     <em class="replaceable"><code>action</code></em> [, ... ]
   5 ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] <em class="replaceable"><code>name</code></em> [ * ]
   6     RENAME [ COLUMN ] <em class="replaceable"><code>column_name</code></em> TO <em class="replaceable"><code>new_column_name</code></em>
   7 ALTER FOREIGN TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
   8     RENAME TO <em class="replaceable"><code>new_name</code></em>
   9 ALTER FOREIGN TABLE [ IF EXISTS ] <em class="replaceable"><code>name</code></em>
  10     SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
  11
  12 <span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
  13
  14     ADD [ COLUMN ] <em class="replaceable"><code>column_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ <em class="replaceable"><code>column_constraint</code></em> [ ... ] ]
  15     DROP [ COLUMN ] [ IF EXISTS ] <em class="replaceable"><code>column_name</code></em> [ RESTRICT | CASCADE ]
  16     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> [ SET DATA ] TYPE <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ]
  17     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET DEFAULT <em class="replaceable"><code>expression</code></em>
  18     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> DROP DEFAULT
  19     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> { SET | DROP } NOT NULL
  20     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STATISTICS <em class="replaceable"><code>integer</code></em>
  21     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
  22     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )
  23     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN | DEFAULT }
  24     ALTER [ COLUMN ] <em class="replaceable"><code>column_name</code></em> OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ])
  25     ADD <em class="replaceable"><code>table_constraint</code></em> [ NOT VALID ]
  26     VALIDATE CONSTRAINT <em class="replaceable"><code>constraint_name</code></em>
  27     DROP CONSTRAINT [ IF EXISTS ]  <em class="replaceable"><code>constraint_name</code></em> [ RESTRICT | CASCADE ]
  28     DISABLE TRIGGER [ <em class="replaceable"><code>trigger_name</code></em> | ALL | USER ]
  29     ENABLE TRIGGER [ <em class="replaceable"><code>trigger_name</code></em> | ALL | USER ]
  30     ENABLE REPLICA TRIGGER <em class="replaceable"><code>trigger_name</code></em>
  31     ENABLE ALWAYS TRIGGER <em class="replaceable"><code>trigger_name</code></em>
  32     SET WITHOUT OIDS
  33     INHERIT <em class="replaceable"><code>parent_table</code></em>
  34     NO INHERIT <em class="replaceable"><code>parent_table</code></em>
  35     OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
  36     OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ])
  37 </pre></div><div class="refsect1" id="id-1.9.3.13.5"><h2>Description</h2><p>
  38    <code class="command">ALTER FOREIGN TABLE</code> changes the definition of an
  39    existing foreign table.  There are several subforms:
  40
  41   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ADD COLUMN</code></span></dt><dd><p>
  42       This form adds a new column to the foreign table, using the same syntax as
  43       <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a>.
  44       Unlike the case when adding a column to a regular table, nothing happens
  45       to the underlying storage: this action simply declares that
  46       some new column is now accessible through the foreign table.
  47      </p></dd><dt><span class="term"><code class="literal">DROP COLUMN [ IF EXISTS ]</code></span></dt><dd><p>
  48       This form drops a column from a foreign table.
  49       You will need to say <code class="literal">CASCADE</code> if
  50       anything outside the table depends on the column; for example,
  51       views.
  52       If <code class="literal">IF EXISTS</code> is specified and the column
  53       does not exist, no error is thrown. In this case a notice
  54       is issued instead.
  55      </p></dd><dt><span class="term"><code class="literal">SET DATA TYPE</code></span></dt><dd><p>
  56       This form changes the type of a column of a foreign table.
  57       Again, this has no effect on any underlying storage: this action simply
  58       changes the type that <span class="productname">PostgreSQL</span> believes the column to
  59       have.
  60      </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP DEFAULT</code></span></dt><dd><p>
  61       These forms set or remove the default value for a column.
  62       Default values only apply in subsequent <code class="command">INSERT</code>
  63       or <code class="command">UPDATE</code> commands; they do not cause rows already in the
  64       table to change.
  65      </p></dd><dt><span class="term"><code class="literal">SET</code>/<code class="literal">DROP NOT NULL</code></span></dt><dd><p>
  66       Mark a column as allowing, or not allowing, null values.
  67      </p></dd><dt><span class="term"><code class="literal">SET STATISTICS</code></span></dt><dd><p>
  68       This form
  69       sets the per-column statistics-gathering target for subsequent
  70       <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a> operations.
  71       See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
  72       for more details.
  73      </p></dd><dt><span class="term"><code class="literal">SET ( <em class="replaceable"><code>attribute_option</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )</code><br /></span><span class="term"><code class="literal">RESET ( <em class="replaceable"><code>attribute_option</code></em> [, ... ] )</code></span></dt><dd><p>
  74       This form sets or resets per-attribute options.
  75       See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
  76       for more details.
  77      </p></dd><dt><span class="term">
  78      <code class="literal">SET STORAGE</code>
  79     </span></dt><dd><p>
  80       This form sets the storage mode for a column.
  81       See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
  82       for more details.
  83       Note that the storage mode has no effect unless the table's
  84       foreign-data wrapper chooses to pay attention to it.
  85      </p></dd><dt><span class="term"><code class="literal">ADD <em class="replaceable"><code>table_constraint</code></em> [ NOT VALID ]</code></span></dt><dd><p>
  86       This form adds a new constraint to a foreign table, using the same
  87       syntax as <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a>.
  88       Currently only <code class="literal">CHECK</code> and <code class="literal">NOT NULL</code>
  89       constraints are supported.
  90      </p><p>
  91       Unlike the case when adding a constraint to a regular table, nothing is
  92       done to verify the constraint is correct; rather, this action simply
  93       declares that some new condition should be assumed to hold for all rows
  94       in the foreign table.  (See the discussion
  95       in <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a>.)
  96       If the constraint is marked <code class="literal">NOT VALID</code> (allowed only for
  97       the <code class="literal">CHECK</code> case), then it isn't
  98       assumed to hold, but is only recorded for possible future use.
  99      </p></dd><dt><span class="term"><code class="literal">VALIDATE CONSTRAINT</code></span></dt><dd><p>
 100       This form marks as valid a constraint that was previously marked
 101       as <code class="literal">NOT VALID</code>.  No action is taken to verify the
 102       constraint, but future queries will assume that it holds.
 103      </p></dd><dt><span class="term"><code class="literal">DROP CONSTRAINT [ IF EXISTS ]</code></span></dt><dd><p>
 104       This form drops the specified constraint on a foreign table.
 105       If <code class="literal">IF EXISTS</code> is specified and the constraint
 106       does not exist, no error is thrown.
 107       In this case a notice is issued instead.
 108      </p></dd><dt><span class="term"><code class="literal">DISABLE</code>/<code class="literal">ENABLE [ REPLICA | ALWAYS ] TRIGGER</code></span></dt><dd><p>
 109       These forms configure the firing of trigger(s) belonging to the foreign
 110       table.  See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a> for more
 111       details.
 112      </p></dd><dt><span class="term"><code class="literal">SET WITHOUT OIDS</code></span></dt><dd><p>
 113       Backward compatibility syntax for removing the <code class="literal">oid</code>
 114       system column. As <code class="literal">oid</code> system columns cannot be added
 115       anymore, this never has an effect.
 116      </p></dd><dt><span class="term"><code class="literal">INHERIT <em class="replaceable"><code>parent_table</code></em></code></span></dt><dd><p>
 117       This form adds the target foreign table as a new child of the specified
 118       parent table.
 119       See the similar form of <a class="link" href="sql-altertable.html" title="ALTER TABLE"><code class="command">ALTER TABLE</code></a>
 120       for more details.
 121      </p></dd><dt><span class="term"><code class="literal">NO INHERIT <em class="replaceable"><code>parent_table</code></em></code></span></dt><dd><p>
 122       This form removes the target foreign table from the list of children of
 123       the specified parent table.
 124      </p></dd><dt><span class="term"><code class="literal">OWNER</code></span></dt><dd><p>
 125       This form changes the owner of the foreign table to the
 126       specified user.
 127      </p></dd><dt><span class="term"><code class="literal">OPTIONS ( [ ADD | SET | DROP ] <em class="replaceable"><code>option</code></em> ['<em class="replaceable"><code>value</code></em>'] [, ... ] )</code></span></dt><dd><p>
 128       Change options for the foreign table or one of its columns.
 129       <code class="literal">ADD</code>, <code class="literal">SET</code>, and <code class="literal">DROP</code>
 130       specify the action to be performed.  <code class="literal">ADD</code> is assumed
 131       if no operation is explicitly specified.  Duplicate option names are not
 132       allowed (although it's OK for a table option and a column option to have
 133       the same name).  Option names and values are also validated using the
 134       foreign data wrapper library.
 135      </p></dd><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
 136       The <code class="literal">RENAME</code> forms change the name of a foreign table
 137       or the name of an individual column in a foreign table.
 138      </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
 139       This form moves the foreign table into another schema.
 140      </p></dd></dl></div><p>
 141   </p><p>
 142    All the actions except <code class="literal">RENAME</code> and <code class="literal">SET SCHEMA</code>
 143    can be combined into
 144    a list of multiple alterations to apply in parallel.  For example, it
 145    is possible to add several columns and/or alter the type of several
 146    columns in a single command.
 147   </p><p>
 148    If the command is written as <code class="literal">ALTER FOREIGN TABLE IF EXISTS ...</code>
 149    and the foreign table does not exist, no error is thrown. A notice is
 150    issued in this case.
 151   </p><p>
 152    You must own the table to use <code class="command">ALTER FOREIGN TABLE</code>.
 153    To change the schema of a foreign table, you must also have
 154    <code class="literal">CREATE</code> privilege on the new schema.
 155    To alter the owner, you must be able to <code class="literal">SET ROLE</code> to the
 156    new owning role, and that role must have <code class="literal">CREATE</code> privilege
 157    on the table's schema.  (These restrictions enforce that altering the owner
 158    doesn't do anything you couldn't do by dropping and recreating the table.
 159    However, a superuser can alter ownership of any table anyway.)
 160    To add a column or alter a column type, you must also
 161    have <code class="literal">USAGE</code> privilege on the data type.
 162   </p></div><div class="refsect1" id="id-1.9.3.13.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
 163         The name (possibly schema-qualified) of an existing foreign table to
 164         alter. If <code class="literal">ONLY</code> is specified before the table name, only
 165         that table is altered. If <code class="literal">ONLY</code> is not specified, the table
 166         and all its descendant tables (if any) are altered.  Optionally,
 167         <code class="literal">*</code> can be specified after the table name to explicitly
 168         indicate that descendant tables are included.
 169        </p></dd><dt><span class="term"><em class="replaceable"><code>column_name</code></em></span></dt><dd><p>
 170         Name of a new or existing column.
 171        </p></dd><dt><span class="term"><em class="replaceable"><code>new_column_name</code></em></span></dt><dd><p>
 172         New name for an existing column.
 173        </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
 174         New name for the table.
 175        </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
 176         Data type of the new column, or new data type for an existing
 177         column.
 178        </p></dd><dt><span class="term"><em class="replaceable"><code>table_constraint</code></em></span></dt><dd><p>
 179         New table constraint for the foreign table.
 180        </p></dd><dt><span class="term"><em class="replaceable"><code>constraint_name</code></em></span></dt><dd><p>
 181         Name of an existing constraint to drop.
 182        </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
 183         Automatically drop objects that depend on the dropped column
 184         or constraint (for example, views referencing the column),
 185         and in turn all objects that depend on those objects
 186         (see <a class="xref" href="ddl-depend.html" title="5.15. Dependency Tracking">Section 5.15</a>).
 187        </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
 188         Refuse to drop the column or constraint if there are any dependent
 189         objects. This is the default behavior.
 190        </p></dd><dt><span class="term"><em class="replaceable"><code>trigger_name</code></em></span></dt><dd><p>
 191         Name of a single trigger to disable or enable.
 192        </p></dd><dt><span class="term"><code class="literal">ALL</code></span></dt><dd><p>
 193         Disable or enable all triggers belonging to the foreign table.  (This
 194         requires superuser privilege if any of the triggers are internally
 195         generated triggers.  The core system does not add such triggers to
 196         foreign tables, but add-on code could do so.)
 197        </p></dd><dt><span class="term"><code class="literal">USER</code></span></dt><dd><p>
 198         Disable or enable all triggers belonging to the foreign table except
 199         for internally generated triggers.
 200        </p></dd><dt><span class="term"><em class="replaceable"><code>parent_table</code></em></span></dt><dd><p>
 201         A parent table to associate or de-associate with this foreign table.
 202        </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
 203         The user name of the new owner of the table.
 204        </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
 205         The name of the schema to which the table will be moved.
 206        </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.13.7"><h2>Notes</h2><p>
 207     The key word <code class="literal">COLUMN</code> is noise and can be omitted.
 208    </p><p>
 209     Consistency with the foreign server is not checked when a column is added
 210     or removed with <code class="literal">ADD COLUMN</code> or
 211     <code class="literal">DROP COLUMN</code>, a <code class="literal">NOT NULL</code>
 212     or <code class="literal">CHECK</code> constraint is added, or a column type is changed
 213     with <code class="literal">SET DATA TYPE</code>.  It is the user's responsibility to ensure
 214     that the table definition matches the remote side.
 215    </p><p>
 216     Refer to <a class="link" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><code class="command">CREATE FOREIGN TABLE</code></a> for a further description of valid
 217     parameters.
 218    </p></div><div class="refsect1" id="id-1.9.3.13.8"><h2>Examples</h2><p>
 219    To mark a column as not-null:
 220 </p><pre class="programlisting">
 221 ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
 222 </pre><p>
 223   </p><p>
 224    To change options of a foreign table:
 225 </p><pre class="programlisting">
 226 ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'value2', DROP opt3);
 227 </pre></div><div class="refsect1" id="id-1.9.3.13.9"><h2>Compatibility</h2><p>
 228    The forms <code class="literal">ADD</code>, <code class="literal">DROP</code>,
 229    and <code class="literal">SET DATA TYPE</code>
 230    conform with the SQL standard.  The other forms are
 231    <span class="productname">PostgreSQL</span> extensions of the SQL standard.
 232    Also, the ability to specify more than one manipulation in a single
 233    <code class="command">ALTER FOREIGN TABLE</code> command is an extension.
 234   </p><p>
 235    <code class="command">ALTER FOREIGN TABLE DROP COLUMN</code> can be used to drop the only
 236    column of a foreign table, leaving a zero-column table.  This is an
 237    extension of SQL, which disallows zero-column foreign tables.
 238   </p></div><div class="refsect1" id="id-1.9.3.13.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createforeigntable.html" title="CREATE FOREIGN TABLE"><span class="refentrytitle">CREATE FOREIGN TABLE</span></a>, <a class="xref" href="sql-dropforeigntable.html" title="DROP FOREIGN TABLE"><span class="refentrytitle">DROP FOREIGN TABLE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-alterforeigndatawrapper.html" title="ALTER FOREIGN DATA WRAPPER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alterfunction.html" title="ALTER FUNCTION">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER FOREIGN DATA WRAPPER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER FUNCTION</td></tr></table></div></body></html>