doc/src/sgml/ref/create_language.sgml

   1 <!--
   2 doc/src/sgml/ref/create_language.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="sql-createlanguage">
   7  <indexterm zone="sql-createlanguage">
   8   <primary>CREATE LANGUAGE</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle>CREATE LANGUAGE</refentrytitle>
  13   <manvolnum>7</manvolnum>
  14   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>CREATE LANGUAGE</refname>
  19   <refpurpose>define a new procedural language</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
  25     HANDLER <replaceable class="parameter">call_handler</replaceable> [ INLINE <replaceable class="parameter">inline_handler</replaceable> ] [ VALIDATOR <replaceable>valfunction</replaceable> ]
  26 CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
  27 </synopsis>
  28  </refsynopsisdiv>
  29
  30  <refsect1 id="sql-createlanguage-description">
  31   <title>Description</title>
  32
  33   <para>
  34    <command>CREATE LANGUAGE</command> registers a new
  35    procedural language with a <productname>PostgreSQL</productname>
  36    database.  Subsequently, functions and procedures can be
  37    defined in this new language.
  38   </para>
  39
  40   <para>
  41    <command>CREATE LANGUAGE</command> effectively associates the
  42    language name with handler function(s) that are responsible for executing
  43    functions written in the language.  Refer to <xref linkend="plhandler"/>
  44    for more information about language handlers.
  45   </para>
  46
  47   <para>
  48    <command>CREATE OR REPLACE LANGUAGE</command> will either create a
  49    new language, or replace an existing definition.  If the language
  50    already exists, its parameters are updated according to the command,
  51    but the language's ownership and permissions settings do not change,
  52    and any existing functions written in the language are assumed to still
  53    be valid.
  54   </para>
  55
  56   <para>
  57    One must have the
  58    <productname>PostgreSQL</productname> superuser privilege to
  59    register a new language or change an existing language's parameters.
  60    However, once the language is created it is valid to assign ownership of
  61    it to a non-superuser, who may then drop it, change its permissions,
  62    rename it, or assign it to a new owner.  (Do not, however, assign
  63    ownership of the underlying C functions to a non-superuser; that would
  64    create a privilege escalation path for that user.)
  65   </para>
  66
  67   <para>
  68    The form of <command>CREATE LANGUAGE</command> that does not supply
  69    any handler function is obsolete.  For backwards compatibility with
  70    old dump files, it is interpreted as <command>CREATE EXTENSION</command>.
  71    That will work if the language has been packaged into an extension of
  72    the same name, which is the conventional way to set up procedural
  73    languages.
  74   </para>
  75  </refsect1>
  76
  77  <refsect1 id="sql-createlanguage-parameters">
  78   <title>Parameters</title>
  79
  80    <variablelist>
  81     <varlistentry>
  82      <term><literal>TRUSTED</literal></term>
  83
  84      <listitem>
  85       <para><literal>TRUSTED</literal> specifies that the language does
  86        not grant access to data that the user would not otherwise
  87        have.  If this key word is omitted
  88        when registering the language, only users with the
  89        <productname>PostgreSQL</productname> superuser privilege can
  90        use this language to create new functions.
  91       </para>
  92      </listitem>
  93     </varlistentry>
  94
  95     <varlistentry>
  96      <term><literal>PROCEDURAL</literal></term>
  97
  98      <listitem>
  99       <para>
 100        This is a noise word.
 101       </para>
 102      </listitem>
 103     </varlistentry>
 104
 105     <varlistentry>
 106      <term><replaceable class="parameter">name</replaceable></term>
 107
 108      <listitem>
 109       <para>
 110        The name of the new procedural language.
 111        The name must be unique among the languages in the database.
 112       </para>
 113      </listitem>
 114     </varlistentry>
 115
 116     <varlistentry>
 117      <term><literal>HANDLER</literal> <replaceable class="parameter">call_handler</replaceable></term>
 118
 119      <listitem>
 120       <para><replaceable class="parameter">call_handler</replaceable> is
 121        the name of a previously registered function that will be
 122        called to execute the procedural language's functions.  The call
 123        handler for a procedural language must be written in a compiled
 124        language such as C with version 1 call convention and
 125        registered with <productname>PostgreSQL</productname> as a
 126        function taking no arguments and returning the
 127        <type>language_handler</type> type, a placeholder type that is
 128        simply used to identify the function as a call handler.
 129       </para>
 130      </listitem>
 131     </varlistentry>
 132
 133     <varlistentry>
 134      <term><literal>INLINE</literal> <replaceable class="parameter">inline_handler</replaceable></term>
 135
 136      <listitem>
 137       <para><replaceable class="parameter">inline_handler</replaceable> is the
 138        name of a previously registered function that will be called
 139        to execute an anonymous code block
 140        (<link linkend="sql-do"><command>DO</command></link> command)
 141        in this language.
 142        If no <replaceable class="parameter">inline_handler</replaceable>
 143        function is specified, the language does not support anonymous code
 144        blocks.
 145        The handler function must take one argument of
 146        type <type>internal</type>, which will be the <command>DO</command> command's
 147        internal representation, and it will typically return
 148        <type>void</type>.  The return value of the handler is ignored.
 149       </para>
 150      </listitem>
 151     </varlistentry>
 152
 153     <varlistentry>
 154      <term><literal>VALIDATOR</literal> <replaceable class="parameter">valfunction</replaceable></term>
 155
 156      <listitem>
 157       <para><replaceable class="parameter">valfunction</replaceable> is the
 158        name of a previously registered function that will be called
 159        when a new function in the language is created, to validate the
 160        new function.
 161        If no
 162        validator function is specified, then a new function will not
 163        be checked when it is created.
 164        The validator function must take one argument of
 165        type <type>oid</type>, which will be the OID of the
 166        to-be-created function, and will typically return <type>void</type>.
 167       </para>
 168
 169       <para>
 170        A validator function would typically inspect the function body
 171        for syntactical correctness, but it can also look at other
 172        properties of the function, for example if the language cannot
 173        handle certain argument types.  To signal an error, the
 174        validator function should use the <function>ereport()</function>
 175        function.  The return value of the function is ignored.
 176       </para>
 177      </listitem>
 178     </varlistentry>
 179    </variablelist>
 180  </refsect1>
 181
 182  <refsect1 id="sql-createlanguage-notes">
 183   <title>Notes</title>
 184
 185   <para>
 186    Use <link linkend="sql-droplanguage"><command>DROP LANGUAGE</command></link> to drop procedural languages.
 187   </para>
 188
 189   <para>
 190    The system catalog <classname>pg_language</classname> (see <xref
 191    linkend="catalog-pg-language"/>) records information about the
 192    currently installed languages.  Also, the <application>psql</application>
 193    command <command>\dL</command> lists the installed languages.
 194   </para>
 195
 196   <para>
 197    To create functions in a procedural language, a user must have the
 198    <literal>USAGE</literal> privilege for the language.  By default,
 199    <literal>USAGE</literal> is granted to <literal>PUBLIC</literal> (i.e., everyone)
 200    for trusted languages.  This can be revoked if desired.
 201   </para>
 202
 203   <para>
 204    Procedural languages are local to individual databases.
 205    However, a language can be installed into the <literal>template1</literal>
 206    database, which will cause it to be available automatically in
 207    all subsequently-created databases.
 208   </para>
 209  </refsect1>
 210
 211  <refsect1 id="sql-createlanguage-examples">
 212   <title>Examples</title>
 213
 214   <para>
 215    A minimal sequence for creating a new procedural language is:
 216 <programlisting>
 217 CREATE FUNCTION plsample_call_handler() RETURNS language_handler
 218     AS '$libdir/plsample'
 219     LANGUAGE C;
 220 CREATE LANGUAGE plsample
 221     HANDLER plsample_call_handler;
 222 </programlisting>
 223    Typically that would be written in an extension's creation script,
 224    and users would do this to install the extension:
 225 <programlisting>
 226 CREATE EXTENSION plsample;
 227 </programlisting></para>
 228  </refsect1>
 229
 230  <refsect1 id="sql-createlanguage-compat">
 231   <title>Compatibility</title>
 232
 233   <para>
 234    <command>CREATE LANGUAGE</command> is a
 235    <productname>PostgreSQL</productname> extension.
 236   </para>
 237  </refsect1>
 238
 239  <refsect1>
 240   <title>See Also</title>
 241
 242   <simplelist type="inline">
 243    <member><xref linkend="sql-alterlanguage"/></member>
 244    <member><xref linkend="sql-createfunction"/></member>
 245    <member><xref linkend="sql-droplanguage"/></member>
 246    <member><xref linkend="sql-grant"/></member>
 247    <member><xref linkend="sql-revoke"/></member>
 248   </simplelist>
 249  </refsect1>
 250 </refentry>