Table of Contents
PL/Perl is a loadable procedural language that enables you to write PostgreSQL functions in the Perl programming language.
The usual advantage to using PL/Perl is that this allows use, within stored functions, of the manyfold “string munging” operators and functions available for Perl. Parsing complex strings may be be easier using Perl than it is with the string functions and control structures provided in PL/pgSQL.
To install PL/Perl in a particular database, use
createlang plperl
.
dbname
If a language is installed into template1
, all subsequently
created databases will have the language installed automatically.
Users of source packages must specially enable the build of PL/Perl during the installation process. (Refer to Section 14.1, “Short Version” for more information.) Users of binary packages might find PL/Perl in a separate subpackage.
To create a function in the PL/Perl language, use the standard CREATE FUNCTION syntax:
CREATE FUNCTIONfuncname
(argument-types
) RETURNSreturn-type
AS $$ # PL/Perl function body $$ LANGUAGE plperl;
The body of the function is ordinary Perl code. In fact, the PL/Perl glue code wraps it inside a Perl subroutine. A PL/Perl function must always return a scalar value. You can return more complex structures (arrays, records, and sets) by returning a reference, as discussed below. Never return a list.
The use of named nested subroutines is dangerous in Perl, especially if
they refer to lexical variables in the enclosing scope. Because a PL/Perl
function is wrapped in a subroutine, any named subroutine you create will
be nested. In general, it is far safer to create anonymous subroutines
which you call via a coderef. See the perldiag
man page for more details.
The syntax of the CREATE FUNCTION
command requires
the function body to be written as a string constant. It is usually
most convenient to use dollar quoting (see Section 4.1.2.2, “Dollar-Quoted String Constants”) for the string constant.
If you choose to use escape string syntax E''
,
you must double the single quote marks ('
) and backslashes
(\
) used in the body of the function
(see Section 4.1.2.1, “String Constants”).
Arguments and results are handled as in any other Perl subroutine:
arguments are passed in @_
, and a result value
is returned with 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:
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$ if ($_[0] > $_[1]) { return $_[0]; } return $_[1]; $$ LANGUAGE plperl;
If an SQL null value is passed to a function,
the argument value will appear as “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 STRICT
to the function definition to make
PostgreSQL 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 perl_max
with
one null and one nonnull argument to return the nonnull argument,
rather than a null value:
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$ my ($x,$y) = @_; if (! defined $x) { if (! defined $y) { return undef; } return $y; } if (! defined $y) { return $x; } if ($x > $y) { return $x; } return $y; $$ LANGUAGE plperl;
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.
Perl can return PostgreSQL arrays as references to Perl arrays. Here is an example:
CREATE OR REPLACE function returns_array() RETURNS text[][] AS $$ return [['a"b','c,d'],['e\\f','g']]; $$ LANGUAGE plperl; select returns_array();
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:
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;
A PL/Perl function can return a composite-type result using the same approach: return a reference to a hash that has the required attributes. For example,
CREATE TYPE testrowperl AS (f1 integer, f2 text, f3 text); CREATE OR REPLACE FUNCTION perl_row() RETURNS testrowperl AS $$ return {f2 => 'hello', f1 => 1, f3 => 'world'}; $$ LANGUAGE plperl; SELECT * FROM perl_row();
Any columns in the declared result data type that are not present in the hash will be returned as null values.
PL/Perl functions can also return sets of either scalar or
composite types. Usually you'll want to return rows one at a
time, both to speed up startup time and to keep from queueing up
the entire result set in memory. You can do this with
return_next
as illustrated below. Note that
after the last return_next
, you must put
either return
or (better) return
undef
.
CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$ foreach (0..$_[0]) { return_next($_); } return undef; $$ LANGUAGE plperl; SELECT * FROM perl_set_int(5); CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testrowperl AS $$ return_next({ f1 => 1, f2 => 'Hello', f3 => 'World' }); return_next({ f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' }); return_next({ f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' }); return undef; $$ LANGUAGE plperl;
For small result sets, you can return a reference to an array that contains either scalars, references to arrays, or references to hashes for simple types, array types, and composite types, respectively. Here are some simple examples of returning the entire result set as an array reference:
CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$ return [0..$_[0]]; $$ LANGUAGE plperl; SELECT * FROM perl_set_int(5); CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testrowperl AS $$ return [ { f1 => 1, f2 => 'Hello', f3 => 'World' }, { f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' }, { f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' } ]; $$ LANGUAGE plperl; SELECT * FROM perl_set();
If you wish to use the strict
pragma with your code,
the easiest way to do so is to SET
plperl.use_strict
to true. This parameter affects
subsequent compilations of PL/Perl functions, but not
functions already compiled in the current session. To set the
parameter before PL/Perl has been loaded, it is
necessary to have added “plperl
” to the custom_variable_classes list in
postgresql.conf
.
Another way to use the strict
pragma is to put
use strict;
in the function body. But this only works in PL/PerlU
functions, since use
is not a trusted operation. In
PL/Perl functions you can instead do
BEGIN { strict->import(); }