From fcc02c20fcc3887cb5c2314a39a789963bd118ff Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Tue, 30 May 2006 11:40:21 +0000 Subject: [PATCH] Update PL documentation: An article at WebProNews quoted from the PG docs as to the merits of stored procedures. I have added a bit more material on their merits, as well as making a few changes to improve the introductions to PL/Perl and PL/Tcl. Chris Browne --- doc/src/sgml/plperl.sgml | 8 +++++++- doc/src/sgml/plpgsql.sgml | 41 ++++++++++++++++++++++++++++------------- doc/src/sgml/pltcl.sgml | 43 ++++++++++++++++++++++++------------------- 3 files changed, 59 insertions(+), 33 deletions(-) diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index 94a375587f..12ac0157c3 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -1,4 +1,4 @@ - + PL/Perl - Perl Procedural Language @@ -17,6 +17,12 @@ Perl programming language. + The usual advantage to using PL/Perl is that this allows use, + within stored functions, of the manyfold string + munging operators and functions available for Perl. Parsing + complex strings may be be easier using Perl than it is with the + string functions and control structures provided in PL/pgsql. + To install PL/Perl in a particular database, use createlang plperl dbname. diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 4f302a858e..2fc998ee90 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,4 +1,4 @@ - + <application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language @@ -155,21 +155,36 @@ $$ LANGUAGE plpgsql; That means that your client application must send each query to - the database server, wait for it to be processed, receive the - results, do some computation, then send other queries to the - server. All this incurs interprocess communication and may also - incur network overhead if your client is on a different machine - than the database server. + the database server, wait for it to be processed, receive and + process the results, do some computation, then send further + queries to the server. All this incurs interprocess + communication and will also incur network overhead if your client + is on a different machine than the database server. - With PL/pgSQL you can group a block of computation and a - series of queries inside the - database server, thus having the power of a procedural - language and the ease of use of SQL, but saving lots of - time because you don't have the whole client/server - communication overhead. This can make for a - considerable performance increase. + With PL/pgSQL you can group a block of + computation and a series of queries inside + the database server, thus having the power of a procedural + language and the ease of use of SQL, but with considerable + savings because you don't have the whole client/server + communication overhead. + + + + Elimination of additional round trips between + client and server + + Intermediate results that the client does not + need do not need to be marshalled or transferred between server + and client + + There is no need for additional rounds of query + parsing + + + This can allow for a considerable performance increase as + compared to an application that does not use stored functions. diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index 3ffaf81fe5..d4bdabeeae 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -1,4 +1,4 @@ - + PL/Tcl - Tcl Procedural Language @@ -25,22 +25,27 @@ Overview - PL/Tcl offers most of the capabilities a function - writer has in the C language, except for some restrictions. + PL/Tcl offers most of the capabilities a function writer has in + the C language, with a few restrictions, and with the addition of + the powerful string processing libraries that are available for + Tcl. - The good restriction is that everything is executed in a safe - Tcl interpreter. In addition to the limited command set of safe Tcl, only - a few commands are available to access the database via SPI and to raise - messages via elog(). There is no way to access internals of the - database server or to gain OS-level access under the permissions of the - PostgreSQL server process, as a C function can do. - Thus, any unprivileged database user may be - permitted to use this language. + One compelling good restriction is that + everything is executed from within the safety of the context of a + Tcl interpreter. In addition to the limited command set of safe + Tcl, only a few commands are available to access the database via + SPI and to raise messages via elog(). PL/Tcl + provides no way to access internals of the database server or to + gain OS-level access under the permissions of the + PostgreSQL server process, as a C + function can do. Thus, unprivileged database users may be trusted + to use this language; it does not give them unlimited authority. - The other, implementation restriction is that Tcl functions cannot - be used to create input/output functions for new data types. + The other notable implementation restriction is that Tcl functions + may not be used to create input/output functions for new data + types. Sometimes it is desirable to write Tcl functions that are not restricted @@ -55,12 +60,12 @@ a user logged in as the database administrator. - The shared object for the PL/Tcl and PL/TclU call handlers is - automatically built and installed in the - PostgreSQL - library directory if Tcl support is specified - in the configuration step of the installation procedure. To install - PL/Tcl and/or PL/TclU in a particular database, use the + The shared object code for the PL/Tcl and + PL/TclU call handlers is automatically built and + installed in the PostgreSQL library + directory if Tcl support is specified in the configuration step of + the installation procedure. To install PL/Tcl + and/or PL/TclU in a particular database, use the createlang program, for example createlang pltcl dbname or createlang pltclu dbname. -- 2.11.0