granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/alter_foreign_table.sgml

   1 <!--
   2 doc/src/sgml/rel/alter_foreign_table.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERFOREIGNTABLE">
   7  <refmeta>
   8   <refentrytitle>ALTER FOREIGN TABLE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>ALTER FOREIGN TABLE</refname>
  15   <refpurpose>change the definition of a foreign table</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-alterforeigntable">
  19   <primary>ALTER FOREIGN TABLE</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
  25     <replaceable class="PARAMETER">action</replaceable> [, ... ]
  26 ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
  27     RENAME [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> TO <replaceable class="PARAMETER">new_column</replaceable>
  28 ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
  29     RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
  30 ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
  31     SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>
  32
  33 <phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase>
  34
  35     ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> [ NULL | NOT NULL ]
  36     DROP [ COLUMN ] [ IF EXISTS ] <replaceable class="PARAMETER">column</replaceable> [ RESTRICT | CASCADE ]
  37     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> [ SET DATA ] TYPE <replaceable class="PARAMETER">type</replaceable>
  38     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET | DROP } NOT NULL
  39     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STATISTICS <replaceable class="PARAMETER">integer</replaceable>
  40     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET ( <replaceable class="PARAMETER">attribute_option</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )
  41     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> RESET ( <replaceable class="PARAMETER">attribute_option</replaceable> [, ... ] )
  42     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ])
  43     OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
  44     OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ])
  45 </synopsis>
  46  </refsynopsisdiv>
  47
  48  <refsect1>
  49   <title>Description</title>
  50
  51   <para>
  52    <command>ALTER FOREIGN TABLE</command> changes the definition of an
  53    existing foreign table.  There are several subforms:
  54
  55   <variablelist>
  56    <varlistentry>
  57     <term><literal>ADD COLUMN</literal></term>
  58     <listitem>
  59      <para>
  60       This form adds a new column to the foreign table, using the same syntax as
  61       <xref linkend="SQL-CREATEFOREIGNTABLE">.
  62      </para>
  63     </listitem>
  64    </varlistentry>
  65
  66    <varlistentry>
  67     <term><literal>DROP COLUMN [ IF EXISTS ]</literal></term>
  68     <listitem>
  69      <para>
  70       This form drops a column from a foreign table.
  71       You will need to say <literal>CASCADE</> if
  72       anything outside the table depends on the column; for example,
  73       views.
  74       If <literal>IF EXISTS</literal> is specified and the column
  75       does not exist, no error is thrown. In this case a notice
  76       is issued instead.
  77      </para>
  78     </listitem>
  79    </varlistentry>
  80
  81    <varlistentry>
  82     <term><literal>IF EXISTS</literal></term>
  83     <listitem>
  84      <para>
  85       Do not throw an error if the foreign table does not exist. A notice is
  86       issued in this case.
  87      </para>
  88     </listitem>
  89    </varlistentry>
  90
  91    <varlistentry>
  92     <term><literal>SET DATA TYPE</literal></term>
  93     <listitem>
  94      <para>
  95       This form changes the type of a column of a foreign table.
  96      </para>
  97     </listitem>
  98    </varlistentry>
  99
 100    <varlistentry>
 101     <term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term>
 102     <listitem>
 103      <para>
 104       Mark a column as allowing, or not allowing, null values.
 105      </para>
 106     </listitem>
 107    </varlistentry>
 108
 109    <varlistentry>
 110     <term><literal>SET STATISTICS</literal></term>
 111     <listitem>
 112      <para>
 113       This form
 114       sets the per-column statistics-gathering target for subsequent
 115       <xref linkend="sql-analyze"> operations.
 116       See the similar form of <xref linkend="sql-altertable">
 117       for more details.
 118      </para>
 119     </listitem>
 120    </varlistentry>
 121
 122    <varlistentry>
 123     <term><literal>SET ( <replaceable class="PARAMETER">attribute_option</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )</literal></term>
 124     <term><literal>RESET ( <replaceable class="PARAMETER">attribute_option</replaceable> [, ... ] )</literal></term>
 125     <listitem>
 126      <para>
 127       This form sets or resets per-attribute options.
 128       See the similar form of <xref linkend="sql-altertable">
 129       for more details.
 130      </para>
 131     </listitem>
 132    </varlistentry>
 133
 134    <varlistentry>
 135     <term><literal>OWNER</literal></term>
 136     <listitem>
 137      <para>
 138       This form changes the owner of the foreign table to the
 139       specified user.
 140      </para>
 141     </listitem>
 142    </varlistentry>
 143
 144    <varlistentry>
 145     <term><literal>RENAME</literal></term>
 146     <listitem>
 147      <para>
 148       The <literal>RENAME</literal> forms change the name of a foreign table
 149       or the name of an individual column in a foreign table.
 150      </para>
 151     </listitem>
 152    </varlistentry>
 153
 154    <varlistentry>
 155     <term><literal>SET SCHEMA</literal></term>
 156     <listitem>
 157      <para>
 158       This form moves the foreign table into another schema.
 159      </para>
 160     </listitem>
 161    </varlistentry>
 162
 163    <varlistentry>
 164     <term><literal>OPTIONS ( [ ADD | SET | DROP ] <replaceable class="PARAMETER">option</replaceable> ['<replaceable class="PARAMETER">value</replaceable>'] [, ... ] )</literal></term>
 165     <listitem>
 166      <para>
 167       Change options for the foreign table or one of its columns.
 168       <literal>ADD</>, <literal>SET</>, and <literal>DROP</>
 169       specify the action to be performed.  <literal>ADD</> is assumed
 170       if no operation is explicitly specified.  Duplicate option names are not
 171       allowed (although it's OK for a table option and a column option to have
 172       the same name).  Option names and values are also validated using the
 173       foreign data wrapper library.
 174      </para>
 175     </listitem>
 176    </varlistentry>
 177
 178   </variablelist>
 179   </para>
 180
 181   <para>
 182    All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</>
 183    can be combined into
 184    a list of multiple alterations to apply in parallel.  For example, it
 185    is possible to add several columns and/or alter the type of several
 186    columns in a single command.
 187   </para>
 188
 189   <para>
 190    You must own the table to use <command>ALTER FOREIGN TABLE</>.
 191    To change the schema of a foreign table, you must also have
 192    <literal>CREATE</literal> privilege on the new schema.
 193    To alter the owner, you must also be a direct or indirect member of the new
 194    owning role, and that role must have <literal>CREATE</literal> privilege on
 195    the table's schema.  (These restrictions enforce that altering the owner
 196    doesn't do anything you couldn't do by dropping and recreating the table.
 197    However, a superuser can alter ownership of any table anyway.)
 198    To add a column or alter a column type, you must also
 199    have <literal>USAGE</literal> privilege on the data type.
 200   </para>
 201  </refsect1>
 202
 203  <refsect1>
 204   <title>Parameters</title>
 205
 206     <variablelist>
 207
 208      <varlistentry>
 209       <term><replaceable class="PARAMETER">name</replaceable></term>
 210       <listitem>
 211        <para>
 212         The name (possibly schema-qualified) of an existing foreign table to
 213         alter.
 214        </para>
 215       </listitem>
 216      </varlistentry>
 217
 218      <varlistentry>
 219       <term><replaceable class="PARAMETER">column</replaceable></term>
 220       <listitem>
 221        <para>
 222         Name of a new or existing column.
 223        </para>
 224       </listitem>
 225      </varlistentry>
 226
 227      <varlistentry>
 228       <term><replaceable class="PARAMETER">new_column</replaceable></term>
 229       <listitem>
 230        <para>
 231         New name for an existing column.
 232        </para>
 233       </listitem>
 234      </varlistentry>
 235
 236      <varlistentry>
 237       <term><replaceable class="PARAMETER">new_name</replaceable></term>
 238       <listitem>
 239        <para>
 240         New name for the table.
 241        </para>
 242       </listitem>
 243      </varlistentry>
 244
 245      <varlistentry>
 246       <term><replaceable class="PARAMETER">type</replaceable></term>
 247       <listitem>
 248        <para>
 249         Data type of the new column, or new data type for an existing
 250         column.
 251        </para>
 252       </listitem>
 253      </varlistentry>
 254
 255      <varlistentry>
 256       <term><literal>CASCADE</literal></term>
 257       <listitem>
 258        <para>
 259         Automatically drop objects that depend on the dropped column
 260         (for example, views referencing the column).
 261        </para>
 262       </listitem>
 263      </varlistentry>
 264
 265      <varlistentry>
 266       <term><literal>RESTRICT</literal></term>
 267       <listitem>
 268        <para>
 269         Refuse to drop the column if there are any dependent
 270         objects. This is the default behavior.
 271        </para>
 272       </listitem>
 273      </varlistentry>
 274
 275      <varlistentry>
 276       <term><replaceable class="PARAMETER">new_owner</replaceable></term>
 277       <listitem>
 278        <para>
 279         The user name of the new owner of the table.
 280        </para>
 281       </listitem>
 282      </varlistentry>
 283
 284      <varlistentry>
 285       <term><replaceable class="PARAMETER">new_schema</replaceable></term>
 286       <listitem>
 287        <para>
 288         The name of the schema to which the table will be moved.
 289        </para>
 290       </listitem>
 291      </varlistentry>
 292     </variablelist>
 293  </refsect1>
 294
 295  <refsect1>
 296   <title>Notes</title>
 297
 298    <para>
 299     The key word <literal>COLUMN</literal> is noise and can be omitted.
 300    </para>
 301
 302    <para>
 303     Consistency with the foreign server is not checked when a column is added
 304     or removed with <literal>ADD COLUMN</literal> or
 305     <literal>DROP COLUMN</literal>, a <literal>NOT NULL</> constraint is
 306     added, or a column type is changed with <literal>SET DATA TYPE</>.  It is
 307     the user's responsibility to ensure that the table definition matches the
 308     remote side.
 309    </para>
 310
 311    <para>
 312     Refer to <xref linkend="sql-createforeigntable"> for a further description of valid
 313     parameters.
 314    </para>
 315  </refsect1>
 316
 317  <refsect1>
 318   <title>Examples</title>
 319
 320   <para>
 321    To mark a column as not-null:
 322 <programlisting>
 323 ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
 324 </programlisting>
 325   </para>
 326
 327   <para>
 328    To change options of a foreign table:
 329 <programlisting>
 330 ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2, 'value2', DROP opt3 'value3');
 331 </programlisting></para>
 332
 333  </refsect1>
 334
 335  <refsect1>
 336   <title>Compatibility</title>
 337
 338   <para>
 339    The forms <literal>ADD</literal>, <literal>DROP</>,
 340    and <literal>SET DATA TYPE</literal>
 341    conform with the SQL standard.  The other forms are
 342    <productname>PostgreSQL</productname> extensions of the SQL standard.
 343    Also, the ability to specify more than one manipulation in a single
 344    <command>ALTER FOREIGN TABLE</> command is an extension.
 345   </para>
 346
 347   <para>
 348    <command>ALTER FOREIGN TABLE DROP COLUMN</> can be used to drop the only
 349    column of a foreign table, leaving a zero-column table.  This is an
 350    extension of SQL, which disallows zero-column foreign tables.
 351   </para>
 352  </refsect1>
 353 </refentry>