mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-03 06:46:54 +02:00
171 lines
6.2 KiB
Plaintext
171 lines
6.2 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.15 2001/09/10 21:58:47 petere Exp $
|
|
-->
|
|
|
|
<chapter id="xplang">
|
|
<title id="xplang-title">Procedural Languages</title>
|
|
|
|
<para>
|
|
<productname>Postgres</productname> allows users to add new
|
|
programming languages to be available for writing functions and
|
|
procedures. These are called <firstterm>procedural
|
|
languages</firstterm> (PL). In the case of a function or trigger
|
|
procedure written in a procedural language, the database server has
|
|
no built-in knowledge about how to interpret the function's source
|
|
text. Instead, the task is passed to a special handler that knows
|
|
the details of the language. The handler could either do all the
|
|
work of parsing, syntax analysis, execution, etc. itself, or it
|
|
could serve as <quote>glue</quote> between
|
|
<productname>Postgres</productname> and an existing implementation
|
|
of a programming language. The handler itself is a special
|
|
programming language function compiled into a shared object and
|
|
loaded on demand.
|
|
</para>
|
|
|
|
<para>
|
|
Writing a handler for a new procedural language is outside the
|
|
scope of this manual, although some information is provided in
|
|
the CREATE LANGUAGE reference page. Several procedural languages are
|
|
available in the standard <productname>Postgres</productname> distribution.
|
|
</para>
|
|
|
|
<sect1 id="xplang-install">
|
|
<title>Installing Procedural Languages</title>
|
|
|
|
<para>
|
|
A procedural language must be <quote>installed</quote> into each
|
|
database where it is to be used. But procedural languages installed in
|
|
the template1 database are automatically available in all
|
|
subsequently created databases. So the database administrator can
|
|
decide which languages are available in which databases, and can make
|
|
some languages available by default if he chooses.
|
|
</para>
|
|
|
|
<para>
|
|
For the languages supplied with the standard distribution, the
|
|
shell script <filename>createlang</filename> may be used instead
|
|
of carrying out the details by hand. For example, to install <application>PL/pgSQL</application>
|
|
into the template1 database, use
|
|
<programlisting>
|
|
createlang plpgsql template1
|
|
</programlisting>
|
|
The manual procedure described below is only recommended for
|
|
installing custom languages that <filename>createlang</filename>
|
|
does not know about.
|
|
</para>
|
|
|
|
<procedure>
|
|
<title>
|
|
Manual Procedural Language Installation
|
|
</title>
|
|
|
|
<para>
|
|
A procedural language is installed in the database in three
|
|
steps, which must be carried out by a database superuser.
|
|
</para>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
The shared object for the language handler must be compiled and
|
|
installed into an appropriate library directory. This works in the same
|
|
way as building and installing modules with regular user-defined C
|
|
functions does; see <xref linkend="dfunc">.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
The handler must be declared with the command
|
|
<synopsis>
|
|
CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
|
|
RETURNS OPAQUE AS
|
|
'<replaceable>path-to-shared-object</replaceable>' LANGUAGE C;
|
|
</synopsis>
|
|
The special return type of <type>OPAQUE</type> tells
|
|
the database that this function does not return one of
|
|
the defined <acronym>SQL</acronym> data types and is not directly usable
|
|
in <acronym>SQL</acronym> statements.
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
The PL must be declared with the command
|
|
<synopsis>
|
|
CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <replaceable>language-name</replaceable>
|
|
HANDLER <replaceable>handler_function_name</replaceable>;
|
|
</synopsis>
|
|
The optional key word <token>TRUSTED</token> tells
|
|
whether ordinary database users that have no superuser
|
|
privileges should be allowed to use this language to create functions
|
|
and trigger procedures. Since PL functions are
|
|
executed inside the database backend, the <acronym>TRUSTED</acronym>
|
|
flag should only be given for
|
|
languages that do not allow access to database backends
|
|
internals or the file system. The languages <application>PL/pgSQL</application>,
|
|
<application>PL/Tcl</application>, and <application>PL/Perl</application> are known to be trusted; the language <application>PL/TclU</application>
|
|
should <emphasis>not</emphasis> be marked trusted.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>
|
|
In a default <productname>Postgres</productname> installation, the
|
|
handler for the <application>PL/pgSQL</application> language is built and installed into the
|
|
<quote>library</quote> directory. If Tcl/Tk support is configured
|
|
in, the handlers for PL/Tcl and PL/TclU are also built and installed in
|
|
the same location. Likewise, the PL/Perl handler is built and installed
|
|
if Perl support is configured. The <filename>createlang</filename>
|
|
script automates the two CREATE steps described above.
|
|
</para>
|
|
|
|
<procedure>
|
|
<title>Example</title>
|
|
|
|
<step performance="required">
|
|
<para>
|
|
The following command tells the database where to find the
|
|
shared object for the <application>PL/pgSQL</application> language's call handler function.
|
|
|
|
<programlisting>
|
|
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
|
|
'$libdir/plpgsql' LANGUAGE C;
|
|
</programlisting>
|
|
</para>
|
|
</step>
|
|
|
|
<step performance="Required">
|
|
<para>
|
|
The command
|
|
<programlisting>
|
|
CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
|
|
HANDLER plpgsql_call_handler;
|
|
</programlisting>
|
|
then defines that the previously declared call handler function
|
|
should be invoked for functions and trigger procedures where the
|
|
language attribute is <literal>plpgsql</literal>.
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode:sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|