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.18 2001/10/26 21:17:03 tgl Exp $
   3 Postgres 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"> command to create a new
 181    function.
 182   </para>
 183
 184   <para>
 185    Use <xref linkend="sql-droplanguage">, 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       | f            |             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  </refsect1>
 216
 217  <refsect1 id="sql-createlanguage-examples">
 218   <title>Examples</title>
 219
 220   <para>
 221    The following two commands executed in sequence will register a new
 222    procedural language and the associated call handler.
 223 <programlisting>
 224 CREATE FUNCTION plsample_call_handler () RETURNS opaque
 225     AS '$libdir/plsample'
 226     LANGUAGE C;
 227 CREATE LANGUAGE plsample
 228     HANDLER plsample_call_handler;
 229 </programlisting>
 230   </para>
 231  </refsect1>
 232
 233  <refsect1 id="sql-createlanguage-compat">
 234   <title>Compatibility</title>
 235
 236   <para>
 237    <command>CREATE LANGUAGE</command> is a
 238    <productname>PostgreSQL</productname> extension.
 239   </para>
 240  </refsect1>
 241
 242  <refsect1>
 243   <title>History</title>
 244
 245   <para>
 246    The <command>CREATE LANGUAGE</command> command first appeared in
 247    <productname>PostgreSQL</productname> 6.3.
 248   </para>
 249  </refsect1>
 250
 251  <refsect1>
 252   <title>See Also</title>
 253
 254   <para>
 255    <simplelist type="inline">
 256     <member><xref linkend="app-createlang"></member>
 257     <member><xref linkend="sql-createfunction"></member>
 258     <member><xref linkend="app-droplang"></member>
 259     <member><xref linkend="sql-droplanguage"></member>
 260     <member><citetitle>PostgreSQL Programmer's Guide</citetitle></member>
 261    </simplelist>
 262   </para>
 263  </refsect1>
 264 </refentry>
 265
 266 <!-- Keep this comment at the end of the file
 267 Local variables:
 268 mode: sgml
 269 sgml-omittag:nil
 270 sgml-shorttag:t
 271 sgml-minimize-attributes:nil
 272 sgml-always-quote-attributes:t
 273 sgml-indent-step:1
 274 sgml-indent-data:t
 275 sgml-parent-document:nil
 276 sgml-default-dtd-file:"../reference.ced"
 277 sgml-exposed-tags:nil
 278 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 279 sgml-local-ecat-files:nil
 280 End:
 281 -->