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