Skip to content

Commit f824d4a

Browse files
peterepetere
committed
Polish PL/Perl documentation. The README file got shrunk to being a
pointer into the real documentation.
1 parent 109cdbb commit f824d4a

File tree

2 files changed

+145
-154
lines changed

2 files changed

+145
-154
lines changed

‎doc/src/sgml/plperl.sgml‎

Lines changed: 137 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,156 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.5 2000/09/29 20:21:34 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.6 2000/12/19 18:16:25 petere Exp $
33
-->
44

5-
<chapter id="pl-perl">
6-
<title>PL/perl - Perl Procedural Language</title>
5+
<chapter id="plperl">
6+
<title>PL/Perl - Perl Procedural Language</title>
7+
8+
<para>
9+
PL/Perl allows you to write functions in the Perl programming
10+
language which may be used in SQL queries as if they were built into
11+
<productname>Postgres</productname>.
12+
</para>
13+
14+
<para>
15+
The PL/Perl intepreter is a full Perl interpreter. However, certain
16+
operations have been disabled in order to maintain the security of
17+
the system. In general, the operations that are restricted are
18+
those that interact with the environment. This includes filehandle
19+
operations, <literal>require</literal>, and <literal>use</literal>
20+
(for external modules). It should be noted that this security is
21+
not absolute. Indeed, several Denial-of-Service attacks are still
22+
possible - memory exhaustion and endless loops are two examples.
23+
</para>
24+
25+
<sect1 id="plperl-install">
26+
<title>Building and Installing</title>
727

828
<para>
9-
This chapter describes how to compile, install and
10-
use PL/Perl.
29+
In order to build and install PL/Perl if you are installing
30+
<productname>Postgres</productname> from source then the
31+
<option>--with-perl</option> must be supplied to the
32+
<filename>configure</filename> script. PL/Perl requires that, when
33+
<productname>Perl</productname> was installed, the
34+
<filename>libperl</filename> library was build as a shared object.
35+
At the time of this writing, this is almost never the case in the
36+
Perl packages that are distributed with the operating systems. A
37+
message like this will appear during the build to point out this
38+
fact:
39+
<screen>
40+
<computeroutput>
41+
*****
42+
* Cannot build PL/Perl because libperl is not a shared library.
43+
* Skipped.
44+
*****
45+
</computeroutput>
46+
</screen>
47+
Therefore it is likely that you will have to re-build and install
48+
<productname>Perl</productname> manually to be able to build
49+
PL/Perl.
1150
</para>
12-
<sect1 id="plperl-overview">
13-
<title>Overview</title>
14-
<para>
15-
PL/Perl allows you to write functions in the Perl scripting
16-
language which may be used in SQL queries as if they were
17-
built into <productname>Postgres</productname>.
18-
</para>
19-
<para>
20-
The PL/Perl intepreter is a full Perl interpreter. However,
21-
certain operations have been disabled in order to increase
22-
the security level of the system.
23-
</para>
24-
<para>
25-
In general, the operations that are restricted are those that
26-
interact with the environment. This includes filehandle operations,
27-
<literal>require</literal>, and <literal>use</literal> (for external
28-
modules).
29-
</para>
30-
<para>
31-
It should be noted that this security is not absolute. Indeed, several
32-
Denial-of-Service attacks are still possible - memory exhaustion and
33-
endless loops are two.
34-
</para>
35-
</sect1>
3651

37-
<sect1 id="plperl-install">
38-
<title>Building and Installing</title>
39-
<para>
40-
Assuming that the <productname>Postgres</productname>
41-
source tree is rooted at $PGSRC, then the Pl/perl source
42-
code is located in $PGSRC/src/pl/plperl.
43-
</para>
44-
<para>
45-
To build, simply do the following:
46-
<programlisting>
47-
cd $PGSRC/src/pl/plperl
48-
perl Makefile.PL
49-
make
50-
</programlisting>
51-
</para>
52+
<para>
53+
When you want to retry to build PL/Perl after having reinstalled
54+
Perl, then change to the directory
55+
<filename>src/pl/plperl</filename> in the
56+
<productname>Postgres</productname> source tree and issue the commands
57+
<programlisting>
58+
gmake clean
59+
gmake all
60+
gmake install
61+
</programlisting>
62+
</para>
5263

53-
<para>
54-
This will create a shared library file. On a Linux system, it will be
55-
named plperl.so. The extension may differ on other systems.
56-
</para>
57-
<para>
58-
The shared library should then be copied into the lib subdirectory of the
59-
postgres installation.
60-
</para>
61-
<para>
62-
The createlang command is used to install the language into a database.
63-
If it is installed into template1, all future databases will have the
64-
language installed automatically.
65-
</para>
66-
</sect1>
64+
<para>
65+
The <command>createlang</command> command is used to install the
66+
language into a database.
67+
<screen>
68+
<prompt>$</prompt> <userinput>createlang plperl template1</userinput>
69+
</screen>
70+
If it is installed into template1, all future databases will have
71+
the language installed automatically.
72+
</para>
73+
</sect1>
6774

68-
<sect1 id="plperl-use">
69-
<title>Using PL/Perl</title>
70-
<para>
71-
Assume you have the following table:
72-
<programlisting>
75+
<sect1 id="plperl-use">
76+
<title>Using PL/Perl</title>
77+
78+
<para>
79+
Assume you have the following table:
80+
<programlisting>
7381
CREATE TABLE EMPLOYEE (
7482
name text,
75-
basesalary int4,
76-
bonus int4 );
77-
</programlisting>
78-
79-
In order to get the total compensation (base + bonus) we could
80-
define a function as follows:
81-
<programlisting>
82-
CREATE FUNCTION totalcomp(int4, int4) RETURNS int4
83+
basesalary integer,
84+
bonus integer
85+
);
86+
</programlisting>
87+
88+
In order to get the total compensation (base + bonus) we could
89+
define a function as follows:
90+
<programlisting>
91+
CREATE FUNCTION totalcomp(integer, integer) RETURNS integer
8392
AS 'return $_[0] + $_[1]'
8493
LANGUAGE 'plperl';
85-
</programlisting>
94+
</programlisting>
8695

87-
Note that the arguments are passed to the function in
88-
<literal>@_</literal> as might be expected. Also, because
89-
of the quoting rules for the SQL creating the function, you
90-
may find yourself using the extended quoting functions (qq[],
91-
q[], qw[]) more often that you are used to.
92-
</para>
93-
<para>
94-
We may now use our function like so:
95-
<programlisting>
96-
SELECT name, totalcomp(basesalary, bonus) from employee
97-
</programlisting>
98-
</para>
99-
<para>
100-
But, we can also pass entire tuples to our function:
101-
<programlisting>
102-
CREATE FUNCTION empcomp(employee) returns int4
103-
AS 'my $emp = shift;
104-
return $emp->{''basesalary''} + $emp->{''bonus''};'
105-
LANGUAGE 'plperl';
106-
</programlisting>
107-
A tuple is passed as a reference to hash. The keys are the names of
108-
fields in the tuples. The values are values of the corresponding
109-
field in the tuple.
110-
</para>
96+
Notice that the arguments to the function are passed in
97+
<varname>@_</varname> as might be expected.
98+
</para>
99+
100+
<para>
101+
We can now use our function like so:
102+
<programlisting>
103+
SELECT name, totalcomp(basesalary, bonus) FROM employee;
104+
</programlisting>
105+
</para>
106+
107+
<para>
108+
But, we can also pass entire tuples to our functions:
109+
<programlisting>
110+
CREATE FUNCTION empcomp(employee) RETURNS integer AS '
111+
my $emp = shift;
112+
return $emp->{''basesalary''} + $emp->{''bonus''};
113+
' LANGUAGE 'plperl';
114+
</programlisting>
115+
A tuple is passed as a reference to a hash. The keys are the names
116+
of the fields in the tuples. The hash values are values of the
117+
corresponding fields in the tuple.
118+
</para>
119+
120+
<tip>
111121
<para>
112-
The new function <literal>empcomp</literal> can used like:
113-
<programlisting>
114-
SELECT name, empcomp(employee) from employee;
115-
</programlisting>
122+
Because the function body is passed as an SQL string literal to
123+
<command>CREATE FUNCTION</command> you have to escape single
124+
quotes within your Perl source, either by doubling them as shown
125+
above, or by using the extended quoting functions
126+
(<literal>q[]</literal>, <literal>qq[]</literal>,
127+
<literal>qw[]</literal>). Backslashes must be escaped by doubling
128+
them.
116129
</para>
117-
</sect1>
118-
</chapter>
130+
</tip>
131+
132+
<para>
133+
The new function <function>empcomp</function> can used like:
134+
<programlisting>
135+
SELECT name, empcomp(employee) FROM employee;
136+
</programlisting>
137+
</para>
138+
139+
<para>
140+
Here is an example of a function which will not work because file
141+
system operations are not allowed for security reasons:
142+
<programlisting>
143+
CREATE FUNCTION badfunc() RETURNS integer AS '
144+
open(TEMP, ">/tmp/badfile");
145+
print TEMP "Gotcha!\n";
146+
return 1;
147+
' LANGUAGE 'plperl';
148+
</programlisting>
149+
The creation of the function will succeed, but executing it will not.
150+
</para>
151+
152+
</sect1>
153+
</chapter>
119154

120155
<!-- Keep this comment at the end of the file
121156
Local variables:

‎src/pl/plperl/README‎

Lines changed: 8 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,8 @@
1-
README for PL/Perl 2000.10.24
2-
3-
PREREQUISITES
4-
======================================================================
5-
+ Perl must be built as a shared library.
6-
+ when compiling Postgres, use the --with-perl option. Alternatively,
7-
you can build plperl separately in an already-configured source tree:
8-
cd to $POSTGRES_SRC/src/pl/plperl/ and do "gmake all install".
9-
10-
CONFIGURING
11-
======================================================================
12-
+ as postgres super user:
13-
createlang plperl [database]
14-
15-
NOTES ON USAGE
16-
======================================================================
17-
+ Use q[], qq[], and qw[] instead of single quotes in
18-
function definitions.
19-
+ When using escape sequences, you must backslash your
20-
backslashes, e.g.
21-
$alphanum =~ s/\W//g; # Wrong! Will replace capital W's
22-
$alphanum =~ s/\\W//g; # Right! Will replace non-word chars
23-
+ Arguments to the function are available in @_
24-
+ If argument is declared as a tuple, then tuple is represented as a
25-
hash reference.
26-
27-
EXAMPLES
28-
======================================================================
29-
CREATE FUNCTION addints(int4, int4) RETURNS int4 AS '
30-
return $_[0] + $_[1]
31-
' LANGUAGE 'plperl';
32-
33-
SELECT addints(3,4);
34-
35-
-- of course, you can pass tuples;
36-
CREATE TABLE twoints ( a integer, b integer);
37-
CREATE FUNCTION addtwoints(twoints) RETURNS integer AS '
38-
$tup = shift;
39-
return $tup->{"a"} + $tup->{"b"};
40-
' LANGUAGE 'plperl';
41-
42-
SELECT addtwoints(twoints) from twoints;
43-
44-
-- here is one that will fail. Creating the function
45-
-- will work, but using it will fail.
46-
CREATE FUNCTION badfunc() RETURNS int4 AS '
47-
open(TEMP, ">/tmp/badfile");
48-
print TEMP "Gotcha!\n";
49-
return 1;
50-
' LANGUAGE 'plperl';
51-
52-
SELECT badfunc();
1+
PL/Perl allows you to write PostgreSQL functions and procedures in
2+
Perl. To include PL/Perl in the build use './configure --with-perl'.
3+
To build from this directory use 'gmake all; gmake install'. libperl
4+
must have been built as a shared library, which is usually not the
5+
case in standard installations.
6+
7+
Consult the PostgreSQL User's Guide and the INSTALL file in the
8+
top-level directory of the source distribution for more information.

0 commit comments

Comments
 (0)