Description

PL/Perl Functions and Arguments

To create a function in the PL/Perl language, use the standard syntax:

CREATE FUNCTION funcname (argument-types) RETURNS return-type AS ' # PL/Perl function body ' LANGUAGE 'plperl';

The body of the function is ordinary Perl code. 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 a NULL 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 WITH (isStrict) to the function definition to make PostgreSQL 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:

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';

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.

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;

Returning a composite-type result value is not currently supported.

Because the function body is passed as an SQL string literal to CREATE FUNCTION, 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 (q[], qq[], qw[]).

Here is an example of a function that will not work because file system operations are not allowed for security reasons:

CREATE FUNCTION badfunc() RETURNS integer AS ' open(TEMP, ">/tmp/badfile"); print TEMP "Gotcha!\n"; return 1; ' LANGUAGE 'plperl';

The creation of the function will succeed, but execution of the function will not.

Data Values in PL/Perl

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 return command will accept any string that is in any 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.

Database Access from PL/Perl

Access to the database itself from your Perl function can be done via an experimental module DBD::PgSPI. This module makes available a DBI-compliant database-handle named $pg_dbh that can be used to perform queries with normal DBI syntax.

PL/Perl itself presently provides only one additional Perl command:

Missing Features

PL/Perl functions cannot call each other directly (because they are anonymous subroutines inside Perl) or share global variables.

PL/Perl cannot currently be used to write trigger functions.