begriffs open source - ai-pg/blob - full-docs/src/sgml/html/xplang-install.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>40.1. Installing Procedural Languages</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="xplang.html" title="Chapter 40. Procedural Languages" /><link rel="next" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">40.1. Installing Procedural Languages</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="xplang.html" title="Chapter 40. Procedural Languages">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="xplang.html" title="Chapter 40. Procedural Languages">Up</a></td><th width="60%" align="center">Chapter 40. Procedural Languages</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language">Next</a></td></tr></table><hr /></div><div class="sect1" id="XPLANG-INSTALL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">40.1. Installing Procedural Languages <a href="#XPLANG-INSTALL" class="id_link">#</a></h2></div></div></div><p>
   3     A procedural language must be <span class="quote">“<span class="quote">installed</span>”</span> into each
   4     database where it is to be used.  But procedural languages installed in
   5     the database <code class="literal">template1</code> are automatically available in all
   6     subsequently created databases, since their entries in
   7     <code class="literal">template1</code> will be copied by <code class="command">CREATE DATABASE</code>.
   8     So the database administrator can
   9     decide which languages are available in which databases and can make
  10     some languages available by default if desired.
  11    </p><p>
  12     For the languages supplied with the standard distribution, it is
  13     only necessary to execute <code class="command">CREATE EXTENSION</code>
  14     <em class="replaceable"><code>language_name</code></em> to install the language into the
  15     current database.
  16     The manual procedure described below is only recommended for
  17     installing languages that have not been packaged as extensions.
  18    </p><div class="procedure" id="id-1.8.7.5.4"><p class="title"><strong>Manual Procedural Language Installation</strong></p><p>
  19      A procedural language is installed in a database in five steps,
  20      which must be carried out by a database superuser.  In most cases
  21      the required SQL commands should be packaged as the installation script
  22      of an <span class="quote">“<span class="quote">extension</span>”</span>, so that <code class="command">CREATE EXTENSION</code> can be
  23      used to execute them.
  24     </p><ol class="procedure" type="1"><li class="step" id="XPLANG-INSTALL-CR1"><p>
  25       The shared object for the language handler must be compiled and
  26       installed into an appropriate library directory.  This works in the same
  27       way as building and installing modules with regular user-defined C
  28       functions does; see <a class="xref" href="xfunc-c.html#DFUNC" title="36.10.5. Compiling and Linking Dynamically-Loaded Functions">Section 36.10.5</a>.  Often, the language
  29       handler will depend on an external library that provides the actual
  30       programming language engine; if so, that must be installed as well.
  31      </p></li><li class="step" id="XPLANG-INSTALL-CR2"><p>
  32       The handler must be declared with the command
  33 </p><pre class="synopsis">
  34 CREATE FUNCTION <em class="replaceable"><code>handler_function_name</code></em>()
  35     RETURNS language_handler
  36     AS '<em class="replaceable"><code>path-to-shared-object</code></em>'
  37     LANGUAGE C;
  38 </pre><p>
  39       The special return type of <code class="type">language_handler</code> tells
  40       the database system that this function does not return one of
  41       the defined <acronym class="acronym">SQL</acronym> data types and is not directly usable
  42       in <acronym class="acronym">SQL</acronym> statements.
  43      </p></li><li class="step" id="XPLANG-INSTALL-CR3"><p>
  44       Optionally, the language handler can provide an <span class="quote">“<span class="quote">inline</span>”</span>
  45       handler function that executes anonymous code blocks
  46       (<a class="link" href="sql-do.html" title="DO"><code class="command">DO</code></a> commands)
  47       written in this language.  If an inline handler function
  48       is provided by the language, declare it with a command like
  49 </p><pre class="synopsis">
  50 CREATE FUNCTION <em class="replaceable"><code>inline_function_name</code></em>(internal)
  51     RETURNS void
  52     AS '<em class="replaceable"><code>path-to-shared-object</code></em>'
  53     LANGUAGE C;
  54 </pre><p>
  55      </p></li><li class="step" id="XPLANG-INSTALL-CR4"><p>
  56       Optionally, the language handler can provide a <span class="quote">“<span class="quote">validator</span>”</span>
  57       function that checks a function definition for correctness without
  58       actually executing it.  The validator function is called by
  59       <code class="command">CREATE FUNCTION</code> if it exists.  If a validator function
  60       is provided by the language, declare it with a command like
  61 </p><pre class="synopsis">
  62 CREATE FUNCTION <em class="replaceable"><code>validator_function_name</code></em>(oid)
  63     RETURNS void
  64     AS '<em class="replaceable"><code>path-to-shared-object</code></em>'
  65     LANGUAGE C STRICT;
  66 </pre><p>
  67      </p></li><li class="step" id="XPLANG-INSTALL-CR5"><p>
  68       Finally, the PL must be declared with the command
  69 </p><pre class="synopsis">
  70 CREATE [<span class="optional">TRUSTED</span>] LANGUAGE <em class="replaceable"><code>language_name</code></em>
  71     HANDLER <em class="replaceable"><code>handler_function_name</code></em>
  72     [<span class="optional">INLINE <em class="replaceable"><code>inline_function_name</code></em></span>]
  73     [<span class="optional">VALIDATOR <em class="replaceable"><code>validator_function_name</code></em></span>] ;
  74 </pre><p>
  75       The optional key word <code class="literal">TRUSTED</code> specifies that
  76       the language does not grant access to data that the user would
  77       not otherwise have.  Trusted languages are designed for ordinary
  78       database users (those without superuser privilege) and allows them
  79       to safely create functions and
  80       procedures. Since PL functions are executed inside the database
  81       server, the <code class="literal">TRUSTED</code> flag should only be given
  82       for languages that do not allow access to database server
  83       internals or the file system. The languages
  84       <span class="application">PL/pgSQL</span>,
  85       <span class="application">PL/Tcl</span>, and
  86       <span class="application">PL/Perl</span>
  87       are considered trusted; the languages
  88       <span class="application">PL/TclU</span>,
  89       <span class="application">PL/PerlU</span>, and
  90       <span class="application">PL/PythonU</span>
  91       are designed to provide unlimited functionality and should
  92       <span class="emphasis"><em>not</em></span> be marked trusted.
  93      </p></li></ol></div><p>
  94     <a class="xref" href="xplang-install.html#XPLANG-INSTALL-EXAMPLE" title="Example 40.1. Manual Installation of PL/Perl">Example 40.1</a> shows how the manual
  95     installation procedure would work with the language
  96     <span class="application">PL/Perl</span>.
  97    </p><div class="example" id="XPLANG-INSTALL-EXAMPLE"><p class="title"><strong>Example 40.1. Manual Installation of <span class="application">PL/Perl</span></strong></p><div class="example-contents"><p>
  98       The following command tells the database server where to find the
  99       shared object for the <span class="application">PL/Perl</span> language's call
 100       handler function:
 101
 102 </p><pre class="programlisting">
 103 CREATE FUNCTION plperl_call_handler() RETURNS language_handler AS
 104     '$libdir/plperl' LANGUAGE C;
 105 </pre><p>
 106      </p><p>
 107       <span class="application">PL/Perl</span> has an inline handler function
 108       and a validator function, so we declare those too:
 109
 110 </p><pre class="programlisting">
 111 CREATE FUNCTION plperl_inline_handler(internal) RETURNS void AS
 112     '$libdir/plperl' LANGUAGE C STRICT;
 113
 114 CREATE FUNCTION plperl_validator(oid) RETURNS void AS
 115     '$libdir/plperl' LANGUAGE C STRICT;
 116 </pre><p>
 117      </p><p>
 118       The command:
 119 </p><pre class="programlisting">
 120 CREATE TRUSTED LANGUAGE plperl
 121     HANDLER plperl_call_handler
 122     INLINE plperl_inline_handler
 123     VALIDATOR plperl_validator;
 124 </pre><p>
 125       then defines that the previously declared functions
 126       should be invoked for functions and procedures where the
 127       language attribute is <code class="literal">plperl</code>.
 128      </p></div></div><br class="example-break" /><p>
 129     In a default <span class="productname">PostgreSQL</span> installation,
 130     the handler for the <span class="application">PL/pgSQL</span> language
 131     is built and installed into the <span class="quote">“<span class="quote">library</span>”</span>
 132     directory; furthermore, the <span class="application">PL/pgSQL</span> language
 133     itself is installed in all databases.
 134     If <span class="application">Tcl</span> support is configured in, the handlers for
 135     <span class="application">PL/Tcl</span> and <span class="application">PL/TclU</span> are built and installed
 136     in the library directory, but the language itself is not installed in any
 137     database by default.
 138     Likewise, the <span class="application">PL/Perl</span> and <span class="application">PL/PerlU</span>
 139     handlers are built and installed if Perl support is configured, and the
 140     <span class="application">PL/PythonU</span> handler is installed if Python support is
 141     configured, but these languages are not installed by default.
 142    </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="xplang.html" title="Chapter 40. Procedural Languages">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="xplang.html" title="Chapter 40. Procedural Languages">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plpgsql.html" title="Chapter 41. PL/pgSQL — SQL Procedural Language">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 40. Procedural Languages </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 41. <span class="application">PL/pgSQL</span> — <acronym class="acronym">SQL</acronym> Procedural Language</td></tr></table></div></body></html>