begriffs open source - ai-pg/blob - full-docs/src/sgml/html/sql-altertype.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ALTER TYPE</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-altertrigger.html" title="ALTER TRIGGER" /><link rel="next" href="sql-alteruser.html" title="ALTER USER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">ALTER TYPE</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-altertrigger.html" title="ALTER TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-alteruser.html" title="ALTER USER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-ALTERTYPE"><div class="titlepage"></div><a id="id-1.9.3.42.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">ALTER TYPE</span></h2><p>ALTER TYPE —
   3    change the definition of a type
   4   </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   5 ALTER TYPE <em class="replaceable"><code>name</code></em> OWNER TO { <em class="replaceable"><code>new_owner</code></em> | CURRENT_ROLE | CURRENT_USER | SESSION_USER }
   6 ALTER TYPE <em class="replaceable"><code>name</code></em> RENAME TO <em class="replaceable"><code>new_name</code></em>
   7 ALTER TYPE <em class="replaceable"><code>name</code></em> SET SCHEMA <em class="replaceable"><code>new_schema</code></em>
   8 ALTER TYPE <em class="replaceable"><code>name</code></em> RENAME ATTRIBUTE <em class="replaceable"><code>attribute_name</code></em> TO <em class="replaceable"><code>new_attribute_name</code></em> [ CASCADE | RESTRICT ]
   9 ALTER TYPE <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>action</code></em> [, ... ]
  10 ALTER TYPE <em class="replaceable"><code>name</code></em> ADD VALUE [ IF NOT EXISTS ] <em class="replaceable"><code>new_enum_value</code></em> [ { BEFORE | AFTER } <em class="replaceable"><code>neighbor_enum_value</code></em> ]
  11 ALTER TYPE <em class="replaceable"><code>name</code></em> RENAME VALUE <em class="replaceable"><code>existing_enum_value</code></em> TO <em class="replaceable"><code>new_enum_value</code></em>
  12 ALTER TYPE <em class="replaceable"><code>name</code></em> SET ( <em class="replaceable"><code>property</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )
  13
  14 <span class="phrase">where <em class="replaceable"><code>action</code></em> is one of:</span>
  15
  16     ADD ATTRIBUTE <em class="replaceable"><code>attribute_name</code></em> <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ CASCADE | RESTRICT ]
  17     DROP ATTRIBUTE [ IF EXISTS ] <em class="replaceable"><code>attribute_name</code></em> [ CASCADE | RESTRICT ]
  18     ALTER ATTRIBUTE <em class="replaceable"><code>attribute_name</code></em> [ SET DATA ] TYPE <em class="replaceable"><code>data_type</code></em> [ COLLATE <em class="replaceable"><code>collation</code></em> ] [ CASCADE | RESTRICT ]
  19 </pre></div><div class="refsect1" id="id-1.9.3.42.5"><h2>Description</h2><p>
  20    <code class="command">ALTER TYPE</code> changes the definition of an existing type.
  21    There are several subforms:
  22
  23   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">OWNER</code></span></dt><dd><p>
  24       This form changes the owner of the type.
  25      </p></dd><dt><span class="term"><code class="literal">RENAME</code></span></dt><dd><p>
  26       This form changes the name of the type.
  27      </p></dd><dt><span class="term"><code class="literal">SET SCHEMA</code></span></dt><dd><p>
  28       This form moves the type into another schema.
  29      </p></dd><dt><span class="term"><code class="literal">RENAME ATTRIBUTE</code></span></dt><dd><p>
  30       This form is only usable with composite types.
  31       It changes the name of an individual attribute of the type.
  32      </p></dd><dt><span class="term"><code class="literal">ADD ATTRIBUTE</code></span></dt><dd><p>
  33       This form adds a new attribute to a composite type, using the same syntax as
  34       <a class="link" href="sql-createtype.html" title="CREATE TYPE"><code class="command">CREATE TYPE</code></a>.
  35      </p></dd><dt><span class="term"><code class="literal">DROP ATTRIBUTE [ IF EXISTS ]</code></span></dt><dd><p>
  36       This form drops an attribute from a composite type.
  37       If <code class="literal">IF EXISTS</code> is specified and the attribute
  38       does not exist, no error is thrown. In this case a notice
  39       is issued instead.
  40      </p></dd><dt><span class="term"><code class="literal">ALTER ATTRIBUTE ... SET DATA TYPE</code></span></dt><dd><p>
  41       This form changes the type of an attribute of a composite type.
  42      </p></dd><dt><span class="term"><code class="literal">ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ]</code></span></dt><dd><p>
  43       This form adds a new value to an enum type.  The new value's place in
  44       the enum's ordering can be specified as being <code class="literal">BEFORE</code>
  45       or <code class="literal">AFTER</code> one of the existing values.  Otherwise,
  46       the new item is added at the end of the list of values.
  47      </p><p>
  48       If <code class="literal">IF NOT EXISTS</code> is specified, it is not an error if
  49       the type already contains the new value: a notice is issued but no other
  50       action is taken. Otherwise, an error will occur if the new value is
  51       already present.
  52      </p></dd><dt><span class="term"><code class="literal">RENAME VALUE</code></span></dt><dd><p>
  53       This form renames a value of an enum type.
  54       The value's place in the enum's ordering is not affected.
  55       An error will occur if the specified value is not present or the new
  56       name is already present.
  57      </p></dd><dt><span class="term">
  58      <code class="literal">SET ( <em class="replaceable"><code>property</code></em> = <em class="replaceable"><code>value</code></em> [, ... ] )</code>
  59     </span></dt><dd><p>
  60       This form is only applicable to base types.  It allows adjustment of a
  61       subset of the base-type properties that can be set in <code class="command">CREATE
  62       TYPE</code>.  Specifically, these properties can be changed:
  63       </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  64          <code class="literal">RECEIVE</code> can be set to the name of a binary input
  65          function, or <code class="literal">NONE</code> to remove the type's binary
  66          input function.  Using this option requires superuser privilege.
  67         </p></li><li class="listitem"><p>
  68          <code class="literal">SEND</code> can be set to the name of a binary output
  69          function, or <code class="literal">NONE</code> to remove the type's binary
  70          output function.  Using this option requires superuser privilege.
  71         </p></li><li class="listitem"><p>
  72          <code class="literal">TYPMOD_IN</code> can be set to the name of a type
  73          modifier input function, or <code class="literal">NONE</code> to remove the
  74          type's type modifier input function.  Using this option requires
  75          superuser privilege.
  76         </p></li><li class="listitem"><p>
  77          <code class="literal">TYPMOD_OUT</code> can be set to the name of a type
  78          modifier output function, or <code class="literal">NONE</code> to remove the
  79          type's type modifier output function.  Using this option requires
  80          superuser privilege.
  81         </p></li><li class="listitem"><p>
  82          <code class="literal">ANALYZE</code> can be set to the name of a type-specific
  83          statistics collection function, or <code class="literal">NONE</code> to remove
  84          the type's statistics collection function.  Using this option
  85          requires superuser privilege.
  86         </p></li><li class="listitem"><p>
  87          <code class="literal">SUBSCRIPT</code> can be set to the name of a type-specific
  88          subscripting handler function, or <code class="literal">NONE</code> to remove
  89          the type's subscripting handler function.  Using this option
  90          requires superuser privilege.
  91         </p></li><li class="listitem"><p>
  92          <code class="literal">STORAGE</code><a id="id-1.9.3.42.5.2.2.10.2.1.2.7.1.2" class="indexterm"></a>
  93          can be set to <code class="literal">plain</code>,
  94          <code class="literal">extended</code>, <code class="literal">external</code>,
  95          or <code class="literal">main</code> (see <a class="xref" href="storage-toast.html" title="66.2. TOAST">Section 66.2</a> for
  96          more information about what these mean).  However, changing
  97          from <code class="literal">plain</code> to another setting requires superuser
  98          privilege (because it requires that the type's C functions all be
  99          TOAST-ready), and changing to <code class="literal">plain</code> from another
 100          setting is not allowed at all (since the type may already have
 101          TOASTed values present in the database).  Note that changing this
 102          option doesn't by itself change any stored data, it just sets the
 103          default TOAST strategy to be used for table columns created in the
 104          future.  See <a class="xref" href="sql-altertable.html" title="ALTER TABLE"><span class="refentrytitle">ALTER TABLE</span></a> to change the TOAST
 105          strategy for existing table columns.
 106         </p></li></ul></div><p>
 107       See <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> for more details about these
 108       type properties.  Note that where appropriate, a change in these
 109       properties for a base type will be propagated automatically to domains
 110       based on that type.
 111      </p></dd></dl></div><p>
 112   </p><p>
 113    The <code class="literal">ADD ATTRIBUTE</code>, <code class="literal">DROP
 114    ATTRIBUTE</code>, and <code class="literal">ALTER ATTRIBUTE</code> actions
 115    can be combined into a list of multiple alterations to apply in
 116    parallel.  For example, it is possible to add several attributes
 117    and/or alter the type of several attributes in a single command.
 118   </p><p>
 119    You must own the type to use <code class="command">ALTER TYPE</code>.
 120    To change the schema of a type, you must also have
 121    <code class="literal">CREATE</code> privilege on the new schema.
 122    To alter the owner, you must be able to <code class="literal">SET ROLE</code> to the
 123    new owning role, and that role must have <code class="literal">CREATE</code>
 124    privilege on the type's schema.
 125    (These restrictions enforce that altering the owner
 126    doesn't do anything you couldn't do by dropping and recreating the type.
 127    However, a superuser can alter ownership of any type anyway.)
 128    To add an attribute or alter an attribute type, you must also
 129    have <code class="literal">USAGE</code> privilege on the attribute's data type.
 130   </p></div><div class="refsect1" id="id-1.9.3.42.6"><h2>Parameters</h2><p>
 131     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>name</code></em></span></dt><dd><p>
 132         The name (possibly schema-qualified) of an existing type to
 133         alter.
 134        </p></dd><dt><span class="term"><em class="replaceable"><code>new_name</code></em></span></dt><dd><p>
 135         The new name for the type.
 136        </p></dd><dt><span class="term"><em class="replaceable"><code>new_owner</code></em></span></dt><dd><p>
 137         The user name of the new owner of the type.
 138        </p></dd><dt><span class="term"><em class="replaceable"><code>new_schema</code></em></span></dt><dd><p>
 139         The new schema for the type.
 140        </p></dd><dt><span class="term"><em class="replaceable"><code>attribute_name</code></em></span></dt><dd><p>
 141         The name of the attribute to add, alter, or drop.
 142        </p></dd><dt><span class="term"><em class="replaceable"><code>new_attribute_name</code></em></span></dt><dd><p>
 143         The new name of the attribute to be renamed.
 144        </p></dd><dt><span class="term"><em class="replaceable"><code>data_type</code></em></span></dt><dd><p>
 145         The data type of the attribute to add, or the new type of the
 146         attribute to alter.
 147        </p></dd><dt><span class="term"><em class="replaceable"><code>new_enum_value</code></em></span></dt><dd><p>
 148         The new value to be added to an enum type's list of values,
 149         or the new name to be given to an existing value.
 150         Like all enum literals, it needs to be quoted.
 151        </p></dd><dt><span class="term"><em class="replaceable"><code>neighbor_enum_value</code></em></span></dt><dd><p>
 152         The existing enum value that the new value should be added immediately
 153         before or after in the enum type's sort ordering.
 154         Like all enum literals, it needs to be quoted.
 155        </p></dd><dt><span class="term"><em class="replaceable"><code>existing_enum_value</code></em></span></dt><dd><p>
 156         The existing enum value that should be renamed.
 157         Like all enum literals, it needs to be quoted.
 158        </p></dd><dt><span class="term"><em class="replaceable"><code>property</code></em></span></dt><dd><p>
 159         The name of a base-type property to be modified; see above for
 160         possible values.
 161        </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p>
 162         Automatically propagate the operation to typed tables of the
 163         type being altered, and their descendants.
 164        </p></dd><dt><span class="term"><code class="literal">RESTRICT</code></span></dt><dd><p>
 165         Refuse the operation if the type being altered is the type of a
 166         typed table.  This is the default.
 167        </p></dd></dl></div><p>
 168    </p></div><div class="refsect1" id="id-1.9.3.42.7"><h2>Notes</h2><p>
 169    If <code class="command">ALTER TYPE ... ADD VALUE</code> (the form that adds a new
 170    value to an enum type) is executed inside a transaction block, the new
 171    value cannot be used until after the transaction has been committed.
 172   </p><p>
 173    Comparisons involving an added enum value will sometimes be slower than
 174    comparisons involving only original members of the enum type.  This will
 175    usually only occur if <code class="literal">BEFORE</code> or <code class="literal">AFTER</code>
 176    is used to set the new value's sort position somewhere other than at the
 177    end of the list.  However, sometimes it will happen even though the new
 178    value is added at the end (this occurs if the OID counter <span class="quote">“<span class="quote">wrapped
 179    around</span>”</span> since the original creation of the enum type).  The slowdown is
 180    usually insignificant; but if it matters, optimal performance can be
 181    regained by dropping and recreating the enum type, or by dumping and
 182    restoring the database.
 183   </p></div><div class="refsect1" id="id-1.9.3.42.8"><h2>Examples</h2><p>
 184    To rename a data type:
 185 </p><pre class="programlisting">
 186 ALTER TYPE electronic_mail RENAME TO email;
 187 </pre><p>
 188   </p><p>
 189    To change the owner of the type <code class="literal">email</code>
 190    to <code class="literal">joe</code>:
 191 </p><pre class="programlisting">
 192 ALTER TYPE email OWNER TO joe;
 193 </pre><p>
 194   </p><p>
 195    To change the schema of the type <code class="literal">email</code>
 196    to <code class="literal">customers</code>:
 197 </p><pre class="programlisting">
 198 ALTER TYPE email SET SCHEMA customers;
 199 </pre><p>
 200   </p><p>
 201    To add a new attribute to a composite type:
 202 </p><pre class="programlisting">
 203 ALTER TYPE compfoo ADD ATTRIBUTE f3 int;
 204 </pre><p>
 205   </p><p>
 206    To add a new value to an enum type in a particular sort position:
 207 </p><pre class="programlisting">
 208 ALTER TYPE colors ADD VALUE 'orange' AFTER 'red';
 209 </pre><p>
 210   </p><p>
 211    To rename an enum value:
 212 </p><pre class="programlisting">
 213 ALTER TYPE colors RENAME VALUE 'purple' TO 'mauve';
 214 </pre><p>
 215   </p><p>
 216    To create binary I/O functions for an existing base type:
 217 </p><pre class="programlisting">
 218 CREATE FUNCTION mytypesend(mytype) RETURNS bytea ...;
 219 CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype ...;
 220 ALTER TYPE mytype SET (
 221     SEND = mytypesend,
 222     RECEIVE = mytyperecv
 223 );
 224 </pre></div><div class="refsect1" id="id-1.9.3.42.9"><h2>Compatibility</h2><p>
 225    The variants to add and drop attributes are part of the SQL
 226    standard; the other variants are PostgreSQL extensions.
 227   </p></div><div class="refsect1" id="SQL-ALTERTYPE-SEE-ALSO"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a>, <a class="xref" href="sql-droptype.html" title="DROP TYPE"><span class="refentrytitle">DROP TYPE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-altertrigger.html" title="ALTER TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-alteruser.html" title="ALTER USER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ALTER TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> ALTER USER</td></tr></table></div></body></html>