335 lines
11 KiB
Plaintext
335 lines
11 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.15 2002/01/25 19:13:15 tgl 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 the <ulink url="http://www.perl.com">Perl</ulink> programming
|
|
language to be used to write
|
|
<productname>PostgreSQL</productname> functions.
|
|
</para>
|
|
|
|
<!-- **** PL/Perl overview **** -->
|
|
|
|
<sect1 id="plperl-overview">
|
|
<title>Overview</title>
|
|
|
|
<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 backend or to gain OS-level access under the permissions of the
|
|
<productname>PostgreSQL</productname> user ID, as a C function can do.
|
|
Thus, any unprivileged database user may be
|
|
permitted to use this language.
|
|
</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 named <literal>plperlu</>).
|
|
In this case the full Perl language is available. The writer of a 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>
|
|
</sect1>
|
|
|
|
<sect1 id="plperl-install">
|
|
<title>Building and Installing PL/Perl</title>
|
|
|
|
<para>
|
|
If the <option>--with-perl</option> option was supplied to the
|
|
<indexterm><primary><filename>configure</filename></primary></indexterm>
|
|
<filename>configure</filename> script,
|
|
the <productname>PostgreSQL</productname> build process will attempt to
|
|
build the PL/Perl shared library and install it in the
|
|
<productname>PostgreSQL</productname> library directory.
|
|
</para>
|
|
|
|
<para>
|
|
On most platforms, since PL/Perl is a shared library, the
|
|
<indexterm><primary>libperl</primary></indexterm>
|
|
<filename>libperl</filename> library must be a shared library also.
|
|
At the time of this writing, this is almost never the case in prebuilt
|
|
Perl packages. If this difficulty arises in your situation, a
|
|
message like this will appear during the build to point out this
|
|
fact:
|
|
<screen>
|
|
<computeroutput>
|
|
*** Cannot build PL/Perl because libperl is not a shared library.
|
|
*** You might have to rebuild your Perl installation. Refer to
|
|
*** the documentation for details.
|
|
</computeroutput>
|
|
</screen>
|
|
If you see this, you will have to re-build and install
|
|
<productname>Perl</productname> manually to be able to build
|
|
PL/Perl. During the configuration process for
|
|
<productname>Perl</productname>, request a shared library.
|
|
</para>
|
|
|
|
<para>
|
|
After having reinstalled Perl, change to the directory
|
|
<filename>src/pl/plperl</filename> in the
|
|
<productname>PostgreSQL</productname> source tree and issue the commands
|
|
<programlisting>
|
|
gmake clean
|
|
gmake all
|
|
gmake install
|
|
</programlisting>
|
|
to complete the build and installation of the PL/Perl shared library.
|
|
</para>
|
|
|
|
<para>
|
|
To install
|
|
PL/Perl and/or PL/PerlU in a particular database, use the
|
|
<filename>createlang</filename> script, for example
|
|
<literal>createlang plperl <replaceable>dbname</></literal> or
|
|
<literal>createlang plperlu <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>
|
|
</sect1>
|
|
|
|
<!-- **** PL/Perl description **** -->
|
|
|
|
<sect1 id="plperl-description">
|
|
<title>Description</title>
|
|
|
|
<sect2>
|
|
<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>
|
|
|
|
PL/PerlU is the same, except that the language should be specified as
|
|
<literal>plperlu</>.
|
|
</para>
|
|
|
|
<para>
|
|
The body of the function is ordinary Perl code. 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. 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>
|
|
|
|
If a NULL 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>WITH (isStrict)</>
|
|
to the function definition to make <productname>PostgreSQL</productname>
|
|
do something more reasonable: if a NULL 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 perl_max
|
|
with one null and one non-null argument to return the non-null
|
|
argument, rather than NULL:
|
|
|
|
<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 a NULL 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 not currently any 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 functions
|
|
(<literal>q[]</literal>, <literal>qq[]</literal>,
|
|
<literal>qw[]</literal>).
|
|
</para>
|
|
</tip>
|
|
|
|
<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>
|
|
Note that if the same function was created by a superuser using language
|
|
<literal>plperlu</>, execution would succeed.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Data Values in PL/Perl</title>
|
|
|
|
<para>
|
|
The argument values supplied to a PL/Perl function's script are simply
|
|
the input arguments converted to text form (just as if they had been
|
|
displayed by a SELECT 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>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<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">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.
|
|
</para>
|
|
|
|
<para>
|
|
PL/Perl itself presently provides only one additional Perl command:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<indexterm>
|
|
<primary>elog</primary>
|
|
</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>NOTICE</>, and <literal>ERROR</>.
|
|
<literal>DEBUG</> and <literal>NOTICE</> simply emit the given message
|
|
into the postmaster log (and send it to the client too, in the case of
|
|
<literal>NOTICE</>). <literal>ERROR</> raises an error condition:
|
|
further execution of the function is abandoned, and the current
|
|
transaction is aborted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Missing Features</title>
|
|
|
|
<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>
|
|
|
|
<para>
|
|
PL/Perl cannot currently be used to write trigger functions.
|
|
</para>
|
|
|
|
<para>
|
|
DBD::PgSPI or similar capability should be integrated
|
|
into the standard <productname>PostgreSQL</productname> distribution.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</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:
|
|
-->
|