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.21 2002/02/18 23:11:02 petere Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATELANGUAGE">
   7  <docinfo>
   8   <date>2001-09-05</date>
   9  </docinfo>
  10
  11  <refmeta>
  12   <refentrytitle id="sql-createlanguage-title">CREATE LANGUAGE</refentrytitle>
  13   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  14  </refmeta>
  15
  16  <refnamediv>
  17   <refname>CREATE LANGUAGE</refname>
  18   <refpurpose>define a new procedural language</refpurpose>
  19  </refnamediv>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langname</replaceable>
  24     HANDLER <replaceable class="parameter">call_handler</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 the
  45    <citetitle>Programmer's Guide</citetitle> for more information
  46    about language call handlers.
  47   </para>
  48
  49   <para>
  50    Note that procedural languages are local to individual databases.
  51    To make a language available in all databases by default, it should
  52    be installed into the <literal>template1</literal> database.
  53   </para>
  54  </refsect1>
  55
  56  <refsect1 id="sql-createlanguage-parameters">
  57   <title>Parameters</title>
  58
  59    <variablelist>
  60     <varlistentry>
  61      <term><literal>TRUSTED</literal></term>
  62
  63      <listitem>
  64       <para>
  65        <literal>TRUSTED</literal> specifies that the call handler for
  66        the language is safe, that is, it does not offer an
  67        unprivileged user any functionality to bypass access
  68        restrictions. If this keyword is omitted when registering the
  69        language, only users with the
  70        <productname>PostgreSQL</productname> superuser privilege can
  71        use this language to create new functions.
  72       </para>
  73      </listitem>
  74     </varlistentry>
  75
  76     <varlistentry>
  77      <term><literal>PROCEDURAL</literal></term>
  78
  79      <listitem>
  80       <para>
  81        This is a noise word.
  82       </para>
  83      </listitem>
  84     </varlistentry>
  85
  86     <varlistentry>
  87      <term><replaceable class="parameter">langname</replaceable></term>
  88
  89      <listitem>
  90       <para>
  91        The name of the new procedural language.  The language name is
  92        case insensitive. A procedural language cannot override one of
  93        the built-in languages of <productname>PostgreSQL</productname>.
  94       </para>
  95
  96       <para>
  97        For backward compatibility, the name may be enclosed by single
  98        quotes.
  99       </para>
 100      </listitem>
 101     </varlistentry>
 102
 103     <varlistentry>
 104      <term><literal>HANDLER</literal> <replaceable class="parameter">call_handler</replaceable></term>
 105
 106      <listitem>
 107       <para>
 108        <replaceable class="parameter">call_handler</replaceable> is
 109        the name of a previously registered function that will be
 110        called to execute the procedural language functions.  The call
 111        handler for a procedural language must be written in a compiled
 112        language such as C with version 1 call convention and
 113        registered with <productname>PostgreSQL</productname> as a
 114        function taking no arguments and returning the
 115        <type>opaque</type> type, a placeholder for unspecified or
 116        undefined types.
 117       </para>
 118      </listitem>
 119     </varlistentry>
 120    </variablelist>
 121  </refsect1>
 122
 123  <refsect1 id="sql-createlanguage-diagnostics">
 124   <title>Diagnostics</title>
 125
 126   <msgset>
 127    <msgentry>
 128     <msg>
 129      <msgmain>
 130       <msgtext>
 131 <screen>
 132 CREATE
 133 </screen>
 134       </msgtext>
 135      </msgmain>
 136     </msg>
 137
 138     <msgexplan>
 139      <para>
 140       This message is returned if the language is successfully
 141       created.
 142      </para>
 143     </msgexplan>
 144    </msgentry>
 145
 146    <msgentry>
 147     <msg>
 148      <msgmain>
 149       <msgtext>
 150 <screen>
 151 ERROR:  PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist
 152 </screen>
 153       </msgtext>
 154      </msgmain>
 155     </msg>
 156
 157     <msgexplan>
 158      <para>
 159       This error is returned if the function <replaceable
 160       class="parameter">funcname</replaceable>() is not found.
 161      </para>
 162     </msgexplan>
 163    </msgentry>
 164   </msgset>
 165  </refsect1>
 166
 167  <refsect1 id="sql-createlanguage-notes">
 168   <title>Notes</title>
 169
 170   <para>
 171    This command normally should not be executed directly by users.
 172    For the procedural languages supplied in the
 173    <productname>PostgreSQL</productname> distribution, the <xref
 174    linkend="app-createlang"> script should be used, which will also
 175    install the correct call handler.  (<command>createlang</command>
 176    will call <command>CREATE LANGUAGE</command> internally.)
 177   </para>
 178
 179   <para>
 180    Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new
 181    function.
 182   </para>
 183
 184   <para>
 185    Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
 186    linkend="app-droplang"> script, to drop procedural languages.
 187   </para>
 188
 189   <para>
 190    The system catalog <classname>pg_language</classname> records
 191    information about the currently installed procedural languages.
 192
 193 <screen>
 194         Table "pg_language"
 195    Attribute   |  Type   | Modifier
 196 ---------------+---------+----------
 197  lanname       | name    |
 198  lanispl       | boolean |
 199  lanpltrusted  | boolean |
 200  lanplcallfoid | oid     |
 201  lancompiler   | text    |
 202
 203    lanname   | lanispl | lanpltrusted | lanplcallfoid | lancompiler
 204 -------------+---------+--------------+---------------+-------------
 205  internal    | f       | f            |             0 | n/a
 206  c           | f       | f            |             0 | /bin/cc
 207  sql         | f       | t            |             0 | postgres
 208 </screen>
 209   </para>
 210
 211   <para>
 212    At present, the definition of a procedural language cannot be
 213    changed once it has been created.
 214   </para>
 215
 216   <para>
 217    To be able to use a procedural language, a user must be granted the
 218    <literal>USAGE</literal> privilege.  The
 219    <command>createlang</command> program automatically grants
 220    permissions to everyone if the language is known to be trusted.
 221   </para>
 222  </refsect1>
 223
 224  <refsect1 id="sql-createlanguage-examples">
 225   <title>Examples</title>
 226
 227   <para>
 228    The following two commands executed in sequence will register a new
 229    procedural language and the associated call handler.
 230 <programlisting>
 231 CREATE FUNCTION plsample_call_handler () RETURNS opaque
 232     AS '$libdir/plsample'
 233     LANGUAGE C;
 234 CREATE LANGUAGE plsample
 235     HANDLER plsample_call_handler;
 236 </programlisting>
 237   </para>
 238  </refsect1>
 239
 240  <refsect1 id="sql-createlanguage-compat">
 241   <title>Compatibility</title>
 242
 243   <para>
 244    <command>CREATE LANGUAGE</command> is a
 245    <productname>PostgreSQL</productname> extension.
 246   </para>
 247  </refsect1>
 248
 249  <refsect1>
 250   <title>History</title>
 251
 252   <para>
 253    The <command>CREATE LANGUAGE</command> command first appeared in
 254    <productname>PostgreSQL</productname> 6.3.
 255   </para>
 256  </refsect1>
 257
 258  <refsect1>
 259   <title>See Also</title>
 260
 261   <para>
 262    <simplelist type="inline">
 263     <member><xref linkend="app-createlang"></member>
 264     <member><xref linkend="sql-createfunction"></member>
 265     <member><xref linkend="app-droplang"></member>
 266     <member><xref linkend="sql-droplanguage"></member>
 267     <member><xref linkend="sql-grant"></member>
 268     <member><xref linkend="sql-revoke"></member>
 269     <member><citetitle>PostgreSQL Programmer's Guide</citetitle></member>
 270    </simplelist>
 271   </para>
 272  </refsect1>
 273 </refentry>
 274
 275 <!-- Keep this comment at the end of the file
 276 Local variables:
 277 mode: sgml
 278 sgml-omittag:nil
 279 sgml-shorttag:t
 280 sgml-minimize-attributes:nil
 281 sgml-always-quote-attributes:t
 282 sgml-indent-step:1
 283 sgml-indent-data:t
 284 sgml-parent-document:nil
 285 sgml-default-dtd-file:"../reference.ced"
 286 sgml-exposed-tags:nil
 287 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 288 sgml-local-ecat-files:nil
 289 End:
 290 -->