From da123b7c58fb8f75bcaf14cf5521e54222ede52b Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Wed, 18 Sep 2002 20:09:32 +0000
Subject: [PATCH] Update installation instructions and put mostly everything in
one place. Also, some editing in PL/Perl and PL/Python chapters.
---
doc/src/sgml/charset.sgml | 26 +-
doc/src/sgml/client-auth.sgml | 9 +-
doc/src/sgml/installation.sgml | 481 ++++++++++++++++++---------------
doc/src/sgml/jdbc.sgml | 89 +-----
doc/src/sgml/maintenance.sgml | 13 +-
doc/src/sgml/plperl.sgml | 416 +++++++++++++---------------
doc/src/sgml/plpython.sgml | 245 +++++++++--------
doc/src/sgml/ref/psql-ref.sgml | 29 +-
doc/src/sgml/runtime.sgml | 11 +-
9 files changed, 617 insertions(+), 702 deletions(-)
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index a4093a2382f..febe4d37326 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.27 2002/08/14 02:45:09 ishii Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.28 2002/09/18 20:09:31 petere Exp $ -->
<chapter id="charset">
<title>Localization</>
@@ -889,30 +889,6 @@ RESET CLIENT_ENCODING;
</para>
</sect2>
- <sect2>
- <title>About Unicode</title>
-
- <indexterm><primary>Unicode</></>
-
- <para>
- An automatic encoding translation between Unicode and other
- encodings has been supported since <productname>PostgreSQL</> 7.1.
- For 7.1 it was not enabled by default.
- To enable this feature, run configure with the
- <option>--enable-unicode-conversion</option> option. Note that this requires
- the <option>--enable-multibyte</option> option also.
- </para>
- <para>
- For 7.2, <option>--enable-unicode-conversion</option> is not necessary.
- The Unicode conversion functionality is automatically enabled
- if <option>--enable-multibyte</option> is specified.
- </para>
- <para>
- For 7.3, <option>--enable-unicode-conversion</option> nor
- <option>--enable-multibyte</option> is needed.
- </para>
- </sect2>
-
<sect2>
<title>What happens if the translation is not possible?</title>
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index dc4b2649c13..6e1d76522a1 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.37 2002/09/14 18:35:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.38 2002/09/18 20:09:31 petere Exp $
-->
<chapter id="client-authentication">
@@ -583,10 +583,9 @@ local db1,db2,@demodbs all md5
<para>
In order to use <productname>Kerberos</>, support for it must be
- enabled at build time. Both Kerberos 4 and 5 are supported
- (<literal>./configure --with-krb4</> or <literal>./configure
- --with-krb5</> respectively), although only one version can be
- supported in any one build.
+ enabled at build time. See <xref linkend="installation"> for more
+ information. Both Kerberos 4 and 5 are supported, but only one
+ version can be supported in any one build.
</para>
<para>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 69aa6737f6b..be27b9dddf8 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.80 2002/09/08 02:33:08 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.81 2002/09/18 20:09:31 petere Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -47,7 +47,9 @@ su - postgres
</para>
<para>
- The following prerequisites exist for building <productname>PostgreSQL</>:
+ The following software packages are required for building
+ <productname>PostgreSQL</>:
+
<itemizedlist>
<listitem>
<para>
@@ -106,46 +108,192 @@ su - postgres
<listitem>
<para>
<indexterm>
- <primary>flex</primary>
- </indexterm>
- <indexterm>
- <primary>bison</primary>
- </indexterm>
- <indexterm>
- <primary>yacc</primary>
+ <primary>installation</primary>
+ <secondary>on Windows</secondary>
</indexterm>
- <acronym>GNU</> <application>Flex</> and <application>Bison</> are
- needed to build from scratch, but they are
- <emphasis>not</> required when building from a released source
- package because pre-generated output files are included in released
- packages. You will
- need these programs only when building from a CVS tree or if you
- changed the actual scanner and parser definition files. If
- you need them, be sure to get <application>Flex</> 2.5.4 or
- later and <application>Bison</> 1.28 or later. Other <application>yacc</>
- programs can sometimes be used, but doing so requires extra
- effort and is not recommended. Other <application>lex</> programs will
- definitely not work.
+ To build on <productname>Windows NT</> or <productname>Windows
+ 2000</> you need the <productname>Cygwin</> and
+ <productname>cygipc</> packages. See the file
+ <filename>doc/FAQ_MSWIN</> for details.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The following packages are optional. They are not required in the
+ default configuration, but they are needed when certain build
+ options are enabled, as explained below.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ To build the server programming language PL/Perl you need a full
+ Perl installation, including the <filename>libperl</filename>
+ library and the header files. Since PL/Perl is a shared
+ library, the <indexterm><primary>libperl</primary></indexterm>
+ <filename>libperl</filename> library must be a shared library
+ also on most platforms. At the time of this writing, this is
+ almost never the case in prebuilt Perl packages.
+ </para>
+
+ <para>
+ If this difficulty arises in your situation, a message like this
+ will appear during the build to point out this fact:
+<screen>
+*** 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.
+</screen>
+ (If you don't follow the onscreen output you will merely notice
+ the the PL/Perl library object will not be installed.) If you
+ see this, you will have to re-build and install
+ <productname>Perl</productname> manually to be able to build
+ PL/Perl. During the configuration process for
+ <productname>Perl</productname>, request a shared library.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the Python interface module or the PL/Python server
+ programming language, you need a Python installation, including
+ the header files.
+ </para>
+
+ <para>
+ Since PL/Python is a shared library, the
+ <indexterm><primary>libpython</primary></indexterm>
+ <filename>libpython</filename> library must be a shared library
+ also on most platforms. This is not the case in a default
+ Python installation. If after building and installing you have
+ a file called <filename>plpython.so</filename> (possibly a
+ different extension), then everything went well. Otherwise you
+ should have seen a notice like this flying by:
+<screen>
+*** Cannot build PL/Python because libpython is not a shared library.
+*** You might have to rebuild your Python installation. Refer to
+*** the documentation for details.
+</screen>
+ That means you have to rebuild (part of) your Python
+ installation to supply this shared library.
+ </para>
+
+ <para>
+ The catch is that the Python distribution or the Python
+ maintainers do not provide any direct way to do this. The
+ closest thing we can offer you is the information in <ulink
+ url="http://www.python.org/doc/FAQ.html#3.30">Python FAQ
+ 3.30</ulink>. On some operating systems you don't really have
+ to build a shared library, but then you will have to convince
+ the PostgreSQL build system of this. Consult the
+ <filename>Makefile</filename> in the
+ <filename>src/pl/plpython</filename> directory for details.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you want to build Tcl or Tk components (clients and the
+ PL/Tcl language) you of course need a Tcl installation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To build the JDBC driver, you need
+ <application>Ant</application> 1.5 or higher and a
+ <acronym>JDK</acronym>. <application>Ant</application> is a
+ special tool for building Java-based packages. It can be
+ downloaded from the <ulink
+ url="http://jakarta.apache.org/ant/index.html"><application>Ant</application>
+ web site</ulink>.
+ </para>
+
+ <para>
+ If you have several Java compilers installed, it depends on the
+ Ant configuration which one gets used. Precompiled
+ <application>Ant</application> distributions are typically set
+ up to read a file <filename>.antrc</filename> in the current
+ user's home directory for configuration. For example, to use a
+ different <acronym>JDK</acronym> than the default, this may
+ work:
+<programlisting>
+JAVA_HOME=/usr/local/sun-jdk1.3
+JAVACMD=$JAVA_HOME/bin/java
+</programlisting>
+ </para>
+
+ <note>
+ <para>
+ Do not try to build the driver by calling
+ <command>ant</command> or even <command>javac</command>
+ directly. This will not work. Run <command>gmake</command>
+ normally as described below.
+ </para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>
+ To enable Native Language Support (<acronym>NLS</acronym>), that
+ is, the ability to display a program's messages in a language
+ other than English, you need an implementation of the Gettext
+ <acronym>API</acronym>. Some operating systems have this
+ built-in (e.g., <systemitem class="osname">Linux</>, <systemitem
+ class="osname">NetBSD</>, <systemitem
+ class="osname">Solaris</>), for other systems you can download
+ an add-on package from here: <ulink
+ url="http://www.postgresql.org/~petere/gettext.html" ></ulink>.
+ If you are using the <application>gettext</> implementation in
+ the GNU C library then you will additionally need the
+ <productname>GNU Gettext</productname> package for some utility
+ programs. For any of the other implementations you will not
+ need it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Kerberos, OpenSSL, or PAM, if you want to support
+ authentication using these services.
</para>
</listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ If you are build from a CVS tree instead of using a released source
+ package, or if you want to do development, you also need the
+ following packages:
+
+ <itemizedlist>
<listitem>
<para>
<indexterm>
- <primary>installation</primary>
- <secondary>on Windows</secondary>
+ <primary>flex</primary>
+ </indexterm>
+ <indexterm>
+ <primary>bison</primary>
+ </indexterm>
+ <indexterm>
+ <primary>yacc</primary>
</indexterm>
- To build on <productname>Windows NT</> or <productname>Windows
- 2000</> you need the <productname>Cygwin</> and
- <productname>cygipc</> packages. See the file
- <filename>doc/FAQ_MSWIN</> for details.
+ <acronym>GNU</> <application>Flex</> and <application>Bison</>
+ are needed to build a CVS checkout or if you changed the actual
+ scanner and parser definition files. If you need them, be sure
+ to get <application>Flex</> 2.5.4 or later and
+ <application>Bison</> 1.28 or later. Other <application>yacc</>
+ programs can sometimes be used, but doing so requires extra
+ effort and is not recommended. Other <application>lex</>
+ programs will definitely not work.
</para>
</listitem>
</itemizedlist>
</para>
-
+
<para>
If you need to get a <acronym>GNU</acronym> package, you can find
it at your local <acronym>GNU</acronym> mirror site (see <ulink
@@ -156,12 +304,13 @@ su - postgres
<para>
Also check that you have sufficient disk space. You will need about
- 30 MB for the source tree during compilation and about 10 MB for the
- installation directory. An empty database cluster takes about 20 MB, databases
- take about five times the amount of space that a flat text file
- with the same data would take. If you are going to run the
- regression tests you will temporarily need an extra 20 MB. Use the
- <command>df</command> command to check for disk space.
+ 65 MB for the source tree during compilation and about 15 MB for
+ the installation directory. An empty database cluster takes about
+ 25 MB, databases take about five times the amount of space that a
+ flat text file with the same data would take. If you are going to
+ run the regression tests you will temporarily need up to an extra
+ 90 MB. Use the <command>df</command> command to check for disk
+ space.
</para>
</sect1>
@@ -335,8 +484,10 @@ su - postgres
</screen>
This script will run a number of tests to guess values for various
system dependent variables and detect some quirks of your
- operating system, and finally will create several files in the build
- tree to record what it found.
+ operating system, and finally will create several files in the
+ build tree to record what it found. (You can also run
+ <filename>configure</filename> in a directory outside the source
+ tree if you want to keep the build directory separate.)
</para>
<para>
@@ -480,9 +631,7 @@ su - postgres
prefix, the documentation will be installed in
<filename>/usr/local/doc/postgresql</filename>, but if the
prefix is <filename>/opt/postgres</filename>, then it will be
- in <filename>/opt/postgres/doc</filename>. Second, the
- installation layout of the C and C++ header files has been
- reorganized in the 7.2 release. The public header files of the
+ in <filename>/opt/postgres/doc</filename>. The public C header files of the
client interfaces are installed into
<varname>includedir</varname> and are namespace-clean. The
internal header files and the server header files are installed
@@ -537,27 +686,11 @@ su - postgres
<listitem>
<para>
Enables single-byte character set recode support. See
- <![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
- <![%standalone-ignore[<xref linkend="recode">]]> about this feature.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--enable-multibyte</option></term>
- <listitem>
- <para>
- Allows the use of multibyte character encodings (including Unicode)
- and character set encoding conversion. Read
- <![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
- <![%standalone-ignore[<xref linkend="multibyte">]]>
- for details.
- </para>
-
- <para>
- Note that some interfaces (such as Tcl or Java) expect all character
- strings to be in Unicode, so this option will be required to correctly
- support these interfaces.
+ <![%standalone-include[the <citetitle>Administrator's
+ Guide</citetitle>]]> <![%standalone-ignore[<xref
+ linkend="recode">]]> about this feature. Note that a more
+ general form of character set conversion is supported in the
+ default configuration; this feature is obsolete.
</para>
</listitem>
</varlistentry>
@@ -566,38 +699,22 @@ su - postgres
<term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
<listitem>
<para>
- Enables Native Language Support (<acronym>NLS</acronym>), that is, the ability
- to display a program's messages in a language other than
- English. <replaceable>LANGUAGES</replaceable> is a space
- separated list of codes of the languages that you want
- supported, for example <literal>--enable-nls='de fr'</>.
- (The intersection between your list and the set
- of actually provided translations will be computed
- automatically.) If you do not specify a list, then all available
- translations are installed.
+ Enables Native Language Support (<acronym>NLS</acronym>),
+ that is, the ability to display a program's messages in a
+ language other than English.
+ <replaceable>LANGUAGES</replaceable> is a space separated
+ list of codes of the languages that you want supported, for
+ example <literal>--enable-nls='de fr'</>. (The intersection
+ between your list and the set of actually provided
+ translations will be computed automatically.) If you do not
+ specify a list, then all available translations are
+ installed.
</para>
- <comment>
- The list of provided translations should be shown somewhere.
- </comment>
-
<para>
To use this option, you will need an implementation of the
- <application>gettext</> API. Some operating systems have this built-in
- (e.g., <systemitem class="osname">Linux</>, <systemitem class="osname">NetBSD</>, <systemitem class="osname">Solaris</>), for other systems you can download
- an add-on package from here: <ulink
- url="http://www.postgresql.org/~petere/gettext.html"
- ></ulink>. If
- you are using the <application>gettext</> implementation in the GNU C library
- then you will additionally need the <productname>GNU gettext</productname> package for
- some utility programs. For any of the other implementations
- you will not need it.
+ <application>gettext</> API; see above.
</para>
-
- <comment>
- The download location should be moved.
- </comment>
-
</listitem>
</varlistentry>
@@ -616,15 +733,6 @@ su - postgres
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--with-CXX</option></term>
- <listitem>
- <para>
- Build the C++ interface library.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--with-perl</option></term>
<listitem>
@@ -638,9 +746,9 @@ su - postgres
<term><option>--with-python</option></term>
<listitem>
<para>
- Build the Python interface module. You need to have root
- access to be able to install the Python module at its default
- place
+ Build the Python interface module and the PL/Python
+ server-side language. You need to have root access to be able
+ to install the Python module at its default place
(<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>).
To be able to use this option, you must have Python installed
and your system needs to support shared libraries. If you
@@ -691,69 +799,12 @@ su - postgres
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--enable-odbc</option></term>
- <listitem>
- <para>
- Build the ODBC driver. By default, the driver will be independent
- of a driver manager. To work better with a driver manager already
- installed on your system, use one of the following options in addition
- to this one. More information can be found in the
- <citetitle>Programmer's Guide</citetitle>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-iodbc</option></term>
- <listitem>
- <para>
- Build the ODBC driver for use with <productname>iODBC</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-unixodbc</option></term>
- <listitem>
- <para>
- Build the ODBC driver for use with <productname>unixODBC</>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-odbcinst=<replaceable>DIRECTORY</></option></term>
- <listitem>
- <para>
- Specifies the directory where the ODBC driver will expect its
- <filename>odbcinst.ini</> configuration file. The default is
- <filename>/usr/local/pgsql/etc</filename> or whatever you
- specified as <option>--sysconfdir</option>. It should be
- arranged that the driver reads the same file as the driver
- manager.
- </para>
-
- <para>
- If either the option <option>--with-iodbc</option> or the
- option <option>--with-unixodbc</option> is used, this option
- will be ignored because in that case the driver manager
- handles the location of the configuration file.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--with-java</option></term>
<listitem>
<para>
Build the <acronym>JDBC</acronym> driver and associated Java
- packages. This option requires
- <application>Ant</application> to be installed (as well as a
- <acronym>JDK</acronym>, of course). Refer to the
- <acronym>JDBC</acronym> driver documentation in the
- <citetitle>Programmer's Guide</citetitle> for more
- information.
+ packages.
</para>
</listitem>
</varlistentry>
@@ -830,19 +881,6 @@ su - postgres
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--enable-syslog</option></term>
- <listitem>
- <para>
- Enables the <productname>PostgreSQL</> server to use the
- <systemitem>syslog</> logging facility. (Using this option does not mean
- that you must log with <systemitem>syslog</> or even that it will be done
- by default, it simply makes it possible to turn that option
- on at run time.)
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--without-readline</option></term>
<listitem>
@@ -917,20 +955,26 @@ su - postgres
</varlistentry>
</variablelist>
- </para>
+ </para>
- <para>
- If you prefer a C or C++ compiler different from the one
- <filename>configure</filename> picks then you can set the
- environment variables <envar>CC</> or <envar>CXX</envar>,
- respectively, to the program of your choice. Similarly, you can
- override the default compiler flags with the <envar>CFLAGS</envar>
- and <envar>CXXFLAGS</envar> variables. For example:
+ <para>
+ If you prefer a C compiler different from the one
+ <filename>configure</filename> picks then you can set the
+ environment variable <envar>CC</> to the program of your choice.
+ By default, <filename>configure</filename> will pick
+ <filename>gcc</filename> unless this is inappropriate for the
+ platform. Similarly, you can override the default compiler flags
+ with the <envar>CFLAGS</envar> variable.
+ </para>
+
+ <para>
+ You can specify environment variables on the
+ <filename>configure</filename> command line, for example:
<screen>
-<userinput>env CC=/opt/bin/gcc CFLAGS='-O2 -pipe' ./configure</>
+<userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</>
</screen>
- </para>
- </step>
+ </para>
+ </step>
<step>
<title>Build</title>
@@ -1057,34 +1101,40 @@ All of PostgreSQL is successfully made. Ready to install.
</screen>
</para>
</formalpara>
+ </step>
+ </procedure>
+ <formalpara>
+ <title>Uninstall:</title>
<para>
To undo the installation use the command <command>gmake
uninstall</>. However, this will not remove any created directories.
</para>
- </step>
- </procedure>
+ </formalpara>
- <para>
- After the installation you can make room by removing the built
- files from the source tree with the <command>gmake clean</>
- command. This will preserve the files made by the configure
- program, so that you can rebuild everything with <command>gmake</>
- later on. To reset the source tree to the state in which it was
- distributed, use <command>gmake distclean</>. If you are going to
- build for several platforms from the same source tree you must do
- this and re-configure for each build.
- </para>
+ <formalpara>
+ <title>Cleaning:</title>
+
+ <para>
+ After the installation you can make room by removing the built
+ files from the source tree with the command <command>gmake
+ clean</>. This will preserve the files made by the configure
+ program, so that you can rebuild everything with <command>gmake</>
+ later on. To reset the source tree to the state in which it was
+ distributed, use <command>gmake distclean</>. If you are going to
+ build for several platforms from the same source tree you must do
+ this and re-configure for each build.
+ </para>
+ </formalpara>
<para>
- If you perform a build and then discover that your configure options
- were wrong, or if you change anything that configure investigates
- (for example, you install GNU <application>Readline</>), then it's
- a good idea to do <command>gmake distclean</> before reconfiguring
- and rebuilding. Without this, your changes in configuration choices
+ If you perform a build and then discover that your configure
+ options were wrong, or if you change anything that configure
+ investigates (for example, software upgrades), then it's a good
+ idea to do <command>gmake distclean</> before reconfiguring and
+ rebuilding. Without this, your changes in configuration choices
may not propagate everywhere they need to.
</para>
-
</sect1>
<sect1 id="install-post">
@@ -1139,17 +1189,13 @@ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
building.
</para>
-<!--
<para>
- On Linux systems the following is the preferred method, but you
- must have root access. Edit the file <filename>/etc/ld.so.conf</>
- to add a line
-<programlisting>
-<filename>/usr/local/pgsql/lib</>
-</programlisting>
- Then run command <command>/sbin/ldconfig</>.
+ On <systemitem class="osname">Cygwin</systemitem>, put the library
+ directory on the <envar>PATH</envar> or move the
+ <filename>.dll</filename> files into the <filename>bin/</filename>
+ directory.
</para>
--->
+
<para>
If in doubt, refer to the manual pages of your system (perhaps
<command>ld.so</command> or <command>rld</command>). If you later
@@ -1194,14 +1240,21 @@ libpq.so.2.1: cannot open shared object file: No such file or directory
<para>
If you installed into <filename>/usr/local/pgsql</> or some other
- location that is not searched for programs by default, you need to
+ location that is not searched for programs by default, you should
add <filename>/usr/local/pgsql/bin</> (or whatever you set
<option><literal>--bindir</></> to in <xref linkend="configure">)
- into your <envar>PATH</>. To do this, add the following to your
- shell start-up file, such as <filename>~/.bash_profile</> (or
- <filename>/etc/profile</>, if you want it to affect every user):
+ into your <envar>PATH</>. Strictly speaking, this is not
+ necessary, but it will make the use of PostgreSQL much more
+ convenient.
+ </para>
+
+ <para>
+ To do this, add the following to your shell start-up file, such as
+ <filename>~/.bash_profile</> (or <filename>/etc/profile</>, if you
+ want it to affect every user):
<programlisting>
PATH=/usr/local/pgsql/bin:$PATH
+export PATH
</programlisting>
If you are using <command>csh</> or <command>tcsh</>, then use this command:
<programlisting>
@@ -1216,9 +1269,11 @@ set path = ( /usr/local/pgsql/bin $path )
</indexterm>
To enable your system to find the <application>man</>
documentation, you need to add a line like the following to a
- shell start-up file:
+ shell start-up file unless you installed into a location that is
+ searched by default.
<programlisting>
MANPATH=/usr/local/pgsql/man:$MANPATH
+export MANPATH
</programlisting>
</para>
diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml
index c77817d16a4..69220dd59c9 100644
--- a/doc/src/sgml/jdbc.sgml
+++ b/doc/src/sgml/jdbc.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.36 2002/03/22 19:20:11 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.37 2002/09/18 20:09:31 petere Exp $
-->
<chapter id="jdbc">
@@ -51,92 +51,34 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.36 2002/03/22 19:20:11
</para>
<para>
- Alternatively you can build the driver from source. Although you
- should only need to do this if you are making changes to the source
- code.
+ Alternatively you can build the driver from source, but you
+ should only need to do this if you are making changes to the
+ source code. For details, refer to the PostgreSQL installation
+ instructions. After installation, the driver should be found in
+ <filename><replaceable>PREFIX</>/share/java/postgresql.jar</filename>.
+ The resulting driver will be built for the version of Java you are
+ running. If you build with a 1.1 JDK you will build a version
+ that supports the JDBC 1 specification, if you build with a Java 2
+ JDK (e.g., JDK 1.2 or JDK 1.3) you will build a version that
+ supports the JDBC 2 specification.
</para>
-
- <para>
- Starting with <productname>PostgreSQL</productname> version 7.1,
- the <acronym>JDBC</acronym> driver is built using
- <application>Ant</application>, a special tool for building
- Java-based packages. You should download
- <application>Ant</application> from the <ulink
- url="http://jakarta.apache.org/ant/index.html"><application>Ant</application>
- web site</ulink> and install it before proceeding. Precompiled
- <application>Ant</application> distributions are typically set up
- to read a file <filename>.antrc</filename> in the current user's
- home directory for configuration. For example, to use a different
- <acronym>JDK</acronym> than the default, this may work:
-<programlisting>
-JAVA_HOME=/usr/local/sun-jdk1.3
-JAVACMD=$JAVA_HOME/bin/java
-</programlisting>
- </para>
-
- <para>
- To build the driver, add the <option>--with-java</option> option to your
- <filename>configure</filename> command line, e.g.,
-<screen>
-<prompt>$</prompt> <userinput>./configure --prefix=<replaceable>xxx</replaceable> --with-java ...</userinput>
-</screen>
- This will build and install the driver along with the rest of the
- <productname>PostgreSQL</productname> package when you issue the
- <literal>make/gmake</literal> and <literal>make/gmake install</literal>
- commands. If you only want to build the driver and not the rest
- of <productname>PostgreSQL</productname>, change into the
- directory <filename
- class="directory">src/interfaces/jdbc</filename> and issue the
- respective <literal>make/gmake</literal> command there. Refer to the
- <productname>PostgreSQL</productname> installation instructions
- for more information about the configuration and build process.
- </para>
-
- <para>When building the driver from source the jar file that is created
- will be named <filename>postgresql.jar</filename>. The build will
- create this file in the <filename>src/interfaces/jdbc/jars</filename>
- directory. The resulting driver will be built for the version of
- Java you are running. If you build with a 1.1 JDK you will build
- a version that supports the jdbc1 specification, if you build with a
- Java2 JDK (i.e. JDK1.2 or JDK1.3) you will build a version that
- supports the jdbc2 specification.
- </para>
-
- <note>
- <para>
- Do not try to build the driver by calling <command>javac</command>
- directly, as the driver uses some dynamic loading techniques for
- performance reasons, and <command>javac</command> cannot cope.
- Do not try to run <command>ant</command> directly either, because
- some configuration information is communicated through the
- makefiles. Running <command>ant</command> directly without
- providing these parameters will result in a broken driver.
- </para>
- </note>
</sect2>
<sect2 id="jdbc-classpath">
<title>Setting up the Class Path</title>
<para>
- To use the driver, the jar archive (named
+ To use the driver, the JAR archive (named
<filename>postgresql.jar</filename> if you built from source, otherwise
it will likely be named <filename>jdbc7.2-1.1.jar</filename> or
- <filename>jdbc7.2-1.2.jar</filename> for the jdbc1 and jdbc2 versions
+ <filename>jdbc7.2-1.2.jar</filename> for the JDBC 1 and JDBC 2 versions
respectively)
needs to be included in the
class path, either by putting it in the <envar>CLASSPATH</envar>
environment variable, or by using flags on the
- <command>java</command> command line. By default, the jar archive
- is installed in the directory <filename
- class="directory">/usr/local/pgsql/share/java</filename>. You may
- have it in a different directory if you used the
- <option>--prefix</option> option when you ran
- <filename>configure</filename>, or if you are using a binary distribution
- that places it in some different location.
+ <command>java</command> command line.
</para>
- <informalexample>
<para>
For instance, I have an application that uses the
<acronym>JDBC</acronym> driver to access a large database
@@ -163,7 +105,6 @@ java Finder
Loading the driver from within the application is covered in
<xref linkend="jdbc-use">.
</para>
- </informalexample>
</sect2>
<sect2 id="jdbc-prepare">
@@ -183,7 +124,7 @@ java Finder
Also, the client authentication setup in the
<filename>pg_hba.conf</filename> file may need to be configured.
Refer to the <citetitle>Administrator's Guide</citetitle> for
- details. The <acronym>JDBC</acronym> Driver supports trust,
+ details. The <acronym>JDBC</acronym> Driver supports the trust,
ident, password, md5, and crypt authentication methods.
</para>
</sect2>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 9793cd93503..939eba14237 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.17 2002/06/23 03:51:55 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.18 2002/09/18 20:09:32 petere Exp $
-->
<chapter id="maintenance">
@@ -424,14 +424,13 @@ VACUUM
<para>
The simplest production-grade approach to managing log output is to
- send it all to <application>syslog</> and let <application>syslog</>
- deal with file rotation. To do this, make sure
- <productname>PostgreSQL</> was built with the
- <option>--enable-syslog</> configure option, and set
+ send it all to <application>syslog</> and let
+ <application>syslog</> deal with file rotation. To do this, set
<literal>syslog</> to 2 (log to syslog only) in
<filename>postgresql.conf</>. Then you can send a
- <literal>SIGHUP</literal> signal to the <application>syslog</> daemon
- whenever you want to force it to start writing a new log file.
+ <literal>SIGHUP</literal> signal to the <application>syslog</>
+ daemon whenever you want to force it to start writing a new log
+ file.
</para>
<para>
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 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.16 2002/03/06 19:05:57 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.17 2002/09/18 20:09:32 petere Exp $
-->
<chapter id="plperl">
@@ -14,154 +14,75 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.16 2002/03/06 19:05:57 momj
</indexterm>
<para>
- PL/Perl is a loadable procedural language
- that enables the <ulink url="http://www.perl.com">Perl</ulink> programming
- language to be used to write
- <productname>PostgreSQL</productname> functions.
- </para>
-
- <!-- **** PL/Perl overview **** -->
-
- <sect1 id="plperl-overview">
- <title>Overview</title>
-
- <para>
- Normally, PL/Perl is installed as a <quote>trusted</> programming
- language named <literal>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, <literal>require</literal>, and
- <literal>use</literal> (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
- <productname>PostgreSQL</productname> user ID, as a C function can do.
- Thus, any unprivileged database user may be
- permitted to use this language.
- </para>
- <para>
- 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
- <quote>untrusted</> language (usually named <literal>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.
- </para>
- </sect1>
-
- <sect1 id="plperl-install">
- <title>Building and Installing PL/Perl</title>
-
- <para>
- If the <option>--with-perl</option> option was supplied to the
- <indexterm><primary><filename>configure</filename></primary></indexterm>
- <filename>configure</filename> script,
- the <productname>PostgreSQL</productname> build process will attempt to
- build the PL/Perl shared library and install it in the
- <productname>PostgreSQL</productname> library directory.
+ PL/Perl is a loadable procedural language that enables you to write
+ <productname>PostgreSQL</productname> functions in the <ulink
+ url="http://www.perl.com">Perl</ulink> programming language.
</para>
<para>
- On most platforms, since PL/Perl is a shared library, the
- <indexterm><primary>libperl</primary></indexterm>
- <filename>libperl</filename> 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:
-<screen>
-<computeroutput>
-*** 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.
-</computeroutput>
-</screen>
- If you see this, you will have to re-build and install
- <productname>Perl</productname> manually to be able to build
- PL/Perl. During the configuration process for
- <productname>Perl</productname>, request a shared library.
+ To install PL/Perl in a particular database, use
+ <literal>createlang plperl <replaceable>dbname</></literal>.
</para>
- <para>
- After having reinstalled Perl, change to the directory
- <filename>src/pl/plperl</filename> in the
- <productname>PostgreSQL</productname> source tree and issue the commands
-<programlisting>
-gmake clean
-gmake all
-gmake install
-</programlisting>
- to complete the build and installation of the PL/Perl shared library.
- </para>
-
- <para>
- To install
- PL/Perl and/or PL/PerlU in a particular database, use the
- <filename>createlang</filename> script, for example
- <literal>createlang plperl <replaceable>dbname</></literal> or
- <literal>createlang plperlu <replaceable>dbname</></literal>.
- </para>
-
<tip>
<para>
If a language is installed into <literal>template1</>, all subsequently
created databases will have the language installed automatically.
</para>
</tip>
- </sect1>
-
- <!-- **** PL/Perl description **** -->
- <sect1 id="plperl-description">
- <title>Description</title>
-
- <sect2>
- <title>PL/Perl Functions and Arguments</title>
+ <note>
+ <para>
+ 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.
+ </para>
+ </note>
- <para>
- To create a function in the PL/Perl language, use the standard syntax
+ <sect1 id="plperl-funcs">
+ <title>PL/Perl Functions and Arguments</title>
- <programlisting>
+ <para>
+ To create a function in the PL/Perl language, use the standard syntax:
+<programlisting>
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS '
# PL/Perl function body
' LANGUAGE plperl;
- </programlisting>
-
- PL/PerlU is the same, except that the language should be specified as
- <literal>plperlu</>.
- </para>
+</programlisting>
+ The body of the function is ordinary Perl code.
+ </para>
- <para>
- The body of the function is ordinary Perl code. Arguments and
- results are handled as in any other Perl subroutine: arguments
- are passed in <varname>@_</varname>, and a result value is returned
- with <literal>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:
+ <para>
+ Arguments and results are handled as in any other Perl subroutine:
+ Arguments are passed in <varname>@_</varname>, and a result value
+ is returned with <literal>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:
- <programlisting>
+<programlisting>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
if ($_[0] > $_[1]) { return $_[0]; }
return $_[1];
' LANGUAGE plperl;
- </programlisting>
-
- If a NULL is passed to a function, the argument value will appear
- as <quote>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 <literal>WITH (isStrict)</>
- to the function definition to make <productname>PostgreSQL</productname>
- 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:
-
- <programlisting>
+</programlisting>
+ </para>
+
+ <para>
+ If an SQL null value is passed to a function, the argument value
+ will appear as <quote>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
+ <literal>STRICT</> to the function definition to make
+ <productname>PostgreSQL</productname> 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 <function>perl_max</function> with
+ one null and one non-null argument to return the non-null argument,
+ rather than a null value:
+
+<programlisting>
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;
- </programlisting>
- </para>
+</programlisting>
+ </para>
- <para>
- 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.
- </para>
+ <para>
+ 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.
+ </para>
- <para>
- 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:
+ <para>
+ 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:
- <programlisting>
+<programlisting>
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;
- </programlisting>
- </para>
+</programlisting>
+ </para>
- <para>
- There is not currently any support for returning a composite-type
- result value.
- </para>
+ <para>
+ There is currently no support for returning a composite-type result
+ value.
+ </para>
<tip>
<para>
Because the function body is passed as an SQL string literal to
<command>CREATE FUNCTION</command>, 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
- (<literal>q[]</literal>, <literal>qq[]</literal>,
- <literal>qw[]</literal>).
+ 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 (<literal>q[]</literal>,
+ <literal>qq[]</literal>, <literal>qw[]</literal>).
</para>
</tip>
+ </sect1>
+
+ <sect1 id="plperl-data">
+ <title>Data Values in PL/Perl</title>
+
+ <para>
+ 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 <literal>SELECT</literal> statement).
+ Conversely, the <literal>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.
+ </para>
+ </sect1>
+
+ <sect1 id="plperl-database">
+ <title>Database Access from PL/Perl</title>
+
+ <para>
+ Access to the database itself from your Perl function can be done via
+ an experimental module <ulink
+ url="http://www.cpan.org/modules/by-module/DBD/APILOS/"><literal>DBD::PgSPI</literal></ulink>
+ (also available at <ulink url="http://www.cpan.org/SITES.html">CPAN
+ mirror sites</ulink>). This module makes available a
+ <acronym>DBI</>-compliant database-handle named
+ <varname>$pg_dbh</varname> that can be used to perform queries
+ with normal <acronym>DBI</> syntax.
+ </para>
+
+ <para>
+ PL/Perl itself presently provides only one additional Perl command:
+
+ <variablelist>
+ <varlistentry>
+ <indexterm>
+ <primary>elog</primary>
+ <secondary>PL/Perl</secondary>
+ </indexterm>
+
+ <term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
+ <listitem>
+ <para>
+ Emit a log or error message. Possible levels are
+ <literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
+ <literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
+ <literal>ERROR</> raises an error condition: further execution
+ of the function is abandoned, and the current transaction is
+ aborted.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect1>
+
+ <sect1 id="plperl-trusted">
+ <title>Trusted and Untrusted PL/Perl</title>
+
+ <para>
+ Normally, PL/Perl is installed as a <quote>trusted</> programming
+ language named <literal>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,
+ <literal>require</literal>, and <literal>use</literal> (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 <productname>PostgreSQL</productname> user ID,
+ as a C function can do. Thus, any unprivileged database user may
+ be permitted to use this language.
+ </para>
<para>
Here is an example of a function that will not work because file
@@ -231,89 +224,66 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
</programlisting>
The creation of the function will succeed, but executing it will not.
</para>
+
<para>
- Note that if the same function was created by a superuser using language
- <literal>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 <quote>untrusted</> language (usually called
+ <quote>PL/PerlU</quote>). In this case the full Perl language is
+ available. If the <command>createlang</command> program is used to
+ install the language, the language name <literal>plperlu</literal>
+ will select the untrusted PL/Perl variant.
</para>
- </sect2>
-
- <sect2>
- <title>Data Values in PL/Perl</title>
-
- <para>
- 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 <literal>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.
- </para>
+ <para>
+ 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.
+ </para>
- </sect2>
+ <para>
+ If the above function was created by a superuser using the language
+ <literal>plperlu</>, execution would succeed.
+ </para>
+ </sect1>
- <sect2>
- <title>Database Access from PL/Perl</title>
+ <sect1 id="plperl-missing">
+ <title>Missing Features</title>
<para>
- Access to the database itself from your Perl function can be done via
- an experimental module <ulink
- url="http://www.cpan.org/modules/by-module/DBD/APILOS/"><literal>DBD::PgSPI</literal></ulink>
- (also available at <ulink url="http://www.cpan.org/SITES.html">CPAN
- mirror sites</ulink>). This module makes available a
- <acronym>DBI</>-compliant database-handle named
- <varname>$pg_dbh</varname> that can be used to perform queries
- with normal <acronym>DBI</> syntax.
+ The following features are currently missing from PL/Perl, but they
+ would make welcome contributions:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ PL/Perl cannot be used to write trigger functions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <application>DBD::PgSPI</applicatioN> or similar capability
+ should be integrated into the standard
+ <productname>PostgreSQL</productname> distribution.
+ </para>
+ </listitem>
+ </itemizedlist>
</para>
+ </sect1>
- <para>
- PL/Perl itself presently provides only one additional Perl command:
- </para>
-
- <variablelist>
- <varlistentry>
- <indexterm>
- <primary>elog</primary>
- </indexterm>
- <term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
- <listitem>
- <para>
- Emit a log or error message. Possible levels are
- <literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
- <literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
- <literal>ERROR</> raises an error condition: further execution
- of the function is abandoned, and the current transaction is
- aborted.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect2>
-
- <sect2>
- <title>Missing Features</title>
-
- <para>
- 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.
- </para>
-
- <para>
- PL/Perl cannot currently be used to write trigger functions.
- </para>
-
- <para>
- DBD::PgSPI or similar capability should be integrated
- into the standard <productname>PostgreSQL</productname> distribution.
- </para>
-
- </sect2>
-
- </sect1>
- </chapter>
+</chapter>
<!-- Keep this comment at the end of the file
Local variables:
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 2e38a5c7917..110c2a826e5 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.10 2002/03/22 19:20:18 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.11 2002/09/18 20:09:32 petere Exp $ -->
<chapter id="plpython">
<title>PL/Python - Python Procedural Language</title>
@@ -6,90 +6,42 @@
<indexterm zone="plpython"><primary>PL/Python</></>
<indexterm zone="plpython"><primary>Python</></>
- <sect1 id="plpython-intro">
- <title>Introduction</title>
+ <para>
+ The <application>PL/Python</application> procedural language allows
+ <productname>PostgreSQL</productname> functions to be written in the
+ <ulink url="http://www.python.org">Python</ulink> language.
+ </para>
- <para>
- The <application>PL/Python</application> procedural language allows
- <productname>PostgreSQL</productname> functions to be written in
- the <ulink url="http://www.python.org">Python</ulink> language.
- </para>
+ <para>
+ To install PL/Python in a particular database, use
+ <literal>createlang plpython <replaceable>dbname</></literal>.
+ </para>
+ <note>
<para>
- The current version of <application>PL/Python</application>
- functions as a trusted language only; access to the file system and
- other local resources is disabled. Specifically,
- <application>PL/Python</application> uses the Python restricted
- execution environment, further restricts it to prevent the use of
- the file <function>open</> call, and allows only modules from a
- specific list to be imported. Presently, that list includes:
- array, bisect, binascii, calendar, cmath, codecs, errno, marshal,
- math, md5, mpz, operator, pcre, pickle, random, re, regex, sre,
- sha, string, StringIO, struct, time, whrandom, and zlib.
+ Users of source packages must specially enable the build of
+ PL/Python during the installation process (refer to the
+ installation instructions for more information). Users of binary
+ packages might find PL/Python in a separate subpackage.
</para>
+ </note>
- <para>
- In the current version, any database error encountered while
- running a <application>PL/Python</application> function will result
- in the immediate termination of that function by the server. It is
- not possible to trap error conditions using Python <literal>try
- ... catch</literal> constructs. For example, a syntax error in an
- SQL statement passed to the <literal>plpy.execute()</literal> call
- will terminate the function. This behavior may be changed in a
- future release.
- </para>
- </sect1>
-
- <sect1 id="plpython-install">
- <title>Installation</title>
-
- <para>
- To build PL/Python, the <option>--with-python</option> option needs
- to be specified when running <filename>configure</filename>. If
- after building and installing you have a file called
- <filename>plpython.so</filename> (possibly a different extension),
- then everything went well. Otherwise you should have seen a notice
- like this flying by:
-<screen>
-*** Cannot build PL/Python because libpython is not a shared library.
-*** You might have to rebuild your Python installation. Refer to
-*** the documentation for details.
-</screen>
- That means you have to rebuild (part of) your Python installation
- to supply this shared library.
- </para>
-
- <para>
- The catch is that the Python distribution or the Python maintainers
- do not provide any direct way to do this. The closest thing we can
- offer you is the information in <ulink
- url="http://www.python.org/doc/FAQ.html#3.30">Python FAQ
- 3.30</ulink>. On some operating systems you don't really have to
- build a shared library, but then you will have to convince the
- PostgreSQL build system of this. Consult the
- <filename>Makefile</filename> in the
- <filename>src/pl/plpython</filename> directory for details.
- </para>
- </sect1>
-
- <sect1 id="plpython-using">
- <title>Using PL/Python</title>
+ <sect1 id="plpython-funcs">
+ <title>PL/Python Functions</title>
<para>
- There are sample functions in
- <filename>plpython_function.sql</filename>. The Python code you
- write gets transformed into a function. E.g.,
+ The Python code you write gets transformed into a function. E.g.,
<programlisting>
-CREATE FUNCTION myfunc(text) RETURNS text AS
-'return args[0]'
-LANGUAGE 'plpython';
+CREATE FUNCTION myfunc(text) RETURNS text
+ AS 'return args[0]'
+ LANGUAGE 'plpython';
</programlisting>
gets transformed into
<programlisting>
def __plpython_procedure_myfunc_23456():
- return args[0]
+ return args[0]
</programlisting>
where 23456 is the OID of the function.
@@ -98,51 +50,68 @@ def __plpython_procedure_myfunc_23456():
<para>
If you do not provide a return value, Python returns the default
<symbol>None</symbol> which may or may not be what you want. The
- language module translates Python's None into SQL NULL.
+ language module translates Python's <symbol>None</symbol> into the
+ SQL null value.
</para>
<para>
- <productname>PostgreSQL</> function variables are available in the global
- <varname>args</varname> list. In the <function>myfunc</function>
- example, <varname>args[0]</> contains whatever was passed in as the text
- argument. For <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
- would contain the <type>text</type> variable and <varname>args[1]</varname> the <type>integer</type> variable.
+ The <productname>PostgreSQL</> function parameters are available in
+ the global <varname>args</varname> list. In the
+ <function>myfunc</function> example, <varname>args[0]</> contains
+ whatever was passed in as the text argument. For
+ <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
+ would contain the <type>text</type> variable and
+ <varname>args[1]</varname> the <type>integer</type> variable.
</para>
<para>
- The global dictionary SD is available to store data between
- function calls. This variable is private static data. The global
- dictionary GD is public data, available to all python functions
- within a backend. Use with care.
+ The global dictionary <varname>SD</varname> is available to store
+ data between function calls. This variable is private static data.
+ The global dictionary <varname>GD</varname> is public data,
+ available to all Python functions within a session. Use with care.
</para>
<para>
Each function gets its own restricted execution object in the
Python interpreter, so that global data and function arguments from
<function>myfunc</function> are not available to
- <function>myfunc2</function>. The exception is the data in the GD
- dictionary, as mentioned above.
+ <function>myfunc2</function>. The exception is the data in the
+ <varname>GD</varname> dictionary, as mentioned above.
</para>
+ </sect1>
+
+ <sect1 id="plpython-trigger">
+ <title>Trigger Functions</title>
<para>
- When a function is used in a trigger, the dictionary TD contains
- transaction related values. The trigger tuples are in <literal>TD["new"]</>
- and/or <literal>TD["old"]</> depending on the trigger event. <literal>TD["event"]</>
- contains the event as a string (<literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>, or
- <literal>UNKNOWN</>). TD["when"] contains one of (<literal>BEFORE</>, <literal>AFTER</>, or
- <literal>UNKNOWN</>). <literal>TD["level"]</> contains one of <literal>ROW</>, <literal>STATEMENT</>, or
- <literal>UNKNOWN</>. <literal>TD["name"]</> contains the trigger name, and <literal>TD["relid"]</>
- contains the relation id of the table on which the trigger occurred.
- If the trigger was called with arguments they are available
- in <literal>TD["args"][0]</> to <literal>TD["args"][(n -1)]</>.
+ When a function is used in a trigger, the dictionary
+ <literal>TD</literal> contains trigger-related values. The trigger
+ rows are in <literal>TD["new"]</> and/or <literal>TD["old"]</>
+ depending on the trigger event. <literal>TD["event"]</> contains
+ the event as a string (<literal>INSERT</>, <literal>UPDATE</>,
+ <literal>DELETE</>, or <literal>UNKNOWN</>).
+ <literal>TD["when"]</> contains one of <literal>BEFORE</>,
+ <literal>AFTER</>, and <literal>UNKNOWN</>.
+ <literal>TD["level"]</> contains one of <literal>ROW</>,
+ <literal>STATEMENT</>, and <literal>UNKNOWN</>.
+ <literal>TD["name"]</> contains the trigger name, and
+ <literal>TD["relid"]</> contains the relation ID of the table on
+ which the trigger occurred. If the trigger was called with
+ arguments they are available in <literal>TD["args"][0]</> to
+ <literal>TD["args"][(n-1)]</>.
</para>
<para>
- If the trigger <quote>when</quote> is <literal>BEFORE</>, you may return <literal>None</literal> or <literal>"OK"</literal>
- from the Python function to indicate the tuple is unmodified,
- <literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to indicate you've
- modified the tuple.
+ If the <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
+ return <literal>None</literal> or <literal>"OK"</literal> from the
+ Python function to indicate the row is unmodified,
+ <literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to
+ indicate you've modified the row.
</para>
+ </sect1>
+
+ <sect1 id="plpython-database">
+ <title>Database Access</title>
<para>
The PL/Python language module automatically imports a Python module
@@ -150,54 +119,64 @@ def __plpython_procedure_myfunc_23456():
this module are available to you in the Python code as
<literal>plpy.<replaceable>foo</replaceable></literal>. At present
<literal>plpy</literal> implements the functions
- <literal>plpy.debug("msg")</literal>,
+ <literal>plpy.debug("msg")</literal>,
<literal>plpy.log("msg")</literal>,
<literal>plpy.info("msg")</literal>,
<literal>plpy.notice("msg")</literal>,
<literal>plpy.warning("msg")</literal>,
<literal>plpy.error("msg")</literal>, and
<literal>plpy.fatal("msg")</literal>. They are mostly equivalent
- to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>.
- <function>plpy.error</function> and <function>plpy.fatal</function>
- actually raise a Python exception which, if uncaught, causes the
- PL/Python module to call <literal>elog(ERROR, msg)</literal> when
- the function handler returns from the Python interpreter. Long
- jumping out of the Python interpreter is probably not good.
- <literal>raise plpy.ERROR("msg")</literal> and <literal>raise
+ to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>
+ from C code. <function>plpy.error</function> and
+ <function>plpy.fatal</function> actually raise a Python exception
+ which, if uncaught, causes the PL/Python module to call
+ <literal>elog(ERROR, msg)</literal> when the function handler
+ returns from the Python interpreter. Long-jumping out of the
+ Python interpreter is probably not good. <literal>raise
+ plpy.ERROR("msg")</literal> and <literal>raise
plpy.FATAL("msg")</literal> are equivalent to calling
- <function>plpy.error</function> or <function>plpy.fatal</function>.
+ <function>plpy.error</function> and
+ <function>plpy.fatal</function>, respectively.
</para>
<para>
- Additionally, the <literal>plpy</literal> module provides two functions called
- <function>execute</function> and <function>prepare</function>.
- Calling <function>plpy.execute</function> with a query string, and
- an optional limit argument, causes that query to be run, and the
- result returned in a result object. The result object emulates a
+ Additionally, the <literal>plpy</literal> module provides two
+ functions called <function>execute</function> and
+ <function>prepare</function>. Calling
+ <function>plpy.execute</function> with a query string and an
+ optional limit argument causes that query to be run and the result
+ to be returned in a result object. The result object emulates a
list or dictionary object. The result object can be accessed by
- row number, and field name. It has these additional methods:
+ row number and field name. It has these additional methods:
<function>nrows()</function> which returns the number of rows
returned by the query, and <function>status</function> which is the
<function>SPI_exec</function> return variable. The result object
can be modified.
+ </para>
+ <para>
+ For example,
<programlisting>
rv = plpy.execute("SELECT * FROM my_table", 5)
</programlisting>
- returns up to 5 rows from my_table. Ff my_table has a column
- my_field it would be accessed as
+ returns up to 5 rows from <literal>my_table</literal>. If
+ <literal>my_table</literal> has a column
+ <literal>my_field</literal>, it would be accessed as
<programlisting>
foo = rv[i]["my_field"]
</programlisting>
+ </para>
+
+ <para>
The second function <function>plpy.prepare</function> is called
- with a query string, and a list of argument types if you have bind
- variables in the query.
+ with a query string and a list of argument types if you have bind
+ variables in the query. For example:
<programlisting>
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
</programlisting>
- text is the type of the variable you will be passing as $1. After
- preparing you use the function <function>plpy.execute</function> to
- run it.
+ <literal>text</literal> is the type of the variable you will be
+ passing as <literal>$1</literal>. After preparing a statement, you
+ use the function <function>plpy.execute</function> to run it:
<programlisting>
rv = plpy.execute(plan, [ "name" ], 5)
</programlisting>
@@ -205,6 +184,17 @@ rv = plpy.execute(plan, [ "name" ], 5)
<function>plpy.execute</function>.
</para>
+ <para>
+ In the current version, any database error encountered while
+ running a <application>PL/Python</application> function will result
+ in the immediate termination of that function by the server; it is
+ not possible to trap error conditions using Python <literal>try
+ ... catch</literal> constructs. For example, a syntax error in an
+ SQL statement passed to the <literal>plpy.execute()</literal> call
+ will terminate the function. This behavior may be changed in a
+ future release.
+ </para>
+
<para>
When you prepare a plan using the PL/Python module it is
automatically saved. Read the SPI documentation (<xref
@@ -220,4 +210,21 @@ plan = plpy.prepare("SOME OTHER QUERY")
</para>
</sect1>
+ <sect1 id="plpython-trusted">
+ <title>Restricted Environment</title>
+
+ <para>
+ The current version of <application>PL/Python</application>
+ functions as a trusted language only; access to the file system and
+ other local resources is disabled. Specifically,
+ <application>PL/Python</application> uses the Python restricted
+ execution environment, further restricts it to prevent the use of
+ the file <function>open</> call, and allows only modules from a
+ specific list to be imported. Presently, that list includes:
+ array, bisect, binascii, calendar, cmath, codecs, errno, marshal,
+ math, md5, mpz, operator, pcre, pickle, random, re, regex, sre,
+ sha, string, StringIO, struct, time, whrandom, and zlib.
+ </para>
+ </sect1>
+
</chapter>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 3bded5cf93b..c4a605683b9 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.74 2002/08/27 20:16:48 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.75 2002/09/18 20:09:32 petere Exp $
PostgreSQL documentation
-->
@@ -2274,33 +2274,6 @@ $endif
<application>readline</application> feature. Read its documentation
for further details.)
</para>
-
- <para>
- If you have the readline library installed but
- <application>psql</application> does not seem to use it, you must
- make sure that <productname>PostgreSQL</productname>'s top-level
- <filename>configure</filename> script finds it.
- <filename>configure</filename> needs to find both the library
- <filename>libreadline.a</filename> (or a shared library equivalent)
- <emphasis>and</emphasis> the header files
- <filename>readline.h</filename> and <filename>history.h</filename>
- (or <filename>readline/readline.h</filename> and
- <filename>readline/history.h</filename>) in appropriate directories.
- If you have the library and header files installed in an obscure
- place you must tell <filename>configure</filename> about them, for
- example:
-<programlisting>
-$ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib ...
-</programlisting>
- Then you have to recompile <application>psql</application> (not
- necessarily the entire code tree).
- </para>
-
- <para>
- The <acronym>GNU</acronym> readline library can be obtained from the
- <acronym>GNU</acronym> project's <acronym>FTP</acronym> server at
- <ulink URL="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
- </para>
</refsect3>
</refsect2>
</refsect1>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index b993323db61..3ae2750fd0c 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.136 2002/09/17 21:41:47 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.137 2002/09/18 20:09:32 petere Exp $
-->
<Chapter Id="runtime">
@@ -973,8 +973,8 @@ env PGOPTIONS='-c geqo=off' psql
to turn this on, as it might expose programming mistakes. To use
this option, the macro <literal>USE_ASSERT_CHECKING</literal>
must be defined when <productname>PostgreSQL</productname> is
- built (see the configure option
- <literal>--enable-cassert</literal>). Note that
+ built (accomplished by the configure option
+ <option>--enable-cassert</option>). Note that
<literal>DEBUG_ASSERTIONS</literal> defaults to on if
<productname>PostgreSQL</productname> has been built with
assertions enabled.
@@ -1176,11 +1176,6 @@ env PGOPTIONS='-c geqo=off' psql
<systemitem>syslog</> is off. This option must be set at server
start.
</para>
- <para>
- To use <systemitem>syslog</>, the build of
- <productname>PostgreSQL</productname> must be configured with
- the <option>--enable-syslog</option> option.
- </para>
</listitem>
</varlistentry>
--
GitLab