From da123b7c58fb8f75bcaf14cf5521e54222ede52b Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 18 Sep 2002 20:09:32 +0000 Subject: Update installation instructions and put mostly everything in one place. Also, some editing in PL/Perl and PL/Python chapters. --- doc/src/sgml/plperl.sgml | 416 ++++++++++++++++++++++------------------------- 1 file changed, 193 insertions(+), 223 deletions(-) (limited to 'doc/src/sgml/plperl.sgml') diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index c04ff95d929..97981bf603e 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -1,5 +1,5 @@ @@ -14,154 +14,75 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.16 2002/03/06 19:05:57 momj - PL/Perl is a loadable procedural language - that enables the Perl programming - language to be used to write - PostgreSQL functions. - - - - - - Overview - - - Normally, PL/Perl is installed as a trusted programming - language named plperl. In this setup, certain Perl - operations are disabled to preserve security. In general, the operations - that are restricted are those that interact with the environment. This - includes file handle operations, require, and - use (for external modules). - There is no way to access internals of the - database backend or to gain OS-level access under the permissions of the - PostgreSQL user ID, as a C function can do. - Thus, any unprivileged database user may be - permitted to use this language. - - - Sometimes it is desirable to write Perl functions that are not restricted - --- for example, one might want a Perl function that sends - mail. To handle these cases, PL/Perl can also be installed as an - untrusted language (usually named plperlu). - In this case the full Perl language is available. The writer of a PL/PerlU - function must take care that the function cannot be used to do anything - unwanted, since it will be able to do anything that could be done by - a user logged in as the database administrator. Note that the database - system allows only database superusers to create functions in untrusted - languages. - - - - - Building and Installing PL/Perl - - - If the option was supplied to the - configure - configure script, - the PostgreSQL build process will attempt to - build the PL/Perl shared library and install it in the - PostgreSQL library directory. + PL/Perl is a loadable procedural language that enables you to write + PostgreSQL functions in the Perl programming language. - On most platforms, since PL/Perl is a shared library, the - libperl - libperl library must be a shared library also. - At the time of this writing, this is almost never the case in prebuilt - Perl packages. If this difficulty arises in your situation, 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. -*** You might have to rebuild your Perl installation. Refer to -*** the documentation for details. - - - If you see this, you will have to re-build and install - Perl manually to be able to build - PL/Perl. During the configuration process for - Perl, request a shared library. + To install PL/Perl in a particular database, use + createlang plperl dbname. - - After having reinstalled Perl, change to the directory - src/pl/plperl in the - PostgreSQL source tree and issue the commands - -gmake clean -gmake all -gmake install - - to complete the build and installation of the PL/Perl shared library. - - - - To install - PL/Perl and/or PL/PerlU in a particular database, use the - createlang script, for example - createlang plperl dbname or - createlang plperlu dbname. - - If a language is installed into template1, all subsequently created databases will have the language installed automatically. - - - - - Description - - - PL/Perl Functions and Arguments + + + Users of source packages must specially enable the build of + PL/Perl during the installation process (refer to the installation + instructions for more information). Users of binary packages + might find PL/Perl in a separate subpackage. + + - - To create a function in the PL/Perl language, use the standard syntax + + PL/Perl Functions and Arguments - + + To create a function in the PL/Perl language, use the standard syntax: + CREATE FUNCTION funcname (argument-types) RETURNS return-type AS ' # PL/Perl function body ' LANGUAGE plperl; - - - PL/PerlU is the same, except that the language should be specified as - plperlu. - + + The body of the function is ordinary Perl code. + - - The body of the function is ordinary Perl code. Arguments and - results are handled as in any other Perl subroutine: arguments - are passed in @_, and a result value is returned - with return or as the last expression evaluated in the - function. For example, a function - returning the greater of two integer values could be defined as: + + Arguments and results are handled as in any other Perl subroutine: + Arguments are passed in @_, and a result value + is returned with return or as the last expression + evaluated in the function. For example, a function returning the + greater of two integer values could be defined as: - + CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS ' if ($_[0] > $_[1]) { return $_[0]; } return $_[1]; ' LANGUAGE plperl; - - - If a NULL is passed to a function, the argument value will appear - as undefined in Perl. The above function definition will - not behave very nicely with NULL inputs (in fact, it will act as - though they are zeroes). We could add WITH (isStrict) - to the function definition to make PostgreSQL - do something more reasonable: if a NULL is passed, the - function will not be called at all, but will just return a NULL - result automatically. Alternatively, we could check for undefined - inputs in the function body. For example, suppose that we wanted perl_max - with one null and one non-null argument to return the non-null - argument, rather than NULL: - - + + + + + If an SQL null value is passed to a function, the argument value + will appear as undefined in Perl. The above function + definition will not behave very nicely with null inputs (in fact, + it will act as though they are zeroes). We could add + STRICT to the function definition to make + PostgreSQL do something more reasonable: + if a null value is passed, the function will not be called at all, + but will just return a null result automatically. Alternatively, + we could check for undefined inputs in the function body. For + example, suppose that we wanted perl_max with + one null and one non-null argument to return the non-null argument, + rather than a null value: + + CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS ' my ($a,$b) = @_; if (! defined $a) { @@ -172,21 +93,21 @@ CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS ' if ($a > $b) { return $a; } return $b; ' LANGUAGE plperl; - - + + - - As shown above, - to return a NULL from a PL/Perl function, return an undefined - value. This can be done whether the function is strict or not. - + + As shown above, to return an SQL null value from a PL/Perl + function, return an undefined value. This can be done whether the + function is strict or not. + - - Composite-type arguments are passed to the function as references to - hashes. The keys of the hash are the attribute names of the composite - type. Here is an example: + + Composite-type arguments are passed to the function as references + to hashes. The keys of the hash are the attribute names of the + composite type. Here is an example: - + CREATE TABLE employee ( name text, basesalary integer, @@ -199,25 +120,97 @@ CREATE FUNCTION empcomp(employee) RETURNS integer AS ' ' LANGUAGE plperl; SELECT name, empcomp(employee) FROM employee; - - + + - - There is not currently any support for returning a composite-type - result value. - + + There is currently no support for returning a composite-type result + value. + Because the function body is passed as an SQL string literal to CREATE FUNCTION, you have to escape single - quotes and backslashes within your Perl source, typically by doubling them - as shown in the above example. Another possible approach is to - avoid writing single quotes by using Perl's extended quoting functions - (q[], qq[], - qw[]). + quotes and backslashes within your Perl source, typically by + doubling them as shown in the above example. Another possible + approach is to avoid writing single quotes by using Perl's + extended quoting operators (q[], + qq[], qw[]). + + + + Data Values in PL/Perl + + + The argument values supplied to a PL/Perl function's script are + simply the input arguments converted to text form (just as if they + had been displayed by a SELECT statement). + Conversely, the return command will accept any string + that is acceptable input format for the function's declared return + type. So, the PL/Perl programmer can manipulate data values as if + they were just text. + + + + + Database Access from PL/Perl + + + Access to the database itself from your Perl function can be done via + an experimental module DBD::PgSPI + (also available at CPAN + mirror sites). This module makes available a + DBI-compliant database-handle named + $pg_dbh that can be used to perform queries + with normal DBI syntax. + + + + PL/Perl itself presently provides only one additional Perl command: + + + + + elog + PL/Perl + + + elog level, msg + + + Emit a log or error message. Possible levels are + DEBUG, LOG, INFO, + NOTICE, WARNING, and ERROR. + ERROR raises an error condition: further execution + of the function is abandoned, and the current transaction is + aborted. + + + + + + + + + Trusted and Untrusted PL/Perl + + + Normally, PL/Perl is installed as a trusted programming + language named plperl. In this setup, certain Perl + operations are disabled to preserve security. In general, the + operations that are restricted are those that interact with the + environment. This includes file handle operations, + require, and use (for + external modules). There is no way to access internals of the + database backend process or to gain OS-level access with the + permissions of the PostgreSQL user ID, + as a C function can do. Thus, any unprivileged database user may + be permitted to use this language. + Here is an example of a function that will not work because file @@ -231,89 +224,66 @@ CREATE FUNCTION badfunc() RETURNS integer AS ' The creation of the function will succeed, but executing it will not. + - Note that if the same function was created by a superuser using language - plperlu, execution would succeed. + Sometimes it is desirable to write Perl functions that are not + restricted --- for example, one might want a Perl function that + sends mail. To handle these cases, PL/Perl can also be installed + as an untrusted language (usually called + PL/PerlU). In this case the full Perl language is + available. If the createlang program is used to + install the language, the language name plperlu + will select the untrusted PL/Perl variant. - - - - Data Values in PL/Perl - - - The argument values supplied to a PL/Perl function's script are simply - the input arguments converted to text form (just as if they had been - displayed by a SELECT statement). Conversely, the return - command will accept any string that is acceptable input format for - the function's declared return type. So, the PL/Perl programmer can - manipulate data values as if they were just text. - + + The writer of a PL/PerlU function must take care that the function + cannot be used to do anything unwanted, since it will be able to do + anything that could be done by a user logged in as the database + administrator. Note that the database system allows only database + superusers to create functions in untrusted languages. + - + + If the above function was created by a superuser using the language + plperlu, execution would succeed. + + - - Database Access from PL/Perl + + Missing Features - Access to the database itself from your Perl function can be done via - an experimental module DBD::PgSPI - (also available at CPAN - mirror sites). This module makes available a - DBI-compliant database-handle named - $pg_dbh that can be used to perform queries - with normal DBI syntax. + The following features are currently missing from PL/Perl, but they + would make welcome contributions: + + + + + PL/Perl functions cannot call each other directly (because they + are anonymous subroutines inside Perl). There's presently no + way for them to share global variables, either. + + + + + + PL/Perl cannot be used to write trigger functions. + + + + + + DBD::PgSPI or similar capability + should be integrated into the standard + PostgreSQL distribution. + + + + - - PL/Perl itself presently provides only one additional Perl command: - - - - - - elog - - elog level, msg - - - Emit a log or error message. Possible levels are - DEBUG, LOG, INFO, - NOTICE, WARNING, and ERROR. - ERROR raises an error condition: further execution - of the function is abandoned, and the current transaction is - aborted. - - - - - - - - - - Missing Features - - - PL/Perl functions cannot call each other directly (because they - are anonymous subroutines inside Perl). There's presently - no way for them to share global variables, either. - - - - PL/Perl cannot currently be used to write trigger functions. - - - - DBD::PgSPI or similar capability should be integrated - into the standard PostgreSQL distribution. - - - - - - +