<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.74 2010/01/20 03:37:10 rhaas Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.75 2010/01/26 23:11:56 adunstan Exp $ -->

<chapter id="plperl">

<title>PL/Perl - Perl Procedural Language</title>

</para>

<para>

If you wish to use the <literal>strict</> pragma with your code,

the easiest way to do so is to <command>SET</>

<literal>plperl.use_strict</literal> to true. This parameter affects

subsequent compilations of <application>PL/Perl</> functions, but not

functions already compiled in the current session. To set the

parameter before <application>PL/Perl</> has been loaded, it is

necessary to have added <quote><literal>plperl</></> to the <xref

linkend="guc-custom-variable-classes"> list in

<filename>postgresql.conf</filename>.

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</> <literal>plperl.use_strict</literal>

to true (see <xref linkend="plperl.use_strict">).

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.

</para>

<para>

Another way tousethe <literal>strict</> pragma is to put:

For permanentusein specific functions you can simply put:

<programlisting>

use strict;

</programlisting>

in the function body. But this only works in <application>PL/PerlU</>

functions, since the <literal>use</> triggers a <literal>require</>

which is not a trusted operation. In

<application>PL/Perl</> functions you can instead do:

<programlisting>

BEGIN { strict->import(); }

</programlisting>

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.

</para>

</sect1>

</sect2>

</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 <literal>return</> command will accept any string

that is acceptable input format for the function's declared return

type. So, within the PL/Perl function,

all values are just text strings.

</para>

</sect1>

<sect1 id="plperl-global">

<itemizedlist>

<listitem>

<para>

PL/Perl functions cannot call each other directly (because they

are anonymous subroutines inside Perl).

PL/Perl functions cannot call each other directly.

</para>

</listitem>

</listitem>

</itemizedlist>

</para>

</sect2>

</sect1>

</chapter>

NOTICE: This is a test

CONTEXT: PL/Perl anonymous code block

-- check that restricted operations are rejected in a plperl DO block

DO $$ use Config; $$ LANGUAGE plperl;

ERROR: 'require' trapped by operation mask at line 1.

DO $$ eval "1+1"; $$ LANGUAGE plperl;

ERROR: 'eval "string"' trapped by operation mask at line 1.

CONTEXT: PL/Perl anonymous code block

-- check that we can't "use" a module that's not been loaded already

-- compile-time error: "Unable to load blib.pm into plperl"

DO $$ use blib; $$ LANGUAGE plperl;

ERROR: Unable to load blib.pm into plperl at line 1.

BEGIN failed--compilation aborted at line 1.

CONTEXT: PL/Perl anonymous code block

-- check that we can "use" a module that has already been loaded

-- runtime error: "Can't use string ("foo") as a SCALAR ref while "strict refs" in use

DO $do$ use strict; my $name = "foo"; my $ref = $$name; $do$ LANGUAGE plperl;

ERROR: Can't use string ("foo") as a SCALAR ref while "strict refs" in use at line 1.

CONTEXT: PL/Perl anonymous code block

-- test plperl/plperlu interaction

-- the language and call ordering of this test sequence is useful

CREATE OR REPLACE FUNCTION bar() RETURNS integer AS $$

#die 'BANG!'; # causes server process to exit(2)

# alternative - causes server process to exit(255)

spi_exec_query("invalid sql statement");

$$ language plperl; -- plperlor plperlu

$$ language plperl; --compileplperlcode

CREATE OR REPLACE FUNCTION foo() RETURNS integer AS $$

spi_exec_query("SELECT * FROM bar()");

return 1;

$$ LANGUAGE plperlu; --must be opposite to language of bar

$$ LANGUAGE plperlu; --compile plperlu code

SELECT * FROM bar(); -- throws exception normally

SELECT * FROM bar(); -- throws exception normally (running plperl)

ERROR: syntax error at or near "invalid" at line 4.

CONTEXT: PL/Perl function "bar"

SELECT * FROM foo(); -- used to cause backend crash

SELECT * FROM foo(); -- used to cause backend crash (after switching to plperlu)

ERROR: syntax error at or near "invalid" at line 4. at line 2.

CONTEXT: PL/Perl function "foo"

PostgreSQL::InServer::Util::bootstrap();

PostgreSQL::InServer::SPI::bootstrap();

}

$SIG{__DIE__} = \&::plperl_die;

sub ::mkfuncsrc {

my ($name,$imports,$prolog,$src) =@_;

sub ::mkunsafefunc {

my$ret =eval(qq[ sub {$_[0]$_[1] }]);

$@ =~s/\(eval\d+\)//gif$@;

return$ret;

my$BEGIN =join"\n",map {

my$names =$imports->{$_} || [];

}sortkeys%$imports;

$BEGIN &&="BEGIN {$BEGIN }";

$name =~s/\\/\\\\/g;

$name =~s/::|'/_/g;# avoid package delimiters

returnqq[ undef *{'$name'}; *{'$name'} = sub {$BEGIN$prolog$src }];

}

use strict;

sub ::mk_strict_unsafefunc {

my$ret =eval(qq[ sub { use strict;$_[0]$_[1] }]);

sub ::mkunsafefunc {

no strict;# default to no strict for the eval

my$ret =eval(::mkfuncsrc(@_));

$@ =~s/\(eval\d+\)//gif$@;

return$ret;

}

ifref$argne'ARRAY';

my$res =join",",map {

(ref$_) ? ::encode_array_constructor($_)

: ::quote_nullable($_)

: ::quote_nullable($_)

}@$arg;

return"ARRAY[$res]";

}

use varsqw($PLContainer);

$PLContainer = new Safe('PLPerl');

$PLContainer->permit_only(':default');

$PLContainer->share(qw[&elog &ERROR]);

my$msg='trusted Perl functions disabled - please upgrade Perl Safe module';

my$msg ='trusted Perl functions disabled - please upgrade Perl Safe module to version 2.09 or later';

sub ::mksafefunc {

return$PLContainer->reval(qq[sub { elog(ERROR,'$msg') }]);

submksafefunc {

my ($name,$pragma,$prolog,$src)=@_;

$src=qq{ ::elog(::ERROR,"$msg\n")};

my$ret= eval(::mkfuncsrc($name,$pragma,'',$src));

$@ =~s/\(eval\d+\)//gif $@;

return$ret;

}

sub ::mk_strict_safefunc {

return$PLContainer->reval(qq[sub { elog(ERROR,'$msg') }]);

}

use strict;

use varsqw($PLContainer);

$PLContainer = new Safe('PLPerl');

$PLContainer->permit_only(':default');

$PLContainer->permit(qw[:base_math !:base_io sort time]);

$PLContainer->permit(qw[:base_math !:base_io sort time require]);

$PLContainer->share(qw[&elog &return_next

]);

$PLContainer->permit(qw[require caller]);

$PLContainer->reval('use strict;');

$PLContainer->deny(qw[require caller]);

sub ::mksafefunc {

my$ret =$PLContainer->reval(qq[sub {$_[0]$_[1] }]);

$PLContainer->permit(qw[caller]);

::safe_eval(q{

})ordie$@;

$PLContainer->deny(qw[caller]);

sub ::safe_eval {

my$ret =$PLContainer->reval(shift);

$@ =~s/\(eval\d+\)//gif$@;

return$ret;

}

sub ::mk_strict_safefunc {

my$ret =$PLContainer->reval(qq[sub { BEGIN { strict->import(); }$_[0]$_[1] }]);

$@ =~s/\(eval\d+\)//gif$@;

return$ret;

sub ::mksafefunc {

return ::safe_eval(::mkfuncsrc(@_));

}