granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/alter_table.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.102 2008/12/13 19:13:44 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERTABLE">
   7  <refmeta>
   8   <refentrytitle id="sql-altertable-title">ALTER TABLE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>ALTER TABLE</refname>
  15   <refpurpose>change the definition of a table</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-altertable">
  19   <primary>ALTER TABLE</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ]
  25     <replaceable class="PARAMETER">action</replaceable> [, ... ]
  26 ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ]
  27     RENAME [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> TO <replaceable class="PARAMETER">new_column</replaceable>
  28 ALTER TABLE <replaceable class="PARAMETER">name</replaceable>
  29     RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
  30 ALTER TABLE <replaceable class="PARAMETER">name</replaceable>
  31     SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>
  32
  33 where <replaceable class="PARAMETER">action</replaceable> is one of:
  34
  35     ADD [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> <replaceable class="PARAMETER">type</replaceable> [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ]
  36     DROP [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> [ RESTRICT | CASCADE ]
  37     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> [ SET DATA ] TYPE <replaceable class="PARAMETER">type</replaceable> [ USING <replaceable class="PARAMETER">expression</replaceable> ]
  38     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET DEFAULT <replaceable class="PARAMETER">expression</replaceable>
  39     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> DROP DEFAULT
  40     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> { SET | DROP } NOT NULL
  41     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STATISTICS <replaceable class="PARAMETER">integer</replaceable>
  42     ALTER [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }
  43     ADD <replaceable class="PARAMETER">table_constraint</replaceable>
  44     DROP CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> [ RESTRICT | CASCADE ]
  45     DISABLE TRIGGER [ <replaceable class="PARAMETER">trigger_name</replaceable> | ALL | USER ]
  46     ENABLE TRIGGER [ <replaceable class="PARAMETER">trigger_name</replaceable> | ALL | USER ]
  47     ENABLE REPLICA TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable>
  48     ENABLE ALWAYS TRIGGER <replaceable class="PARAMETER">trigger_name</replaceable>
  49     DISABLE RULE <replaceable class="PARAMETER">rewrite_rule_name</replaceable>
  50     ENABLE RULE <replaceable class="PARAMETER">rewrite_rule_name</replaceable>
  51     ENABLE REPLICA RULE <replaceable class="PARAMETER">rewrite_rule_name</replaceable>
  52     ENABLE ALWAYS RULE <replaceable class="PARAMETER">rewrite_rule_name</replaceable>
  53     CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable>
  54     SET WITHOUT CLUSTER
  55     SET WITHOUT OIDS
  56     SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )
  57     RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )
  58     INHERIT <replaceable class="PARAMETER">parent_table</replaceable>
  59     NO INHERIT <replaceable class="PARAMETER">parent_table</replaceable>
  60     OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
  61     SET TABLESPACE <replaceable class="PARAMETER">new_tablespace</replaceable>
  62 </synopsis>
  63  </refsynopsisdiv>
  64
  65  <refsect1>
  66   <title>Description</title>
  67
  68   <para>
  69    <command>ALTER TABLE</command> changes the definition of an existing table.
  70    There are several subforms:
  71
  72   <variablelist>
  73    <varlistentry>
  74     <term><literal>ADD COLUMN</literal></term>
  75     <listitem>
  76      <para>
  77       This form adds a new column to the table, using the same syntax as
  78       <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-TITLE">.
  79      </para>
  80     </listitem>
  81    </varlistentry>
  82
  83    <varlistentry>
  84     <term><literal>DROP COLUMN</literal></term>
  85     <listitem>
  86      <para>
  87       This form drops a column from a table.  Indexes and
  88       table constraints involving the column will be automatically
  89       dropped as well.  You will need to say <literal>CASCADE</> if
  90       anything outside the table depends on the column, for example,
  91       foreign key references or views.
  92      </para>
  93     </listitem>
  94    </varlistentry>
  95
  96    <varlistentry>
  97     <term><literal>SET DATA TYPE</literal></term>
  98     <listitem>
  99      <para>
 100       This form changes the type of a column of a table. Indexes and
 101       simple table constraints involving the column will be automatically
 102       converted to use the new column type by reparsing the originally
 103       supplied expression.  The optional <literal>USING</literal>
 104       clause specifies how to compute the new column value from the old;
 105       if omitted, the default conversion is the same as an assignment
 106       cast from old data type to new.  A  <literal>USING</literal>
 107       clause must be provided if there is no implicit or assignment
 108       cast from old to new type.
 109      </para>
 110     </listitem>
 111    </varlistentry>
 112
 113    <varlistentry>
 114     <term><literal>SET</literal>/<literal>DROP DEFAULT</literal></term>
 115     <listitem>
 116      <para>
 117       These forms set or remove the default value for a column.
 118       The default values only apply to subsequent <command>INSERT</command>
 119       commands; they do not cause rows already in the table to change.
 120       Defaults can also be created for views, in which case they are
 121       inserted into <command>INSERT</> statements on the view before
 122       the view's <literal>ON INSERT</literal> rule is applied.
 123      </para>
 124     </listitem>
 125    </varlistentry>
 126
 127    <varlistentry>
 128     <term><literal>SET</literal>/<literal>DROP NOT NULL</literal></term>
 129     <listitem>
 130      <para>
 131       These forms change whether a column is marked to allow null
 132       values or to reject null values.  You can only use <literal>SET
 133       NOT NULL</> when the column contains no null values.
 134      </para>
 135     </listitem>
 136    </varlistentry>
 137
 138    <varlistentry>
 139     <term><literal>SET STATISTICS</literal></term>
 140     <listitem>
 141      <para>
 142       This form
 143       sets the per-column statistics-gathering target for subsequent
 144       <xref linkend="sql-analyze" endterm="sql-analyze-title"> operations.
 145       The target can be set in the range 0 to 10000; alternatively, set it
 146       to -1 to revert to using the system default statistics
 147       target (<xref linkend="guc-default-statistics-target">).
 148       For more information on the use of statistics by the
 149       <productname>PostgreSQL</productname> query planner, refer to
 150       <xref linkend="planner-stats">.
 151      </para>
 152     </listitem>
 153    </varlistentry>
 154
 155    <varlistentry>
 156     <indexterm>
 157      <primary>TOAST</primary>
 158      <secondary>per-column storage settings</secondary>
 159     </indexterm>
 160
 161     <term><literal>SET STORAGE</literal></term>
 162     <listitem>
 163      <para>
 164       This form sets the storage mode for a column. This controls whether this
 165       column is held inline or in a supplementary table, and whether the data
 166       should be compressed or not. <literal>PLAIN</literal> must be used
 167       for fixed-length values such as <type>integer</type> and is
 168       inline, uncompressed. <literal>MAIN</literal> is for inline,
 169       compressible data. <literal>EXTERNAL</literal> is for external,
 170       uncompressed data, and <literal>EXTENDED</literal> is for external,
 171       compressed data.  <literal>EXTENDED</literal> is the default for most
 172       data types that support non-<literal>PLAIN</literal> storage.
 173       Use of <literal>EXTERNAL</literal> will
 174       make substring operations on <type>text</type> and <type>bytea</type>
 175       columns faster, at the penalty of increased storage space.  Note that
 176       <literal>SET STORAGE</> doesn't itself change anything in the table,
 177       it just sets the strategy to be pursued during future table updates.
 178       See <xref linkend="storage-toast"> for more information.
 179      </para>
 180     </listitem>
 181    </varlistentry>
 182
 183    <varlistentry>
 184     <term><literal>ADD <replaceable class="PARAMETER">table_constraint</replaceable></literal></term>
 185     <listitem>
 186      <para>
 187       This form adds a new constraint to a table using the same syntax as
 188       <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-TITLE">.
 189      </para>
 190     </listitem>
 191    </varlistentry>
 192
 193    <varlistentry>
 194     <term><literal>DROP CONSTRAINT</literal></term>
 195     <listitem>
 196      <para>
 197       This form drops the specified constraint on a table.
 198      </para>
 199     </listitem>
 200    </varlistentry>
 201
 202    <varlistentry>
 203     <term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] TRIGGER</literal></term>
 204     <listitem>
 205      <para>
 206       These forms configure the firing of trigger(s) belonging to the table.
 207       A disabled trigger is still known to the system, but is not executed
 208       when its triggering event occurs.  For a deferred trigger, the enable
 209       status is checked when the event occurs, not when the trigger function
 210       is actually executed.  One can disable or enable a single
 211       trigger specified by name, or all triggers on the table, or only
 212       user triggers (this option excludes triggers that are used to implement
 213       foreign key constraints).  Disabling or enabling constraint triggers
 214       requires superuser privileges; it should be done with caution since
 215       of course the integrity of the constraint cannot be guaranteed if the
 216       triggers are not executed.
 217       The trigger firing mechanism is also affected by the configuration
 218       variable <xref linkend="guc-session-replication-role">. Simply enabled
 219       triggers will fire when the replication role is <quote>origin</>
 220       (the default) or <quote>local</>. Triggers configured <literal>ENABLE REPLICA</literal>
 221       will only fire if the session is in <quote>replica</> mode and triggers
 222       configured <literal>ENABLE ALWAYS</literal> will fire regardless of the current replication
 223       mode.
 224      </para>
 225     </listitem>
 226    </varlistentry>
 227
 228    <varlistentry>
 229     <term><literal>DISABLE</literal>/<literal>ENABLE [ REPLICA | ALWAYS ] RULE</literal></term>
 230     <listitem>
 231      <para>
 232       These forms configure the firing of rewrite rules belonging to the table.
 233       A disabled rule is still known to the system, but is not applied
 234       during query rewriting. The semantics are as for disabled/enabled
 235       triggers. This configuration is ignored for <literal>ON SELECT</literal> rules, which
 236       are always applied in order to keep views working even if the current
 237       session is in a non-default replication role.
 238      </para>
 239     </listitem>
 240    </varlistentry>
 241
 242    <varlistentry>
 243     <term><literal>CLUSTER</literal></term>
 244     <listitem>
 245      <para>
 246       This form selects the default index for future
 247       <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">
 248       operations.  It does not actually re-cluster the table.
 249      </para>
 250     </listitem>
 251    </varlistentry>
 252
 253    <varlistentry>
 254     <term><literal>SET WITHOUT CLUSTER</literal></term>
 255     <listitem>
 256      <para>
 257       This form removes the most recently used
 258       <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">
 259       index specification from the table.  This affects
 260       future cluster operations that don't specify an index.
 261      </para>
 262     </listitem>
 263    </varlistentry>
 264
 265    <varlistentry>
 266     <term><literal>SET WITHOUT OIDS</literal></term>
 267     <listitem>
 268      <para>
 269       This form removes the <literal>oid</literal> system column from the
 270       table.  This is exactly equivalent to
 271       <literal>DROP COLUMN oid RESTRICT</literal>,
 272       except that it will not complain if there is already no
 273       <literal>oid</literal> column.
 274      </para>
 275
 276      <para>
 277       Note that there is no variant of <command>ALTER TABLE</command>
 278       that allows OIDs to be restored to a table once they have been
 279       removed.
 280      </para>
 281     </listitem>
 282    </varlistentry>
 283
 284    <varlistentry>
 285     <term><literal>SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )</literal></term>
 286     <listitem>
 287      <para>
 288       This form changes one or more storage parameters for the table.  See
 289       <xref linkend="SQL-CREATETABLE" endterm="sql-createtable-title">
 290       for details on the available parameters.  Note that the table contents
 291       will not be modified immediately by this command; depending on the
 292       parameter you might need to rewrite the table to get the desired effects.
 293       That can be done with <xref linkend="SQL-CLUSTER"
 294       endterm="sql-cluster-title"> or one of the forms of <command>ALTER
 295       TABLE</> that forces a table rewrite.
 296      </para>
 297
 298      <note>
 299       <para>
 300        While <command>CREATE TABLE</> allows <literal>OIDS</> to be specified
 301        in the <literal>WITH (<replaceable
 302        class="PARAMETER">storage_parameter</>)</literal> syntax,
 303        <command>ALTER TABLE</> does not treat <literal>OIDS</> as a
 304        storage parameter.
 305       </para>
 306      </note>
 307     </listitem>
 308    </varlistentry>
 309
 310    <varlistentry>
 311     <term><literal>RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )</literal></term>
 312     <listitem>
 313      <para>
 314       This form resets one or more storage parameters to their
 315       defaults.  As with <literal>SET</>, a table rewrite might be
 316       needed to update the table entirely.
 317      </para>
 318     </listitem>
 319    </varlistentry>
 320
 321    <varlistentry>
 322     <term><literal>INHERIT <replaceable class="PARAMETER">parent_table</replaceable></literal></term>
 323     <listitem>
 324      <para>
 325       This form adds the target table as a new child of the specified parent
 326       table.  Subsequently, queries against the parent will include records
 327       of the target table.  To be added as a child, the target table must
 328       already contain all the same columns as the parent (it could have
 329       additional columns, too).  The columns must have matching data types,
 330       and if they have <literal>NOT NULL</literal> constraints in the parent
 331       then they must also have <literal>NOT NULL</literal> constraints in the
 332       child.
 333      </para>
 334
 335      <para>
 336       There must also be matching child-table constraints for all
 337       <literal>CHECK</literal> constraints of the parent. Currently
 338       <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and
 339       <literal>FOREIGN KEY</literal> constraints are not considered, but
 340       this might change in the future.
 341      </para>
 342     </listitem>
 343    </varlistentry>
 344
 345    <varlistentry>
 346     <term><literal>NO INHERIT <replaceable class="PARAMETER">parent_table</replaceable></literal></term>
 347     <listitem>
 348      <para>
 349       This form removes the target table from the list of children of the
 350       specified parent table.
 351       Queries against the parent table will no longer include records drawn
 352       from the target table.
 353      </para>
 354     </listitem>
 355    </varlistentry>
 356
 357    <varlistentry>
 358     <term><literal>OWNER</literal></term>
 359     <listitem>
 360      <para>
 361       This form changes the owner of the table, sequence, or view to the
 362       specified user.
 363      </para>
 364     </listitem>
 365    </varlistentry>
 366
 367    <varlistentry>
 368     <term><literal>SET TABLESPACE</literal></term>
 369     <listitem>
 370      <para>
 371       This form changes the table's tablespace to the specified tablespace and
 372       moves the data file(s) associated with the table to the new tablespace.
 373       Indexes on the table, if any, are not moved; but they can be moved
 374       separately with additional <literal>SET TABLESPACE</literal> commands.
 375       See also
 376       <xref linkend="SQL-CREATETABLESPACE" endterm="sql-createtablespace-title">.
 377      </para>
 378     </listitem>
 379    </varlistentry>
 380
 381    <varlistentry>
 382     <term><literal>RENAME</literal></term>
 383     <listitem>
 384      <para>
 385       The <literal>RENAME</literal> forms change the name of a table
 386       (or an index, sequence, or view) or the name of an individual column in
 387       a table. There is no effect on the stored data.
 388      </para>
 389     </listitem>
 390    </varlistentry>
 391
 392    <varlistentry>
 393     <term><literal>SET SCHEMA</literal></term>
 394     <listitem>
 395      <para>
 396       This form moves the table into another schema.  Associated indexes,
 397       constraints, and sequences owned by table columns are moved as well.
 398      </para>
 399     </listitem>
 400    </varlistentry>
 401
 402   </variablelist>
 403   </para>
 404
 405   <para>
 406    All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</>
 407    can be combined into
 408    a list of multiple alterations to apply in parallel.  For example, it
 409    is possible to add several columns and/or alter the type of several
 410    columns in a single command.  This is particularly useful with large
 411    tables, since only one pass over the table need be made.
 412   </para>
 413
 414   <para>
 415    You must own the table to use <command>ALTER TABLE</>.
 416    To change the schema of a table, you must also have
 417    <literal>CREATE</literal> privilege on the new schema.
 418    To add the table as a new child of a parent table, you must own the
 419    parent table as well.
 420    To alter the owner, you must also be a direct or indirect member of the new
 421    owning role, and that role must have <literal>CREATE</literal> privilege on
 422    the table's schema.  (These restrictions enforce that altering the owner
 423    doesn't do anything you couldn't do by dropping and recreating the table.
 424    However, a superuser can alter ownership of any table anyway.)
 425   </para>
 426  </refsect1>
 427
 428  <refsect1>
 429   <title>Parameters</title>
 430
 431     <variablelist>
 432
 433      <varlistentry>
 434       <term><replaceable class="PARAMETER">name</replaceable></term>
 435       <listitem>
 436        <para>
 437         The name (possibly schema-qualified) of an existing table to
 438         alter. If <literal>ONLY</> is specified, only that table is
 439         altered. If <literal>ONLY</> is not specified, the table and all
 440         its descendant tables (if any) are updated. <literal>*</> can be
 441         appended to the table name to indicate that descendant tables are
 442         to be altered, but in the current version, this is the default
 443         behavior.  (In releases before 7.1, <literal>ONLY</> was the
 444         default behavior.  The default can be altered by changing the
 445         configuration parameter <xref linkend="guc-sql-inheritance">.)
 446        </para>
 447       </listitem>
 448      </varlistentry>
 449
 450      <varlistentry>
 451       <term><replaceable class="PARAMETER">column</replaceable></term>
 452       <listitem>
 453        <para>
 454         Name of a new or existing column.
 455        </para>
 456       </listitem>
 457      </varlistentry>
 458
 459      <varlistentry>
 460       <term><replaceable class="PARAMETER">new_column</replaceable></term>
 461       <listitem>
 462        <para>
 463         New name for an existing column.
 464        </para>
 465       </listitem>
 466      </varlistentry>
 467
 468      <varlistentry>
 469       <term><replaceable class="PARAMETER">new_name</replaceable></term>
 470       <listitem>
 471        <para>
 472         New name for the table.
 473        </para>
 474       </listitem>
 475      </varlistentry>
 476
 477      <varlistentry>
 478       <term><replaceable class="PARAMETER">type</replaceable></term>
 479       <listitem>
 480        <para>
 481         Data type of the new column, or new data type for an existing
 482         column.
 483        </para>
 484       </listitem>
 485      </varlistentry>
 486
 487      <varlistentry>
 488       <term><replaceable class="PARAMETER">table_constraint</replaceable></term>
 489       <listitem>
 490        <para>
 491         New table constraint for the table.
 492        </para>
 493       </listitem>
 494      </varlistentry>
 495
 496      <varlistentry>
 497       <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
 498       <listitem>
 499        <para>
 500         Name of an existing constraint to drop.
 501        </para>
 502       </listitem>
 503      </varlistentry>
 504
 505      <varlistentry>
 506       <term><literal>CASCADE</literal></term>
 507       <listitem>
 508        <para>
 509         Automatically drop objects that depend on the dropped column
 510         or constraint (for example, views referencing the column).
 511        </para>
 512       </listitem>
 513      </varlistentry>
 514
 515      <varlistentry>
 516       <term><literal>RESTRICT</literal></term>
 517       <listitem>
 518        <para>
 519         Refuse to drop the column or constraint if there are any dependent
 520         objects. This is the default behavior.
 521        </para>
 522       </listitem>
 523      </varlistentry>
 524
 525      <varlistentry>
 526       <term><replaceable class="PARAMETER">trigger_name</replaceable></term>
 527       <listitem>
 528        <para>
 529         Name of a single trigger to disable or enable.
 530        </para>
 531       </listitem>
 532      </varlistentry>
 533
 534      <varlistentry>
 535       <term><literal>ALL</literal></term>
 536       <listitem>
 537        <para>
 538         Disable or enable all triggers belonging to the table.
 539         (This requires superuser privilege if any of the triggers are for
 540         foreign key constraints.)
 541        </para>
 542       </listitem>
 543      </varlistentry>
 544
 545      <varlistentry>
 546       <term><literal>USER</literal></term>
 547       <listitem>
 548        <para>
 549         Disable or enable all triggers belonging to the table except for
 550         foreign key constraint triggers.
 551        </para>
 552       </listitem>
 553      </varlistentry>
 554
 555      <varlistentry>
 556       <term><replaceable class="PARAMETER">index_name</replaceable></term>
 557       <listitem>
 558        <para>
 559         The index name on which the table should be marked for clustering.
 560        </para>
 561       </listitem>
 562      </varlistentry>
 563
 564      <varlistentry>
 565       <term><replaceable class="PARAMETER">storage_parameter</replaceable></term>
 566       <listitem>
 567        <para>
 568         The name of a table storage parameter.
 569        </para>
 570       </listitem>
 571      </varlistentry>
 572
 573      <varlistentry>
 574       <term><replaceable class="PARAMETER">value</replaceable></term>
 575       <listitem>
 576        <para>
 577         The new value for a table storage parameter.
 578         This might be a number or a word depending on the parameter.
 579        </para>
 580       </listitem>
 581      </varlistentry>
 582
 583      <varlistentry>
 584       <term><replaceable class="PARAMETER">parent_table</replaceable></term>
 585       <listitem>
 586        <para>
 587         A parent table to associate or de-associate with this table.
 588        </para>
 589       </listitem>
 590      </varlistentry>
 591
 592      <varlistentry>
 593       <term><replaceable class="PARAMETER">new_owner</replaceable></term>
 594       <listitem>
 595        <para>
 596         The user name of the new owner of the table.
 597        </para>
 598       </listitem>
 599      </varlistentry>
 600
 601      <varlistentry>
 602       <term><replaceable class="PARAMETER">new_tablespace</replaceable></term>
 603       <listitem>
 604        <para>
 605         The name of the tablespace to which the table will be moved.
 606        </para>
 607       </listitem>
 608      </varlistentry>
 609
 610      <varlistentry>
 611       <term><replaceable class="PARAMETER">new_schema</replaceable></term>
 612       <listitem>
 613        <para>
 614         The name of the schema to which the table will be moved.
 615        </para>
 616       </listitem>
 617      </varlistentry>
 618
 619     </variablelist>
 620  </refsect1>
 621
 622  <refsect1>
 623   <title>Notes</title>
 624
 625    <para>
 626     The key word <literal>COLUMN</literal> is noise and can be omitted.
 627    </para>
 628
 629    <para>
 630     When a column is added with <literal>ADD COLUMN</literal>, all existing
 631     rows in the table are initialized with the column's default value
 632     (NULL if no <literal>DEFAULT</> clause is specified).
 633    </para>
 634
 635    <para>
 636     Adding a column with a non-null default or changing the type of an
 637     existing column will require the entire table to be rewritten.  This
 638     might take a significant amount of time for a large table; and it will
 639     temporarily require double the disk space.
 640    </para>
 641
 642    <para>
 643     Adding a <literal>CHECK</> or <literal>NOT NULL</> constraint requires
 644     scanning the table to verify that existing rows meet the constraint.
 645    </para>
 646
 647    <para>
 648     The main reason for providing the option to specify multiple changes
 649     in a single <command>ALTER TABLE</> is that multiple table scans or
 650     rewrites can thereby be combined into a single pass over the table.
 651    </para>
 652
 653    <para>
 654     The <literal>DROP COLUMN</literal> form does not physically remove
 655     the column, but simply makes it invisible to SQL operations.  Subsequent
 656     insert and update operations in the table will store a null value for the
 657     column. Thus, dropping a column is quick but it will not immediately
 658     reduce the on-disk size of your table, as the space occupied
 659     by the dropped column is not reclaimed.  The space will be
 660     reclaimed over time as existing rows are updated.
 661    </para>
 662
 663    <para>
 664     The fact that <literal>ALTER TYPE</> requires rewriting the whole table
 665     is sometimes an advantage, because the rewriting process eliminates
 666     any dead space in the table.  For example, to reclaim the space occupied
 667     by a dropped column immediately, the fastest way is:
 668 <programlisting>
 669 ALTER TABLE table ALTER COLUMN anycol TYPE anytype;
 670 </programlisting>
 671     where <literal>anycol</> is any remaining table column and
 672     <literal>anytype</> is the same type that column already has.
 673     This results in no semantically-visible change in the table,
 674     but the command forces rewriting, which gets rid of no-longer-useful
 675     data.
 676    </para>
 677
 678    <para>
 679     The <literal>USING</literal> option of <literal>ALTER TYPE</> can actually
 680     specify any expression involving the old values of the row; that is, it
 681     can refer to other columns as well as the one being converted.  This allows
 682     very general conversions to be done with the <literal>ALTER TYPE</>
 683     syntax.  Because of this flexibility, the <literal>USING</literal>
 684     expression is not applied to the column's default value (if any); the
 685     result might not be a constant expression as required for a default.
 686     This means that when there is no implicit or assignment cast from old to
 687     new type, <literal>ALTER TYPE</> might fail to convert the default even
 688     though a <literal>USING</literal> clause is supplied.  In such cases,
 689     drop the default with <literal>DROP DEFAULT</>, perform the <literal>ALTER
 690     TYPE</>, and then use <literal>SET DEFAULT</> to add a suitable new
 691     default.  Similar considerations apply to indexes and constraints involving
 692     the column.
 693    </para>
 694
 695    <para>
 696     If a table has any descendant tables, it is not permitted to add,
 697     rename, or change the type of a column in the parent table without doing
 698     the same to the descendants.  That is, <command>ALTER TABLE ONLY</command>
 699     will be rejected.  This ensures that the descendants always have
 700     columns matching the parent.
 701    </para>
 702
 703    <para>
 704     A recursive <literal>DROP COLUMN</literal> operation will remove a
 705     descendant table's column only if the descendant does not inherit
 706     that column from any other parents and never had an independent
 707     definition of the column.  A nonrecursive <literal>DROP
 708     COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP
 709     COLUMN</command>) never removes any descendant columns, but
 710     instead marks them as independently defined rather than inherited.
 711    </para>
 712
 713    <para>
 714     The <literal>TRIGGER</>, <literal>CLUSTER</>, <literal>OWNER</>,
 715     and <literal>TABLESPACE</> actions never recurse to descendant tables;
 716     that is, they always act as though <literal>ONLY</> were specified.
 717     Adding a constraint can recurse only for <literal>CHECK</> constraints,
 718     and is required to do so for such constraints.
 719    </para>
 720
 721    <para>
 722     Changing any part of a system catalog table is not permitted.
 723    </para>
 724
 725    <para>
 726     Refer to <xref linkend="sql-createtable"
 727     endterm="sql-createtable-title"> for a further description of valid
 728     parameters. <xref linkend="ddl"> has further information on
 729     inheritance.
 730    </para>
 731  </refsect1>
 732
 733  <refsect1>
 734   <title>Examples</title>
 735
 736   <para>
 737    To add a column of type <type>varchar</type> to a table:
 738 <programlisting>
 739 ALTER TABLE distributors ADD COLUMN address varchar(30);
 740 </programlisting>
 741   </para>
 742
 743   <para>
 744    To drop a column from a table:
 745 <programlisting>
 746 ALTER TABLE distributors DROP COLUMN address RESTRICT;
 747 </programlisting>
 748   </para>
 749
 750   <para>
 751    To change the types of two existing columns in one operation:
 752 <programlisting>
 753 ALTER TABLE distributors
 754     ALTER COLUMN address TYPE varchar(80),
 755     ALTER COLUMN name TYPE varchar(100);
 756 </programlisting>
 757   </para>
 758
 759   <para>
 760    To change an integer column containing UNIX timestamps to <type>timestamp
 761    with time zone</type> via a <literal>USING</literal> clause:
 762 <programlisting>
 763 ALTER TABLE foo
 764     ALTER COLUMN foo_timestamp SET DATA TYPE timestamp with time zone
 765     USING
 766         timestamp with time zone 'epoch' + foo_timestamp * interval '1 second';
 767 </programlisting>
 768   </para>
 769
 770   <para>
 771    The same, when the column has a default expression that won't automatically
 772    cast to the new data type:
 773 <programlisting>
 774 ALTER TABLE foo
 775     ALTER COLUMN foo_timestamp DROP DEFAULT,
 776     ALTER COLUMN foo_timestamp TYPE timestamp with time zone
 777     USING
 778         timestamp with time zone 'epoch' + foo_timestamp * interval '1 second',
 779     ALTER COLUMN foo_timestamp SET DEFAULT now();
 780 </programlisting>
 781   </para>
 782
 783   <para>
 784    To rename an existing column:
 785 <programlisting>
 786 ALTER TABLE distributors RENAME COLUMN address TO city;
 787 </programlisting>
 788   </para>
 789
 790   <para>
 791    To rename an existing table:
 792 <programlisting>
 793 ALTER TABLE distributors RENAME TO suppliers;
 794 </programlisting>
 795   </para>
 796
 797   <para>
 798    To add a not-null constraint to a column:
 799 <programlisting>
 800 ALTER TABLE distributors ALTER COLUMN street SET NOT NULL;
 801 </programlisting>
 802    To remove a not-null constraint from a column:
 803 <programlisting>
 804 ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL;
 805 </programlisting>
 806   </para>
 807
 808   <para>
 809    To add a check constraint to a table and all its children:
 810 <programlisting>
 811 ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5);
 812 </programlisting>
 813   </para>
 814
 815   <para>
 816    To remove a check constraint from a table and all its children:
 817 <programlisting>
 818 ALTER TABLE distributors DROP CONSTRAINT zipchk;
 819 </programlisting>
 820   </para>
 821
 822   <para>
 823    To remove a check constraint from a table only:
 824 <programlisting>
 825 ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
 826 </programlisting>
 827    (The check constraint remains in place for any child tables.)
 828   </para>
 829
 830   <para>
 831    To add a foreign key constraint to a table:
 832 <programlisting>
 833 ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) MATCH FULL;
 834 </programlisting>
 835   </para>
 836
 837   <para>
 838    To add a (multicolumn) unique constraint to a table:
 839 <programlisting>
 840 ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode);
 841 </programlisting>
 842   </para>
 843
 844   <para>
 845    To add an automatically named primary key constraint to a table, noting
 846    that a table can only ever have one primary key:
 847 <programlisting>
 848 ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
 849 </programlisting>
 850   </para>
 851
 852   <para>
 853    To move a table to a different tablespace:
 854 <programlisting>
 855 ALTER TABLE distributors SET TABLESPACE fasttablespace;
 856 </programlisting>
 857   </para>
 858
 859   <para>
 860    To move a table to a different schema:
 861 <programlisting>
 862 ALTER TABLE myschema.distributors SET SCHEMA yourschema;
 863 </programlisting>
 864   </para>
 865
 866  </refsect1>
 867
 868  <refsect1>
 869   <title>Compatibility</title>
 870
 871   <para>
 872    The forms <literal>ADD</literal>, <literal>DROP</>, <literal>SET DEFAULT</>,
 873    and <literal>SET DATA TYPE</literal> (without <literal>USING</literal>)
 874    conform with the SQL standard.  The other forms are
 875    <productname>PostgreSQL</productname> extensions of the SQL standard.
 876    Also, the ability to specify more than one manipulation in a single
 877    <command>ALTER TABLE</> command is an extension.
 878   </para>
 879
 880   <para>
 881    <command>ALTER TABLE DROP COLUMN</> can be used to drop the only
 882    column of a table, leaving a zero-column table.  This is an
 883    extension of SQL, which disallows zero-column tables.
 884   </para>
 885  </refsect1>
 886 </refentry>