|
Server : Apache/2.2.2 (Fedora) System : Linux App1.pathumtani.go.th 2.6.20-1.2320.fc5smp #1 SMP Tue Jun 12 19:40:16 EDT 2007 i686 User : apache ( 48) PHP Version : 5.2.9 Disable Function : NONE Directory : /proc/self/root/usr/share/doc/postgresql-8.1.9/html/ |
Upload File : |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>PL/Perl - Perl Procedural Language</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 8.1.9 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Server Programming"
HREF="server-programming.html"><LINK
REL="PREVIOUS"
TITLE="Tcl Procedure Names"
HREF="pltcl-procnames.html"><LINK
REL="NEXT"
TITLE="Database Access from PL/Perl"
HREF="plperl-database.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2007-04-20T04:40:08"></HEAD
><BODY
CLASS="CHAPTER"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL 8.1.9 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="pltcl-procnames.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="pltcl.html"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="plpython.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="plperl-database.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="PLPERL"
></A
>Chapter 38. PL/Perl - Perl Procedural Language</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>38.1. <A
HREF="plperl.html#PLPERL-FUNCS"
>PL/Perl Functions and Arguments</A
></DT
><DT
>38.2. <A
HREF="plperl-database.html"
>Database Access from PL/Perl</A
></DT
><DT
>38.3. <A
HREF="plperl-data.html"
>Data Values in PL/Perl</A
></DT
><DT
>38.4. <A
HREF="plperl-global.html"
>Global Values in PL/Perl</A
></DT
><DT
>38.5. <A
HREF="plperl-trusted.html"
>Trusted and Untrusted PL/Perl</A
></DT
><DT
>38.6. <A
HREF="plperl-triggers.html"
>PL/Perl Triggers</A
></DT
><DT
>38.7. <A
HREF="plperl-missing.html"
>Limitations and Missing Features</A
></DT
></DL
></DIV
><A
NAME="AEN36440"
></A
><A
NAME="AEN36442"
></A
><P
> PL/Perl is a loadable procedural language that enables you to write
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> functions in the
<A
HREF="http://www.perl.com"
TARGET="_top"
>Perl programming language</A
>.
</P
><P
> The usual advantage to using PL/Perl is that this allows use,
within stored functions, of the manyfold <SPAN
CLASS="QUOTE"
>"string
munging"</SPAN
> operators and functions available for Perl. Parsing
complex strings may be be easier using Perl than it is with the
string functions and control structures provided in PL/pgsql.</P
><P
> To install PL/Perl in a particular database, use
<TT
CLASS="LITERAL"
>createlang plperl <TT
CLASS="REPLACEABLE"
><I
>dbname</I
></TT
></TT
>.
</P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
> If a language is installed into <TT
CLASS="LITERAL"
>template1</TT
>, all subsequently
created databases will have the language installed automatically.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> Users of source packages must specially enable the build of
PL/Perl during the installation process. (Refer to <A
HREF="installation.html#INSTALL-SHORT"
>Section 14.1</A
> for more information.) Users of
binary packages might find PL/Perl in a separate subpackage.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="PLPERL-FUNCS"
>38.1. PL/Perl Functions and Arguments</A
></H1
><P
> To create a function in the PL/Perl language, use the standard
<A
HREF="sql-createfunction.html"
><I
>CREATE FUNCTION</I
></A
>
syntax:
</P><PRE
CLASS="PROGRAMLISTING"
>CREATE FUNCTION <TT
CLASS="REPLACEABLE"
><I
>funcname</I
></TT
> (<TT
CLASS="REPLACEABLE"
><I
>argument-types</I
></TT
>) RETURNS <TT
CLASS="REPLACEABLE"
><I
>return-type</I
></TT
> AS $$
# PL/Perl function body
$$ LANGUAGE plperl;</PRE
><P>
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 must
always return a scalar value. You can return more complex structures
(arrays, records, and sets) by returning a reference, as discussed below.
Never return a list.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> 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 create will
be nested. In general, it is far safer to create anonymous subroutines
which you call via a coderef. See the <TT
CLASS="LITERAL"
>perldiag</TT
>
man page for more details.
</P
></BLOCKQUOTE
></DIV
><P
> The syntax of the <TT
CLASS="COMMAND"
>CREATE FUNCTION</TT
> command requires
the function body to be written as a string constant. It is usually
most convenient to use dollar quoting (see <A
HREF="sql-syntax.html#SQL-SYNTAX-DOLLAR-QUOTING"
>Section 4.1.2.2</A
>) for the string constant.
If you choose to use regular single-quoted string constant syntax,
you must escape single quote marks (<TT
CLASS="LITERAL"
>'</TT
>) and backslashes
(<TT
CLASS="LITERAL"
>\</TT
>) used in the body of the function, typically by
doubling them (see <A
HREF="sql-syntax.html#SQL-SYNTAX-STRINGS"
>Section 4.1.2.1</A
>).
</P
><P
> Arguments and results are handled as in any other Perl subroutine:
arguments are passed in <TT
CLASS="VARNAME"
>@_</TT
>, and a result value
is returned with <TT
CLASS="LITERAL"
>return</TT
> or as the last expression
evaluated in the function.
</P
><P
> For example, a function returning the greater of two integer values
could be defined as:
</P><PRE
CLASS="PROGRAMLISTING"
>CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
if ($_[0] > $_[1]) { return $_[0]; }
return $_[1];
$$ LANGUAGE plperl;</PRE
><P>
</P
><P
> If an SQL null value<A
NAME="AEN36481"
></A
> is passed to a function,
the argument value will appear as <SPAN
CLASS="QUOTE"
>"undefined"</SPAN
> 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 <TT
CLASS="LITERAL"
>STRICT</TT
> to the function definition to make
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> 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 <CODE
CLASS="FUNCTION"
>perl_max</CODE
> with
one null and one nonnull argument to return the nonnull argument,
rather than a null value:
</P><PRE
CLASS="PROGRAMLISTING"
>CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS $$
my ($x,$y) = @_;
if (! defined $x) {
if (! defined $y) { return undef; }
return $y;
}
if (! defined $y) { return $x; }
if ($x > $y) { return $x; }
return $y;
$$ LANGUAGE plperl;</PRE
><P>
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.
</P
><P
> Perl can return <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> arrays as
references to Perl arrays. Here is an example:
</P><PRE
CLASS="PROGRAMLISTING"
>CREATE OR REPLACE function returns_array()
RETURNS text[][] AS $$
return [['a"b','c,d'],['e\\f','g']];
$$ LANGUAGE plperl;
select returns_array();</PRE
><P>
</P
><P
> 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:
</P><PRE
CLASS="PROGRAMLISTING"
>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;</PRE
><P>
</P
><P
> 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,
</P><PRE
CLASS="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();</PRE
><P>
Any columns in the declared result data type that are not present in the
hash will be returned as NULLs.
</P
><P
> 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 queueing up
the entire result set in memory. You can do this with
<CODE
CLASS="FUNCTION"
>return_next</CODE
> as illustrated below. Note that
after the last <CODE
CLASS="FUNCTION"
>return_next</CODE
>, you must put
either <TT
CLASS="LITERAL"
>return</TT
> or (better) <TT
CLASS="LITERAL"
>return
undef</TT
>.
</P><PRE
CLASS="PROGRAMLISTING"
>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;</PRE
><P>
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:
</P><PRE
CLASS="PROGRAMLISTING"
>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();</PRE
><P>
</P
><P
> <SPAN
CLASS="APPLICATION"
>PL/Perl</SPAN
> does not currently have full support for
domain types: it treats a domain the same as the underlying scalar
type. This means that constraints associated with the domain will
not be enforced. This is not an issue for function arguments, but
it is a hazard if you declare a <SPAN
CLASS="APPLICATION"
>PL/Perl</SPAN
> function
as returning a domain type.
</P
><P
> If you wish to use the <TT
CLASS="LITERAL"
>strict</TT
> pragma with your code,
the easiest way to do so is to <TT
CLASS="COMMAND"
>SET</TT
>
<TT
CLASS="LITERAL"
>plperl.use_strict</TT
> to true. This parameter affects
subsequent compilations of <SPAN
CLASS="APPLICATION"
>PL/Perl</SPAN
> functions, but not
functions already compiled in the current session. To set the
parameter before <SPAN
CLASS="APPLICATION"
>PL/Perl</SPAN
> has been loaded, it is
necessary to have added <SPAN
CLASS="QUOTE"
>"<TT
CLASS="LITERAL"
>plperl</TT
>"</SPAN
> to the <A
HREF="runtime-config-custom.html#GUC-CUSTOM-VARIABLE-CLASSES"
>custom_variable_classes</A
> list in
<TT
CLASS="FILENAME"
>postgresql.conf</TT
>.
</P
><P
> Another way to use the <TT
CLASS="LITERAL"
>strict</TT
> pragma is to put
</P><PRE
CLASS="PROGRAMLISTING"
>use strict;</PRE
><P>
in the function body. But this only works in <SPAN
CLASS="APPLICATION"
>PL/PerlU</SPAN
>
functions, since <TT
CLASS="LITERAL"
>use</TT
> is not a trusted operation. In
<SPAN
CLASS="APPLICATION"
>PL/Perl</SPAN
> functions you can instead do
</P><PRE
CLASS="PROGRAMLISTING"
>BEGIN { strict->import(); }</PRE
><P>
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="pltcl-procnames.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="plperl-database.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Tcl Procedure Names</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="server-programming.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Database Access from PL/Perl</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>