PL/Perl - Perl Procedural Language
PL/Perl
Perl
PL/Perl is a loadable procedural language that enables you to write
PostgreSQL functions in the
Perl programming language.
The main 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 might 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
CREATE EXTENSION plperl, or from the shell command line 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 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. In fact, the PL/Perl
glue code wraps it inside a Perl subroutine. A PL/Perl function is
called in a scalar context, so it can't return a list. You can return
non-scalar values (arrays, records, and sets) by returning a reference,
as discussed below.
PL/Perl also supports anonymous code blocks called with the
statement:
DO $$
# PL/Perl code
$$ LANGUAGE plperl;
An anonymous code block receives no arguments, and whatever value it
might return is discarded. Otherwise it behaves just like a function.
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 place inside
one will be nested. In general, it is far safer to create anonymous
subroutines which you call via a coderef. For more information, see the
entries for Variable "%s" will not stay shared and
Variable "%s" is not available in the
perldiag man page, or
search the Internet for perl nested named subroutine.
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 ) for the string constant.
If you choose to use escape string syntax E'',
you must double any single quote marks (') and backslashes
(\) used in the body of the function
(see ).
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;
Arguments will be converted from the database's encoding to UTF-8
for use inside PL/Perl, and then converted from UTF-8 back to the
database encoding upon return.
If an SQL null valuenull valuein PL/Perl 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 (not defined $x) {
return undef if not defined $y;
return $y;
}
return $x if not defined $y;
return $x if $x > $y;
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.
Anything in a function argument that is not a reference is
a string, which is in the standard PostgreSQL
external text representation for the relevant data type. In the case of
ordinary numeric or text types, Perl will just do the right thing and
the programmer will normally not have to worry about it. However, in
other cases the argument will need to be converted into a form that is
more usable in Perl. For example, the decode_bytea
function can be used to convert an argument of
type bytea into unescaped binary.
Similarly, values passed back to PostgreSQL
must be in the external text representation format. For example, the
encode_bytea function can be used to
escape binary data for a return value of type bytea.
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();
Perl passes PostgreSQL arrays as a blessed
PostgreSQL::InServer::ARRAY object. This object may be treated as an array
reference or a string, allowing for backward compatibility with Perl
code written for PostgreSQL versions below 9.1 to
run. For example:
CREATE OR REPLACE FUNCTION concat_array_elements(text[]) RETURNS TEXT AS $$
my $arg = shift;
my $result = "";
return undef if (!defined $arg);
# as an array reference
for (@$arg) {
$result .= $_;
}
# also works as a string
$result .= $arg;
return $result;
$$ LANGUAGE plperl;
SELECT concat_array_elements(ARRAY['PL','/','Perl']);
Multidimensional arrays are represented as references to
lower-dimensional arrays of references in a way common to every Perl
programmer.
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 queuing 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 you
have a few options. For temporary global use you can SET
plperl.use_strict to true.
This will affect subsequent compilations of PL/Perl
functions, but not functions already compiled in the current session.
For permanent global use you can set plperl.use_strict
to true in the postgresql.conf file.
For permanent use in specific functions you can simply put:
use strict;
at the top of the function body.
The feature pragma is also available to use if your Perl is version 5.10.0 or higher.
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 and return_next
commands will accept any string that is acceptable input format
for the function's declared return type.
Built-in Functions
Database Access from PL/Perl
Access to the database itself from your Perl function can be done
via the following functions:
spi_exec_query(query [, max-rows])
spi_exec_query
in PL/Perl
spi_exec_query executes an SQL command and
returns the entire row set as a reference to an array of hash
references. You should only use this command when you know
that the result set will be relatively small. Here is an
example of a query (SELECT command) with the
optional maximum number of rows:
$rv = spi_exec_query('SELECT * FROM my_table', 5);
This returns up to 5 rows from the table
my_table. If my_table
has a column my_column, you can get that
value from row $i of the result like this:
$foo = $rv->{rows}[$i]->{my_column};
The total number of rows returned from a SELECT
query can be accessed like this:
$nrows = $rv->{processed}
Here is an example using a different command type:
$query = "INSERT INTO my_table VALUES (1, 'test')";
$rv = spi_exec_query($query);
You can then access the command status (e.g.,
SPI_OK_INSERT) like this:
$res = $rv->{status};
To get the number of rows affected, do:
$nrows = $rv->{processed};
Here is a complete example:
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 OR REPLACE FUNCTION test_munge() RETURNS SETOF test AS $$
my $rv = spi_exec_query('select i, v from test;');
my $status = $rv->{status};
my $nrows = $rv->{processed};
foreach my $rn (0 .. $nrows - 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}));
return_next($row);
}
return undef;
$$ LANGUAGE plperl;
SELECT * FROM test_munge();
spi_query(command)
spi_query
in PL/Perl
spi_fetchrow(cursor)
spi_fetchrow
in PL/Perl
spi_cursor_close(cursor)
spi_cursor_close
in PL/Perl
spi_query and spi_fetchrow
work together as a pair for row sets which might be large, or for cases
where you wish to return rows as they arrive.
spi_fetchrow works only with
spi_query. The following example illustrates how
you use them together:
CREATE TYPE foo_type AS (the_num INTEGER, the_text TEXT);
CREATE OR REPLACE FUNCTION lotsa_md5 (INTEGER) RETURNS SETOF foo_type AS $$
use Digest::MD5 qw(md5_hex);
my $file = '/usr/share/dict/words';
my $t = localtime;
elog(NOTICE, "opening file $file at $t" );
open my $fh, '<', $file # ooh, it's a file access!
or elog(ERROR, "cannot open $file for reading: $!");
my @words = <$fh>;
close $fh;
$t = localtime;
elog(NOTICE, "closed file $file at $t");
chomp(@words);
my $row;
my $sth = spi_query("SELECT * FROM generate_series(1,$_[0]) AS b(a)");
while (defined ($row = spi_fetchrow($sth))) {
return_next({
the_num => $row->{a},
the_text => md5_hex($words[rand @words])
});
}
return;
$$ LANGUAGE plperlu;
SELECT * from lotsa_md5(500);
Normally, spi_fetchrow should be repeated until it
returns undef, indicating that there are no more
rows to read. The cursor returned by spi_query
is automatically freed when
spi_fetchrow returns undef.
If you do not wish to read all the rows, instead call
spi_cursor_close to free the cursor.
Failure to do so will result in memory leaks.
spi_prepare(command, argument types)
spi_prepare
in PL/Perl
spi_query_prepared(plan, arguments)
spi_query_prepared
in PL/Perl
spi_exec_prepared(plan [, attributes], arguments)
spi_exec_prepared
in PL/Perl
spi_freeplan(plan)
spi_freeplan
in PL/Perl
spi_prepare, spi_query_prepared, spi_exec_prepared,
and spi_freeplan implement the same functionality but for prepared queries.
spi_prepare accepts a query string with numbered argument placeholders ($1, $2, etc)
and a string list of argument types:
$plan = spi_prepare('SELECT * FROM test WHERE id > $1 AND name = $2',
'INTEGER', 'TEXT');
Once a query plan is prepared by a call to spi_prepare, the plan can be used instead
of the string query, either in spi_exec_prepared, where the result is the same as returned
by spi_exec_query, or in spi_query_prepared which returns a cursor
exactly as spi_query does, which can be later passed to spi_fetchrow.
The optional second parameter to spi_exec_prepared is a hash reference of attributes;
the only attribute currently supported is limit, which sets the maximum number of rows returned by a query.
The advantage of prepared queries is that is it possible to use one prepared plan for more
than one query execution. After the plan is not needed anymore, it can be freed with
spi_freeplan:
CREATE OR REPLACE FUNCTION init() RETURNS VOID AS $$
$_SHARED{my_plan} = spi_prepare('SELECT (now() + $1)::date AS now',
'INTERVAL');
$$ LANGUAGE plperl;
CREATE OR REPLACE FUNCTION add_time( INTERVAL ) RETURNS TEXT AS $$
return spi_exec_prepared(
$_SHARED{my_plan},
$_[0]
)->{rows}->[0]->{now};
$$ LANGUAGE plperl;
CREATE OR REPLACE FUNCTION done() RETURNS VOID AS $$
spi_freeplan( $_SHARED{my_plan});
undef $_SHARED{my_plan};
$$ LANGUAGE plperl;
SELECT init();
SELECT add_time('1 day'), add_time('2 days'), add_time('3 days');
SELECT done();
add_time | add_time | add_time
------------+------------+------------
2005-12-10 | 2005-12-11 | 2005-12-12
Note that the parameter subscript in spi_prepare is defined via
$1, $2, $3, etc, so avoid declaring query strings in double quotes that might easily
lead to hard-to-catch bugs.
Another example illustrates usage of an optional parameter in spi_exec_prepared:
CREATE TABLE hosts AS SELECT id, ('192.168.1.'||id)::inet AS address
FROM generate_series(1,3) AS id;
CREATE OR REPLACE FUNCTION init_hosts_query() RETURNS VOID AS $$
$_SHARED{plan} = spi_prepare('SELECT * FROM hosts
WHERE address << $1', 'inet');
$$ LANGUAGE plperl;
CREATE OR REPLACE FUNCTION query_hosts(inet) RETURNS SETOF hosts AS $$
return spi_exec_prepared(
$_SHARED{plan},
{limit => 2},
$_[0]
)->{rows};
$$ LANGUAGE plperl;
CREATE OR REPLACE FUNCTION release_hosts_query() RETURNS VOID AS $$
spi_freeplan($_SHARED{plan});
undef $_SHARED{plan};
$$ LANGUAGE plperl;
SELECT init_hosts_query();
SELECT query_hosts('192.168.1.0/30');
SELECT release_hosts_query();
query_hosts
-----------------
(1,192.168.1.1)
(2,192.168.1.2)
(2 rows)
Utility Functions in PL/Perl
elog(level, msg)
elog
in PL/Perl
Emit a log or error message. Possible levels are
DEBUG, LOG, INFO,
NOTICE, WARNING, and ERROR.
ERROR
raises an error condition; if this is not trapped by the surrounding
Perl code, the error propagates out to the calling query, causing
the current transaction or subtransaction to be aborted. This
is effectively the same as the Perl die command.
The other levels only generate messages of different
priority levels.
Whether messages of a particular priority are reported to the client,
written to the server log, or both is controlled by the
and
configuration
variables. See for more
information.
quote_literal(string)
quote_literal
in PL/Perl
Return the given string suitably quoted to be used as a string literal in an SQL
statement string. Embedded single-quotes and backslashes are properly doubled.
Note that quote_literal returns undef on undef input; if the argument
might be undef, quote_nullable is often more suitable.
quote_nullable(string)
quote_nullable
in PL/Perl
Return the given string suitably quoted to be used as a string literal in an SQL
statement string; or, if the argument is undef, return the unquoted string "NULL".
Embedded single-quotes and backslashes are properly doubled.
quote_ident(string)
quote_ident
in PL/Perl
Return the given string suitably quoted to be used as an identifier in
an SQL statement string. Quotes are added only if necessary (i.e., if
the string contains non-identifier characters or would be case-folded).
Embedded quotes are properly doubled.
decode_bytea(string)
decode_bytea
in PL/Perl
Return the unescaped binary data represented by the contents of the given string,
which should be bytea encoded.
encode_bytea(string)
encode_bytea
in PL/Perl
Return the bytea encoded form of the binary data contents of the given string.
encode_array_literal(array)
encode_array_literal
in PL/Perl
encode_array_literal(array, delimiter)
Returns the contents of the referenced array as a string in array literal format
(see ).
Returns the argument value unaltered if it's not a reference to an array.
The delimiter used between elements of the array literal defaults to ", "
if a delimiter is not specified or is undef.
encode_typed_literal(value, typename)
encode_typed_literal
in PL/Perl
Converts a Perl variable to the value of the data type passed as a
second argument and returns a string representation of this value.
Correctly handles nested arrays and values of composite types.
encode_array_constructor(array)
encode_array_constructor
in PL/Perl
Returns the contents of the referenced array as a string in array constructor format
(see ).
Individual values are quoted using quote_nullable.
Returns the argument value, quoted using quote_nullable,
if it's not a reference to an array.
looks_like_number(string)
looks_like_number
in PL/Perl
Returns a true value if the content of the given string looks like a
number, according to Perl, returns false otherwise.
Returns undef if the argument is undef. Leading and trailing space is
ignored. Inf and Infinity are regarded as numbers.
is_array_ref(argument)
is_array_ref
in PL/Perl
Returns a true value if the given argument may be treated as an
array reference, that is, if ref of the argument is ARRAY or
PostgreSQL::InServer::ARRAY. Returns false otherwise.
Global Values in PL/Perl
You can use the global hash %_SHARED to store
data, including code references, between function calls for the
lifetime of the current session.
Here is a simple example for shared data:
CREATE OR REPLACE FUNCTION set_var(name text, val text) RETURNS text AS $$
if ($_SHARED{$_[0]} = $_[1]) {
return 'ok';
} else {
return "cannot 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', 'Hello, PL/Perl! How''s tricks?');
SELECT get_var('sample');
Here is a slightly more complicated example using a code reference:
CREATE OR REPLACE FUNCTION myfuncs() RETURNS void AS $$
$_SHARED{myquote} = sub {
my $arg = shift;
$arg =~ s/(['\\])/\\$1/g;
return "'$arg'";
};
$$ LANGUAGE plperl;
SELECT myfuncs(); /* initializes the function */
/* Set up a function that uses the quote function */
CREATE OR REPLACE FUNCTION use_quote(TEXT) RETURNS text AS $$
my $text_to_quote = shift;
my $qfunc = $_SHARED{myquote};
return &$qfunc($text_to_quote);
$$ LANGUAGE plperl;
(You could have replaced the above with the one-liner
return $_SHARED{myquote}->($_[0]);
at the expense of readability.)
For security reasons, PL/Perl executes functions called by any one SQL role
in a separate Perl interpreter for that role. This prevents accidental or
malicious interference by one user with the behavior of another user's
PL/Perl functions. Each such interpreter has its own value of the
%_SHARED variable and other global state. Thus, two
PL/Perl functions will share the same value of %_SHARED
if and only if they are executed by the same SQL role. In an application
wherein a single session executes code under multiple SQL roles (via
SECURITY DEFINER functions, use of SET ROLE, etc)
you may need to take explicit steps to ensure that PL/Perl functions can
share data via %_SHARED. To do that, make sure that
functions that should communicate are owned by the same user, and mark
them SECURITY DEFINER. You must of course take care that
such functions can't be used to do anything unintended.
Trusted and Untrusted PL/Perl
trusted
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 can
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 $$
my $tmpfile = "/tmp/badfile";
open my $fh, '>', $tmpfile
or elog(ERROR, qq{could not open the file "$tmpfile": $!});
print $fh "Testing writing to a file\n";
close $fh or elog(ERROR, qq{could not close the file "$tmpfile": $!});
return 1;
$$ LANGUAGE plperl;
The creation of this function will fail as its use of a forbidden
operation will be caught by the validator.
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/PerlUPL/PerlU).
In this case the full Perl language is available. When installing 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.
In the same way, anonymous code blocks written in Perl can use
restricted operations if the language is specified as
plperlu rather than plperl, but the caller
must be a superuser.
While PL/Perl functions run in a separate Perl
interpreter for each SQL role, all PL/PerlU functions
executed in a given session run in a single Perl interpreter (which is
not any of the ones used for PL/Perl functions).
This allows PL/PerlU functions to share data freely,
but no communication can occur between PL/Perl and
PL/PerlU functions.
Perl cannot support multiple interpreters within one process unless
it was built with the appropriate flags, namely either
usemultiplicity or useithreads.
(usemultiplicity is preferred unless you actually need
to use threads. For more details, see the
perlembed man page.)
If PL/Perl is used with a copy of Perl that was not built
this way, then it is only possible to have one Perl interpreter per
session, and so any one session can only execute either
PL/PerlU functions, or PL/Perl functions
that are all called by the same SQL role.
PL/Perl Triggers
PL/Perl can be used to write trigger functions. In a trigger function,
the hash reference $_TD contains information about the
current trigger event. $_TD is a global variable,
which gets a separate local value for each invocation of the trigger.
The fields of the $_TD hash reference are:
$_TD->{new}{foo}
NEW value of column foo
$_TD->{old}{foo}
OLD value of column foo
$_TD->{name}
Name of the trigger being called
$_TD->{event}
Trigger event: INSERT, UPDATE,
DELETE, TRUNCATE, or UNKNOWN
$_TD->{when}
When the trigger was called: BEFORE,
AFTER, INSTEAD OF, or
UNKNOWN
$_TD->{level}
The trigger level: ROW, STATEMENT, or UNKNOWN
$_TD->{relid}
OID of the table on which the trigger fired
$_TD->{table_name}
Name of the table on which the trigger fired
$_TD->{relname}
Name of the table on which the trigger fired. This has been deprecated,
and could be removed in a future release.
Please use $_TD->{table_name} instead.
$_TD->{table_schema}
Name of the schema in which the table on which the trigger fired, is
$_TD->{argc}
Number of arguments of the trigger function
@{$_TD->{args}}
Arguments of the trigger function. Does not exist if $_TD->{argc} is 0.
Row-level triggers can return one of the following:
return;
Execute the operation
"SKIP"
Don't execute the operation
"MODIFY"
Indicates that the NEW row was modified by
the trigger function
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 row and execute INSERT/UPDATE command
} else {
return; # execute INSERT/UPDATE command
}
$$ LANGUAGE plperl;
CREATE TRIGGER test_valid_id_trig
BEFORE INSERT OR UPDATE ON test
FOR EACH ROW EXECUTE PROCEDURE valid_id();
PL/Perl Event Triggers
PL/Perl can be used to write event trigger functions. In an event trigger
function, the hash reference $_TD contains information
about the current trigger event. $_TD is a global variable,
which gets a separate local value for each invocation of the trigger. The
fields of the $_TD hash reference are:
$_TD->{event}
The name of the event the trigger is fired for.
$_TD->{tag}
The command tag for which the trigger is fired.
The return value of the trigger procedure is ignored.
Here is an example of an event trigger function, illustrating some of the
above:
CREATE OR REPLACE FUNCTION perlsnitch() RETURNS event_trigger AS $$
elog(NOTICE, "perlsnitch: " . $_TD->{event} . " " . $_TD->{tag} . " ");
$$ LANGUAGE plperl;
CREATE EVENT TRIGGER perl_a_snitch
ON ddl_command_start
EXECUTE PROCEDURE perlsnitch();
PL/Perl Under the Hood
Configuration
This section lists configuration parameters that affect PL/Perl.
plperl.on_init (string)
plperl.on_init configuration parameter
Specifies Perl code to be executed when a Perl interpreter is first
initialized, before it is specialized for use by plperl or
plperlu.
The SPI functions are not available when this code is executed.
If the code fails with an error it will abort the initialization of
the interpreter and propagate out to the calling query, causing the
current transaction or subtransaction to be aborted.
The Perl code is limited to a single string. Longer code can be placed
into a module and loaded by the on_init string.
Examples:
plperl.on_init = 'require "plperlinit.pl"'
plperl.on_init = 'use lib "/my/app"; use MyApp::PgInit;'
Any modules loaded by plperl.on_init, either directly or
indirectly, will be available for use by plperl. This may
create a security risk. To see what modules have been loaded you can use:
DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl;
Initialization will happen in the postmaster if the plperl library is
included in , in which
case extra consideration should be given to the risk of destabilizing
the postmaster. The principal reason for making use of this feature
is that Perl modules loaded by plperl.on_init need be
loaded only at postmaster start, and will be instantly available
without loading overhead in individual database sessions. However,
keep in mind that the overhead is avoided only for the first Perl
interpreter used by a database session — either PL/PerlU, or
PL/Perl for the first SQL role that calls a PL/Perl function. Any
additional Perl interpreters created in a database session will have
to execute plperl.on_init afresh. Also, on Windows there
will be no savings whatsoever from preloading, since the Perl
interpreter created in the postmaster process does not propagate to
child processes.
This parameter can only be set in the postgresql.conf file or on the server command line.
plperl.on_plperl_init (string)
plperl.on_plperl_init configuration parameter
plperl.on_plperlu_init (string)
plperl.on_plperlu_init configuration parameter
These parameters specify Perl code to be executed when a Perl
interpreter is specialized for plperl or
plperlu respectively. This will happen when a PL/Perl or
PL/PerlU function is first executed in a database session, or when
an additional interpreter has to be created because the other language
is called or a PL/Perl function is called by a new SQL role. This
follows any initialization done by plperl.on_init.
The SPI functions are not available when this code is executed.
The Perl code in plperl.on_plperl_init is executed after
locking down the interpreter, and thus it can only perform
trusted operations.
If the code fails with an error it will abort the initialization and
propagate out to the calling query, causing the current transaction or
subtransaction to be aborted. Any actions already done within Perl
won't be undone; however, that interpreter won't be used again.
If the language is used again the initialization will be attempted
again within a fresh Perl interpreter.
Only superusers can change these settings. Although these settings
can be changed within a session, such changes will not affect Perl
interpreters that have already been used to execute functions.
plperl.use_strict (boolean)
plperl.use_strict configuration parameter
When set true subsequent compilations of PL/Perl functions will have
the strict pragma enabled. This parameter does not affect
functions already compiled in the current session.
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.
SPI is not yet fully implemented.
If you are fetching very large data sets using
spi_exec_query, you should be aware that
these will all go into memory. You can avoid this by using
spi_query/spi_fetchrow as
illustrated earlier.
A similar problem occurs if a set-returning function passes a
large set of rows back to PostgreSQL via return. You
can avoid this problem too by instead using
return_next for each row returned, as shown
previously.
When a session ends normally, not due to a fatal error, any
END blocks that have been defined are executed.
Currently no other actions are performed. Specifically,
file handles are not automatically flushed and objects are
not automatically destroyed.