363 lines
12 KiB
Plaintext
363 lines
12 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.20.2.1 2010/05/13 16:44:35 adunstan Exp $
|
|
-->
|
|
|
|
<chapter id="plperl">
|
|
<title>PL/Perl - Perl Procedural Language</title>
|
|
|
|
<indexterm zone="plperl">
|
|
<primary>PL/Perl</primary>
|
|
</indexterm>
|
|
|
|
<indexterm zone="plperl">
|
|
<primary>Perl</primary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
PL/Perl is a loadable procedural language that enables you to write
|
|
<productname>PostgreSQL</productname> functions in the <ulink
|
|
url="http://www.perl.com">Perl</ulink> programming language.
|
|
</para>
|
|
|
|
<para>
|
|
To install PL/Perl in a particular database, use
|
|
<literal>createlang plperl <replaceable>dbname</></literal>.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
If a language is installed into <literal>template1</>, all subsequently
|
|
created databases will have the language installed automatically.
|
|
</para>
|
|
</tip>
|
|
|
|
<note>
|
|
<para>
|
|
Users of source packages must specially enable the build of
|
|
PL/Perl during the installation process. (Refer to the installation
|
|
instructions for more information.) Users of binary packages
|
|
might find PL/Perl in a separate subpackage.
|
|
</para>
|
|
</note>
|
|
|
|
<sect1 id="plperl-funcs">
|
|
<title>PL/Perl Functions and Arguments</title>
|
|
|
|
<para>
|
|
To create a function in the PL/Perl language, use the standard syntax:
|
|
<programlisting>
|
|
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS '
|
|
# PL/Perl function body
|
|
' LANGUAGE plperl;
|
|
</programlisting>
|
|
The body of the function is ordinary Perl code.
|
|
</para>
|
|
|
|
<para>
|
|
Arguments and results are handled as in any other Perl subroutine:
|
|
Arguments are passed in <varname>@_</varname>, and a result value
|
|
is returned with <literal>return</> or as the last expression
|
|
evaluated in the function.
|
|
</para>
|
|
|
|
<para>
|
|
For example, a function returning the greater of two integer values
|
|
could be defined as:
|
|
|
|
<programlisting>
|
|
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
|
|
if ($_[0] > $_[1]) { return $_[0]; }
|
|
return $_[1];
|
|
' LANGUAGE plperl;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
If an SQL null value<indexterm><primary>null value</><secondary
|
|
sortas="PL/Perl">in PL/Perl</></indexterm> is passed to a function,
|
|
the argument value will appear as <quote>undefined</> in Perl. The
|
|
above function definition will not behave very nicely with null
|
|
inputs (in fact, it will act as though they are zeroes). We could
|
|
add <literal>STRICT</> to the function definition to make
|
|
<productname>PostgreSQL</productname> do something more reasonable:
|
|
if a null value is passed, the function will not be called at all,
|
|
but will just return a null result automatically. Alternatively,
|
|
we could check for undefined inputs in the function body. For
|
|
example, suppose that we wanted <function>perl_max</function> with
|
|
one null and one non-null argument to return the non-null argument,
|
|
rather than a null value:
|
|
|
|
<programlisting>
|
|
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
|
|
my ($a,$b) = @_;
|
|
if (! defined $a) {
|
|
if (! defined $b) { return undef; }
|
|
return $b;
|
|
}
|
|
if (! defined $b) { return $a; }
|
|
if ($a > $b) { return $a; }
|
|
return $b;
|
|
' LANGUAGE plperl;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
As shown above, to return an SQL null value from a PL/Perl
|
|
function, return an undefined value. This can be done whether the
|
|
function is strict or not.
|
|
</para>
|
|
|
|
<para>
|
|
Composite-type arguments are passed to the function as references
|
|
to hashes. The keys of the hash are the attribute names of the
|
|
composite type. Here is an example:
|
|
|
|
<programlisting>
|
|
CREATE TABLE employee (
|
|
name text,
|
|
basesalary integer,
|
|
bonus integer
|
|
);
|
|
|
|
CREATE FUNCTION empcomp(employee) RETURNS integer AS '
|
|
my ($emp) = @_;
|
|
return $emp->{''basesalary''} + $emp->{''bonus''};
|
|
' LANGUAGE plperl;
|
|
|
|
SELECT name, empcomp(employee) FROM employee;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
There is currently no support for returning a composite-type result
|
|
value.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
Because the function body is passed as an SQL string literal to
|
|
<command>CREATE FUNCTION</command>, you have to escape single
|
|
quotes and backslashes within your Perl source, typically by
|
|
doubling them as shown in the above example. Another possible
|
|
approach is to avoid writing single quotes by using Perl's
|
|
extended quoting operators (<literal>q[]</literal>,
|
|
<literal>qq[]</literal>, <literal>qw[]</literal>).
|
|
</para>
|
|
</tip>
|
|
</sect1>
|
|
|
|
<sect1 id="plperl-data">
|
|
<title>Data Values in PL/Perl</title>
|
|
|
|
<para>
|
|
The argument values supplied to a PL/Perl function's code are
|
|
simply the input arguments converted to text form (just as if they
|
|
had been displayed by a <literal>SELECT</literal> statement).
|
|
Conversely, the <literal>return</> command will accept any string
|
|
that is acceptable input format for the function's declared return
|
|
type. So, the PL/Perl programmer can manipulate data values as if
|
|
they were just text.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plperl-database">
|
|
<title>Database Access from PL/Perl</title>
|
|
|
|
<para>
|
|
Access to the database itself from your Perl function can be done via
|
|
an experimental module <ulink
|
|
url="http://www.cpan.org/modules/by-module/DBD/APILOS/"><literal>DBD::PgSPI</literal></ulink>
|
|
(also available at <ulink url="http://www.cpan.org/SITES.html"><acronym>CPAN</>
|
|
mirror sites</ulink>). This module makes available a
|
|
<acronym>DBI</>-compliant database-handle named
|
|
<varname>$pg_dbh</varname> that can be used to perform queries
|
|
with normal <acronym>DBI</> syntax.<indexterm><primary>DBI</></indexterm>
|
|
</para>
|
|
|
|
<para>
|
|
PL/Perl itself presently provides only one additional Perl command:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<indexterm>
|
|
<primary>elog</primary>
|
|
<secondary>in PL/Perl</secondary>
|
|
</indexterm>
|
|
|
|
<term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Emit a log or error message. Possible levels are
|
|
<literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
|
|
<literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
|
|
<literal>ERROR</> raises an error condition: further execution
|
|
of the function is abandoned, and the current transaction is
|
|
aborted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plperl-trusted">
|
|
<title>Trusted and Untrusted PL/Perl</title>
|
|
|
|
<indexterm zone="plperl-trusted">
|
|
<primary>trusted</primary>
|
|
<secondary>PL/Perl</secondary>
|
|
</indexterm>
|
|
|
|
<para>
|
|
Normally, PL/Perl is installed as a <quote>trusted</> programming
|
|
language named <literal>plperl</>. In this setup, certain Perl
|
|
operations are disabled to preserve security. In general, the
|
|
operations that are restricted are those that interact with the
|
|
environment. This includes file handle operations,
|
|
<literal>require</literal>, and <literal>use</literal> (for
|
|
external modules). There is no way to access internals of the
|
|
database server process or to gain OS-level access with the
|
|
permissions of the server process,
|
|
as a C function can do. Thus, any unprivileged database user may
|
|
be permitted to use this language.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example of a function that will not work because file
|
|
system operations are not allowed for security reasons:
|
|
<programlisting>
|
|
CREATE FUNCTION badfunc() RETURNS integer AS '
|
|
open(TEMP, ">/tmp/badfile");
|
|
print TEMP "Gotcha!\n";
|
|
return 1;
|
|
' LANGUAGE plperl;
|
|
</programlisting>
|
|
The creation of the function will succeed, but executing it will not.
|
|
</para>
|
|
|
|
<para>
|
|
Sometimes it is desirable to write Perl functions that are not
|
|
restricted. For example, one might want a Perl function that sends
|
|
mail. To handle these cases, PL/Perl can also be installed as an
|
|
<quote>untrusted</> language (usually called
|
|
<application>PL/PerlU</application><indexterm><primary>PL/PerlU</></indexterm>).
|
|
In this case the full Perl language is available. If the
|
|
<command>createlang</command> program is used to install the
|
|
language, the language name <literal>plperlu</literal> will select
|
|
the untrusted PL/Perl variant.
|
|
</para>
|
|
|
|
<para>
|
|
The writer of a <application>PL/PerlU</> function must take care that the function
|
|
cannot be used to do anything unwanted, since it will be able to do
|
|
anything that could be done by a user logged in as the database
|
|
administrator. Note that the database system allows only database
|
|
superusers to create functions in untrusted languages.
|
|
</para>
|
|
|
|
<para>
|
|
If the above function was created by a superuser using the language
|
|
<literal>plperlu</>, execution would succeed.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
While <application>PL/Perl</> functions run in a separate Perl
|
|
interpreter for each SQL role, all <application>PL/PerlU</> functions
|
|
executed in a given session run in a single Perl interpreter (which is
|
|
not any of the ones used for <application>PL/Perl</> functions).
|
|
This allows <application>PL/PerlU</> functions to share data freely,
|
|
but no communication can occur between <application>PL/Perl</> and
|
|
<application>PL/PerlU</> functions.
|
|
</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>
|
|
Perl cannot support multiple interpreters within one process unless
|
|
it was built with the appropriate flags, namely either
|
|
<literal>usemultiplicity</> or <literal>useithreads</>.
|
|
(<literal>usemultiplicity</> is preferred unless you actually need
|
|
to use threads. For more details, see the
|
|
<citerefentry><refentrytitle>perlembed</></citerefentry> man page.)
|
|
If <application>PL/Perl</> is used with a copy of Perl that was not built
|
|
this way, then it is only possible to have one Perl interpreter per
|
|
session, and so any one session can only execute either
|
|
<application>PL/PerlU</> functions, or <application>PL/Perl</> functions
|
|
that are all called by the same SQL role.
|
|
</para>
|
|
</note>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="plperl-missing">
|
|
<title>Missing Features</title>
|
|
|
|
<para>
|
|
The following features are currently missing from PL/Perl, but they
|
|
would make welcome contributions.
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
PL/Perl functions cannot call each other directly (because they
|
|
are anonymous subroutines inside Perl). There's presently no
|
|
way for them to share global variables, either.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
PL/Perl cannot be used to write trigger
|
|
functions.<indexterm><primary>trigger</><secondary>in
|
|
PL/Perl</></indexterm>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<application>DBD::PgSPI</applicatioN> or similar capability
|
|
should be integrated into the standard
|
|
<productname>PostgreSQL</productname> distribution.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
For security reasons, PL/Perl executes functions called by any one SQL role
|
|
in a separate Perl interpreter for that role. This prevents accidental or
|
|
malicious interference by one user with the behavior of another user's
|
|
PL/Perl functions. Each such interpreter has its own value of the
|
|
<varname>%_SHARED</varname> variable and other global state. Thus, two
|
|
PL/Perl functions will share the same value of <varname>%_SHARED</varname>
|
|
if and only if they are executed by the same SQL role. In an application
|
|
wherein a single session executes code under multiple SQL roles (via
|
|
<literal>SECURITY DEFINER</> functions, use of <command>SET ROLE</>, etc)
|
|
you may need to take explicit steps to ensure that PL/Perl functions can
|
|
share data via <varname>%_SHARED</varname>. To do that, make sure that
|
|
functions that should communicate are owned by the same user, and mark
|
|
them <literal>SECURITY DEFINER</>. You must of course take care that
|
|
such functions can't be used to do anything unintended.
|
|
</para>
|
|
</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:
|
|
-->
|