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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.37 2003/09/22 00:16:57 petere Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATELANGUAGE">
   7  <refmeta>
   8   <refentrytitle id="sql-createlanguage-title">CREATE LANGUAGE</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE LANGUAGE</refname>
  14   <refpurpose>define a new procedural language</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createlanguage">
  18   <primary>CREATE LANGUAGE</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
  24     HANDLER <replaceable class="parameter">call_handler</replaceable> [ VALIDATOR <replaceable>valfunction</replaceable> ]
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1 id="sql-createlanguage-description">
  29   <title>Description</title>
  30
  31   <para>
  32    Using <command>CREATE LANGUAGE</command>, a
  33    <productname>PostgreSQL</productname> user can register a new
  34    procedural language with a <productname>PostgreSQL</productname>
  35    database.  Subsequently, functions and trigger procedures can be
  36    defined in this new language.  The user must have the
  37    <productname>PostgreSQL</productname> superuser privilege to
  38    register a new language.
  39   </para>
  40
  41   <para>
  42    <command>CREATE LANGUAGE</command> effectively associates the
  43    language name with a call handler that is responsible for executing
  44    functions written in the language.  Refer to <xref linkend="xfunc">
  45    for more information about language call handlers.
  46   </para>
  47
  48   <para>
  49    Note that procedural languages are local to individual databases.
  50    To make a language available in all databases by default, it should
  51    be installed into the <literal>template1</literal> database.
  52   </para>
  53  </refsect1>
  54
  55  <refsect1 id="sql-createlanguage-parameters">
  56   <title>Parameters</title>
  57
  58    <variablelist>
  59     <varlistentry>
  60      <term><literal>TRUSTED</literal></term>
  61
  62      <listitem>
  63       <para>
  64        <literal>TRUSTED</literal> specifies that the call handler for
  65        the language is safe, that is, it does not offer an
  66        unprivileged user any functionality to bypass access
  67        restrictions. If this key word is omitted when registering the
  68        language, only users with the
  69        <productname>PostgreSQL</productname> superuser privilege can
  70        use this language to create new functions.
  71       </para>
  72      </listitem>
  73     </varlistentry>
  74
  75     <varlistentry>
  76      <term><literal>PROCEDURAL</literal></term>
  77
  78      <listitem>
  79       <para>
  80        This is a noise word.
  81       </para>
  82      </listitem>
  83     </varlistentry>
  84
  85     <varlistentry>
  86      <term><replaceable class="parameter">name</replaceable></term>
  87
  88      <listitem>
  89       <para>
  90        The name of the new procedural language.  The language name is
  91        case insensitive. The name must be unique among the languages
  92        in the database.
  93       </para>
  94
  95       <para>
  96        For backward compatibility, the name may be enclosed by single
  97        quotes.
  98       </para>
  99      </listitem>
 100     </varlistentry>
 101
 102     <varlistentry>
 103      <term><literal>HANDLER</literal> <replaceable class="parameter">call_handler</replaceable></term>
 104
 105      <listitem>
 106       <para>
 107        <replaceable class="parameter">call_handler</replaceable> is
 108        the name of a previously registered function that will be
 109        called to execute the procedural language functions.  The call
 110        handler for a procedural language must be written in a compiled
 111        language such as C with version 1 call convention and
 112        registered with <productname>PostgreSQL</productname> as a
 113        function taking no arguments and returning the
 114        <type>language_handler</type> type, a placeholder type that is
 115        simply used to identify the function as a call handler.
 116       </para>
 117      </listitem>
 118     </varlistentry>
 119
 120     <varlistentry>
 121      <term><literal>VALIDATOR</literal> <replaceable class="parameter">valfunction</replaceable></term>
 122
 123      <listitem>
 124       <para>
 125        <replaceable class="parameter">valfunction</replaceable> is the
 126        name of a previously registered function that will be called
 127        when a new function in the language is created, to validate the
 128        new function.
 129        If no
 130        validator function is specified, then a new function will not
 131        be checked when it is created.
 132        The validator function must take one argument of
 133        type <type>oid</type>, which will be the OID of the
 134        to-be-created function, and will typically return <type>void</>.
 135       </para>
 136
 137       <para>
 138        A validator function would typically inspect the function body
 139        for syntactical correctness, but it can also look at other
 140        properties of the function, for example if the language cannot
 141        handle certain argument types.  To signal an error, the
 142        validator function should use the <function>ereport()</function>
 143        function.  The return value of the function is ignored.
 144       </para>
 145      </listitem>
 146     </varlistentry>
 147    </variablelist>
 148  </refsect1>
 149
 150  <refsect1 id="sql-createlanguage-notes">
 151   <title>Notes</title>
 152
 153   <para>
 154    This command normally should not be executed directly by users.
 155    For the procedural languages supplied in the
 156    <productname>PostgreSQL</productname> distribution, the <xref
 157    linkend="app-createlang"> program should be used, which will also
 158    install the correct call handler.  (<command>createlang</command>
 159    will call <command>CREATE LANGUAGE</command> internally.)
 160   </para>
 161
 162   <para>
 163    In <productname>PostgreSQL</productname> versions before 7.3, it was
 164    necessary to declare handler functions as returning the placeholder
 165    type <type>opaque</>, rather than <type>language_handler</>.
 166    To support loading
 167    of old dump files, <command>CREATE LANGUAGE</> will accept a function
 168    declared as returning <type>opaque</>, but it will issue a notice and
 169    change the function's declared return type to <type>language_handler</>.
 170   </para>
 171
 172   <para>
 173    Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new
 174    function.
 175   </para>
 176
 177   <para>
 178    Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
 179    linkend="app-droplang"> program, to drop procedural languages.
 180   </para>
 181
 182   <para>
 183    The system catalog <classname>pg_language</classname> (see <xref
 184    linkend="catalog-pg-language">) records information about the
 185    currently installed languages.  Also <command>createlang</command>
 186    has an option to list the installed languages.
 187   </para>
 188
 189   <para>
 190    The definition of a procedural language cannot be changed once it
 191    has been created, with the exception of the privileges.
 192   </para>
 193
 194   <para>
 195    To be able to use a procedural language, a user must be granted the
 196    <literal>USAGE</literal> privilege.  The
 197    <command>createlang</command> program automatically grants
 198    permissions to everyone if the language is known to be trusted.
 199   </para>
 200  </refsect1>
 201
 202  <refsect1 id="sql-createlanguage-examples">
 203   <title>Examples</title>
 204
 205   <para>
 206    The following two commands executed in sequence will register a new
 207    procedural language and the associated call handler.
 208 <programlisting>
 209 CREATE FUNCTION plsample_call_handler() RETURNS language_handler
 210     AS '$libdir/plsample'
 211     LANGUAGE C;
 212 CREATE LANGUAGE plsample
 213     HANDLER plsample_call_handler;
 214 </programlisting>
 215   </para>
 216  </refsect1>
 217
 218  <refsect1 id="sql-createlanguage-compat">
 219   <title>Compatibility</title>
 220
 221   <para>
 222    <command>CREATE LANGUAGE</command> is a
 223    <productname>PostgreSQL</productname> extension.
 224   </para>
 225  </refsect1>
 226
 227  <refsect1>
 228   <title>See Also</title>
 229
 230   <simplelist type="inline">
 231    <member><xref linkend="sql-alterlanguage" endterm="sql-alterlanguage-title"></member>
 232    <member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
 233    <member><xref linkend="sql-droplanguage" endterm="sql-droplanguage-title"></member>
 234    <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
 235    <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
 236    <member><xref linkend="app-createlang"></member>
 237    <member><xref linkend="app-droplang"></member>
 238   </simplelist>
 239  </refsect1>
 240 </refentry>
 241
 242 <!-- Keep this comment at the end of the file
 243 Local variables:
 244 mode: sgml
 245 sgml-omittag:nil
 246 sgml-shorttag:t
 247 sgml-minimize-attributes:nil
 248 sgml-always-quote-attributes:t
 249 sgml-indent-step:1
 250 sgml-indent-data:t
 251 sgml-parent-document:nil
 252 sgml-default-dtd-file:"../reference.ced"
 253 sgml-exposed-tags:nil
 254 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 255 sgml-local-ecat-files:nil
 256 End:
 257 -->