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.42 2002/04/21 19:02:39 thomas Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERTABLE">
   7  <refmeta>
   8   <refentrytitle id="sql-altertable-title">ALTER TABLE</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11  <refnamediv>
  12   <refname>
  13    ALTER TABLE
  14   </refname>
  15   <refpurpose>
  16    change the definition of a table
  17   </refpurpose>
  18  </refnamediv>
  19  <refsynopsisdiv>
  20   <refsynopsisdivinfo>
  21    <date>1999-07-20</date>
  22   </refsynopsisdivinfo>
  23   <synopsis>
  24 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  25     ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ]
  26 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  27     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET DEFAULT <replaceable
  28     class="PARAMETER">value</replaceable> | DROP DEFAULT }
  29 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  30     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET | DROP } NOT NULL
  31 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  32     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STATISTICS <replaceable class="PARAMETER">integer</replaceable>
  33 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  34     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STORAGE {PLAIN | EXTERNAL | EXTENDED | MAIN}
  35 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ]
  36     RENAME [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> TO <replaceable
  37     class="PARAMETER">newcolumn</replaceable>
  38 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  39     RENAME TO <replaceable class="PARAMETER">new_table</replaceable>
  40 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  41     ADD <replaceable class="PARAMETER">table_constraint_definition</replaceable>
  42 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">table</replaceable>
  43         DROP CONSTRAINT <replaceable class="PARAMETER">constraint</replaceable> { RESTRICT | CASCADE }
  44 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  45         OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
  46   </synopsis>
  47
  48   <refsect2 id="R2-SQL-ALTERTABLE-1">
  49    <refsect2info>
  50     <date>1998-04-15</date>
  51    </refsect2info>
  52    <title>
  53     Inputs
  54    </title>
  55    <para>
  56     <variablelist>
  57      <varlistentry>
  58       <term><replaceable class="PARAMETER"> table </replaceable></term>
  59       <listitem>
  60        <para>
  61         The name of an existing table to alter.
  62        </para>
  63       </listitem>
  64      </varlistentry>
  65
  66      <varlistentry>
  67       <term><replaceable class="PARAMETER"> column </replaceable></term>
  68       <listitem>
  69        <para>
  70         Name of a new or existing column.
  71        </para>
  72       </listitem>
  73      </varlistentry>
  74
  75      <varlistentry>
  76       <term><replaceable class="PARAMETER"> type </replaceable></term>
  77       <listitem>
  78        <para>
  79         Type of the new column.
  80        </para>
  81       </listitem>
  82      </varlistentry>
  83
  84      <varlistentry>
  85       <term><replaceable class="PARAMETER"> newcolumn </replaceable></term>
  86       <listitem>
  87        <para>
  88         New name for an existing column.
  89        </para>
  90       </listitem>
  91      </varlistentry>
  92
  93      <varlistentry>
  94       <term><replaceable class="PARAMETER"> new_table </replaceable></term>
  95       <listitem>
  96        <para>
  97         New name for the table.
  98        </para>
  99       </listitem>
 100      </varlistentry>
 101
 102      <varlistentry>
 103       <term><replaceable class="PARAMETER"> table_constraint_definition </replaceable></term>
 104       <listitem>
 105        <para>
 106         New table constraint for the table
 107        </para>
 108       </listitem>
 109      </varlistentry>
 110
 111      <varlistentry>
 112       <term><replaceable class="PARAMETER">new_owner </replaceable></term>
 113       <listitem>
 114        <para>
 115         The user name of the new owner of the table.
 116        </para>
 117       </listitem>
 118      </varlistentry>
 119
 120     </variablelist>
 121    </para>
 122   </refsect2>
 123
 124   <refsect2 id="R2-SQL-ALTERTABLE-2">
 125    <refsect2info>
 126     <date>1998-04-15</date>
 127    </refsect2info>
 128    <title>
 129     Outputs
 130    </title>
 131    <para>
 132
 133     <variablelist>
 134      <varlistentry>
 135       <term><computeroutput>ALTER</computeroutput></term>
 136       <listitem>
 137        <para>
 138         Message returned from column or table renaming.
 139        </para>
 140       </listitem>
 141      </varlistentry>
 142
 143      <varlistentry>
 144       <term><computeroutput>ERROR</computeroutput></term>
 145       <listitem>
 146        <para>
 147         Message returned if table or column is not available.
 148        </para>
 149       </listitem>
 150      </varlistentry>
 151     </variablelist>
 152    </para>
 153   </refsect2>
 154  </refsynopsisdiv>
 155
 156  <refsect1 id="R1-SQL-ALTERTABLE-1">
 157   <refsect1info>
 158    <date>1998-04-15</date>
 159   </refsect1info>
 160   <title>
 161    Description
 162   </title>
 163   <para>
 164    <command>ALTER TABLE</command> changes the definition of an existing table.
 165    The <literal>ADD COLUMN</literal> form adds a new column to the table
 166    using the same syntax as <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-TITLE">.
 167    The <literal>ALTER COLUMN SET/DROP DEFAULT</literal> forms
 168    allow you to set or remove the default for the column. Note that defaults
 169    only apply to subsequent <command>INSERT</command> commands; they do not
 170    cause rows already in the table to change.
 171    The <literal>ALTER COLUMN SET/DROP NOT NULL</literal> forms allow you to
 172    change whether a column is marked to allow NULL values or to reject NULL
 173    values.
 174    The <literal>ALTER COLUMN SET STATISTICS</literal> form allows you to
 175    set the statistics-gathering target for subsequent
 176    <xref linkend="sql-analyze" endterm="sql-analyze-title"> operations.
 177    The <literal>ALTER COLUMN SET STORAGE</literal> form allows the
 178    column storage mode to be set. This controls whether this column is
 179    held inline or in a supplementary table, and whether the data
 180    should be compressed or not. <literal>PLAIN</literal> must be used
 181    for fixed-length values such as <literal>INTEGER</literal> and is
 182    inline, uncompressed. <literal>MAIN</literal> is for inline,
 183    compressible data. <literal>EXTERNAL</literal> is for external,
 184    uncompressed data and <literal>EXTENDED</literal> is for external,
 185    compressed data. The use of <literal>EXTERNAL</literal> will make
 186    substring operations on a column faster, at the penalty of
 187    increased storage space.
 188    The <literal>RENAME</literal> clause causes the name of a table,
 189    column, index, sequence or view to change without changing any of the
 190    data. The data will remain of the same type and size after the
 191    command is executed.
 192    The ADD <replaceable class="PARAMETER">table_constraint_definition</replaceable> clause
 193    adds a new constraint to the table using the same syntax as <xref
 194    linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-TITLE">.
 195    The DROP CONSTRAINT <replaceable class="PARAMETER">constraint</replaceable> clause
 196    drops all constraints on the table (and its children) that match <replaceable class="PARAMETER">constraint</replaceable>.
 197    The OWNER clause changes the owner of the table, index, sequence or view to the
 198    user <replaceable class="PARAMETER">new user</replaceable>.
 199   </para>
 200
 201   <para>
 202    You must own the table in order to change its schema.
 203   </para>
 204
 205   <refsect2 id="R2-SQL-ALTERTABLE-3">
 206    <refsect2info>
 207     <date>1998-04-15</date>
 208    </refsect2info>
 209    <title>
 210     Notes
 211 </title>
 212    <para>
 213     The keyword <literal>COLUMN</literal> is noise and can be omitted.
 214    </para>
 215
 216    <para>
 217     In the current implementation of <literal>ADD COLUMN</literal>,
 218     default and NOT NULL clauses for the new column are not supported.
 219     You can use the <literal>SET DEFAULT</literal> form
 220     of <command>ALTER TABLE</command> to set the default later.
 221     (You may also want to update the already existing rows to the
 222     new default value, using <xref linkend="sql-update" endterm="sql-update-title">.)
 223    </para>
 224
 225    <para>
 226     In DROP CONSTRAINT, the RESTRICT keyword is required, although
 227     dependencies are not yet checked.  The CASCADE option is unsupported.
 228     Currently DROP CONSTRAINT drops only CHECK constraints.
 229     To remove a PRIMARY or UNIQUE constraint, drop the
 230     relevant index using the <xref linkend="SQL-DROPINDEX" endterm="sql-dropindex-title"> command.
 231     To remove FOREIGN KEY constraints you need to recreate
 232     and reload the table, using other parameters to the
 233     <xref linkend="SQL-CREATETABLE" endterm="sql-createtable-title"> command.
 234    </para>
 235    <para>
 236     For example, to drop all constraints on a table <literal>distributors</literal>:
 237     <programlisting>
 238 CREATE TABLE temp AS SELECT * FROM distributors;
 239 DROP TABLE distributors;
 240 CREATE TABLE distributors AS SELECT * FROM temp;
 241 DROP TABLE temp;
 242     </programlisting>
 243    </para>
 244
 245    <para>
 246     You must own the table in order to change it.
 247     Changing any  part  of  the schema of a system
 248     catalog is not permitted.
 249     The <citetitle>PostgreSQL User's Guide</citetitle> has further
 250     information on inheritance.
 251    </para>
 252
 253    <para>
 254     Refer to <command>CREATE TABLE</command> for a further description
 255     of valid arguments.
 256    </para>
 257   </refsect2>
 258  </refsect1>
 259
 260  <refsect1 id="R1-SQL-ALTERTABLE-2">
 261   <title>
 262    Usage
 263   </title>
 264   <para>
 265    To add a column of type <type>varchar</type> to a table:
 266    <programlisting>
 267 ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
 268    </programlisting>
 269   </para>
 270
 271   <para>
 272    To rename an existing column:
 273    <programlisting>
 274 ALTER TABLE distributors RENAME COLUMN address TO city;
 275    </programlisting>
 276   </para>
 277
 278   <para>
 279    To rename an existing table:
 280    <programlisting>
 281 ALTER TABLE distributors RENAME TO suppliers;
 282    </programlisting>
 283   </para>
 284
 285   <para>
 286    To add a NOT NULL constraint to a column:
 287    <programlisting>
 288 ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
 289    </programlisting>
 290    To remove a NOT NULL constraint from a column:
 291    <programlisting>
 292 ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
 293    </programlisting>
 294   </para>
 295
 296   <para>
 297    To add a check constraint to a table:
 298    <programlisting>
 299 ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5);
 300    </programlisting>
 301   </para>
 302
 303   <para>
 304    To remove a check constraint from a table and all its children:
 305    <programlisting>
 306 ALTER TABLE distributors DROP CONSTRAINT zipchk RESTRICT;
 307    </programlisting>
 308   </para>
 309
 310   <para>
 311    To add a foreign key constraint to a table:
 312    <programlisting>
 313 ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses(address) MATCH FULL;
 314    </programlisting>
 315   </para>
 316
 317   <para>
 318    To add a (multicolumn) unique constraint to a table:
 319    <programlisting>
 320 ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode);
 321    </programlisting>
 322   </para>
 323
 324   <para>
 325    To add an automatically named primary key constraint to a table, noting
 326    that a table can only ever have one primary key:
 327    <programlisting>
 328 ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
 329    </programlisting>
 330   </para>
 331  </refsect1>
 332
 333  <refsect1 id="R1-SQL-ALTERTABLE-3">
 334   <title>
 335    Compatibility
 336   </title>
 337
 338   <refsect2 id="R2-SQL-ALTERTABLE-4">
 339    <refsect2info>
 340     <date>1998-04-15</date>
 341    </refsect2info>
 342    <title>SQL92</title>
 343     <para>
 344      The <literal>ADD COLUMN</literal> form is compliant with the exception that
 345      it does not support defaults and NOT NULL constraints, as explained above.
 346      The <literal>ALTER COLUMN</literal> form is in full compliance.
 347     </para>
 348
 349     <para>
 350      SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
 351      statement which are not yet directly supported by <productname>PostgreSQL</productname>:
 352
 353     <variablelist>
 354     <varlistentry>
 355      <term>
 356       <synopsis>
 357 ALTER TABLE <replaceable class="PARAMETER">table</replaceable> DROP [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { RESTRICT | CASCADE }
 358       </synopsis>
 359      </term>
 360      <listitem>
 361       <para>
 362        Removes a column from a table.
 363        Currently, to remove an existing column the table must be
 364        recreated and reloaded:
 365        <programlisting>
 366 CREATE TABLE temp AS SELECT did, city FROM distributors;
 367 DROP TABLE distributors;
 368 CREATE TABLE distributors (
 369     did      DECIMAL(3)  DEFAULT 1,
 370     name     VARCHAR(40) NOT NULL
 371 );
 372 INSERT INTO distributors SELECT * FROM temp;
 373 DROP TABLE temp;
 374        </programlisting>
 375       </para>
 376      </listitem>
 377     </varlistentry>
 378    </variablelist>
 379    </para>
 380
 381    <para>
 382     The clauses to rename tables, columns, indexes, and sequences are
 383     <productname>PostgreSQL</productname> extensions from SQL92.
 384    </para>
 385
 386   </refsect2>
 387  </refsect1>
 388 </refentry>
 389
 390 <!-- Keep this comment at the end of the file
 391 Local variables:
 392 mode: sgml
 393 sgml-omittag:nil
 394 sgml-shorttag:t
 395 sgml-minimize-attributes:nil
 396 sgml-always-quote-attributes:t
 397 sgml-indent-step:1
 398 sgml-indent-data:t
 399 sgml-parent-document:nil
 400 sgml-default-dtd-file:"../reference.ced"
 401 sgml-exposed-tags:nil
 402 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 403 sgml-local-ecat-files:nil
 404 End:
 405 -->