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

   1 <!--
   2 doc/src/sgml/ref/alter_type.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTERTYPE">
   7  <refmeta>
   8   <refentrytitle>ALTER TYPE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>ALTER TYPE</refname>
  15   <refpurpose>
  16    change the definition of a type
  17   </refpurpose>
  18  </refnamediv>
  19
  20  <indexterm zone="sql-altertype">
  21   <primary>ALTER TYPE</primary>
  22  </indexterm>
  23
  24  <refsynopsisdiv>
  25 <synopsis>
  26 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> <replaceable class="PARAMETER">action</replaceable> [, ... ]
  27 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
  28 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME ATTRIBUTE <replaceable class="PARAMETER">attribute_name</replaceable> TO <replaceable class="PARAMETER">new_attribute_name</replaceable>
  29 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable> [ CASCADE | RESTRICT ]
  30 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>
  31 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> ADD VALUE [ IF NOT EXISTS ] <replaceable class="PARAMETER">new_enum_value</replaceable> [ { BEFORE | AFTER } <replaceable class="PARAMETER">existing_enum_value</replaceable> ]
  32
  33 <phrase>where <replaceable class="PARAMETER">action</replaceable> is one of:</phrase>
  34
  35     ADD ATTRIBUTE <replaceable class="PARAMETER">attribute_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ COLLATE <replaceable class="PARAMETER">collation</replaceable> ] [ CASCADE | RESTRICT ]
  36     DROP ATTRIBUTE [ IF EXISTS ] <replaceable class="PARAMETER">attribute_name</replaceable> [ CASCADE | RESTRICT ]
  37     ALTER ATTRIBUTE <replaceable class="PARAMETER">attribute_name</replaceable> [ SET DATA ] TYPE <replaceable class="PARAMETER">data_type</replaceable> [ COLLATE <replaceable class="PARAMETER">collation</replaceable> ] [ CASCADE | RESTRICT ]
  38 </synopsis>
  39  </refsynopsisdiv>
  40
  41  <refsect1>
  42   <title>Description</title>
  43
  44   <para>
  45    <command>ALTER TYPE</command> changes the definition of an existing type.
  46    There are several subforms:
  47
  48   <variablelist>
  49    <varlistentry>
  50     <term><literal>ADD ATTRIBUTE</literal></term>
  51     <listitem>
  52      <para>
  53       This form adds a new attribute to a composite type, using the same syntax as
  54       <xref linkend="SQL-CREATETYPE">.
  55      </para>
  56     </listitem>
  57    </varlistentry>
  58
  59    <varlistentry>
  60     <term><literal>DROP ATTRIBUTE [ IF EXISTS ]</literal></term>
  61     <listitem>
  62      <para>
  63       This form drops an attribute from a composite type.
  64       If <literal>IF EXISTS</literal> is specified and the attribute
  65       does not exist, no error is thrown. In this case a notice
  66       is issued instead.
  67      </para>
  68     </listitem>
  69    </varlistentry>
  70
  71    <varlistentry>
  72     <term><literal>SET DATA TYPE</literal></term>
  73     <listitem>
  74      <para>
  75       This form changes the type of an attribute of a composite type.
  76      </para>
  77     </listitem>
  78    </varlistentry>
  79
  80    <varlistentry>
  81     <term><literal>OWNER</literal></term>
  82     <listitem>
  83      <para>
  84       This form changes the owner of the type.
  85      </para>
  86     </listitem>
  87    </varlistentry>
  88
  89    <varlistentry>
  90     <term><literal>RENAME</literal></term>
  91     <listitem>
  92      <para>
  93       This form changes the name of the type or the name of an
  94       individual attribute of a composite type.
  95      </para>
  96     </listitem>
  97    </varlistentry>
  98
  99    <varlistentry>
 100     <term><literal>SET SCHEMA</literal></term>
 101     <listitem>
 102      <para>
 103       This form moves the type into another schema.
 104      </para>
 105     </listitem>
 106    </varlistentry>
 107
 108    <varlistentry>
 109     <term><literal>ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ]</literal></term>
 110     <listitem>
 111      <para>
 112       This form adds a new value to an enum type.  The new value's place in
 113       the enum's ordering can be specified as being <literal>BEFORE</literal>
 114       or <literal>AFTER</literal> one of the existing values.  Otherwise,
 115       the new item is added at the end of the list of values.
 116      </para>
 117      <para>
 118       If <literal>IF NOT EXISTS</literal> is specified, it is not an error if
 119       the type already contains the new value: a notice is issued but no other
 120       action is taken. Otherwise, an error will occur if the new value is
 121       already present.
 122      </para>
 123     </listitem>
 124    </varlistentry>
 125
 126    <varlistentry>
 127     <term><literal>CASCADE</literal></term>
 128     <listitem>
 129      <para>
 130       Automatically propagate the operation to typed tables of the
 131       type being altered, and their descendants.
 132      </para>
 133     </listitem>
 134    </varlistentry>
 135
 136    <varlistentry>
 137     <term><literal>RESTRICT</literal></term>
 138     <listitem>
 139      <para>
 140       Refuse the operation if the type being altered is the type of a
 141       typed table.  This is the default.
 142      </para>
 143     </listitem>
 144    </varlistentry>
 145   </variablelist>
 146   </para>
 147
 148   <para>
 149    The <literal>ADD ATTRIBUTE</literal>, <literal>DROP
 150    ATTRIBUTE</literal>, and <literal>ALTER ATTRIBUTE</literal> actions
 151    can be combined into a list of multiple alterations to apply in
 152    parallel.  For example, it is possible to add several attributes
 153    and/or alter the type of several attributes in a single command.
 154   </para>
 155
 156   <para>
 157    You must own the type to use <command>ALTER TYPE</>.
 158    To change the schema of a type, you must also have
 159    <literal>CREATE</literal> privilege on the new schema.
 160    To alter the owner, you must also be a direct or indirect member of the new
 161    owning role, and that role must have <literal>CREATE</literal> privilege on
 162    the type's schema.  (These restrictions enforce that altering the owner
 163    doesn't do anything you couldn't do by dropping and recreating the type.
 164    However, a superuser can alter ownership of any type anyway.)
 165    To add an attribute or alter an attribute type, you must also
 166    have <literal>USAGE</literal> privilege on the data type.
 167   </para>
 168  </refsect1>
 169
 170  <refsect1>
 171   <title>Parameters</title>
 172
 173    <para>
 174     <variablelist>
 175      <varlistentry>
 176       <term><replaceable class="PARAMETER">name</replaceable></term>
 177       <listitem>
 178        <para>
 179         The name (possibly schema-qualified) of an existing type to
 180         alter.
 181        </para>
 182       </listitem>
 183      </varlistentry>
 184
 185      <varlistentry>
 186       <term><replaceable class="PARAMETER">new_name</replaceable></term>
 187       <listitem>
 188        <para>
 189         The new name for the type.
 190        </para>
 191       </listitem>
 192      </varlistentry>
 193
 194      <varlistentry>
 195       <term><replaceable class="PARAMETER">new_owner</replaceable></term>
 196       <listitem>
 197        <para>
 198         The user name of the new owner of the type.
 199        </para>
 200       </listitem>
 201      </varlistentry>
 202
 203      <varlistentry>
 204       <term><replaceable class="PARAMETER">new_schema</replaceable></term>
 205       <listitem>
 206        <para>
 207         The new schema for the type.
 208        </para>
 209       </listitem>
 210      </varlistentry>
 211
 212      <varlistentry>
 213       <term><replaceable class="PARAMETER">attribute_name</replaceable></term>
 214       <listitem>
 215        <para>
 216         The name of the attribute to add, alter, or drop.
 217        </para>
 218       </listitem>
 219      </varlistentry>
 220
 221      <varlistentry>
 222       <term><replaceable class="PARAMETER">new_attribute_name</replaceable></term>
 223       <listitem>
 224        <para>
 225         The new name of the attribute to be renamed.
 226        </para>
 227       </listitem>
 228      </varlistentry>
 229
 230      <varlistentry>
 231       <term><replaceable class="PARAMETER">data_type</replaceable></term>
 232       <listitem>
 233        <para>
 234         The data type of the attribute to add, or the new type of the
 235         attribute to alter.
 236        </para>
 237       </listitem>
 238      </varlistentry>
 239
 240      <varlistentry>
 241       <term><replaceable class="PARAMETER">new_enum_value</replaceable></term>
 242       <listitem>
 243        <para>
 244         The new value to be added to an enum type's list of values.
 245         Like all enum literals, it needs to be quoted.
 246        </para>
 247       </listitem>
 248      </varlistentry>
 249
 250      <varlistentry>
 251       <term><replaceable class="PARAMETER">existing_enum_value</replaceable></term>
 252       <listitem>
 253        <para>
 254         The existing enum value that the new value should be added immediately
 255         before or after in the enum type's sort ordering.
 256         Like all enum literals, it needs to be quoted.
 257        </para>
 258       </listitem>
 259      </varlistentry>
 260
 261     </variablelist>
 262    </para>
 263   </refsect1>
 264
 265  <refsect1>
 266   <title>Notes</title>
 267
 268   <para>
 269    <command>ALTER TYPE ... ADD VALUE</> (the form that adds a new value to an
 270    enum type) cannot be executed inside a transaction block.
 271   </para>
 272
 273   <para>
 274    Comparisons involving an added enum value will sometimes be slower than
 275    comparisons involving only original members of the enum type.  This will
 276    usually only occur if <literal>BEFORE</literal> or <literal>AFTER</literal>
 277    is used to set the new value's sort position somewhere other than at the
 278    end of the list.  However, sometimes it will happen even though the new
 279    value is added at the end (this occurs if the OID counter <quote>wrapped
 280    around</> since the original creation of the enum type).  The slowdown is
 281    usually insignificant; but if it matters, optimal performance can be
 282    regained by dropping and recreating the enum type, or by dumping and
 283    reloading the database.
 284   </para>
 285  </refsect1>
 286
 287  <refsect1>
 288   <title>Examples</title>
 289
 290   <para>
 291    To rename a data type:
 292 <programlisting>
 293 ALTER TYPE electronic_mail RENAME TO email;
 294 </programlisting>
 295   </para>
 296
 297   <para>
 298    To change the owner of the type <literal>email</literal>
 299    to <literal>joe</literal>:
 300 <programlisting>
 301 ALTER TYPE email OWNER TO joe;
 302 </programlisting>
 303   </para>
 304
 305   <para>
 306    To change the schema of the type <literal>email</literal>
 307    to <literal>customers</literal>:
 308 <programlisting>
 309 ALTER TYPE email SET SCHEMA customers;
 310 </programlisting>
 311   </para>
 312
 313   <para>
 314    To add a new attribute to a type:
 315 <programlisting>
 316 ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
 317 </programlisting>
 318   </para>
 319
 320   <para>
 321    To add a new value to an enum type in a particular sort position:
 322 <programlisting>
 323 ALTER TYPE colors ADD VALUE 'orange' AFTER 'red';
 324 </programlisting></para>
 325  </refsect1>
 326
 327  <refsect1>
 328   <title>Compatibility</title>
 329
 330   <para>
 331    The variants to add and drop attributes are part of the SQL
 332    standard; the other variants are PostgreSQL extensions.
 333   </para>
 334  </refsect1>
 335
 336  <refsect1 id="SQL-ALTERTYPE-see-also">
 337   <title>See Also</title>
 338
 339   <simplelist type="inline">
 340    <member><xref linkend="sql-createtype"></member>
 341    <member><xref linkend="sql-droptype"></member>
 342   </simplelist>
 343  </refsect1>
 344 </refentry>