From fcc02c20fcc3887cb5c2314a39a789963bd118ff Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
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 94a375587fc..12ac0157c3e 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.54 2006/05/29 13:51:23 adunstan Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.55 2006/05/30 11:40:21 momjian Exp $ -->
<chapter id="plperl">
<title>PL/Perl - Perl Procedural Language</title>
@@ -17,6 +17,12 @@
<ulink url="http://www.perl.com">Perl programming language</ulink>.
</para>
+ <para> The usual advantage to using PL/Perl is that this allows use,
+ within stored functions, of the manyfold <quote>string
+ munging</quote> 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.</para>
+
<para>
To install PL/Perl in a particular database, use
<literal>createlang plperl <replaceable>dbname</></literal>.
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 4f302a858e7..2fc998ee909 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.89 2006/05/28 03:03:17 adunstan Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.90 2006/05/30 11:40:21 momjian Exp $ -->
<chapter id="plpgsql">
<title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title>
@@ -155,21 +155,36 @@ $$ LANGUAGE plpgsql;
<para>
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.
</para>
<para>
- With <application>PL/pgSQL</application> you can group a block of computation and a
- series of queries <emphasis>inside</emphasis> 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 <application>PL/pgSQL</application> you can group a block of
+ computation and a series of queries <emphasis>inside</emphasis>
+ 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.
+ </para>
+ <itemizedlist>
+
+ <listitem><para> Elimination of additional round trips between
+ client and server </para></listitem>
+
+ <listitem><para> Intermediate results that the client does not
+ need do not need to be marshalled or transferred between server
+ and client </para></listitem>
+
+ <listitem><para> There is no need for additional rounds of query
+ parsing </para></listitem>
+
+ </itemizedlist>
+ <para> This can allow for a considerable performance increase as
+ compared to an application that does not use stored functions.
</para>
<para>
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 3ffaf81fe5e..d4bdabeeaed 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.40 2006/05/27 20:24:16 adunstan Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.41 2006/05/30 11:40:21 momjian Exp $ -->
<chapter id="pltcl">
<title>PL/Tcl - Tcl Procedural Language</title>
@@ -25,22 +25,27 @@
<title>Overview</title>
<para>
- 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.
</para>
<para>
- 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 <function>elog()</>. There is no way to access internals of the
- database server or to gain OS-level access under the permissions of the
- <productname>PostgreSQL</productname> server process, as a C function can do.
- Thus, any unprivileged database user may be
- permitted to use this language.
+ One compelling <emphasis>good</emphasis> 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 <function>elog()</>. PL/Tcl
+ provides no way to access internals of the database server or to
+ gain OS-level access under the permissions of the
+ <productname>PostgreSQL</productname> 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.
</para>
<para>
- 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.
</para>
<para>
Sometimes it is desirable to write Tcl functions that are not restricted
@@ -55,12 +60,12 @@
a user logged in as the database administrator.
</para>
<para>
- The shared object for the <application>PL/Tcl</> and <application>PL/TclU</> call handlers is
- automatically built and installed in the
- <productname>PostgreSQL</productname>
- library directory if Tcl support is specified
- in the configuration step of the installation procedure. To install
- <application>PL/Tcl</> and/or <application>PL/TclU</> in a particular database, use the
+ The shared object code for the <application>PL/Tcl</> and
+ <application>PL/TclU</> call handlers is automatically built and
+ installed in the <productname>PostgreSQL</productname> library
+ directory if Tcl support is specified in the configuration step of
+ the installation procedure. To install <application>PL/Tcl</>
+ and/or <application>PL/TclU</> in a particular database, use the
<command>createlang</command> program, for example
<literal>createlang pltcl <replaceable>dbname</></literal> or
<literal>createlang pltclu <replaceable>dbname</></literal>.
--
GitLab