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