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