# PL/Perl - Perl Procedural Language

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

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 install-short for more information.) Users of binary packages might find PL/Perl in a separate subpackage.

## 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. Since the body of the function is treated as a string by PostgreSQL, it can be specified using dollar quoting (as shown above), or via the legacy single quote syntax (see sql-syntax-strings for more information).

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 non-`NULL` argument to return the non-`NULL` 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;

There is now support for returning a composite-type result value.

## Database Access from PL/Perl

Access to the database itself from your Perl function can be done via spi_exec_query, or via an experimental module `DBD::PgSPI` (also available at CPAN mirror sites). 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 two additional Perl commands:

`spi_exec_query(` [ `SELECT query` [, `max_rows`]] | [`non-SELECT query`] )

- Here is an example of a SELECT query with the optional maximum number of rows.

      $rv = spi_exec_query('SELECT * from my_table', 5);

  This returns up to 5 rows from my_table.

  If my_table has a column my_column, it would be accessed as

      $foo = $rv->{rows}[$i]->{my_column};

  The number of rows actually returned would be:

      $nrows = @{$rv->{rows}};

  Here is an example using a non-SELECT statement.

      $query = "INSERT INTO my_table VALUES (1, 'test')";
      $rv = spi_exec_query($query);

  You can then access status (SPI_OK_INSERT, e.g.) like this.

      $res = $rv->{status};

  To get the rows affected, do:

      $nrows = $rv->{rows};

`elog` `level`, `msg`

- Emit a log or error message. Possible levels are `DEBUG`, `LOG`, `INFO`, `NOTICE`, `WARNING`, and `ERROR`. `ERROR` raises an error condition: further execution of the function is abandoned, and the current transaction is aborted.

## Data Values in PL/Perl

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 `SELECT` statement). Conversely, the `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.

PL/Perl can now return rowsets and composite types, and rowsets of composite types.

Here is an example of a PL/Perl function returning a rowset of a row type:

    CREATE TABLE test (
           i int,
           v varchar
    );

    INSERT INTO test (i, v) VALUES (1,'first line');
    INSERT INTO test (i, v) VALUES (2,'second line');
    INSERT INTO test (i, v) VALUES (3,'third line');
    INSERT INTO test (i, v) VALUES (4,'immortal');

    create function test_munge() returns setof test language plperl as $$
        my $res = [];
        my $rv = spi_exec_query('select i,v from test;');
        my $status = $rv->{status};
        my $rows = @{$rv->{rows}};
        my $processed = $rv->{processed};
        foreach my $rn (0..$rows-1) {
            my $row = $rv->{rows}[$rn];
            $row->{i} += 200 if defined($row->{i});
            $row->{v} =~ tr/A-Za-z/a-zA-Z/ if (defined($row->{v}));
            push @$res,$row;
        }
        return $res;
    $$;

    select * from test_munge();

Here is an example of a PL/Perl function returning a composite type:

    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;

Here is an example of a PL/Perl function returning a rowset of a composite type.

    CREATE TYPE testsetperl AS (f1 integer, f2 text, f3 text);

    CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testsetperl AS $$
     return[
            {f1 => 1, f2 => 'hello', f3 =>  'world'},
            {f1 => 2, f2 => 'hello', f3 =>  'postgres'},
            {f1 => 3, f2 => 'hello', f3 =>  'plperl'}
           ];
    $$  LANGUAGE plperl;

## Global Values in PL/Perl

You can use the %_SHARED to store data between function calls.

For example:

    CREATE OR REPLACE FUNCTION set_var(name TEXT, val TEXT) RETURNS TEXT AS $$
        if ($_SHARED{$_[0]} = $_[1]) {
            return 'ok';
        } else {
            return "Can't set shared variable $_[0] to $_[1]";
        }
    $$ LANGUAGE plperl;

    CREATE OR REPLACE FUNCTION get_var(name TEXT) RETURNS text AS $$
        return $_SHARED{$_[0]};
    $$ LANGUAGE plperl;

    SELECT set_var('sample', $q$Hello, PL/Perl!  How's tricks?$q$);
    SELECT get_var('sample');

## Trusted and Untrusted PL/Perl

Normally, PL/Perl is installed as a trusted programming language named `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, `require`, and `use` (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.

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 executing it will not.

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 untrusted language (usually called PL/PerlU
). In this case the full Perl language is available. If the `createlang` program is used to install the language, the language name `plperlu` will select the untrusted PL/Perl variant.

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.

If the above function was created by a superuser using the language `plperlu`, execution would succeed.

## PL/Perl Triggers

PL/Perl can now be used to write trigger functions using the `$_TD` hash reference.

Some useful parts of the $_TD hash reference are:

    $_TD->{new}{foo} # NEW value of column foo
    $_TD->{old}{bar} # OLD value of column bar
    $_TD{name}       # Name of the trigger being called
    $_TD{event}      # INSERT, UPDATE, DELETE or UNKNOWN
    $_TD{when}       # BEFORE, AFTER or UNKNOWN
    $_TD{level}      # ROW, STATEMENT or UNKNOWN
    $_TD{relid}      # Relation ID of the table on which the trigger occurred.
    $_TD{relname}    # Name of the table on which the trigger occurred.
    @{$_TD{argv}}    # Array of arguments to the trigger function.  May be empty.
    $_TD{argc}       # Number of arguments to the trigger.  Why is this here?

Triggers can return one of the following:

    return;   -- Executes the statement
    SKIP;     -- Doesn't execute the statement
    MODIFY; -- Says it modified a NEW row

Here is an example of a trigger function, illustrating some of the above.

    CREATE TABLE test (
            i int,
            v varchar
    );

    CREATE OR REPLACE FUNCTION valid_id() RETURNS trigger AS $$
        if (($_TD->{new}{i}>=100) || ($_TD->{new}{i}<=0)) {
            return "SKIP";   # Skip INSERT/UPDATE command
        } elsif ($_TD->{new}{v} ne "immortal") {
            $_TD->{new}{v} .= "(modified by trigger)";
            return "MODIFY"; # Modify tuple and proceed INSERT/UPDATE command
        } else {
            return;      # Proceed INSERT/UPDATE command
        }
    $$ LANGUAGE plperl;

    CREATE TRIGGER "test_valid_id_trig" BEFORE INSERT OR UPDATE ON test
    FOR EACH ROW EXECUTE PROCEDURE "valid_id"();

## Limitations and Missing Features

The following features are currently missing from PL/Perl, but they would make welcome contributions.

- PL/Perl functions cannot call each other directly (because they are anonymous subroutines inside Perl).

- Full SPI is not yet implemented.

- In the current implementation, if you are fetching or returning very large datasets, you should be aware that these will all go into memory. Future features will help with this. In the meantime, we suggest that you not use pl/perl if you will fetch or return very large result sets.