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

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