Re: plpgsql documentation

Patch applied. Thanks. Your documentation changes can be viewed in
five minutes using links on the developer's page,
http://www.postgresql.org/developer/testing.

---------------------------------------------------------------------------

Chris Browne wrote:
> 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.
>
> Index: plperl.sgml
> ===================================================================
> RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plperl.sgml,v
> retrieving revision 2.52
> diff -c -u -r2.52 plperl.sgml
> --- plperl.sgml 10 Mar 2006 19:10:48 -0000 2.52
> +++ plperl.sgml 25 May 2006 22:38:45 -0000
> @@ -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>.
> Index: plpgsql.sgml
> ===================================================================
> RCS file: /projects/cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v
> retrieving revision 1.88
> diff -c -u -r1.88 plpgsql.sgml
> --- plpgsql.sgml 10 Mar 2006 19:10:48 -0000 1.88
> +++ plpgsql.sgml 25 May 2006 22:38:46 -0000
> @@ -155,21 +155,36 @@
>
> <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>
> Index: pltcl.sgml
> ===================================================================
> RCS file: /projects/cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v
> retrieving revision 2.39
> diff -c -u -r2.39 pltcl.sgml
> --- pltcl.sgml 10 Mar 2006 19:10:48 -0000 2.39
> +++ pltcl.sgml 25 May 2006 22:38:46 -0000
> @@ -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>.
>
> --
> (format nil "~S(at)~S" "cbbrowne" "acm.org")
> http://www3.sympatico.ca/cbbrowne/advocacy.html
> If at first you don't succeed, then you didn't do it right!
> If at first you don't succeed, then skydiving definitely isn't for you.
>
> ---------------------------(end of broadcast)---------------------------
> TIP 5: don't forget to increase your free space map settings
>

--
Bruce Momjian http://candle.pha.pa.us
EnterpriseDB http://www.enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +