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.8 1999/07/22 15:09:06 thomas 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 <replaceable class="PARAMETER">table</replaceable>
  27     [ * ] ADD [ COLUMN ] <replaceable class="PARAMETER">ER">co</replaceable>BLE> <replaceable
  28     class="PARAMETER">type</replaceable>
  29 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  30     [ * ] RENAME [ COLUMN ] <replaceable class="PARAMETER">ER">co</replaceable>BLE> TO <replaceable
  31     class="PARAMETER">newcolumn</replaceable>
  32 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
  33     RENAME TO <replaceable class="PARAMETER">newtable</replaceable>
  34   </synopsis>
  35
  36   <refsect2 id="R2-SQL-ALTERTABLE-1">
  37    <refsect2info>
  38     <date>1998-04-15</date>
  39    </refsect2info>
  40    <title>
  41     Inputs
  42    </title>
  43    <para>
  44     <variablelist>
  45      <varlistentry>
  46       <term><replaceable class="PARAMETER"> table </replaceable></term>
  47       <listitem>
  48        <para>
  49         The name of an existing table to alter.
  50        </para>
  51       </listitem>
  52      </varlistentry>
  53
  54      <varlistentry>
  55       <term><replaceable class="PARAMETER"> column </replaceable></term>
  56       <listitem>
  57        <para>
  58         Name of a new or existing column.
  59        </para>
  60       </listitem>
  61      </varlistentry>
  62
  63      <varlistentry>
  64       <term><replaceable class="PARAMETER"> type </replaceable></term>
  65       <listitem>
  66        <para>
  67         Type of the new column.
  68        </para>
  69       </listitem>
  70      </varlistentry>
  71
  72      <varlistentry>
  73       <term><replaceable class="PARAMETER"> newcolumn </replaceable></term>
  74       <listitem>
  75        <para>
  76         New name for an existing column.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><replaceable class="PARAMETER"> newtable </replaceable></term>
  83       <listitem>
  84        <para>
  85         New name for an existing column.
  86        </para>
  87       </listitem>
  88      </varlistentry>
  89     </variablelist>
  90    </para>
  91   </refsect2>
  92
  93   <refsect2 id="R2-SQL-ALTERTABLE-2">
  94    <refsect2info>
  95     <date>1998-04-15</date>
  96    </refsect2info>
  97    <title>
  98     Outputs
  99    </title>
 100    <para>
 101
 102     <variablelist>
 103      <varlistentry>
 104       <term><computeroutput>
 105 ALTER
 106        </computeroutput></term>
 107       <listitem>
 108        <para>
 109         Message returned from column or table renaming.
 110        </para>
 111       </listitem>
 112      </varlistentry>
 113
 114      <varlistentry>
 115       <term><computeroutput>
 116 NEW
 117        </computeroutput></term>
 118       <listitem>
 119        <para>
 120         Message returned from column addition.
 121        </para>
 122       </listitem>
 123      </varlistentry>
 124
 125      <varlistentry>
 126       <term><computeroutput>
 127 ERROR
 128        </computeroutput></term>
 129       <listitem>
 130        <para>
 131         Message returned if table or column is not available.
 132        </para>
 133       </listitem>
 134      </varlistentry>
 135     </variablelist>
 136    </para>
 137   </refsect2>
 138  </refsynopsisdiv>
 139
 140  <refsect1 id="R1-SQL-ALTERTABLE-1">
 141   <refsect1info>
 142    <date>1998-04-15</date>
 143   </refsect1info>
 144   <title>
 145    Description
 146   </title>
 147   <para>
 148    <command>ALTER TABLE</command> changes the definition of an existing table.
 149    The new columns and their types are specified in the same style
 150    and with the the same restrictions as in <command>CREATE TABLE</command>.
 151    The RENAME clause causes the name of a table or column
 152    to change without changing any of the data contained in
 153    the affected table. Thus, the table or column will
 154    remain of the same type and size after this command is
 155    executed.
 156   </para>
 157
 158   <para>
 159    You must own the table in order to change its schema.
 160   </para>
 161
 162   <refsect2 id="R2-SQL-ALTERTABLE-3">
 163    <refsect2info>
 164     <date>1998-04-15</date>
 165    </refsect2info>
 166    <title>
 167     Notes
 168 </title>
 169    <para>
 170     The keyword <literal>COLUMN</literal> is noise and can be omitted.
 171    </para>
 172
 173    <para>
 174     <quote>*</quote> following a name of a table indicates that the statement
 175     should be run over that table and all tables below it in the
 176     inheritance hierarchy;
 177     by default, the attribute will not be added to or renamed in any of the subclasses.
 178
 179     This should always be done when adding or modifying an attribute in a
 180     superclass. If it is not, queries on  the  inheritance  hierarchy
 181     such as
 182
 183     <programlisting>
 184 SELECT <replaceable>NewColumn</replaceable> FROM <replaceable>SuperClass</replaceable>*
 185     </programlisting>
 186
 187     will not work because the subclasses will be missing an attribute
 188     found in the superclass.
 189    </para>
 190
 191    <para>
 192     For efficiency reasons, default values for added attributes are
 193     not placed in existing instances of a class.
 194     That is, existing instances will have NULL values in the new
 195     attributes. If non-NULL  values  are  desired,  a subsequent
 196     <command>UPDATE</command> query
 197     (<xref linkend="sql-update-title" endterm="sql-update-title">)
 198     should be run.
 199    </para>
 200
 201    <para>
 202     You must own the class in order to change its schema.
 203     Renaming any  part  of  the schema of a system
 204     catalog is not permitted.
 205     The <citetitle>PostgreSQL User's Guide</citetitle> has further
 206     information on inheritance.
 207    </para>
 208
 209    <para>
 210     Refer to <command>CREATE TABLE</command> for a further description
 211     of valid arguments.
 212    </para>
 213   </refsect2>
 214  </refsect1>
 215
 216  <refsect1 id="R1-SQL-ALTERTABLE-2">
 217   <title>
 218    Usage
 219   </title>
 220   <para>
 221    To add a column of type VARCHAR to a table:
 222    <programlisting>
 223 ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
 224    </programlisting>
 225   </para>
 226
 227   <para>
 228    To rename an existing column:
 229    <programlisting>
 230 ALTER TABLE distributors RENAME COLUMN address TO city;
 231    </programlisting>
 232   </para>
 233
 234   <para>
 235    To rename an existing table:
 236    <programlisting>
 237 ALTER TABLE distributors RENAME TO suppliers;
 238    </programlisting>
 239   </para>
 240  </refsect1>
 241
 242  <refsect1 id="R1-SQL-ALTERTABLE-3">
 243   <title>
 244    Compatibility
 245   </title>
 246
 247   <refsect2 id="R2-SQL-ALTERTABLE-4">
 248    <refsect2info>
 249     <date>1998-04-15</date>
 250    </refsect2info>
 251    <title>
 252     SQL92
 253    </title>
 254    <para>
 255     <command>ALTER TABLE/RENAME</command>
 256     is a <productname>Postgres</productname> language extension.
 257    </para>
 258
 259    <para>
 260     SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
 261     statement which are not yet directly supported by
 262     <productname>Postgres</productname>:
 263    </para>
 264
 265    <variablelist>
 266     <varlistentry>
 267      <term>
 268       <synopsis>
 269 ALTER TABLE <replaceable class="PARAMETER">table</replaceable> ALTER [
 270        COLUMN ] <replaceable class="PARAMETER">column</replaceable>
 271     SET DEFAULT <replaceable class="PARAMETER">default</replaceable>
 272 ALTER TABLE <replaceable class="PARAMETER">table</replaceable> ALTER [
 273        COLUMN ] <replaceable class="PARAMETER">column</replaceable>
 274     ADD [ CONSTRAINT <replaceable class="PARAMETER">>constrain</replaceable>> ] <replaceable
 275         class="PARAMETER">table-constraint</replaceable>
 276       </synopsis>
 277      </term>
 278      <listitem>
 279       <para>
 280        Puts the default value or constraint specified into the
 281        definition of column in the table.
 282        See <command>CREATE TABLE</command> for the
 283        syntax of the default and table-constraint clauses.
 284        If a default clause already exists, it will be replaced by
 285        the new definition. If any constraints on this column already
 286        exist, they will be retained using a boolean AND with the new
 287        constraint.
 288       </para>
 289
 290       <para>
 291        Currently, to set new default constraints on an existing column
 292        the table must be recreated and reloaded:
 293
 294        <programlisting>
 295 CREATE TABLE temp AS SELECT * FROM distributors;
 296 DROP TABLE distributors;
 297 CREATE TABLE distributors (
 298     did      DECIMAL(3) DEFAULT 1,
 299     name     VARCHAR(40) NOT NULL,
 300     city     VARCHAR(30)
 301 );
 302 INSERT INTO distributors SELECT * FROM temp;
 303 DROP TABLE temp;
 304        </programlisting>
 305       </para>
 306      </listitem>
 307     </varlistentry>
 308
 309     <varlistentry>
 310      <term>
 311       <synopsis>
 312 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
 313     DROP DEFAULT <replaceable class="PARAMETER">default</replaceable>
 314 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
 315     DROP CONSTRAINT <replaceable class="PARAMETER">constraint</replaceable> { RESTRICT | CASCADE }
 316       </synopsis>
 317      </term>
 318      <listitem>
 319       <para>
 320        Removes the default value specified by default or the rule
 321        specified by constraint from the definition of a table.
 322        If RESTRICT is specified only a constraint with no dependent
 323        constraints can be destroyed.
 324        If CASCADE is specified, Any constraints that are dependent on
 325        this constraint are also dropped.
 326       </para>
 327
 328       <para>
 329        Currently, to remove a default value or constraints on an
 330        existing column the table must be recreated and reloaded:
 331
 332        <programlisting>
 333 CREATE TABLE temp AS SELECT * FROM distributors;
 334 DROP TABLE distributors;
 335 CREATE TABLE distributors AS SELECT * FROM temp;
 336 DROP TABLE temp;
 337        </programlisting>
 338       </para>
 339      </listitem>
 340     </varlistentry>
 341
 342     <varlistentry>
 343      <term>
 344       <synopsis>
 345 ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
 346     DROP [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { RESTRICT | CASCADE }
 347       </synopsis>
 348      </term>
 349      <listitem>
 350       <para>
 351        Removes a column from a table.
 352        If RESTRICT is specified only a column with no dependent
 353        objects can be destroyed.
 354        If CASCADE is specified, all objects that are dependent on
 355        this column are also dropped.
 356       </para>
 357
 358       <para>
 359        Currently, to remove an existing column the table must be
 360        recreated and reloaded:
 361
 362        <programlisting>
 363 CREATE TABLE temp AS SELECT did, city FROM distributors;
 364 DROP TABLE distributors;
 365 CREATE TABLE distributors (
 366     did      DECIMAL(3)  DEFAULT 1,
 367     name     VARCHAR(40) NOT NULL,
 368 );
 369 INSERT INTO distributors SELECT * FROM temp;
 370 DROP TABLE temp;
 371        </programlisting>
 372       </para>
 373      </listitem>
 374     </varlistentry>
 375    </variablelist>
 376   </refsect2>
 377  </refsect1>
 378 </refentry>
 379
 380 <!-- Keep this comment at the end of the file
 381 Local variables:
 382 mode: sgml
 383 sgml-omittag:nil
 384 sgml-shorttag:t
 385 sgml-minimize-attributes:nil
 386 sgml-always-quote-attributes:t
 387 sgml-indent-step:1
 388 sgml-indent-data:t
 389 sgml-parent-document:nil
 390 sgml-default-dtd-file:"../reference.ced"
 391 sgml-exposed-tags:nil
 392 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 393 sgml-local-ecat-files:nil
 394 End:
 395 -->