diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index 58023ac209a..2d47404c71e 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -1,121 +1,156 @@ - - PL/perl - Perl Procedural Language + + PL/Perl - Perl Procedural Language + + + 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 + Postgres. + + + + 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, require, and use + (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. + + + + Building and Installing - This chapter describes how to compile, install and - use PL/Perl. + In order to build and install PL/Perl if you are installing + Postgres from source then the + must be supplied to the + configure script. PL/Perl requires that, when + Perl was installed, the + libperl 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: + + +***** +* Cannot build PL/Perl because libperl is not a shared library. +* Skipped. +***** + + + Therefore it is likely that you will have to re-build and install + Perl manually to be able to build + PL/Perl. - - Overview - - 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 Postgres. - - - 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. - - - In general, the operations that are restricted are those that - interact with the environment. This includes filehandle operations, - require, and use (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. - - - - Building and Installing - - Assuming that the Postgres - source tree is rooted at $PGSRC, then the Pl/perl source - code is located in $PGSRC/src/pl/plperl. - - - To build, simply do the following: - -cd $PGSRC/src/pl/plperl -perl Makefile.PL -make - - + + When you want to retry to build PL/Perl after having reinstalled + Perl, then change to the directory + src/pl/plperl in the + Postgres source tree and issue the commands + +gmake clean +gmake all +gmake install + + - - This will create a shared library file. On a Linux system, it will be - named plperl.so. The extension may differ on other systems. - - - The shared library should then be copied into the lib subdirectory of the - postgres installation. - - - The createlang command is used to install the language into a database. - If it is installed into template1, all future databases will have the - language installed automatically. - - + + The createlang command is used to install the + language into a database. + +$ createlang plperl template1 + + If it is installed into template1, all future databases will have + the language installed automatically. + + - - Using PL/Perl - - Assume you have the following table: - + + Using PL/Perl + + + Assume you have the following table: + CREATE TABLE EMPLOYEE ( name text, - basesalary int4, - bonus int4 ); - + basesalary integer, + bonus integer +); + - In order to get the total compensation (base + bonus) we could - define a function as follows: - -CREATE FUNCTION totalcomp(int4, int4) RETURNS int4 + In order to get the total compensation (base + bonus) we could + define a function as follows: + +CREATE FUNCTION totalcomp(integer, integer) RETURNS integer AS 'return $_[0] + $_[1]' LANGUAGE 'plperl'; - + - Note that the arguments are passed to the function in - @_ as might be expected. Also, because - of the quoting rules for the SQL creating the function, you - may find yourself using the extended quoting functions (qq[], - q[], qw[]) more often that you are used to. - + Notice that the arguments to the function are passed in + @_ as might be expected. + + + + We can now use our function like so: + +SELECT name, totalcomp(basesalary, bonus) FROM employee; + + + + + But, we can also pass entire tuples to our functions: + +CREATE FUNCTION empcomp(employee) RETURNS integer AS ' + my $emp = shift; + return $emp->{''basesalary''} + $emp->{''bonus''}; +' LANGUAGE 'plperl'; + + 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. + + + - We may now use our function like so: - -SELECT name, totalcomp(basesalary, bonus) from employee - + Because the function body is passed as an SQL string literal to + CREATE FUNCTION you have to escape single + quotes within your Perl source, either by doubling them as shown + above, or by using the extended quoting functions + (q[], qq[], + qw[]). Backslashes must be escaped by doubling + them. - - But, we can also pass entire tuples to our function: - -CREATE FUNCTION empcomp(employee) returns int4 - AS 'my $emp = shift; - return $emp->{''basesalary''} + $emp->{''bonus''};' - LANGUAGE 'plperl'; - - 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 - field in the tuple. - - - The new function empcomp can used like: - -SELECT name, empcomp(employee) from employee; - - - - + + + + The new function empcomp can used like: + +SELECT name, empcomp(employee) FROM employee; + + + + + Here is an example of a function which will not work because file + system operations are not allowed for security reasons: + +CREATE FUNCTION badfunc() RETURNS integer AS ' + open(TEMP, ">/tmp/badfile"); + print TEMP "Gotcha!\n"; + return 1; +' LANGUAGE 'plperl'; + + The creation of the function will succeed, but executing it will not. + + + +