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

   1 <REFENTRY ID="SQL-ALTERTABLE">
   2 <REFMETA>
   3 <REFENTRYTITLE>
   4 ALTER TABLE
   5 </REFENTRYTITLE>
   6 <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
   7 </REFMETA>
   8 <REFNAMEDIV>
   9 <REFNAME>
  10 ALTER TABLE
  11 </REFNAME>
  12 <REFPURPOSE>
  13 Modifies table properties
  14 </REFPURPOSE>
  15 </refnamediv>
  16 <REFSYNOPSISDIV>
  17 <REFSYNOPSISDIVINFO>
  18 <DATE>1998-04-15</DATE>
  19 </REFSYNOPSISDIVINFO>
  20 <SYNOPSIS>
  21 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
  22     [ * ] ADD [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">type</REPLACEABLE>
  23 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
  24     [ * ] RENAME [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> TO <REPLACEABLE CLASS="PARAMETER">newcolumn</REPLACEABLE>
  25 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
  26     RENAME TO <REPLACEABLE CLASS="PARAMETER">newtable</REPLACEABLE>
  27 </SYNOPSIS>
  28
  29 <REFSECT2 ID="R2-SQL-ALTERTABLE-1">
  30 <REFSECT2INFO>
  31 <DATE>1998-04-15</DATE>
  32 </REFSECT2INFO>
  33 <TITLE>
  34 Inputs
  35 </TITLE>
  36 <PARA>
  37 <VARIABLELIST>
  38 <VARLISTENTRY>
  39 <TERM>
  40 <REPLACEABLE CLASS="PARAMETER"> table </REPLACEABLE>
  41 </TERM>
  42 <LISTITEM>
  43 <PARA>
  44           The name of an existing table to alter.
  45 </PARA>
  46 </LISTITEM>
  47 </VARLISTENTRY>
  48
  49 <VARLISTENTRY>
  50 <TERM>
  51 <REPLACEABLE CLASS="PARAMETER"> column </REPLACEABLE>
  52 </TERM>
  53 <LISTITEM>
  54 <PARA>
  55           Name of a new or existing column.
  56 </PARA>
  57 </LISTITEM>
  58 </VARLISTENTRY>
  59
  60 <VARLISTENTRY>
  61 <TERM>
  62 <REPLACEABLE CLASS="PARAMETER"> type </REPLACEABLE>
  63 </TERM>
  64 <LISTITEM>
  65 <PARA>
  66           Type of the new column.
  67 </PARA>
  68 </LISTITEM>
  69 </VARLISTENTRY>
  70
  71 <VARLISTENTRY>
  72 <TERM>
  73 <REPLACEABLE CLASS="PARAMETER"> newcolumn </REPLACEABLE>
  74 </TERM>
  75 <LISTITEM>
  76 <PARA>
  77           New name for an existing column.
  78 </PARA>
  79 </LISTITEM>
  80 </VARLISTENTRY>
  81
  82 <VARLISTENTRY>
  83 <TERM>
  84 <REPLACEABLE CLASS="PARAMETER"> newtable </REPLACEABLE>
  85 </TERM>
  86 <LISTITEM>
  87 <PARA>
  88           New name for an existing column.
  89 </PARA>
  90 </LISTITEM>
  91 </VARLISTENTRY>
  92 </VARIABLELIST>
  93 </para>
  94 </REFSECT2>
  95
  96 <REFSECT2 ID="R2-SQL-ALTERTABLE-2">
  97 <REFSECT2INFO>
  98 <DATE>1998-04-15</DATE>
  99 </REFSECT2INFO>
 100 <TITLE>
 101 Outputs
 102 </TITLE>
 103 <PARA>
 104
 105 <VARIABLELIST>
 106 <VARLISTENTRY>
 107 <TERM>
 108 <returnvalue>ALTER</returnvalue>
 109 </TERM>
 110 <LISTITEM>
 111 <PARA>
 112           Message returned from column or table renaming.
 113 </PARA>
 114 </LISTITEM>
 115 </VARLISTENTRY>
 116
 117 <VARLISTENTRY>
 118 <TERM>
 119 <returnvalue>NEW</returnvalue>
 120 </TERM>
 121 <LISTITEM>
 122 <PARA>
 123           Message returned from column addition.
 124 </PARA>
 125 </LISTITEM>
 126 </VARLISTENTRY>
 127
 128 <VARLISTENTRY>
 129 <TERM>
 130 <ReturnValue>ERROR</ReturnValue>
 131 </TERM>
 132 <LISTITEM>
 133 <PARA>
 134           Message returned if table or column is not available.
 135 </para>
 136 </listitem>
 137 </VARLISTENTRY>
 138 </VARIABLELIST>
 139 </para>
 140 </REFSECT2>
 141 </REFSYNOPSISDIV>
 142
 143 <REFSECT1 ID="R1-SQL-ALTERTABLE-1">
 144 <REFSECT1INFO>
 145 <DATE>1998-04-15</DATE>
 146 </REFSECT1INFO>
 147 <TITLE>
 148 Description
 149 </TITLE>
 150 <PARA>
 151    <command>ALTER TABLE</command> changes the definition of an existing table.
 152    The new columns and their types are specified in the same style
 153    and with the the same restrictions as in <command>CREATE TABLE</command>.
 154    The RENAME clause causes the name of a table or column
 155    to change without changing any of the data contained in
 156    the affected table. Thus, the table or column will
 157    remain of the same type and size after this command is
 158    executed.
 159 </para>
 160 <PARA>
 161    You must own the table in order to change its schema.
 162 </PARA>
 163
 164 <REFSECT2 ID="R2-SQL-ALTERTABLE-3">
 165 <REFSECT2INFO>
 166 <DATE>1998-04-15</DATE>
 167 </REFSECT2INFO>
 168 <TITLE>
 169 Notes
 170 </TITLE>
 171 <PARA>
 172 The keyword COLUMN is noise and can be omitted.
 173 </para>
 174 <PARA>
 175 <Quote>[*]</Quote> following a name of a table indicates that statement
 176      should be run over that table and all tables below it in the
 177      inheritance hierarchy.
 178     The <citetitle>PostgreSQL User's Guide</citetitle> has further
 179      information on inheritance.
 180 </para>
 181
 182 <PARA>
 183    Refer to CREATE TABLE for a further description
 184      of valid arguments.
 185 </para>
 186 </REFSECT2>
 187 </REFSECT1>
 188
 189 <REFSECT1 ID="R1-SQL-ALTERTABLE-2">
 190 <TITLE>
 191 Usage
 192 </TITLE>
 193 <PARA>
 194    To add a column of type VARCHAR to a table:
 195 <ProgramListing>
 196     ALTER TABLE distributors ADD COLUMN address VARCHAR(30);
 197 </ProgramListing>
 198 </para>
 199
 200 <PARA>
 201    To rename an existing column:
 202 <ProgramListing>
 203     ALTER TABLE distributors RENAME COLUMN address TO city;
 204 </ProgramListing>
 205 </para>
 206
 207 <PARA>
 208    To rename an existing table:
 209 <ProgramListing>
 210     ALTER TABLE distributors RENAME TO suppliers;
 211 </ProgramListing>
 212 </para>
 213
 214 </REFSECT1>
 215
 216 <REFSECT1 ID="R1-SQL-ALTERTABLE-3">
 217 <TITLE>
 218 Compatibility
 219 </TITLE>
 220
 221 <REFSECT2 ID="R2-SQL-ALTERTABLE-4">
 222 <REFSECT2INFO>
 223 <DATE>1998-04-15</DATE>
 224 </REFSECT2INFO>
 225 <TITLE>
 226 SQL92
 227 </TITLE>
 228 <PARA>
 229 <command>ALTER TABLE/RENAME</command>
 230  is a <productname>Postgres</productname> language extension.
 231 </para>
 232
 233 <PARA>
 234    SQL92 specifies some additional capabilities for <command>ALTER TABLE</command>
 235    statement which are not yet directly supported by
 236  <ProductName>Postgres</ProductName>:
 237 </para>
 238
 239 <VARIABLELIST>
 240 <VARLISTENTRY>
 241 <TERM>
 242 <Synopsis>
 243 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
 244     SET DEFAULT <REPLACEABLE CLASS="PARAMETER">default</REPLACEABLE>
 245
 246 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ALTER [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
 247     ADD [ CONSTRAINT <REPLACEABLE CLASS="PARAMETER">constraint</REPLACEABLE> ] <REPLACEABLE CLASS="PARAMETER">table-constraint</REPLACEABLE>
 248 </Synopsis>
 249 </TERM>
 250 <LISTITEM>
 251 <PARA>
 252           Puts the default value or constraint specified into the
 253           definition of column in the table.
 254  See <command>CREATE TABLE</command> for the
 255           syntax of the default and table-constraint clauses.
 256           If a default clause already exists, it will be replaced by
 257           the new definition. If any constraints on this column already
 258           exist, they will be retained using a boolean AND with the new
 259           constraint.
 260 </para>
 261
 262 <PARA>
 263 Currently, to set new default constraints on an existing column
 264           the table must be recreated and reloaded:
 265
 266 <ProgramListing>
 267 CREATE TABLE temp AS SELECT * FROM distributors;
 268 DROP TABLE distributors;
 269 CREATE TABLE distributors (
 270     did      DECIMAL(3) DEFAULT 1,
 271     name     VARCHAR(40) NOT NULL,
 272     city     VARCHAR(30)
 273 );
 274 INSERT INTO distributors SELECT * FROM temp;
 275 DROP TABLE temp;
 276 </ProgramListing>
 277 </PARA>
 278 </LISTITEM>
 279 </VARLISTENTRY>
 280
 281 <VARLISTENTRY>
 282 <TERM>
 283 <Synopsis>
 284 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
 285     DROP DEFAULT <REPLACEABLE CLASS="PARAMETER">default</REPLACEABLE>
 286 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
 287     DROP CONSTRAINT <REPLACEABLE CLASS="PARAMETER">constraint</REPLACEABLE> { RESTRICT | CASCADE }
 288 </Synopsis>
 289 </TERM>
 290 <LISTITEM>
 291 <PARA>
 292           Removes the default value specified by default or the rule
 293           specified by constraint from the definition of a table.
 294           If RESTRICT is specified only a constraint with no dependent
 295           constraints can be destroyed.
 296           If CASCADE is specified, Any constraints that are dependent on
 297           this constraint are also dropped.
 298 </para>
 299
 300 <PARA>
 301 Currently, to remove a default value or constraints on an
 302           existing column the table must be recreated and reloaded:
 303
 304 <ProgramListing>
 305 CREATE TABLE temp AS SELECT * FROM distributors;
 306 DROP TABLE distributors;
 307 CREATE TABLE distributors AS SELECT * FROM temp;
 308 DROP TABLE temp;
 309 </ProgramListing>
 310 </para>
 311 </listitem>
 312 </varlistentry>
 313
 314 <VARLISTENTRY>
 315 <TERM>
 316 <Synopsis>
 317 ALTER TABLE <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
 318     DROP [ COLUMN ] <REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> { RESTRICT | CASCADE }
 319 </Synopsis>
 320 </TERM>
 321 <LISTITEM>
 322 <PARA>
 323           Removes a column from a table.
 324           If RESTRICT is specified only a column with no dependent
 325           objects can be destroyed.
 326           If CASCADE is specified, all objects that are dependent on
 327           this column are also dropped.
 328 </para>
 329
 330 <PARA>
 331 Currently, to remove an existing column the table must be
 332           recreated and reloaded:
 333
 334 <ProgramListing>
 335 CREATE TABLE temp AS SELECT did, city FROM distributors;
 336 DROP TABLE distributors;
 337 CREATE TABLE distributors (
 338     did      DECIMAL(3)  DEFAULT 1,
 339     name     VARCHAR(40) NOT NULL,
 340 );
 341 INSERT INTO distributors SELECT * FROM temp;
 342 DROP TABLE temp;
 343 </ProgramListing>
 344 </PARA>
 345 </listitem>
 346 </varlistentry>
 347 </VARIABLELIST>
 348 </refsect2>
 349 </refsect1>
 350 </REFENTRY>