rdelaage/postgresql
1
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-09-30 13:41:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
pointer into the real documentation.
This commit is contained in:
Peter Eisentraut 2000-12-19 18:16:26 +00:00
parent 109cdbb4f7
commit f824d4a363
2 changed files with 143 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
doc/src/sgml/plperl.sgml
View File

@ -1,121 +1,156 @@
<!-- <!--
$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 In order to get the total compensation (base + bonus) we could
define a function as follows: define a function as follows:
<programlisting> <programlisting>
CREATE FUNCTION totalcomp(int4, int4) RETURNS int4 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:
<programlisting>
SELECT name, totalcomp(basesalary, bonus) FROM employee;
</programlisting>
</para>
<para>
But, we can also pass entire tuples to our functions:
<programlisting>
CREATE FUNCTION empcomp(employee) RETURNS integer AS '
my $emp = shift;
return $emp->{''basesalary''} + $emp->{''bonus''};
' LANGUAGE 'plperl';
</programlisting>
A tuple is passed as a reference to a hash. The keys are the names
of the fields in the tuples. The hash values are values of the
corresponding fields in the tuple.
</para>
<tip>
<para> <para>
We may now use our function like so: Because the function body is passed as an SQL string literal to
<programlisting> <command>CREATE FUNCTION</command> you have to escape single
SELECT name, totalcomp(basesalary, bonus) 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>
<para> </tip>
But, we can also pass entire tuples to our function:
<programlisting> <para>
CREATE FUNCTION empcomp(employee) returns int4 The new function <function>empcomp</function> can used like:
AS 'my $emp = shift; <programlisting>
return $emp->{''basesalary''} + $emp->{''bonus''};' SELECT name, empcomp(employee) FROM employee;
LANGUAGE 'plperl'; </programlisting>
</programlisting> </para>
A tuple is passed as a reference to hash. The keys are the names of
fields in the tuples. The values are values of the corresponding <para>
field in the tuple. Here is an example of a function which will not work because file
</para> system operations are not allowed for security reasons:
<para> <programlisting>
The new function <literal>empcomp</literal> can used like: CREATE FUNCTION badfunc() RETURNS integer AS '
<programlisting> open(TEMP, ">/tmp/badfile");
SELECT name, empcomp(employee) from employee; print TEMP "Gotcha!\n";
</programlisting> return 1;
</para> ' LANGUAGE 'plperl';
</sect1> </programlisting>
</chapter> 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:

58
src/pl/plperl/README
View File

@ -1,52 +1,8 @@
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'.
To build from this directory use 'gmake all; gmake install'. libperl
must have been built as a shared library, which is usually not the
case in standard installations.
PREREQUISITES Consult the PostgreSQL User's Guide and the INSTALL file in the
====================================================================== top-level directory of the source distribution for more information.
+ Perl must be built as a shared library.
+ when compiling Postgres, use the --with-perl option. Alternatively,
you can build plperl separately in an already-configured source tree:
cd to $POSTGRES_SRC/src/pl/plperl/ and do "gmake all install".
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();