2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/plperl.sgml -->
|
2000-03-31 05:27:42 +02:00
|
|
|
|
2002-01-25 20:13:15 +01:00
|
|
|
<chapter id="plperl">
|
|
|
|
<title>PL/Perl - Perl Procedural Language</title>
|
|
|
|
|
|
|
|
<indexterm zone="plperl">
|
|
|
|
<primary>PL/Perl</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<indexterm zone="plperl">
|
|
|
|
<primary>Perl</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2002-09-18 22:09:32 +02:00
|
|
|
PL/Perl is a loadable procedural language that enables you to write
|
2010-01-20 02:08:21 +01:00
|
|
|
<productname>PostgreSQL</productname> functions in the
|
2010-01-09 03:40:50 +01:00
|
|
|
<ulink url="http://www.perl.org">Perl programming language</ulink>.
|
2002-01-25 20:13:15 +01:00
|
|
|
</para>
|
|
|
|
|
2008-03-28 01:21:56 +01:00
|
|
|
<para>
|
|
|
|
The main advantage to using PL/Perl is that this allows use,
|
2006-05-30 13:40:21 +02:00
|
|
|
within stored functions, of the manyfold <quote>string
|
2008-03-28 01:21:56 +01:00
|
|
|
munging</quote> operators and functions available for Perl. Parsing
|
2007-05-03 17:05:56 +02:00
|
|
|
complex strings might be easier using Perl than it is with the
|
2008-03-28 01:21:56 +01:00
|
|
|
string functions and control structures provided in PL/pgSQL.
|
|
|
|
</para>
|
|
|
|
|
2002-01-25 20:13:15 +01:00
|
|
|
<para>
|
2002-09-18 22:09:32 +02:00
|
|
|
To install PL/Perl in a particular database, use
|
2017-03-23 19:16:45 +01:00
|
|
|
<literal>CREATE EXTENSION plperl</>.
|
2000-03-31 00:13:30 +02:00
|
|
|
</para>
|
|
|
|
|
2002-01-25 20:13:15 +01:00
|
|
|
<tip>
|
|
|
|
<para>
|
|
|
|
If a language is installed into <literal>template1</>, all subsequently
|
|
|
|
created databases will have the language installed automatically.
|
|
|
|
</para>
|
|
|
|
</tip>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
Users of source packages must specially enable the build of
|
2004-07-21 22:44:52 +02:00
|
|
|
PL/Perl during the installation process. (Refer to <xref
|
2010-09-30 23:18:51 +02:00
|
|
|
linkend="installation"> for more information.) Users of
|
2004-07-21 22:44:52 +02:00
|
|
|
binary packages might find PL/Perl in a separate subpackage.
|
2002-09-18 22:09:32 +02:00
|
|
|
</para>
|
|
|
|
</note>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<sect1 id="plperl-funcs">
|
|
|
|
<title>PL/Perl Functions and Arguments</title>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
2005-05-20 03:52:25 +02:00
|
|
|
To create a function in the PL/Perl language, use the standard
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-createfunction">
|
2005-08-24 20:56:07 +02:00
|
|
|
syntax:
|
2005-08-12 23:42:53 +02:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<programlisting>
|
2004-09-21 00:48:29 +02:00
|
|
|
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$
|
2002-01-25 20:13:15 +01:00
|
|
|
# PL/Perl function body
|
2004-05-17 01:22:08 +02:00
|
|
|
$$ LANGUAGE plperl;
|
2002-09-18 22:09:32 +02:00
|
|
|
</programlisting>
|
2009-11-29 04:02:27 +01:00
|
|
|
|
2005-10-12 16:28:33 +02:00
|
|
|
The body of the function is ordinary Perl code. In fact, the PL/Perl
|
2009-11-29 04:02:27 +01:00
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
PL/Perl also supports anonymous code blocks called with the
|
2010-04-03 09:23:02 +02:00
|
|
|
<xref linkend="sql-do"> statement:
|
2009-11-29 04:02:27 +01:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
DO $$
|
|
|
|
# PL/Perl code
|
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
An anonymous code block receives no arguments, and whatever value it
|
|
|
|
might return is discarded. Otherwise it behaves just like a function.
|
2002-09-18 22:09:32 +02:00
|
|
|
</para>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2005-10-12 16:28:33 +02:00
|
|
|
<note>
|
2004-09-21 00:48:29 +02:00
|
|
|
<para>
|
2005-10-12 16:28:33 +02:00
|
|
|
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
|
2010-02-25 04:08:07 +01:00
|
|
|
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 <literal>Variable "%s" will not stay shared</literal> and
|
|
|
|
<literal>Variable "%s" is not available</literal> in the
|
|
|
|
<citerefentry><refentrytitle>perldiag</></citerefentry> man page, or
|
|
|
|
search the Internet for <quote>perl nested named subroutine</>.
|
2004-09-21 00:48:29 +02:00
|
|
|
</para>
|
2005-10-12 16:28:33 +02:00
|
|
|
</note>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The syntax of the <command>CREATE FUNCTION</command> command requires
|
|
|
|
the function body to be written as a string constant. It is usually
|
|
|
|
most convenient to use dollar quoting (see <xref
|
|
|
|
linkend="sql-syntax-dollar-quoting">) for the string constant.
|
2007-01-30 23:29:23 +01:00
|
|
|
If you choose to use escape string syntax <literal>E''</>,
|
2010-09-30 23:18:51 +02:00
|
|
|
you must double any single quote marks (<literal>'</>) and backslashes
|
2010-01-20 02:08:21 +01:00
|
|
|
(<literal>\</>) used in the body of the function
|
2007-01-30 23:29:23 +01:00
|
|
|
(see <xref linkend="sql-syntax-strings">).
|
2005-10-12 16:28:33 +02:00
|
|
|
</para>
|
2004-09-21 00:48:29 +02:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
|
|
|
Arguments and results are handled as in any other Perl subroutine:
|
2004-11-20 00:22:54 +01:00
|
|
|
arguments are passed in <varname>@_</varname>, and a result value
|
2002-09-18 22:09:32 +02:00
|
|
|
is returned with <literal>return</> or as the last expression
|
2003-04-07 03:29:26 +02:00
|
|
|
evaluated in the function.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For example, a function returning the greater of two integer values
|
|
|
|
could be defined as:
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<programlisting>
|
2004-05-17 01:22:08 +02:00
|
|
|
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
|
2004-11-20 00:22:54 +01:00
|
|
|
if ($_[0] > $_[1]) { return $_[0]; }
|
2002-01-25 20:13:15 +01:00
|
|
|
return $_[1];
|
2004-05-17 01:22:08 +02:00
|
|
|
$$ LANGUAGE plperl;
|
2002-09-18 22:09:32 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2011-02-06 23:29:26 +01:00
|
|
|
<note>
|
|
|
|
<para>
|
2011-03-05 07:08:38 +01:00
|
|
|
Arguments will be converted from the database's encoding to UTF-8
|
2011-05-19 00:14:45 +02:00
|
|
|
for use inside PL/Perl, and then converted from UTF-8 back to the
|
2011-03-05 07:08:38 +01:00
|
|
|
database encoding upon return.
|
2011-02-06 23:29:26 +01:00
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
2004-11-06 15:32:10 +01:00
|
|
|
If an SQL null value<indexterm><primary>null value</><secondary
|
|
|
|
sortas="PL/Perl">in PL/Perl</></indexterm> is passed to a function,
|
|
|
|
the argument value will appear as <quote>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 <literal>STRICT</> to the function definition to make
|
|
|
|
<productname>PostgreSQL</productname> 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 <function>perl_max</function> with
|
|
|
|
one null and one nonnull argument to return the nonnull argument,
|
|
|
|
rather than a null value:
|
2002-09-18 22:09:32 +02:00
|
|
|
|
|
|
|
<programlisting>
|
2004-05-17 01:22:08 +02:00
|
|
|
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
|
2010-01-20 02:08:21 +01:00
|
|
|
my ($x, $y) = @_;
|
|
|
|
if (not defined $x) {
|
|
|
|
return undef if not defined $y;
|
2005-10-19 00:53:54 +02:00
|
|
|
return $y;
|
2002-01-25 20:13:15 +01:00
|
|
|
}
|
2010-01-20 02:08:21 +01:00
|
|
|
return $x if not defined $y;
|
|
|
|
return $x if $x > $y;
|
2005-10-19 00:53:54 +02:00
|
|
|
return $y;
|
2004-05-17 01:22:08 +02:00
|
|
|
$$ LANGUAGE plperl;
|
2002-09-18 22:09:32 +02:00
|
|
|
</programlisting>
|
2004-11-06 15:32:10 +01:00
|
|
|
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.
|
2002-09-18 22:09:32 +02:00
|
|
|
</para>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2007-05-04 16:55:32 +02:00
|
|
|
<para>
|
|
|
|
Anything in a function argument that is not a reference is
|
2010-01-20 02:08:21 +01:00
|
|
|
a string, which is in the standard <productname>PostgreSQL</productname>
|
2007-05-04 16:55:32 +02:00
|
|
|
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
|
2010-01-20 02:08:21 +01:00
|
|
|
other cases the argument will need to be converted into a form that is
|
|
|
|
more usable in Perl. For example, the <function>decode_bytea</function>
|
|
|
|
function can be used to convert an argument of
|
|
|
|
type <type>bytea</> into unescaped binary.
|
2007-05-04 16:55:32 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-01-20 02:08:21 +01:00
|
|
|
Similarly, values passed back to <productname>PostgreSQL</productname>
|
|
|
|
must be in the external text representation format. For example, the
|
|
|
|
<function>encode_bytea</function> function can be used to
|
2010-07-08 23:35:33 +02:00
|
|
|
escape binary data for a return value of type <type>bytea</>.
|
2007-05-04 16:55:32 +02:00
|
|
|
</para>
|
|
|
|
|
2005-07-13 04:10:42 +02:00
|
|
|
<para>
|
|
|
|
Perl can return <productname>PostgreSQL</productname> arrays as
|
|
|
|
references to Perl arrays. Here is an example:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE OR REPLACE function returns_array()
|
|
|
|
RETURNS text[][] AS $$
|
2007-05-04 16:55:32 +02:00
|
|
|
return [['a"b','c,d'],['e\\f','g']];
|
2005-07-13 04:10:42 +02:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
|
|
|
select returns_array();
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2011-02-18 02:11:50 +01:00
|
|
|
<para>
|
|
|
|
Perl passes <productname>PostgreSQL</productname> arrays as a blessed
|
2013-05-21 03:13:13 +02:00
|
|
|
<type>PostgreSQL::InServer::ARRAY</type> object. This object may be treated as an array
|
2011-03-11 20:33:10 +01:00
|
|
|
reference or a string, allowing for backward compatibility with Perl
|
2011-02-18 02:11:50 +01:00
|
|
|
code written for <productname>PostgreSQL</productname> versions below 9.1 to
|
|
|
|
run. For example:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
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']);
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
2013-05-21 03:13:13 +02:00
|
|
|
Multidimensional arrays are represented as references to
|
2011-02-18 02:11:50 +01:00
|
|
|
lower-dimensional arrays of references in a way common to every Perl
|
|
|
|
programmer.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
</para>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
|
|
|
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:
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<programlisting>
|
2002-01-07 03:29:15 +01:00
|
|
|
CREATE TABLE employee (
|
2000-03-31 00:13:30 +02:00
|
|
|
name text,
|
2000-12-19 19:16:26 +01:00
|
|
|
basesalary integer,
|
|
|
|
bonus integer
|
|
|
|
);
|
2000-03-31 00:13:30 +02:00
|
|
|
|
2004-05-17 01:22:08 +02:00
|
|
|
CREATE FUNCTION empcomp(employee) RETURNS integer AS $$
|
2002-01-25 20:13:15 +01:00
|
|
|
my ($emp) = @_;
|
2004-11-20 00:22:54 +01:00
|
|
|
return $emp->{basesalary} + $emp->{bonus};
|
2004-05-17 01:22:08 +02:00
|
|
|
$$ LANGUAGE plperl;
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2004-12-30 22:45:37 +01:00
|
|
|
SELECT name, empcomp(employee.*) FROM employee;
|
2002-09-18 22:09:32 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
2004-12-30 22:45:37 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
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.
|
2007-02-01 01:28:19 +01:00
|
|
|
For example:
|
2004-12-30 22:45:37 +01:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
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();
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
Any columns in the declared result data type that are not present in the
|
2006-10-23 20:10:32 +02:00
|
|
|
hash will be returned as null values.
|
2004-12-30 22:45:37 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-07-13 04:10:42 +02:00
|
|
|
PL/Perl functions can also return sets of either scalar or
|
2005-08-24 20:56:07 +02:00
|
|
|
composite types. Usually you'll want to return rows one at a
|
2013-05-21 03:13:13 +02:00
|
|
|
time, both to speed up startup time and to keep from queuing up
|
2005-07-13 04:10:42 +02:00
|
|
|
the entire result set in memory. You can do this with
|
|
|
|
<function>return_next</function> as illustrated below. Note that
|
|
|
|
after the last <function>return_next</function>, you must put
|
2005-08-24 20:56:07 +02:00
|
|
|
either <literal>return</literal> or (better) <literal>return
|
|
|
|
undef</literal>.
|
2004-12-30 22:45:37 +01:00
|
|
|
|
|
|
|
<programlisting>
|
2005-07-13 04:10:42 +02:00
|
|
|
CREATE OR REPLACE FUNCTION perl_set_int(int)
|
|
|
|
RETURNS SETOF INTEGER AS $$
|
|
|
|
foreach (0..$_[0]) {
|
|
|
|
return_next($_);
|
|
|
|
}
|
|
|
|
return undef;
|
2004-12-30 22:45:37 +01:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
|
|
|
SELECT * FROM perl_set_int(5);
|
|
|
|
|
2005-07-13 04:10:42 +02:00
|
|
|
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;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
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
|
2005-08-24 20:56:07 +02:00
|
|
|
result set as an array reference:
|
2005-07-13 04:10:42 +02:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$
|
|
|
|
return [0..$_[0]];
|
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
|
|
|
SELECT * FROM perl_set_int(5);
|
2004-12-30 22:45:37 +01:00
|
|
|
|
|
|
|
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' }
|
|
|
|
];
|
2005-07-13 04:10:42 +02:00
|
|
|
$$ LANGUAGE plperl;
|
2004-12-30 22:45:37 +01:00
|
|
|
|
|
|
|
SELECT * FROM perl_set();
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2005-08-24 20:56:07 +02:00
|
|
|
<para>
|
2010-11-23 21:27:50 +01:00
|
|
|
If you wish to use the <literal>strict</> pragma with your code you
|
|
|
|
have a few options. For temporary global use you can <command>SET</>
|
2010-01-27 03:55:04 +01:00
|
|
|
<literal>plperl.use_strict</literal> to true.
|
2010-01-27 00:11:56 +01:00
|
|
|
This will affect subsequent compilations of <application>PL/Perl</>
|
|
|
|
functions, but not functions already compiled in the current session.
|
|
|
|
For permanent global use you can set <literal>plperl.use_strict</literal>
|
|
|
|
to true in the <filename>postgresql.conf</filename> file.
|
2005-08-24 20:56:07 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-01-27 00:11:56 +01:00
|
|
|
For permanent use in specific functions you can simply put:
|
2005-08-24 20:56:07 +02:00
|
|
|
<programlisting>
|
|
|
|
use strict;
|
|
|
|
</programlisting>
|
2010-01-27 00:11:56 +01:00
|
|
|
at the top of the function body.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <literal>feature</> pragma is also available to <function>use</> if your Perl is version 5.10.0 or higher.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="plperl-data">
|
|
|
|
<title>Data Values in PL/Perl</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
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 <command>SELECT</command> statement).
|
|
|
|
Conversely, the <function>return</function> and <function>return_next</function>
|
|
|
|
commands will accept any string that is acceptable input format
|
|
|
|
for the function's declared return type.
|
2005-08-24 20:56:07 +02:00
|
|
|
</para>
|
2002-09-18 22:09:32 +02:00
|
|
|
</sect1>
|
|
|
|
|
2010-01-20 02:08:21 +01:00
|
|
|
<sect1 id="plperl-builtins">
|
|
|
|
<title>Built-in Functions</title>
|
|
|
|
|
|
|
|
<sect2 id="plperl-database">
|
2002-09-18 22:09:32 +02:00
|
|
|
<title>Database Access from PL/Perl</title>
|
|
|
|
|
|
|
|
<para>
|
2004-11-06 15:32:10 +01:00
|
|
|
Access to the database itself from your Perl function can be done
|
2008-04-10 17:16:46 +02:00
|
|
|
via the following functions:
|
2010-01-20 04:37:10 +01:00
|
|
|
</para>
|
2002-09-18 22:09:32 +02:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>spi_exec_query</>(<replaceable>query</replaceable> [, <replaceable>max-rows</replaceable>])</literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_exec_query</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2004-07-21 22:44:52 +02:00
|
|
|
<listitem>
|
2004-11-06 15:32:10 +01:00
|
|
|
<para>
|
2005-08-12 23:42:53 +02:00
|
|
|
<literal>spi_exec_query</literal> executes an SQL command and
|
2005-11-05 00:14:02 +01:00
|
|
|
returns the entire row set as a reference to an array of hash
|
2005-08-12 23:42:53 +02:00
|
|
|
references. <emphasis>You should only use this command when you know
|
|
|
|
that the result set will be relatively small.</emphasis> Here is an
|
|
|
|
example of a query (<command>SELECT</command> command) with the
|
|
|
|
optional maximum number of rows:
|
|
|
|
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
2004-11-06 15:32:10 +01:00
|
|
|
$rv = spi_exec_query('SELECT * FROM my_table', 5);
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
2004-11-20 00:22:54 +01:00
|
|
|
This returns up to 5 rows from the table
|
|
|
|
<literal>my_table</literal>. If <literal>my_table</literal>
|
|
|
|
has a column <literal>my_column</literal>, you can get that
|
|
|
|
value from row <literal>$i</literal> of the result like this:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
2004-11-20 00:22:54 +01:00
|
|
|
$foo = $rv->{rows}[$i]->{my_column};
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
2004-11-20 00:22:54 +01:00
|
|
|
The total number of rows returned from a <command>SELECT</command>
|
|
|
|
query can be accessed like this:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
2004-11-20 00:22:54 +01:00
|
|
|
$nrows = $rv->{processed}
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is an example using a different command type:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
|
|
|
$query = "INSERT INTO my_table VALUES (1, 'test')";
|
|
|
|
$rv = spi_exec_query($query);
|
|
|
|
</programlisting>
|
2004-11-06 15:32:10 +01:00
|
|
|
You can then access the command status (e.g.,
|
|
|
|
<literal>SPI_OK_INSERT</literal>) like this:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
2004-11-20 00:22:54 +01:00
|
|
|
$res = $rv->{status};
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
2004-11-06 15:32:10 +01:00
|
|
|
To get the number of rows affected, do:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
2004-11-20 00:22:54 +01:00
|
|
|
$nrows = $rv->{processed};
|
2004-12-30 22:45:37 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is a complete example:
|
|
|
|
<programlisting>
|
|
|
|
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');
|
|
|
|
|
2005-08-12 23:42:53 +02:00
|
|
|
CREATE OR REPLACE FUNCTION test_munge() RETURNS SETOF test AS $$
|
2004-12-30 22:45:37 +01:00
|
|
|
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}));
|
2005-07-13 04:10:42 +02:00
|
|
|
return_next($row);
|
2004-12-30 22:45:37 +01:00
|
|
|
}
|
2005-07-13 04:10:42 +02:00
|
|
|
return undef;
|
2004-12-30 22:45:37 +01:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
|
|
|
SELECT * FROM test_munge();
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
2005-08-12 23:42:53 +02:00
|
|
|
</para>
|
2010-02-05 19:11:46 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>spi_query(<replaceable>command</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_query</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<literal><function>spi_fetchrow(<replaceable>cursor</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_fetchrow</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<literal><function>spi_cursor_close(<replaceable>cursor</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_cursor_close</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2008-04-10 17:16:46 +02:00
|
|
|
|
2010-02-05 19:11:46 +01:00
|
|
|
<listitem>
|
2005-08-12 23:42:53 +02:00
|
|
|
<para>
|
|
|
|
<literal>spi_query</literal> and <literal>spi_fetchrow</literal>
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
work together as a pair for row sets which might be large, or for cases
|
2005-08-12 23:42:53 +02:00
|
|
|
where you wish to return rows as they arrive.
|
|
|
|
<literal>spi_fetchrow</literal> works <emphasis>only</emphasis> with
|
|
|
|
<literal>spi_query</literal>. The following example illustrates how
|
|
|
|
you use them together:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
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!
|
Wording cleanup for error messages. Also change can't -> cannot.
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 20:10:30 +01:00
|
|
|
or elog(ERROR, "cannot open $file for reading: $!");
|
2005-08-12 23:42:53 +02:00
|
|
|
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);
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
2010-01-20 02:08:21 +01:00
|
|
|
|
2010-02-05 19:11:46 +01:00
|
|
|
<para>
|
|
|
|
Normally, <function>spi_fetchrow</> should be repeated until it
|
|
|
|
returns <literal>undef</literal>, indicating that there are no more
|
|
|
|
rows to read. The cursor returned by <literal>spi_query</literal>
|
|
|
|
is automatically freed when
|
|
|
|
<function>spi_fetchrow</> returns <literal>undef</literal>.
|
|
|
|
If you do not wish to read all the rows, instead call
|
|
|
|
<function>spi_cursor_close</> to free the cursor.
|
|
|
|
Failure to do so will result in memory leaks.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>spi_prepare(<replaceable>command</replaceable>, <replaceable>argument types</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_prepare</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<literal><function>spi_query_prepared(<replaceable>plan</replaceable>, <replaceable>arguments</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_query_prepared</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<literal><function>spi_exec_prepared(<replaceable>plan</replaceable> [, <replaceable>attributes</replaceable>], <replaceable>arguments</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_exec_prepared</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<literal><function>spi_freeplan(<replaceable>plan</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>spi_freeplan</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-02-05 19:11:46 +01:00
|
|
|
|
|
|
|
<listitem>
|
2006-03-05 17:40:51 +01:00
|
|
|
<para>
|
2010-01-20 02:08:21 +01:00
|
|
|
<literal>spi_prepare</literal>, <literal>spi_query_prepared</literal>, <literal>spi_exec_prepared</literal>,
|
2010-02-05 19:11:46 +01:00
|
|
|
and <literal>spi_freeplan</literal> implement the same functionality but for prepared queries.
|
|
|
|
<literal>spi_prepare</literal> accepts a query string with numbered argument placeholders ($1, $2, etc)
|
|
|
|
and a string list of argument types:
|
|
|
|
<programlisting>
|
2010-07-08 23:35:33 +02:00
|
|
|
$plan = spi_prepare('SELECT * FROM test WHERE id > $1 AND name = $2',
|
|
|
|
'INTEGER', 'TEXT');
|
2010-02-05 19:11:46 +01:00
|
|
|
</programlisting>
|
|
|
|
Once a query plan is prepared by a call to <literal>spi_prepare</literal>, the plan can be used instead
|
2006-03-05 17:40:51 +01:00
|
|
|
of the string query, either in <literal>spi_exec_prepared</literal>, where the result is the same as returned
|
|
|
|
by <literal>spi_exec_query</literal>, or in <literal>spi_query_prepared</literal> which returns a cursor
|
|
|
|
exactly as <literal>spi_query</literal> does, which can be later passed to <literal>spi_fetchrow</literal>.
|
2010-02-05 19:11:46 +01:00
|
|
|
The optional second parameter to <literal>spi_exec_prepared</literal> is a hash reference of attributes;
|
2010-11-23 21:27:50 +01:00
|
|
|
the only attribute currently supported is <literal>limit</literal>, which sets the maximum number of rows returned by a query.
|
2006-03-05 17:40:51 +01:00
|
|
|
</para>
|
2010-01-20 02:08:21 +01:00
|
|
|
|
2006-03-05 17:40:51 +01:00
|
|
|
<para>
|
|
|
|
The advantage of prepared queries is that is it possible to use one prepared plan for more
|
2010-01-20 02:08:21 +01:00
|
|
|
than one query execution. After the plan is not needed anymore, it can be freed with
|
2006-03-05 17:40:51 +01:00
|
|
|
<literal>spi_freeplan</literal>:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-02-05 19:11:46 +01:00
|
|
|
CREATE OR REPLACE FUNCTION init() RETURNS VOID AS $$
|
2010-07-08 23:35:33 +02:00
|
|
|
$_SHARED{my_plan} = spi_prepare('SELECT (now() + $1)::date AS now',
|
|
|
|
'INTERVAL');
|
2006-03-05 17:40:51 +01:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
|
|
|
CREATE OR REPLACE FUNCTION add_time( INTERVAL ) RETURNS TEXT AS $$
|
2010-01-20 02:08:21 +01:00
|
|
|
return spi_exec_prepared(
|
2006-08-12 22:05:56 +02:00
|
|
|
$_SHARED{my_plan},
|
2010-02-05 19:11:46 +01:00
|
|
|
$_[0]
|
2006-08-12 22:05:56 +02:00
|
|
|
)->{rows}->[0]->{now};
|
2006-03-05 17:40:51 +01:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
2010-02-05 19:11:46 +01:00
|
|
|
CREATE OR REPLACE FUNCTION done() RETURNS VOID AS $$
|
2006-08-12 22:05:56 +02:00
|
|
|
spi_freeplan( $_SHARED{my_plan});
|
|
|
|
undef $_SHARED{my_plan};
|
2006-03-05 17:40:51 +01:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
|
|
|
SELECT init();
|
|
|
|
SELECT add_time('1 day'), add_time('2 days'), add_time('3 days');
|
|
|
|
SELECT done();
|
|
|
|
|
2010-01-20 02:08:21 +01:00
|
|
|
add_time | add_time | add_time
|
2006-03-05 17:40:51 +01:00
|
|
|
------------+------------+------------
|
|
|
|
2005-12-10 | 2005-12-11 | 2005-12-12
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2006-03-05 17:40:51 +01:00
|
|
|
Note that the parameter subscript in <literal>spi_prepare</literal> is defined via
|
|
|
|
$1, $2, $3, etc, so avoid declaring query strings in double quotes that might easily
|
|
|
|
lead to hard-to-catch bugs.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-02-05 19:11:46 +01:00
|
|
|
Another example illustrates usage of an optional parameter in <literal>spi_exec_prepared</literal>:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-07-08 23:35:33 +02:00
|
|
|
CREATE TABLE hosts AS SELECT id, ('192.168.1.'||id)::inet AS address
|
|
|
|
FROM generate_series(1,3) AS id;
|
2010-02-05 19:11:46 +01:00
|
|
|
|
|
|
|
CREATE OR REPLACE FUNCTION init_hosts_query() RETURNS VOID AS $$
|
2010-07-29 21:34:41 +02:00
|
|
|
$_SHARED{plan} = spi_prepare('SELECT * FROM hosts
|
2010-07-08 23:35:33 +02:00
|
|
|
WHERE address << $1', 'inet');
|
2010-02-05 19:11:46 +01:00
|
|
|
$$ 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)
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2006-03-05 17:40:51 +01:00
|
|
|
</para>
|
2010-02-05 19:11:46 +01:00
|
|
|
</listitem>
|
2004-07-21 22:44:52 +02:00
|
|
|
</varlistentry>
|
2010-01-20 02:08:21 +01:00
|
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="plperl-utility-functions">
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Utility Functions in PL/Perl</title>
|
2004-11-06 15:32:10 +01:00
|
|
|
|
2010-01-20 02:08:21 +01:00
|
|
|
<variablelist>
|
2004-07-21 22:44:52 +02:00
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>elog(<replaceable>level</replaceable>, <replaceable>msg</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>elog</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2002-09-18 22:09:32 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Emit a log or error message. Possible levels are
|
|
|
|
<literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
|
|
|
|
<literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
|
2004-11-21 22:17:07 +01:00
|
|
|
<literal>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 <literal>die</> command.
|
2004-12-30 22:45:37 +01:00
|
|
|
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
|
|
|
|
<xref linkend="guc-log-min-messages"> and
|
|
|
|
<xref linkend="guc-client-min-messages"> configuration
|
|
|
|
variables. See <xref linkend="runtime-config"> for more
|
|
|
|
information.
|
2002-09-18 22:09:32 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-01-20 02:08:21 +01:00
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>quote_literal(<replaceable>string</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>quote_literal</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
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 <function>quote_literal</> returns undef on undef input; if the argument
|
|
|
|
might be undef, <function>quote_nullable</> is often more suitable.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>quote_nullable(<replaceable>string</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>quote_nullable</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>quote_ident(<replaceable>string</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>quote_ident</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>decode_bytea(<replaceable>string</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>decode_bytea</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Return the unescaped binary data represented by the contents of the given string,
|
2010-08-17 06:37:21 +02:00
|
|
|
which should be <type>bytea</type> encoded.
|
2010-01-20 02:08:21 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>encode_bytea(<replaceable>string</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>encode_bytea</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-08-17 06:37:21 +02:00
|
|
|
Return the <type>bytea</type> encoded form of the binary data contents of the given string.
|
2010-01-20 02:08:21 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>encode_array_literal(<replaceable>array</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>encode_array_literal</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<literal><function>encode_array_literal(<replaceable>array</replaceable>, <replaceable>delimiter</replaceable>)</function></literal>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Returns the contents of the referenced array as a string in array literal format
|
|
|
|
(see <xref linkend="arrays-input">).
|
|
|
|
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 "<literal>, </literal>"
|
|
|
|
if a delimiter is not specified or is undef.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2011-02-18 02:11:50 +01:00
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>encode_typed_literal(<replaceable>value</replaceable>, <replaceable>typename</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>encode_typed_literal</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2011-02-18 02:11:50 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2011-05-19 00:14:45 +02:00
|
|
|
Converts a Perl variable to the value of the data type passed as a
|
2011-02-18 02:11:50 +01:00
|
|
|
second argument and returns a string representation of this value.
|
|
|
|
Correctly handles nested arrays and values of composite types.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-01-20 02:08:21 +01:00
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>encode_array_constructor(<replaceable>array</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>encode_array_constructor</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Returns the contents of the referenced array as a string in array constructor format
|
|
|
|
(see <xref linkend="sql-syntax-array-constructors">).
|
|
|
|
Individual values are quoted using <function>quote_nullable</function>.
|
|
|
|
Returns the argument value, quoted using <function>quote_nullable</function>,
|
|
|
|
if it's not a reference to an array.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>looks_like_number(<replaceable>string</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>looks_like_number</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-20 02:08:21 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
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. <literal>Inf</> and <literal>Infinity</> are regarded as numbers.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2011-02-18 02:11:50 +01:00
|
|
|
<varlistentry>
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<literal><function>is_array_ref(<replaceable>argument</replaceable>)</function></literal>
|
|
|
|
<indexterm>
|
|
|
|
<primary>is_array_ref</primary>
|
|
|
|
<secondary>in PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2011-02-18 02:11:50 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Returns a true value if the given argument may be treated as an
|
|
|
|
array reference, that is, if ref of the argument is <literal>ARRAY</> or
|
|
|
|
<literal>PostgreSQL::InServer::ARRAY</>. Returns false otherwise.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
</variablelist>
|
2011-02-18 02:11:50 +01:00
|
|
|
</sect2>
|
2002-09-18 22:09:32 +02:00
|
|
|
</sect1>
|
|
|
|
|
2004-07-21 22:44:52 +02:00
|
|
|
<sect1 id="plperl-global">
|
|
|
|
<title>Global Values in PL/Perl</title>
|
2004-11-06 15:32:10 +01:00
|
|
|
|
2004-07-21 22:44:52 +02:00
|
|
|
<para>
|
2004-12-11 21:03:37 +01:00
|
|
|
You can use the global hash <varname>%_SHARED</varname> to store
|
|
|
|
data, including code references, between function calls for the
|
2004-12-30 22:45:37 +01:00
|
|
|
lifetime of the current session.
|
2004-12-11 21:03:37 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is a simple example for shared data:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
2004-11-06 15:32:10 +01:00
|
|
|
CREATE OR REPLACE FUNCTION set_var(name text, val text) RETURNS text AS $$
|
2004-08-18 05:37:56 +02:00
|
|
|
if ($_SHARED{$_[0]} = $_[1]) {
|
|
|
|
return 'ok';
|
|
|
|
} else {
|
Wording cleanup for error messages. Also change can't -> cannot.
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 20:10:30 +01:00
|
|
|
return "cannot set shared variable $_[0] to $_[1]";
|
2004-08-18 05:37:56 +02:00
|
|
|
}
|
2004-07-21 22:44:52 +02:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
CREATE OR REPLACE FUNCTION get_var(name text) RETURNS text AS $$
|
2004-08-18 05:37:56 +02:00
|
|
|
return $_SHARED{$_[0]};
|
2004-07-21 22:44:52 +02:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
2010-01-20 02:08:21 +01:00
|
|
|
SELECT set_var('sample', 'Hello, PL/Perl! How''s tricks?');
|
2004-08-18 05:37:56 +02:00
|
|
|
SELECT get_var('sample');
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
2004-12-11 21:03:37 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is a slightly more complicated example using a code reference:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
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};
|
2004-12-30 22:45:37 +01:00
|
|
|
return &$qfunc($text_to_quote);
|
2004-12-11 21:03:37 +01:00
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
(You could have replaced the above with the one-liner
|
2004-12-30 22:45:37 +01:00
|
|
|
<literal>return $_SHARED{myquote}->($_[0]);</literal>
|
2004-12-11 21:03:37 +01:00
|
|
|
at the expense of readability.)
|
|
|
|
</para>
|
2010-02-12 20:35:25 +01:00
|
|
|
|
|
|
|
<para>
|
2010-09-30 23:18:51 +02:00
|
|
|
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
|
|
|
|
<varname>%_SHARED</varname> variable and other global state. Thus, two
|
|
|
|
PL/Perl functions will share the same value of <varname>%_SHARED</varname>
|
|
|
|
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
|
|
|
|
<literal>SECURITY DEFINER</> functions, use of <command>SET ROLE</>, etc)
|
|
|
|
you may need to take explicit steps to ensure that PL/Perl functions can
|
|
|
|
share data via <varname>%_SHARED</varname>. To do that, make sure that
|
|
|
|
functions that should communicate are owned by the same user, and mark
|
|
|
|
them <literal>SECURITY DEFINER</>. You must of course take care that
|
|
|
|
such functions can't be used to do anything unintended.
|
2010-02-12 20:35:25 +01:00
|
|
|
</para>
|
2004-07-21 22:44:52 +02:00
|
|
|
</sect1>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<sect1 id="plperl-trusted">
|
|
|
|
<title>Trusted and Untrusted PL/Perl</title>
|
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="plperl-trusted">
|
|
|
|
<primary>trusted</primary>
|
|
|
|
<secondary>PL/Perl</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
|
|
|
Normally, PL/Perl is installed as a <quote>trusted</> programming
|
|
|
|
language named <literal>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,
|
|
|
|
<literal>require</literal>, and <literal>use</literal> (for
|
|
|
|
external modules). There is no way to access internals of the
|
2003-04-07 03:29:26 +02:00
|
|
|
database server process or to gain OS-level access with the
|
|
|
|
permissions of the server process,
|
Update documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
Also update two error messages mentioned in the documenation to match.
2007-01-31 21:56:20 +01:00
|
|
|
as a C function can do. Thus, any unprivileged database user can
|
2002-09-18 22:09:32 +02:00
|
|
|
be permitted to use this language.
|
|
|
|
</para>
|
2000-12-19 19:16:26 +01:00
|
|
|
|
|
|
|
<para>
|
2000-12-22 19:57:50 +01:00
|
|
|
Here is an example of a function that will not work because file
|
2000-12-19 19:16:26 +01:00
|
|
|
system operations are not allowed for security reasons:
|
|
|
|
<programlisting>
|
2004-05-17 01:22:08 +02:00
|
|
|
CREATE FUNCTION badfunc() RETURNS integer AS $$
|
2005-10-24 17:39:50 +02:00
|
|
|
my $tmpfile = "/tmp/badfile";
|
|
|
|
open my $fh, '>', $tmpfile
|
2006-03-01 07:30:32 +01:00
|
|
|
or elog(ERROR, qq{could not open the file "$tmpfile": $!});
|
2005-10-24 17:39:50 +02:00
|
|
|
print $fh "Testing writing to a file\n";
|
2006-03-01 07:30:32 +01:00
|
|
|
close $fh or elog(ERROR, qq{could not close the file "$tmpfile": $!});
|
2000-12-19 19:16:26 +01:00
|
|
|
return 1;
|
2004-05-17 01:22:08 +02:00
|
|
|
$$ LANGUAGE plperl;
|
2000-12-19 19:16:26 +01:00
|
|
|
</programlisting>
|
2006-08-12 22:05:56 +02:00
|
|
|
The creation of this function will fail as its use of a forbidden
|
2007-05-03 17:05:56 +02:00
|
|
|
operation will be caught by the validator.
|
2002-01-07 03:29:15 +01:00
|
|
|
</para>
|
2002-09-18 22:09:32 +02:00
|
|
|
|
2002-01-07 03:29:15 +01:00
|
|
|
<para>
|
2002-09-18 22:09:32 +02:00
|
|
|
Sometimes it is desirable to write Perl functions that are not
|
2003-08-31 19:32:24 +02:00
|
|
|
restricted. For example, one might want a Perl function that sends
|
|
|
|
mail. To handle these cases, PL/Perl can also be installed as an
|
|
|
|
<quote>untrusted</> language (usually called
|
|
|
|
<application>PL/PerlU</application><indexterm><primary>PL/PerlU</></indexterm>).
|
2011-03-05 07:08:38 +01:00
|
|
|
In this case the full Perl language is available. When installing the
|
2003-08-31 19:32:24 +02:00
|
|
|
language, the language name <literal>plperlu</literal> will select
|
|
|
|
the untrusted PL/Perl variant.
|
2001-06-22 23:37:14 +02:00
|
|
|
</para>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
2002-09-21 20:32:54 +02:00
|
|
|
The writer of a <application>PL/PerlU</> function must take care that the function
|
2002-09-18 22:09:32 +02:00
|
|
|
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.
|
|
|
|
</para>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<para>
|
|
|
|
If the above function was created by a superuser using the language
|
|
|
|
<literal>plperlu</>, execution would succeed.
|
|
|
|
</para>
|
2006-11-13 18:13:57 +01:00
|
|
|
|
2009-11-29 04:02:27 +01:00
|
|
|
<para>
|
|
|
|
In the same way, anonymous code blocks written in Perl can use
|
|
|
|
restricted operations if the language is specified as
|
|
|
|
<literal>plperlu</> rather than <literal>plperl</>, but the caller
|
|
|
|
must be a superuser.
|
|
|
|
</para>
|
|
|
|
|
2006-11-13 18:13:57 +01:00
|
|
|
<note>
|
2010-09-30 23:18:51 +02:00
|
|
|
<para>
|
|
|
|
While <application>PL/Perl</> functions run in a separate Perl
|
|
|
|
interpreter for each SQL role, all <application>PL/PerlU</> functions
|
|
|
|
executed in a given session run in a single Perl interpreter (which is
|
|
|
|
not any of the ones used for <application>PL/Perl</> functions).
|
|
|
|
This allows <application>PL/PerlU</> functions to share data freely,
|
|
|
|
but no communication can occur between <application>PL/Perl</> and
|
|
|
|
<application>PL/PerlU</> functions.
|
|
|
|
</para>
|
|
|
|
</note>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
Perl cannot support multiple interpreters within one process unless
|
|
|
|
it was built with the appropriate flags, namely either
|
|
|
|
<literal>usemultiplicity</> or <literal>useithreads</>.
|
|
|
|
(<literal>usemultiplicity</> is preferred unless you actually need
|
|
|
|
to use threads. For more details, see the
|
|
|
|
<citerefentry><refentrytitle>perlembed</></citerefentry> man page.)
|
|
|
|
If <application>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
|
|
|
|
<application>PL/PerlU</> functions, or <application>PL/Perl</> functions
|
|
|
|
that are all called by the same SQL role.
|
|
|
|
</para>
|
2006-11-13 18:13:57 +01:00
|
|
|
</note>
|
2010-01-20 02:08:21 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
</sect1>
|
2004-11-06 15:32:10 +01:00
|
|
|
|
2004-07-21 22:44:52 +02:00
|
|
|
<sect1 id="plperl-triggers">
|
|
|
|
<title>PL/Perl Triggers</title>
|
|
|
|
|
|
|
|
<para>
|
2004-11-20 00:22:54 +01:00
|
|
|
PL/Perl can be used to write trigger functions. In a trigger function,
|
|
|
|
the hash reference <varname>$_TD</varname> contains information about the
|
2010-01-20 02:08:21 +01:00
|
|
|
current trigger event. <varname>$_TD</> is a global variable,
|
|
|
|
which gets a separate local value for each invocation of the trigger.
|
2006-05-29 15:51:23 +02:00
|
|
|
The fields of the <varname>$_TD</varname> hash reference are:
|
2004-07-21 22:44:52 +02:00
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2004-11-20 00:22:54 +01:00
|
|
|
<term><literal>$_TD->{new}{foo}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<literal>NEW</literal> value of column <literal>foo</literal>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2004-07-21 22:44:52 +02:00
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
<varlistentry>
|
2004-11-20 00:22:54 +01:00
|
|
|
<term><literal>$_TD->{old}{foo}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
<literal>OLD</literal> value of column <literal>foo</literal>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2005-01-17 04:04:17 +01:00
|
|
|
<term><literal>$_TD->{name}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Name of the trigger being called
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2005-01-17 04:04:17 +01:00
|
|
|
<term><literal>$_TD->{event}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2008-03-28 01:21:56 +01:00
|
|
|
Trigger event: <literal>INSERT</>, <literal>UPDATE</>,
|
|
|
|
<literal>DELETE</>, <literal>TRUNCATE</>, or <literal>UNKNOWN</>
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2005-01-17 04:04:17 +01:00
|
|
|
<term><literal>$_TD->{when}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-10-10 19:43:33 +02:00
|
|
|
When the trigger was called: <literal>BEFORE</literal>,
|
|
|
|
<literal>AFTER</literal>, <literal>INSTEAD OF</literal>, or
|
|
|
|
<literal>UNKNOWN</literal>
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2005-01-17 04:04:17 +01:00
|
|
|
<term><literal>$_TD->{level}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The trigger level: <literal>ROW</literal>, <literal>STATEMENT</literal>, or <literal>UNKNOWN</literal>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2005-01-17 04:04:17 +01:00
|
|
|
<term><literal>$_TD->{relid}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
OID of the table on which the trigger fired
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2004-07-21 22:44:52 +02:00
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
<varlistentry>
|
2006-05-26 19:34:16 +02:00
|
|
|
<term><literal>$_TD->{table_name}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Name of the table on which the trigger fired
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2006-05-26 19:34:16 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><literal>$_TD->{relname}</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Name of the table on which the trigger fired. This has been deprecated,
|
2010-01-20 02:08:21 +01:00
|
|
|
and could be removed in a future release.
|
2006-08-12 22:05:56 +02:00
|
|
|
Please use $_TD->{table_name} instead.
|
2006-05-26 19:34:16 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>$_TD->{table_schema}</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Name of the schema in which the table on which the trigger fired, is
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
<varlistentry>
|
2005-01-17 18:29:49 +01:00
|
|
|
<term><literal>$_TD->{argc}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2005-01-17 18:29:49 +01:00
|
|
|
Number of arguments of the trigger function
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2005-01-17 18:29:49 +01:00
|
|
|
<term><literal>@{$_TD->{args}}</literal></term>
|
2004-11-06 15:32:10 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2005-11-05 00:14:02 +01:00
|
|
|
Arguments of the trigger function. Does not exist if <literal>$_TD->{argc}</literal> is 0.
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2005-01-17 18:29:49 +01:00
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
</variablelist>
|
2004-07-21 22:44:52 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2008-03-28 01:21:56 +01:00
|
|
|
Row-level triggers can return one of the following:
|
2004-11-06 15:32:10 +01:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>return;</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2008-03-28 01:21:56 +01:00
|
|
|
Execute the operation
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>"SKIP"</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2008-03-28 01:21:56 +01:00
|
|
|
Don't execute the operation
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>"MODIFY"</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-11-20 00:22:54 +01:00
|
|
|
Indicates that the <literal>NEW</literal> row was modified by
|
2004-11-06 15:32:10 +01:00
|
|
|
the trigger function
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2004-07-21 22:44:52 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2004-11-06 15:32:10 +01:00
|
|
|
Here is an example of a trigger function, illustrating some of the
|
|
|
|
above:
|
2004-07-21 22:44:52 +02:00
|
|
|
<programlisting>
|
|
|
|
CREATE TABLE test (
|
2004-11-06 15:32:10 +01:00
|
|
|
i int,
|
|
|
|
v varchar
|
2004-07-21 22:44:52 +02:00
|
|
|
);
|
|
|
|
|
|
|
|
CREATE OR REPLACE FUNCTION valid_id() RETURNS trigger AS $$
|
2004-11-20 00:22:54 +01:00
|
|
|
if (($_TD->{new}{i} >= 100) || ($_TD->{new}{i} <= 0)) {
|
2004-11-06 15:32:10 +01:00
|
|
|
return "SKIP"; # skip INSERT/UPDATE command
|
2004-11-20 00:22:54 +01:00
|
|
|
} elsif ($_TD->{new}{v} ne "immortal") {
|
|
|
|
$_TD->{new}{v} .= "(modified by trigger)";
|
2004-11-06 15:32:10 +01:00
|
|
|
return "MODIFY"; # modify row and execute INSERT/UPDATE command
|
2004-07-21 22:44:52 +02:00
|
|
|
} else {
|
2004-11-06 15:32:10 +01:00
|
|
|
return; # execute INSERT/UPDATE command
|
2004-07-21 22:44:52 +02:00
|
|
|
}
|
|
|
|
$$ LANGUAGE plperl;
|
|
|
|
|
2004-11-06 15:32:10 +01:00
|
|
|
CREATE TRIGGER test_valid_id_trig
|
|
|
|
BEFORE INSERT OR UPDATE ON test
|
|
|
|
FOR EACH ROW EXECUTE PROCEDURE valid_id();
|
2004-07-21 22:44:52 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect1>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2013-12-11 14:11:59 +01:00
|
|
|
<sect1 id="plperl-event-triggers">
|
|
|
|
<title>PL/Perl Event Triggers</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
PL/Perl can be used to write event trigger functions. In an event trigger
|
|
|
|
function, the hash reference <varname>$_TD</varname> contains information
|
|
|
|
about the current trigger event. <varname>$_TD</> is a global variable,
|
|
|
|
which gets a separate local value for each invocation of the trigger. The
|
|
|
|
fields of the <varname>$_TD</varname> hash reference are:
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>$_TD->{event}</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of the event the trigger is fired for.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><literal>$_TD->{tag}</literal></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The command tag for which the trigger is fired.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The return value of the trigger procedure is ignored.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is an example of an event trigger function, illustrating some of the
|
|
|
|
above:
|
|
|
|
<programlisting>
|
|
|
|
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();
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
2010-01-30 02:46:57 +01:00
|
|
|
<sect1 id="plperl-under-the-hood">
|
|
|
|
<title>PL/Perl Under the Hood</title>
|
|
|
|
|
|
|
|
<sect2 id="plperl-config">
|
|
|
|
<title>Configuration</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This section lists configuration parameters that affect <application>PL/Perl</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
2010-02-12 20:35:25 +01:00
|
|
|
<varlistentry id="guc-plperl-on-init" xreflabel="plperl.on_init">
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<varname>plperl.on_init</varname> (<type>string</type>)
|
2010-01-30 02:46:57 +01:00
|
|
|
<indexterm>
|
2010-02-12 20:35:25 +01:00
|
|
|
<primary><varname>plperl.on_init</> configuration parameter</primary>
|
2010-01-30 02:46:57 +01:00
|
|
|
</indexterm>
|
2014-05-07 03:28:58 +02:00
|
|
|
</term>
|
2010-01-30 02:46:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-09-30 23:18:51 +02:00
|
|
|
Specifies Perl code to be executed when a Perl interpreter is first
|
|
|
|
initialized, before it is specialized for use by <literal>plperl</> or
|
|
|
|
<literal>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.
|
2010-01-30 02:46:57 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2010-02-12 20:35:25 +01:00
|
|
|
The Perl code is limited to a single string. Longer code can be placed
|
|
|
|
into a module and loaded by the <literal>on_init</> string.
|
2010-02-01 16:48:35 +01:00
|
|
|
Examples:
|
2010-01-30 02:46:57 +01:00
|
|
|
<programlisting>
|
2010-05-13 18:39:43 +02:00
|
|
|
plperl.on_init = 'require "plperlinit.pl"'
|
2010-02-25 11:02:30 +01:00
|
|
|
plperl.on_init = 'use lib "/my/app"; use MyApp::PgInit;'
|
2010-05-13 18:39:43 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Any modules loaded by <literal>plperl.on_init</>, either directly or
|
|
|
|
indirectly, will be available for use by <literal>plperl</>. This may
|
|
|
|
create a security risk. To see what modules have been loaded you can use:
|
|
|
|
<programlisting>
|
2012-04-24 20:16:07 +02:00
|
|
|
DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl;
|
2010-01-30 02:46:57 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>
|
2017-06-18 20:01:45 +02:00
|
|
|
Initialization will happen in the postmaster if the <literal>plperl</literal> library is
|
2010-09-30 23:18:51 +02:00
|
|
|
included in <xref linkend="guc-shared-preload-libraries">, 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 <literal>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 <literal>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.
|
2010-01-30 02:46:57 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2011-05-19 00:14:45 +02:00
|
|
|
This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line.
|
2010-01-30 02:46:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-02-12 20:35:25 +01:00
|
|
|
<varlistentry id="guc-plperl-on-plperl-init" xreflabel="plperl.on_plperl_init">
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<varname>plperl.on_plperl_init</varname> (<type>string</type>)
|
|
|
|
<indexterm>
|
|
|
|
<primary><varname>plperl.on_plperl_init</> configuration parameter</primary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
|
|
|
<term>
|
|
|
|
<varname>plperl.on_plperlu_init</varname> (<type>string</type>)
|
|
|
|
<indexterm>
|
|
|
|
<primary><varname>plperl.on_plperlu_init</> configuration parameter</primary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-02-12 20:35:25 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-09-30 23:18:51 +02:00
|
|
|
These parameters specify Perl code to be executed when a Perl
|
|
|
|
interpreter is specialized for <literal>plperl</> or
|
|
|
|
<literal>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 <literal>plperl.on_init</>.
|
|
|
|
The SPI functions are not available when this code is executed.
|
|
|
|
The Perl code in <literal>plperl.on_plperl_init</> is executed after
|
|
|
|
<quote>locking down</> the interpreter, and thus it can only perform
|
|
|
|
trusted operations.
|
2010-02-12 20:35:25 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2010-09-30 23:18:51 +02:00
|
|
|
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.
|
2010-02-12 20:35:25 +01:00
|
|
|
</para>
|
|
|
|
<para>
|
2010-09-30 23:18:51 +02:00
|
|
|
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.
|
2010-02-12 20:35:25 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-01-30 02:46:57 +01:00
|
|
|
<varlistentry id="guc-plperl-use-strict" xreflabel="plperl.use_strict">
|
2014-05-07 03:28:58 +02:00
|
|
|
<term>
|
|
|
|
<varname>plperl.use_strict</varname> (<type>boolean</type>)
|
|
|
|
<indexterm>
|
|
|
|
<primary><varname>plperl.use_strict</> configuration parameter</primary>
|
|
|
|
</indexterm>
|
|
|
|
</term>
|
2010-01-30 02:46:57 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-09-30 23:18:51 +02:00
|
|
|
When set true subsequent compilations of PL/Perl functions will have
|
|
|
|
the <literal>strict</> pragma enabled. This parameter does not affect
|
|
|
|
functions already compiled in the current session.
|
2010-01-30 02:46:57 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="plperl-missing">
|
2004-07-21 22:44:52 +02:00
|
|
|
<title>Limitations and Missing Features</title>
|
2002-01-25 20:13:15 +01:00
|
|
|
|
2001-06-22 23:37:14 +02:00
|
|
|
<para>
|
2002-09-18 22:09:32 +02:00
|
|
|
The following features are currently missing from PL/Perl, but they
|
2003-04-07 03:29:26 +02:00
|
|
|
would make welcome contributions.
|
2002-09-18 22:09:32 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-01-27 00:11:56 +01:00
|
|
|
PL/Perl functions cannot call each other directly.
|
2002-09-18 22:09:32 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-11-06 15:32:10 +01:00
|
|
|
SPI is not yet fully implemented.
|
2002-09-18 22:09:32 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
2004-11-06 15:32:10 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
<listitem>
|
2004-11-06 15:32:10 +01:00
|
|
|
<para>
|
2005-08-12 23:42:53 +02:00
|
|
|
If you are fetching very large data sets using
|
|
|
|
<literal>spi_exec_query</literal>, you should be aware that
|
|
|
|
these will all go into memory. You can avoid this by using
|
|
|
|
<literal>spi_query</literal>/<literal>spi_fetchrow</literal> as
|
|
|
|
illustrated earlier.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
A similar problem occurs if a set-returning function passes a
|
2005-11-05 00:14:02 +01:00
|
|
|
large set of rows back to PostgreSQL via <literal>return</literal>. You
|
2005-08-12 23:42:53 +02:00
|
|
|
can avoid this problem too by instead using
|
|
|
|
<literal>return_next</literal> for each row returned, as shown
|
|
|
|
previously.
|
2004-11-06 15:32:10 +01:00
|
|
|
</para>
|
2002-09-18 22:09:32 +02:00
|
|
|
</listitem>
|
2010-01-30 02:46:57 +01:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When a session ends normally, not due to a fatal error, any
|
|
|
|
<literal>END</> blocks that have been defined are executed.
|
2010-11-23 21:27:50 +01:00
|
|
|
Currently no other actions are performed. Specifically,
|
|
|
|
file handles are not automatically flushed and objects are
|
2010-01-30 02:46:57 +01:00
|
|
|
not automatically destroyed.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2002-09-18 22:09:32 +02:00
|
|
|
</itemizedlist>
|
2000-12-19 19:16:26 +01:00
|
|
|
</para>
|
2010-01-30 02:46:57 +01:00
|
|
|
</sect2>
|
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
</sect1>
|
2000-12-19 19:16:26 +01:00
|
|
|
|
2002-09-18 22:09:32 +02:00
|
|
|
</chapter>
|