2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/xplang.sgml -->
|
2000-03-31 05:27:42 +02:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<chapter id="xplang">
|
2010-04-03 09:23:02 +02:00
|
|
|
<title>Procedural Languages</title>
|
1998-10-21 07:30:16 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="xplang">
|
|
|
|
<primary>procedural language</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<para>
|
2004-12-30 22:45:37 +01:00
|
|
|
<productname>PostgreSQL</productname> allows user-defined functions
|
|
|
|
to be written in other languages besides SQL and C. These other
|
|
|
|
languages are generically called <firstterm>procedural
|
|
|
|
languages</firstterm> (<acronym>PL</>s). For a function
|
|
|
|
written in a procedural language, the database server has
|
2000-04-03 00:59:40 +02:00
|
|
|
no built-in knowledge about how to interpret the function's source
|
2001-02-04 16:28:18 +01:00
|
|
|
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
|
2001-02-09 03:20:52 +01:00
|
|
|
could serve as <quote>glue</quote> between
|
2001-11-21 07:09:45 +01:00
|
|
|
<productname>PostgreSQL</productname> and an existing implementation
|
2004-12-30 22:45:37 +01:00
|
|
|
of a programming language. The handler itself is a
|
2003-04-07 03:29:26 +02:00
|
|
|
C language function compiled into a shared object and
|
2004-12-30 22:45:37 +01:00
|
|
|
loaded on demand, just like any other C function.
|
2000-03-31 00:13:30 +02:00
|
|
|
</para>
|
|
|
|
|
2000-04-03 00:59:40 +02:00
|
|
|
<para>
|
2004-12-30 22:45:37 +01:00
|
|
|
There are currently four procedural languages available in the
|
|
|
|
standard <productname>PostgreSQL</productname> distribution:
|
|
|
|
<application>PL/pgSQL</application> (<xref linkend="plpgsql">),
|
|
|
|
<application>PL/Tcl</application> (<xref linkend="pltcl">),
|
|
|
|
<application>PL/Perl</application> (<xref linkend="plperl">), and
|
|
|
|
<application>PL/Python</application> (<xref linkend="plpython">).
|
2004-12-30 04:13:56 +01:00
|
|
|
There are additional procedural languages available that are not
|
|
|
|
included in the core distribution. <xref linkend="external-projects">
|
2009-12-19 02:49:02 +01:00
|
|
|
has information about finding them. In addition other languages can
|
|
|
|
be defined by users; the basics of developing a new procedural
|
2006-11-20 18:42:16 +01:00
|
|
|
language are covered in <xref linkend="plhandler">.
|
2004-12-30 04:13:56 +01:00
|
|
|
</para>
|
|
|
|
|
2000-09-29 22:21:34 +02:00
|
|
|
<sect1 id="xplang-install">
|
2000-03-31 00:13:30 +02:00
|
|
|
<title>Installing Procedural Languages</title>
|
|
|
|
|
2001-02-09 03:20:52 +01:00
|
|
|
<para>
|
|
|
|
A procedural language must be <quote>installed</quote> into each
|
|
|
|
database where it is to be used. But procedural languages installed in
|
2003-04-07 03:29:26 +02:00
|
|
|
the database <literal>template1</> are automatically available in all
|
2004-12-30 22:45:37 +01:00
|
|
|
subsequently created databases, since their entries in
|
|
|
|
<literal>template1</> will be copied by <command>CREATE DATABASE</>.
|
|
|
|
So the database administrator can
|
2003-04-07 03:29:26 +02:00
|
|
|
decide which languages are available in which databases and can make
|
2001-02-09 03:20:52 +01:00
|
|
|
some languages available by default if he chooses.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-09-06 01:50:49 +02:00
|
|
|
For the languages supplied with the standard distribution, it is
|
2011-03-05 07:08:38 +01:00
|
|
|
only necessary to execute <command>CREATE EXTENSION</>
|
2005-09-06 01:50:49 +02:00
|
|
|
<replaceable>language_name</> to install the language into the
|
|
|
|
current database. Alternatively, the program <xref
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
linkend="app-createlang"> can be used to do this from the shell
|
2005-09-06 01:50:49 +02:00
|
|
|
command line. For example, to install the language
|
2009-12-19 02:49:02 +01:00
|
|
|
<application>PL/Perl</application> into the database
|
2007-02-01 01:28:19 +01:00
|
|
|
<literal>template1</>, use:
|
2001-02-09 03:20:52 +01:00
|
|
|
<programlisting>
|
2009-12-19 02:49:02 +01:00
|
|
|
createlang plperl template1
|
2001-02-09 03:20:52 +01:00
|
|
|
</programlisting>
|
|
|
|
The manual procedure described below is only recommended for
|
2011-03-05 07:08:38 +01:00
|
|
|
installing languages that have not been packaged as extensions.
|
2001-02-09 03:20:52 +01:00
|
|
|
</para>
|
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<procedure>
|
1999-07-22 17:11:05 +02:00
|
|
|
<title>
|
2001-02-09 03:20:52 +01:00
|
|
|
Manual Procedural Language Installation
|
1999-07-22 17:11:05 +02:00
|
|
|
</title>
|
1998-10-25 02:29:01 +02:00
|
|
|
|
|
|
|
<para>
|
2009-09-23 01:43:43 +02:00
|
|
|
A procedural language is installed in a database in five steps,
|
2011-03-05 07:08:38 +01:00
|
|
|
which must be carried out by a database superuser. In most cases
|
|
|
|
the required SQL commands should be packaged as the installation script
|
|
|
|
of an <quote>extension</>, so that <command>CREATE EXTENSION</> can be
|
|
|
|
used to execute them.
|
1998-12-29 03:24:47 +01:00
|
|
|
</para>
|
1999-07-22 17:11:05 +02:00
|
|
|
|
2004-12-30 22:45:37 +01:00
|
|
|
<step performance="required" id="xplang-install-cr1">
|
2000-03-31 00:13:30 +02:00
|
|
|
<para>
|
2001-02-04 16:28:18 +01:00
|
|
|
The shared object for the language handler must be compiled and
|
2001-02-09 03:20:52 +01:00
|
|
|
installed into an appropriate library directory. This works in the same
|
|
|
|
way as building and installing modules with regular user-defined C
|
2004-12-30 22:45:37 +01:00
|
|
|
functions does; see <xref linkend="dfunc">. Often, the language
|
|
|
|
handler will depend on an external library that provides the actual
|
|
|
|
programming language engine; if so, that must be installed as well.
|
2000-03-31 00:13:30 +02:00
|
|
|
</para>
|
|
|
|
</step>
|
2001-02-04 16:28:18 +01:00
|
|
|
|
2004-12-30 22:45:37 +01:00
|
|
|
<step performance="required" id="xplang-install-cr2">
|
2000-03-31 00:13:30 +02:00
|
|
|
<para>
|
|
|
|
The handler must be declared with the command
|
2001-02-04 16:28:18 +01:00
|
|
|
<synopsis>
|
2003-04-07 03:29:26 +02:00
|
|
|
CREATE FUNCTION <replaceable>handler_function_name</replaceable>()
|
|
|
|
RETURNS language_handler
|
|
|
|
AS '<replaceable>path-to-shared-object</replaceable>'
|
|
|
|
LANGUAGE C;
|
2001-02-04 16:28:18 +01:00
|
|
|
</synopsis>
|
2003-04-07 03:29:26 +02:00
|
|
|
The special return type of <type>language_handler</type> tells
|
|
|
|
the database system that this function does not return one of
|
2001-02-04 16:28:18 +01:00
|
|
|
the defined <acronym>SQL</acronym> data types and is not directly usable
|
2000-03-31 00:13:30 +02:00
|
|
|
in <acronym>SQL</acronym> statements.
|
|
|
|
</para>
|
|
|
|
</step>
|
2001-02-04 16:28:18 +01:00
|
|
|
|
2004-12-30 22:45:37 +01:00
|
|
|
<step performance="optional" id="xplang-install-cr3">
|
2009-09-23 01:43:43 +02:00
|
|
|
<para>
|
|
|
|
Optionally, the language handler can provide an <quote>inline</>
|
|
|
|
handler function that executes anonymous code blocks
|
2010-04-03 09:23:02 +02:00
|
|
|
(<xref linkend="sql-do"> commands)
|
2009-09-23 01:43:43 +02:00
|
|
|
written in this language. If an inline handler function
|
|
|
|
is provided by the language, declare it with a command like
|
|
|
|
<synopsis>
|
|
|
|
CREATE FUNCTION <replaceable>inline_function_name</replaceable>(internal)
|
|
|
|
RETURNS void
|
|
|
|
AS '<replaceable>path-to-shared-object</replaceable>'
|
|
|
|
LANGUAGE C;
|
|
|
|
</synopsis>
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
|
|
|
|
<step performance="optional" id="xplang-install-cr4">
|
2004-12-30 22:45:37 +01:00
|
|
|
<para>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
Optionally, the language handler can provide a <quote>validator</>
|
2004-12-30 22:45:37 +01:00
|
|
|
function that checks a function definition for correctness without
|
|
|
|
actually executing it. The validator function is called by
|
|
|
|
<command>CREATE FUNCTION</> if it exists. If a validator function
|
2009-09-23 01:43:43 +02:00
|
|
|
is provided by the language, declare it with a command like
|
2004-12-30 22:45:37 +01:00
|
|
|
<synopsis>
|
|
|
|
CREATE FUNCTION <replaceable>validator_function_name</replaceable>(oid)
|
|
|
|
RETURNS void
|
|
|
|
AS '<replaceable>path-to-shared-object</replaceable>'
|
2011-03-05 07:08:38 +01:00
|
|
|
LANGUAGE C STRICT;
|
2004-12-30 22:45:37 +01:00
|
|
|
</synopsis>
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
|
2009-09-23 01:43:43 +02:00
|
|
|
<step performance="required" id="xplang-install-cr5">
|
2000-03-31 00:13:30 +02:00
|
|
|
<para>
|
2011-03-05 07:08:38 +01:00
|
|
|
Finally, the PL must be declared with the command
|
2001-02-04 16:28:18 +01:00
|
|
|
<synopsis>
|
2001-08-13 23:34:54 +02:00
|
|
|
CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <replaceable>language-name</replaceable>
|
2004-12-30 22:45:37 +01:00
|
|
|
HANDLER <replaceable>handler_function_name</replaceable>
|
2009-09-23 01:43:43 +02:00
|
|
|
<optional>INLINE <replaceable>inline_function_name</replaceable></optional>
|
2004-12-30 22:45:37 +01:00
|
|
|
<optional>VALIDATOR <replaceable>validator_function_name</replaceable></optional> ;
|
2001-02-04 16:28:18 +01:00
|
|
|
</synopsis>
|
2003-04-07 03:29:26 +02:00
|
|
|
The optional key word <literal>TRUSTED</literal> specifies that
|
2010-05-30 04:23:09 +02:00
|
|
|
the language does not grant access to data that the user would
|
|
|
|
not otherwise have. Trusted languages are designed for ordinary
|
|
|
|
database users (those without superuser privilege) and allows them
|
2011-03-05 07:08:38 +01:00
|
|
|
to safely create functions and trigger
|
2002-01-07 03:29:15 +01:00
|
|
|
procedures. Since PL functions are executed inside the database
|
|
|
|
server, the <literal>TRUSTED</literal> flag should only be given
|
|
|
|
for languages that do not allow access to database server
|
|
|
|
internals or the file system. The languages
|
|
|
|
<application>PL/pgSQL</application>,
|
2003-06-30 20:31:42 +02:00
|
|
|
<application>PL/Tcl</application>, and
|
|
|
|
<application>PL/Perl</application>
|
|
|
|
are considered trusted; the languages
|
|
|
|
<application>PL/TclU</application>,
|
|
|
|
<application>PL/PerlU</application>, and
|
|
|
|
<application>PL/PythonU</application>
|
|
|
|
are designed to provide unlimited functionality and should
|
|
|
|
<emphasis>not</emphasis> be marked trusted.
|
2000-03-31 00:13:30 +02:00
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
</procedure>
|
|
|
|
|
2001-02-04 16:28:18 +01:00
|
|
|
<para>
|
2003-04-07 03:29:26 +02:00
|
|
|
<xref linkend="xplang-install-example"> shows how the manual
|
|
|
|
installation procedure would work with the language
|
2009-12-19 02:49:02 +01:00
|
|
|
<application>PL/Perl</application>.
|
2001-02-04 16:28:18 +01:00
|
|
|
</para>
|
|
|
|
|
2003-04-07 03:29:26 +02:00
|
|
|
<example id="xplang-install-example">
|
2009-12-19 02:49:02 +01:00
|
|
|
<title>Manual Installation of <application>PL/Perl</application></title>
|
2001-02-04 16:28:18 +01:00
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<para>
|
2009-12-19 02:49:02 +01:00
|
|
|
The following command tells the database server where to find the
|
|
|
|
shared object for the <application>PL/Perl</application> language's call
|
|
|
|
handler function:
|
2000-03-31 00:13:30 +02:00
|
|
|
|
2001-02-04 16:28:18 +01:00
|
|
|
<programlisting>
|
2009-12-19 02:49:02 +01:00
|
|
|
CREATE FUNCTION plperl_call_handler() RETURNS language_handler AS
|
|
|
|
'$libdir/plperl' LANGUAGE C;
|
2001-02-04 16:28:18 +01:00
|
|
|
</programlisting>
|
2000-03-31 00:13:30 +02:00
|
|
|
</para>
|
1998-10-21 07:30:16 +02:00
|
|
|
|
2004-12-30 22:45:37 +01:00
|
|
|
<para>
|
2009-12-19 02:49:02 +01:00
|
|
|
<application>PL/Perl</application> has an inline handler function
|
2009-09-23 01:43:43 +02:00
|
|
|
and a validator function, so we declare those too:
|
2004-12-30 22:45:37 +01:00
|
|
|
|
|
|
|
<programlisting>
|
2009-12-19 02:49:02 +01:00
|
|
|
CREATE FUNCTION plperl_inline_handler(internal) RETURNS void AS
|
|
|
|
'$libdir/plperl' LANGUAGE C;
|
2009-09-23 01:43:43 +02:00
|
|
|
|
2009-12-19 02:49:02 +01:00
|
|
|
CREATE FUNCTION plperl_validator(oid) RETURNS void AS
|
2011-03-05 07:08:38 +01:00
|
|
|
'$libdir/plperl' LANGUAGE C STRICT;
|
2004-12-30 22:45:37 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2001-05-19 11:01:10 +02:00
|
|
|
<para>
|
2007-02-01 01:28:19 +01:00
|
|
|
The command:
|
2001-02-04 16:28:18 +01:00
|
|
|
<programlisting>
|
2009-12-19 02:49:02 +01:00
|
|
|
CREATE TRUSTED PROCEDURAL LANGUAGE plperl
|
|
|
|
HANDLER plperl_call_handler
|
|
|
|
INLINE plperl_inline_handler
|
|
|
|
VALIDATOR plperl_validator;
|
2001-02-04 16:28:18 +01:00
|
|
|
</programlisting>
|
2004-12-30 22:45:37 +01:00
|
|
|
then defines that the previously declared functions
|
2001-02-04 16:28:18 +01:00
|
|
|
should be invoked for functions and trigger procedures where the
|
2009-12-19 02:49:02 +01:00
|
|
|
language attribute is <literal>plperl</literal>.
|
2000-03-31 00:13:30 +02:00
|
|
|
</para>
|
2002-01-07 03:29:15 +01:00
|
|
|
</example>
|
2001-02-04 16:28:18 +01:00
|
|
|
|
2003-04-07 03:29:26 +02:00
|
|
|
<para>
|
|
|
|
In a default <productname>PostgreSQL</productname> installation,
|
|
|
|
the handler for the <application>PL/pgSQL</application> language
|
|
|
|
is built and installed into the <quote>library</quote>
|
2009-12-19 02:49:02 +01:00
|
|
|
directory; furthermore, the <application>PL/pgSQL</application> language
|
|
|
|
itself is installed in all databases.
|
|
|
|
If <application>Tcl</> support is configured in, the handlers for
|
|
|
|
<application>PL/Tcl</> and <application>PL/TclU</> are built and installed
|
|
|
|
in the library directory, but the language itself is not installed in any
|
|
|
|
database by default.
|
|
|
|
Likewise, the <application>PL/Perl</> and <application>PL/PerlU</>
|
|
|
|
handlers are built and installed if Perl support is configured, and the
|
|
|
|
<application>PL/PythonU</> handler is installed if Python support is
|
|
|
|
configured, but these languages are not installed by default.
|
2003-04-07 03:29:26 +02:00
|
|
|
</para>
|
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
</sect1>
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
</chapter>
|