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

   1 <!--
   2 doc/src/sgml/ref/alter_extension.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTEREXTENSION">
   7  <refmeta>
   8   <refentrytitle>ALTER EXTENSION</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>ALTER EXTENSION</refname>
  15   <refpurpose>
  16    change the definition of an extension
  17   </refpurpose>
  18  </refnamediv>
  19
  20  <indexterm zone="sql-alterextension">
  21   <primary>ALTER EXTENSION</primary>
  22  </indexterm>
  23
  24  <refsynopsisdiv>
  25 <synopsis>
  26 ALTER EXTENSION <replaceable class="PARAMETER">extension_name</replaceable> UPDATE [ TO <replaceable class="PARAMETER">new_version</replaceable> ]
  27 ALTER EXTENSION <replaceable class="PARAMETER">extension_name</replaceable> SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>
  28 ALTER EXTENSION <replaceable class="PARAMETER">extension_name</replaceable> ADD <replaceable class="PARAMETER">member_object</replaceable>
  29 ALTER EXTENSION <replaceable class="PARAMETER">extension_name</replaceable> DROP <replaceable class="PARAMETER">member_object</replaceable>
  30
  31 <phrase>where <replaceable class="PARAMETER">member_object</replaceable> is:</phrase>
  32
  33   AGGREGATE <replaceable class="PARAMETER">agg_name</replaceable> (<replaceable class="PARAMETER">agg_type</replaceable> [, ...] ) |
  34   CAST (<replaceable>source_type</replaceable> AS <replaceable>target_type</replaceable>) |
  35   COLLATION <replaceable class="PARAMETER">object_name</replaceable> |
  36   CONVERSION <replaceable class="PARAMETER">object_name</replaceable> |
  37   DOMAIN <replaceable class="PARAMETER">object_name</replaceable> |
  38   FOREIGN DATA WRAPPER <replaceable class="PARAMETER">object_name</replaceable> |
  39   FOREIGN TABLE <replaceable class="PARAMETER">object_name</replaceable> |
  40   FUNCTION <replaceable class="PARAMETER">function_name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] ) |
  41   OPERATOR <replaceable class="PARAMETER">operator_name</replaceable> (<replaceable class="PARAMETER">left_type</replaceable>, <replaceable class="PARAMETER">right_type</replaceable>) |
  42   OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
  43   OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> |
  44   [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> |
  45   SCHEMA <replaceable class="PARAMETER">object_name</replaceable> |
  46   SEQUENCE <replaceable class="PARAMETER">object_name</replaceable> |
  47   SERVER <replaceable class="PARAMETER">object_name</replaceable> |
  48   TABLE <replaceable class="PARAMETER">object_name</replaceable> |
  49   TEXT SEARCH CONFIGURATION <replaceable class="PARAMETER">object_name</replaceable> |
  50   TEXT SEARCH DICTIONARY <replaceable class="PARAMETER">object_name</replaceable> |
  51   TEXT SEARCH PARSER <replaceable class="PARAMETER">object_name</replaceable> |
  52   TEXT SEARCH TEMPLATE <replaceable class="PARAMETER">object_name</replaceable> |
  53   TYPE <replaceable class="PARAMETER">object_name</replaceable> |
  54   VIEW <replaceable class="PARAMETER">object_name</replaceable>
  55 </synopsis>
  56  </refsynopsisdiv>
  57
  58  <refsect1>
  59   <title>Description</title>
  60
  61   <para>
  62    <command>ALTER EXTENSION</command> changes the definition of an installed
  63    extension.  There are several subforms:
  64
  65    <variablelist>
  66    <varlistentry>
  67     <term><literal>UPDATE</literal></term>
  68     <listitem>
  69      <para>
  70       This form updates the extension to a newer version.  The extension
  71       must supply a suitable update script (or series of scripts) that can
  72       modify the currently-installed version into the requested version.
  73      </para>
  74     </listitem>
  75    </varlistentry>
  76
  77    <varlistentry>
  78     <term><literal>SET SCHEMA</literal></term>
  79     <listitem>
  80      <para>
  81       This form moves the extension's objects into another schema. The
  82       extension has to be <firstterm>relocatable</> for this command to
  83       succeed.
  84      </para>
  85     </listitem>
  86    </varlistentry>
  87
  88    <varlistentry>
  89     <term><literal>ADD <replaceable class="PARAMETER">member_object</replaceable></literal></term>
  90     <listitem>
  91      <para>
  92       This form adds an existing object to the extension.  This is mainly
  93       useful in extension update scripts.  The object will subsequently
  94       be treated as a member of the extension; notably, it can only be
  95       dropped by dropping the extension.
  96      </para>
  97     </listitem>
  98    </varlistentry>
  99
 100    <varlistentry>
 101     <term><literal>DROP <replaceable class="PARAMETER">member_object</replaceable></literal></term>
 102     <listitem>
 103      <para>
 104       This form removes a member object from the extension.  This is mainly
 105       useful in extension update scripts.  The object is not dropped, only
 106       disassociated from the extension.
 107      </para>
 108     </listitem>
 109    </varlistentry>
 110    </variablelist>
 111
 112    See <xref linkend="extend-extensions"> for more information about these
 113    operations.
 114   </para>
 115
 116   <para>
 117    You must own the extension to use <command>ALTER EXTENSION</command>.
 118    The <literal>ADD</>/<literal>DROP</> forms require ownership of the
 119    added/dropped object as well.
 120   </para>
 121  </refsect1>
 122
 123  <refsect1>
 124   <title>Parameters</title>
 125
 126   <para>
 127    <variablelist>
 128     <varlistentry>
 129      <term><replaceable class="PARAMETER">extension_name</replaceable></term>
 130      <listitem>
 131       <para>
 132        The name of an installed extension.
 133       </para>
 134      </listitem>
 135     </varlistentry>
 136
 137     <varlistentry>
 138      <term><replaceable class="PARAMETER">new_version</replaceable></term>
 139      <listitem>
 140       <para>
 141        The desired new version of the extension.  This can be written as
 142        either an identifier or a string literal.  If not specified,
 143        <command>ALTER EXTENSION UPDATE</> attempts to update to whatever is
 144        shown as the default version in the extension's control file.
 145       </para>
 146      </listitem>
 147     </varlistentry>
 148
 149     <varlistentry>
 150      <term><replaceable class="PARAMETER">new_schema</replaceable></term>
 151      <listitem>
 152       <para>
 153        The new schema for the extension.
 154       </para>
 155      </listitem>
 156     </varlistentry>
 157
 158     <varlistentry>
 159      <term><replaceable class="parameter">object_name</replaceable></term>
 160      <term><replaceable class="parameter">agg_name</replaceable></term>
 161      <term><replaceable class="parameter">function_name</replaceable></term>
 162      <term><replaceable class="parameter">operator_name</replaceable></term>
 163      <listitem>
 164       <para>
 165        The name of an object to be added to or removed from the extension.
 166        Names of tables,
 167        aggregates, domains, foreign tables, functions, operators,
 168        operator classes, operator families, sequences, text search objects,
 169        types, and views can be schema-qualified.
 170       </para>
 171      </listitem>
 172     </varlistentry>
 173
 174     <varlistentry>
 175      <term><replaceable class="parameter">agg_type</replaceable></term>
 176      <listitem>
 177       <para>
 178        An input data type on which the aggregate function operates.
 179        To reference a zero-argument aggregate function, write <literal>*</>
 180        in place of the list of input data types.
 181       </para>
 182      </listitem>
 183     </varlistentry>
 184
 185     <varlistentry>
 186      <term><replaceable>source_type</replaceable></term>
 187      <listitem>
 188       <para>
 189        The name of the source data type of the cast.
 190       </para>
 191      </listitem>
 192     </varlistentry>
 193
 194     <varlistentry>
 195      <term><replaceable>target_type</replaceable></term>
 196      <listitem>
 197       <para>
 198        The name of the target data type of the cast.
 199       </para>
 200      </listitem>
 201     </varlistentry>
 202
 203     <varlistentry>
 204      <term><replaceable class="parameter">argmode</replaceable></term>
 205
 206      <listitem>
 207       <para>
 208        The mode of a function argument: <literal>IN</>, <literal>OUT</>,
 209        <literal>INOUT</>, or <literal>VARIADIC</>.
 210        If omitted, the default is <literal>IN</>.
 211        Note that <command>ALTER EXTENSION</command> does not actually pay
 212        any attention to <literal>OUT</> arguments, since only the input
 213        arguments are needed to determine the function's identity.
 214        So it is sufficient to list the <literal>IN</>, <literal>INOUT</>,
 215        and <literal>VARIADIC</> arguments.
 216       </para>
 217      </listitem>
 218     </varlistentry>
 219
 220     <varlistentry>
 221      <term><replaceable class="parameter">argname</replaceable></term>
 222
 223      <listitem>
 224       <para>
 225        The name of a function argument.
 226        Note that <command>ALTER EXTENSION</command> does not actually pay
 227        any attention to argument names, since only the argument data
 228        types are needed to determine the function's identity.
 229       </para>
 230      </listitem>
 231     </varlistentry>
 232
 233     <varlistentry>
 234      <term><replaceable class="parameter">argtype</replaceable></term>
 235
 236      <listitem>
 237       <para>
 238        The data type(s) of the function's arguments (optionally
 239        schema-qualified), if any.
 240       </para>
 241      </listitem>
 242     </varlistentry>
 243
 244     <varlistentry>
 245      <term><replaceable class="parameter">left_type</replaceable></term>
 246      <term><replaceable class="parameter">right_type</replaceable></term>
 247      <listitem>
 248       <para>
 249        The data type(s) of the operator's arguments (optionally
 250        schema-qualified).  Write <literal>NONE</> for the missing argument
 251        of a prefix or postfix operator.
 252       </para>
 253      </listitem>
 254     </varlistentry>
 255
 256     <varlistentry>
 257      <term><literal>PROCEDURAL</literal></term>
 258
 259      <listitem>
 260       <para>
 261        This is a noise word.
 262       </para>
 263      </listitem>
 264     </varlistentry>
 265    </variablelist>
 266   </para>
 267  </refsect1>
 268
 269  <refsect1>
 270   <title>Examples</title>
 271
 272   <para>
 273    To update the <literal>hstore</literal> extension to version 2.0:
 274 <programlisting>
 275 ALTER EXTENSION hstore UPDATE TO '2.0';
 276 </programlisting>
 277   </para>
 278
 279   <para>
 280    To change the schema of the <literal>hstore</literal> extension
 281    to <literal>utils</literal>:
 282 <programlisting>
 283 ALTER EXTENSION hstore SET SCHEMA utils;
 284 </programlisting>
 285   </para>
 286
 287   <para>
 288    To add an existing function to the <literal>hstore</literal> extension:
 289 <programlisting>
 290 ALTER EXTENSION hstore ADD FUNCTION populate_record(anyelement, hstore);
 291 </programlisting></para>
 292  </refsect1>
 293
 294  <refsect1>
 295   <title>Compatibility</title>
 296
 297   <para>
 298    <command>ALTER EXTENSION</command> is a <productname>PostgreSQL</>
 299    extension.
 300   </para>
 301  </refsect1>
 302
 303  <refsect1 id="SQL-ALTEREXTENSION-see-also">
 304   <title>See Also</title>
 305
 306   <simplelist type="inline">
 307    <member><xref linkend="sql-createextension"></member>
 308    <member><xref linkend="sql-dropextension"></member>
 309   </simplelist>
 310  </refsect1>
 311 </refentry>