Chapter 37. PL/Perl - Perl Procedural Language

Table of Contents

37.1. PL/Perl Functions and Arguments
37.2. Database Access from PL/Perl
37.3. Data Values in PL/Perl
37.4. Global Values in PL/Perl
37.5. Trusted and Untrusted PL/Perl
37.6. PL/Perl Triggers
37.7. Limitations and Missing Features

PL/Perl is a loadable procedural language that enables you to write PostgreSQL functions in the Perl programming language.

To install PL/Perl in a particular database, use createlang plperl dbname.

Tip

If a language is installed into template1, all subsequently created databases will have the language installed automatically.

Note

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.

37.1. 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.

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 regular single-quoted string constant syntax, you must escape single quote marks (') and backslashes (\) used in the body of the function, typically by doubling them (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 ($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 an SQL null value 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;