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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.18 2001/01/05 06:34:16 tgl Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERTABLE">
   7  <refmeta>
   8   <refentrytitle id="sql-altertable-title">
   9    ALTER TABLE
  10   </refentrytitle>
  11   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    ALTER TABLE
  16   </refname>
  17   <refpurpose>
  18    Modifies table properties
  19   </refpurpose>
  20  </refnamediv>
  21  <refsynopsisdiv>
  22   <refsynopsisdivinfo>
  23    <date>1999-07-20</date>
  24   </refsynopsisdivinfo>
  25   <synopsis>
  26 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  27     ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable
  28     class="PARAMETER">type</replaceable>
  29 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  30     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET DEFAULT <replaceable
  31     class="PARAMETER">value</replaceable> | DROP DEFAULT }
  32 ALTER TABLE <replaceable class="PARAMETER">table</replaceable> [ * ]
  33     RENAME [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> TO <replaceable
  34     class="PARAMETER">newcolumn</replaceable>
  35 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  36     RENAME TO <replaceable class="PARAMETER">newtable</replaceable>
  37 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  38     ADD <replaceable class="PARAMETER">table constraint definition</replaceable>
  39 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  40         OWNER TO <replaceable class="PARAMETER">new owner</replaceable>
  41   </synopsis>
  42
  43   <refsect2 id="R2-SQL-ALTERTABLE-1">
  44    <refsect2info>
  45     <date>1998-04-15</date>
  46    </refsect2info>
  47    <title>
  48     Inputs
  49    </title>
  50    <para>
  51     <variablelist>
  52      <varlistentry>
  53       <term><replaceable class="PARAMETER"> table </replaceable></term>
  54       <listitem>
  55        <para>
  56         The name of an existing table to alter.
  57        </para>
  58       </listitem>
  59      </varlistentry>
  60
  61      <varlistentry>
  62       <term><replaceable class="PARAMETER"> column </replaceable></term>
  63       <listitem>
  64        <para>
  65         Name of a new or existing column.
  66        </para>
  67       </listitem>
  68      </varlistentry>
  69
  70      <varlistentry>
  71       <term><replaceable class="PARAMETER"> type </replaceable></term>
  72       <listitem>
  73        <para>
  74         Type of the new column.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term><replaceable class="PARAMETER"> newcolumn </replaceable></term>
  81       <listitem>
  82        <para>
  83         New name for an existing column.
  84        </para>
  85       </listitem>
  86      </varlistentry>
  87
  88      <varlistentry>
  89       <term><replaceable class="PARAMETER"> newtable </replaceable></term>
  90       <listitem>
  91        <para>
  92         New name for the table.
  93        </para>
  94       </listitem>
  95      </varlistentry>
  96
  97      <varlistentry>
  98       <term><replaceable class="PARAMETER"> table constraint definition </replaceable></term>
  99       <listitem>
 100        <para>
 101         New table constraint for the table
 102        </para>
 103       </listitem>
 104      </varlistentry>
 105
 106      <varlistentry>
 107       <term><replaceable class="PARAMETER">New user </replaceable></term>
 108       <listitem>
 109        <para>
 110         The userid of the new owner of the table.
 111        </para>
 112       </listitem>
 113      </varlistentry>
 114
 115     </variablelist>
 116    </para>
 117   </refsect2>
 118
 119   <refsect2 id="R2-SQL-ALTERTABLE-2">
 120    <refsect2info>
 121     <date>1998-04-15</date>
 122    </refsect2info>
 123    <title>
 124     Outputs
 125    </title>
 126    <para>
 127
 128     <variablelist>
 129      <varlistentry>
 130       <term><computeroutput>ALTER</computeroutput></term>
 131       <listitem>
 132        <para>
 133         Message returned from column or table renaming.
 134        </para>
 135       </listitem>
 136      </varlistentry>
 137
 138      <varlistentry>
 139       <term><computeroutput>ERROR</computeroutput></term>
 140       <listitem>
 141        <para>
 142         Message returned if table or column is not available.
 143        </para>
 144       </listitem>
 145      </varlistentry>
 146     </variablelist>
 147    </para>
 148   </refsect2>
 149  </refsynopsisdiv>
 150
 151  <refsect1 id="R1-SQL-ALTERTABLE-1">
 152   <refsect1info>
 153    <date>1998-04-15</date>
 154   </refsect1info>
 155   <title>
 156    Description
 157   </title>
 158   <para>
 159    <command>ALTER TABLE</command> changes the definition of an existing table.
 160    The <literal>ADD COLUMN</literal> form adds a new column to the table
 161    using the same syntax as <xref linkend="SQL-CREATETABLE"
 162    endterm="SQL-CREATETABLE-title">. The <literal>ALTER COLUMN</literal> form
 163    allows you to set or remove the default for the column. Note that defaults
 164    only apply to newly inserted rows.
 165    The <literal>RENAME</literal> clause causes the name of a table or column
 166    to change without changing any of the data contained in
 167    the affected table. Thus, the table or column will
 168    remain of the same type and size after this command is
 169    executed.
 170    The ADD <replaceable class="PARAMETER">table constraint definition</replaceable> clause
 171    adds a new constraint to the table using the same syntax as <xref
 172    linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-title">.
 173    The OWNER clause chnages the owner of the table to the user <replaceable class="PARAMETER">
 174    new user</replaceable>.
 175   </para>
 176
 177   <para>
 178    You must own the table in order to change its schema.
 179   </para>
 180
 181   <refsect2 id="R2-SQL-ALTERTABLE-3">
 182    <refsect2info>
 183     <date>1998-04-15</date>
 184    </refsect2info>
 185    <title>
 186     Notes
 187 </title>
 188    <para>
 189     The keyword <literal>COLUMN</literal> is noise and can be omitted.
 190    </para>
 191
 192    <para>
 193     In the current implementation, default and constraint clauses for the
 194     new column will be ignored. You can use the <literal>SET DEFAULT</literal>
 195     form of <command>ALTER TABLE</command> to set the default later.
 196     (You will also have to update the already existing rows to the
 197     new default value, using <xref linkend="sql-update"
 198     endterm="sql-update-title">.)
 199    </para>
 200
 201    <para>
 202     In the current implementation, only FOREIGN KEY constraints can
 203     be added to a table.  To create or remove a unique constraint, create
 204     a unique index (see <xref linkend="SQL-CREATEINDEX"
 205     endterm="SQL-CREATEINDEX-title">).  To add check constraints
 206     you need to recreate and reload the table, using other
 207     parameters to the <xref linkend="SQL-CREATETABLE"
 208     endterm="SQL-CREATETABLE-title"> command.
 209    </para>
 210
 211    <para>
 212     You must own the class in order to change its schema.
 213     Renaming any  part  of  the schema of a system
 214     catalog is not permitted.
 215     The <citetitle>PostgreSQL User's Guide</citetitle> has further
 216     information on inheritance.
 217    </para>
 218
 219    <para>
 220     Refer to <command>CREATE TABLE</command> for a further description
 221     of valid arguments.
 222    </para>
 223   </refsect2>
 224  </refsect1>
 225
 226  <refsect1 id="R1-SQL-ALTERTABLE-2">
 227   <title>
 228    Usage
 229   </title>
 230   <para>
 231    To add a column of type VARCHAR to a table:
 232    <programlisting>
 233 ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
 234    </programlisting>
 235   </para>
 236
 237   <para>
 238    To rename an existing column:
 239    <programlisting>
 240 ALTER TABLE distributors RENAME COLUMN address TO city;
 241    </programlisting>
 242   </para>
 243
 244   <para>
 245    To rename an existing table:
 246    <programlisting>
 247 ALTER TABLE distributors RENAME TO suppliers;
 248    </programlisting>
 249   </para>
 250
 251   <para>
 252    To add a foreign key constraint to a table:
 253    <programlisting>
 254 ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses(address) MATCH FULL
 255    </programlisting>
 256   </para>
 257  </refsect1>
 258
 259  <refsect1 id="R1-SQL-ALTERTABLE-3">
 260   <title>
 261    Compatibility
 262   </title>
 263
 264   <refsect2 id="R2-SQL-ALTERTABLE-4">
 265    <refsect2info>
 266     <date>1998-04-15</date>
 267    </refsect2info>
 268    <title>SQL92</title>
 269     <para>
 270      The <literal>ADD COLUMN</literal> form is compliant with the exception that
 271      it does not support defaults and constraints, as explained above.
 272      The <literal>ALTER COLUMN</literal> form is in full compliance.
 273     </para>
 274
 275     <para>
 276      SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
 277      statement which are not yet directly supported by <productname>Postgres</productname>:
 278
 279     <variablelist>
 280      <varlistentry>
 281       <term>
 282        <synopsis>
 283 ALTER TABLE <replaceable class="PARAMETER">table</replaceable> DROP CONSTRAINT <replaceable class="PARAMETER">constraint</replaceable> { RESTRICT | CASCADE }
 284       </synopsis>
 285      </term>
 286      <listitem>
 287       <para>
 288        Removes a table constraint (such as a check constraint,
 289        unique constraint, or foreign key constraint). To
 290        remove a unique constraint, drop a unique index.
 291        To remove other kinds of constraints you need to recreate
 292        and reload the table, using other parameters to the
 293        <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-title">
 294        command.
 295       </para>
 296       <para>
 297        For example, to drop any constraints on a table <literal>distributors</literal>:
 298        <programlisting>
 299 CREATE TABLE temp AS SELECT * FROM distributors;
 300 DROP TABLE distributors;
 301 CREATE TABLE distributors AS SELECT * FROM temp;
 302 DROP TABLE temp;
 303        </programlisting>
 304       </para>
 305      </listitem>
 306     </varlistentry>
 307
 308     <varlistentry>
 309      <term>
 310       <synopsis>
 311 ALTER TABLE <replaceable class="PARAMETER">table</replaceable> DROP [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { RESTRICT | CASCADE }
 312       </synopsis>
 313      </term>
 314      <listitem>
 315       <para>
 316        Removes a column from a table.
 317        Currently, to remove an existing column the table must be
 318        recreated and reloaded:
 319        <programlisting>
 320 CREATE TABLE temp AS SELECT did, city FROM distributors;
 321 DROP TABLE distributors;
 322 CREATE TABLE distributors (
 323     did      DECIMAL(3)  DEFAULT 1,
 324     name     VARCHAR(40) NOT NULL
 325 );
 326 INSERT INTO distributors SELECT * FROM temp;
 327 DROP TABLE temp;
 328        </programlisting>
 329       </para>
 330      </listitem>
 331     </varlistentry>
 332    </variablelist>
 333    </para>
 334
 335    <para>
 336     The clauses to rename columns and tables are <productname>Postgres</productname>
 337     extensions from SQL92.
 338    </para>
 339
 340   </refsect2>
 341  </refsect1>
 342 </refentry>
 343
 344 <!-- Keep this comment at the end of the file
 345 Local variables:
 346 mode: sgml
 347 sgml-omittag:nil
 348 sgml-shorttag:t
 349 sgml-minimize-attributes:nil
 350 sgml-always-quote-attributes:t
 351 sgml-indent-step:1
 352 sgml-indent-data:t
 353 sgml-parent-document:nil
 354 sgml-default-dtd-file:"../reference.ced"
 355 sgml-exposed-tags:nil
 356 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 357 sgml-local-ecat-files:nil
 358 End:
 359 -->