Skip to content

P
Postgres FD Implementation
Commit f824d4a3 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Polish PL/Perl documentation. The README file got shrunk to being a 

pointer into the real documentation.
parent 109cdbb4
Hide whitespace changes
Inline Side-by-side
Showing with 145 additions and 154 deletions
doc/src/sgml/plperl.sgml
View file @ f824d4a3
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.5 2000/09/29 20:21:34 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.6 2000/12/19 18:16:25 petere Exp $
--> -->
<chapter id="pl-perl"> <chapter id="plperl">
<title>PL/perl - Perl Procedural Language</title> <title>PL/Perl - Perl Procedural Language</title>
<para>
PL/Perl allows you to write functions in the Perl programming
language which may be used in SQL queries as if they were built into
<productname>Postgres</productname>.
</para>
<para>
The PL/Perl intepreter is a full Perl interpreter. However, certain
operations have been disabled in order to maintain the security of
the system. In general, the operations that are restricted are
those that interact with the environment. This includes filehandle
operations, <literal>require</literal>, and <literal>use</literal>
(for external modules). It should be noted that this security is
not absolute. Indeed, several Denial-of-Service attacks are still
possible - memory exhaustion and endless loops are two examples.
</para>
<sect1 id="plperl-install">
<title>Building and Installing</title>
<para> <para>
This chapter describes how to compile, install and In order to build and install PL/Perl if you are installing
use PL/Perl. <productname>Postgres</productname> from source then the
<option>--with-perl</option> must be supplied to the
<filename>configure</filename> script. PL/Perl requires that, when
<productname>Perl</productname> was installed, the
<filename>libperl</filename> library was build as a shared object.
At the time of this writing, this is almost never the case in the
Perl packages that are distributed with the operating systems. A
message like this will appear during the build to point out this
fact:
<screen>
<computeroutput>
*****
* Cannot build PL/Perl because libperl is not a shared library.
* Skipped.
*****
</computeroutput>
</screen>
Therefore it is likely that you will have to re-build and install
<productname>Perl</productname> manually to be able to build
PL/Perl.
</para> </para>
<sect1 id="plperl-overview">
<title>Overview</title>
<para>
PL/Perl allows you to write functions in the Perl scripting
language which may be used in SQL queries as if they were
built into <productname>Postgres</productname>.
</para>
<para>
The PL/Perl intepreter is a full Perl interpreter. However,
certain operations have been disabled in order to increase
the security level of the system.
</para>
<para>
In general, the operations that are restricted are those that
interact with the environment. This includes filehandle operations,
<literal>require</literal>, and <literal>use</literal> (for external
modules).
</para>
<para>
It should be noted that this security is not absolute. Indeed, several
Denial-of-Service attacks are still possible - memory exhaustion and
endless loops are two.
</para>
</sect1>
<sect1 id="plperl-install"> <para>
<title>Building and Installing</title> When you want to retry to build PL/Perl after having reinstalled
<para> Perl, then change to the directory
Assuming that the <productname>Postgres</productname> <filename>src/pl/plperl</filename> in the
source tree is rooted at $PGSRC, then the Pl/perl source <productname>Postgres</productname> source tree and issue the commands
code is located in $PGSRC/src/pl/plperl. <programlisting>
</para> gmake clean
<para> gmake all
To build, simply do the following: gmake install
<programlisting> </programlisting>
cd $PGSRC/src/pl/plperl </para>
perl Makefile.PL
make
</programlisting>
</para>
<para> <para>
This will create a shared library file. On a Linux system, it will be The <command>createlang</command> command is used to install the
named plperl.so. The extension may differ on other systems. language into a database.
</para> <screen>
<para> <prompt>$</prompt> <userinput>createlang plperl template1</userinput>
The shared library should then be copied into the lib subdirectory of the </screen>
postgres installation. If it is installed into template1, all future databases will have
</para> the language installed automatically.
<para> </para>
The createlang command is used to install the language into a database. </sect1>
If it is installed into template1, all future databases will have the
language installed automatically.
</para>
</sect1>
<sect1 id="plperl-use"> <sect1 id="plperl-use">
<title>Using PL/Perl</title> <title>Using PL/Perl</title>
<para>
Assume you have the following table: <para>
<programlisting> Assume you have the following table:
<programlisting>
CREATE TABLE EMPLOYEE ( CREATE TABLE EMPLOYEE (
name text, name text,
basesalary int4, basesalary integer,
bonus int4 ); bonus integer
</programlisting> );
</programlisting>
In order to get the total compensation (base + bonus) we could
define a function as follows: In order to get the total compensation (base + bonus) we could
<programlisting> define a function as follows:
CREATE FUNCTION totalcomp(int4, int4) RETURNS int4 <programlisting>
CREATE FUNCTION totalcomp(integer, integer) RETURNS integer
AS 'return $_[0] + $_[1]' AS 'return $_[0] + $_[1]'
LANGUAGE 'plperl'; LANGUAGE 'plperl';
</programlisting> </programlisting>
Note that the arguments are passed to the function in Notice that the arguments to the function are passed in
<literal>@_</literal> as might be expected. Also, because <varname>@_</varname> as might be expected.
of the quoting rules for the SQL creating the function, you </para>
may find yourself using the extended quoting functions (qq[],
q[], qw[]) more often that you are used to. <para>
</para> We can now use our function like so:
<para> <programlisting>
We may now use our function like so: SELECT name, totalcomp(basesalary, bonus) FROM employee;
<programlisting> </programlisting>
SELECT name, totalcomp(basesalary, bonus) from employee </para>
</programlisting>
</para> <para>
<para> But, we can also pass entire tuples to our functions:
But, we can also pass entire tuples to our function: <programlisting>
<programlisting> CREATE FUNCTION empcomp(employee) RETURNS integer AS '
CREATE FUNCTION empcomp(employee) returns int4 my $emp = shift;
AS 'my $emp = shift; return $emp->{''basesalary''} + $emp->{''bonus''};
return $emp->{''basesalary''} + $emp->{''bonus''};' ' LANGUAGE 'plperl';
LANGUAGE 'plperl'; </programlisting>
</programlisting> A tuple is passed as a reference to a hash. The keys are the names
A tuple is passed as a reference to hash. The keys are the names of of the fields in the tuples. The hash values are values of the
fields in the tuples. The values are values of the corresponding corresponding fields in the tuple.
field in the tuple. </para>
</para>
<tip>
<para> <para>
The new function <literal>empcomp</literal> can used like: Because the function body is passed as an SQL string literal to
<programlisting> <command>CREATE FUNCTION</command> you have to escape single
SELECT name, empcomp(employee) from employee; quotes within your Perl source, either by doubling them as shown
</programlisting> above, or by using the extended quoting functions
(<literal>q[]</literal>, <literal>qq[]</literal>,
<literal>qw[]</literal>). Backslashes must be escaped by doubling
them.
</para> </para>
</sect1> </tip>
</chapter>
<para>
The new function <function>empcomp</function> can used like:
<programlisting>
SELECT name, empcomp(employee) FROM employee;
</programlisting>
</para>
<para>
Here is an example of a function which will not work because file
system operations are not allowed for security reasons:
<programlisting>
CREATE FUNCTION badfunc() RETURNS integer AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE 'plperl';
</programlisting>
The creation of the function will succeed, but executing it will not.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:
......
src/pl/plperl/README
View file @ f824d4a3
README for PL/Perl 2000.10.24 PL/Perl allows you to write PostgreSQL functions and procedures in
Perl. To include PL/Perl in the build use './configure --with-perl'.
PREREQUISITES To build from this directory use 'gmake all; gmake install'. libperl
====================================================================== must have been built as a shared library, which is usually not the
+ Perl must be built as a shared library. case in standard installations.
+ when compiling Postgres, use the --with-perl option. Alternatively,
you can build plperl separately in an already-configured source tree: Consult the PostgreSQL User's Guide and the INSTALL file in the
cd to $POSTGRES_SRC/src/pl/plperl/ and do "gmake all install". top-level directory of the source distribution for more information.
CONFIGURING
======================================================================
+ as postgres super user:
createlang plperl [database]
NOTES ON USAGE
======================================================================
+ Use q[], qq[], and qw[] instead of single quotes in
function definitions.
+ When using escape sequences, you must backslash your
backslashes, e.g.
$alphanum =~ s/\W//g; # Wrong! Will replace capital W's
$alphanum =~ s/\\W//g; # Right! Will replace non-word chars
+ Arguments to the function are available in @_
+ If argument is declared as a tuple, then tuple is represented as a
hash reference.
EXAMPLES
======================================================================
CREATE FUNCTION addints(int4, int4) RETURNS int4 AS '
return $_[0] + $_[1]
' LANGUAGE 'plperl';
SELECT addints(3,4);
-- of course, you can pass tuples;
CREATE TABLE twoints ( a integer, b integer);
CREATE FUNCTION addtwoints(twoints) RETURNS integer AS '
$tup = shift;
return $tup->{"a"} + $tup->{"b"};
' LANGUAGE 'plperl';
SELECT addtwoints(twoints) from twoints;
-- here is one that will fail. Creating the function
-- will work, but using it will fail.
CREATE FUNCTION badfunc() RETURNS int4 AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE 'plperl';
SELECT badfunc();
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment