database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-22 23:02:54 +03:00
Code

Update installation instructions and put mostly everything in one place.

Browse Source 
Also, some editing in PL/Perl and PL/Python chapters.
This commit is contained in:
Peter Eisentraut 2002-09-18 20:09:32 +00:00
parent 0db8c41523
commit da123b7c58
9 changed files with 623 additions and 708 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/src/sgml/charset.sgml
View File

@ -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>

9
doc/src/sgml/client-auth.sgml
View File

@ -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>

487
doc/src/sgml/installation.sgml
View File

@ -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>
@ -103,33 +105,6 @@ su - postgres
</para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>flex</primary>
</indexterm>
<indexterm>
<primary>bison</primary>
</indexterm>
<indexterm>
<primary>yacc</primary>
</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.
</para>
</listitem>
<listitem>
<para>
<indexterm>
@ -145,7 +120,180 @@ su - postgres
</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>flex</primary>
</indexterm>
<indexterm>
<primary>bison</primary>
</indexterm>
<indexterm>
<primary>yacc</primary>
</indexterm>
<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>
<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>
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>
<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>

89
doc/src/sgml/jdbc.sgml
View File

@ -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>

13
doc/src/sgml/maintenance.sgml
View File

@ -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>

414
doc/src/sgml/plperl.sgml
View File

@ -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 **** -->
<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>
<sect1 id="plperl-description">
<title>Description</title>
<sect1 id="plperl-funcs">
<title>PL/Perl Functions and Arguments</title>
<sect2>
<title>PL/Perl Functions and Arguments</title>
<para>
To create a function in the PL/Perl language, use the standard syntax
<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>
</programlisting>
The body of the function is ordinary Perl code.
</para>
PL/PerlU is the same, except that the language should be specified as
<literal>plperlu</>.
</para>
<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:
<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:
<programlisting>
<programlisting>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
if ($_[0] > $_[1]) { return $_[0]; }
return $_[1];
' LANGUAGE plperl;
</programlisting>
</programlisting>
</para>
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:
<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>
<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
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>
<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>
<para>
If the above function was created by a superuser using the language
<literal>plperlu</>, execution would succeed.
</para>
</sect1>
</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>
</sect2>
<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:

253
doc/src/sgml/plpython.sgml
View File

@ -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>
To install PL/Python in a particular database, use
<literal>createlang plpython <replaceable>dbname</></literal>.
</para>
<note>
<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.
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>
<sect1 id="plpython-funcs">
<title>PL/Python Functions</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>
<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>
<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
<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>
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)]</>.
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>
<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.
</para>
<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>

29
doc/src/sgml/ref/psql-ref.sgml
View File

@ -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>

11
doc/src/sgml/runtime.sgml
View File

@ -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>