sharpetronics/PostgreSQL
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-24 00:03:23 -04:00
Code Issues Projects Releases Wiki Activity

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"> <chapter id="charset">
<title>Localization</> <title>Localization</>
@ -889,30 +889,6 @@ RESET CLIENT_ENCODING;
</para> </para>
</sect2> </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> <sect2>
<title>What happens if the translation is not possible?</title> <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"> <chapter id="client-authentication">
@ -583,10 +583,9 @@ local db1,db2,@demodbs all md5
<para> <para>
In order to use <productname>Kerberos</>, support for it must be In order to use <productname>Kerberos</>, support for it must be
enabled at build time. Both Kerberos 4 and 5 are supported enabled at build time. See <xref linkend="installation"> for more
(<literal>./configure --with-krb4</> or <literal>./configure information. Both Kerberos 4 and 5 are supported, but only one
--with-krb5</> respectively), although only one version can be version can be supported in any one build.
supported in any one build.
</para> </para>
<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"> <chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]> <title><![%standalone-include[<productname>PostgreSQL</>]]>
@ -47,7 +47,9 @@ su - postgres
</para> </para>
<para> <para>
The following prerequisites exist for building <productname>PostgreSQL</>: The following software packages are required for building
<productname>PostgreSQL</>:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
@ -103,33 +105,6 @@ su - postgres
</para> </para>
</listitem> </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> <listitem>
<para> <para>
<indexterm> <indexterm>
@ -145,7 +120,180 @@ su - postgres
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </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> <para>
If you need to get a <acronym>GNU</acronym> package, you can find If you need to get a <acronym>GNU</acronym> package, you can find
it at your local <acronym>GNU</acronym> mirror site (see <ulink it at your local <acronym>GNU</acronym> mirror site (see <ulink
@ -156,12 +304,13 @@ su - postgres
<para> <para>
Also check that you have sufficient disk space. You will need about 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 65 MB for the source tree during compilation and about 15 MB for
installation directory. An empty database cluster takes about 20 MB, databases the installation directory. An empty database cluster takes about
take about five times the amount of space that a flat text file 25 MB, databases take about five times the amount of space that a
with the same data would take. If you are going to run the flat text file with the same data would take. If you are going to
regression tests you will temporarily need an extra 20 MB. Use the run the regression tests you will temporarily need up to an extra
<command>df</command> command to check for disk space. 90 MB. Use the <command>df</command> command to check for disk
space.
</para> </para>
</sect1> </sect1>
@ -335,8 +484,10 @@ su - postgres
</screen> </screen>
This script will run a number of tests to guess values for various This script will run a number of tests to guess values for various
system dependent variables and detect some quirks of your system dependent variables and detect some quirks of your
operating system, and finally will create several files in the build operating system, and finally will create several files in the
tree to record what it found. 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>
<para> <para>
@ -480,9 +631,7 @@ su - postgres
prefix, the documentation will be installed in prefix, the documentation will be installed in
<filename>/usr/local/doc/postgresql</filename>, but if the <filename>/usr/local/doc/postgresql</filename>, but if the
prefix is <filename>/opt/postgres</filename>, then it will be prefix is <filename>/opt/postgres</filename>, then it will be
in <filename>/opt/postgres/doc</filename>. Second, the in <filename>/opt/postgres/doc</filename>. The public C header files of the
installation layout of the C and C++ header files has been
reorganized in the 7.2 release. The public header files of the
client interfaces are installed into client interfaces are installed into
<varname>includedir</varname> and are namespace-clean. The <varname>includedir</varname> and are namespace-clean. The
internal header files and the server header files are installed internal header files and the server header files are installed
@ -537,27 +686,11 @@ su - postgres
<listitem> <listitem>
<para> <para>
Enables single-byte character set recode support. See Enables single-byte character set recode support. See
<![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]> <![%standalone-include[the <citetitle>Administrator's
<![%standalone-ignore[<xref linkend="recode">]]> about this feature. Guide</citetitle>]]> <![%standalone-ignore[<xref
</para> linkend="recode">]]> about this feature. Note that a more
</listitem> general form of character set conversion is supported in the
</varlistentry> default configuration; this feature is obsolete.
<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.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -566,38 +699,22 @@ su - postgres
<term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term> <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
<listitem> <listitem>
<para> <para>
Enables Native Language Support (<acronym>NLS</acronym>), that is, the ability Enables Native Language Support (<acronym>NLS</acronym>),
to display a program's messages in a language other than that is, the ability to display a program's messages in a
English. <replaceable>LANGUAGES</replaceable> is a space language other than English.
separated list of codes of the languages that you want <replaceable>LANGUAGES</replaceable> is a space separated
supported, for example <literal>--enable-nls='de fr'</>. list of codes of the languages that you want supported, for
(The intersection between your list and the set example <literal>--enable-nls='de fr'</>. (The intersection
of actually provided translations will be computed between your list and the set of actually provided
automatically.) If you do not specify a list, then all available translations will be computed automatically.) If you do not
translations are installed. specify a list, then all available translations are
installed.
</para> </para>
<comment>
The list of provided translations should be shown somewhere.
</comment>
<para> <para>
To use this option, you will need an implementation of the To use this option, you will need an implementation of the
<application>gettext</> API. Some operating systems have this built-in <application>gettext</> API; see above.
(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> </para>
<comment>
The download location should be moved.
</comment>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -616,15 +733,6 @@ su - postgres
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><option>--with-CXX</option></term>
<listitem>
<para>
Build the C++ interface library.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term><option>--with-perl</option></term> <term><option>--with-perl</option></term>
<listitem> <listitem>
@ -638,9 +746,9 @@ su - postgres
<term><option>--with-python</option></term> <term><option>--with-python</option></term>
<listitem> <listitem>
<para> <para>
Build the Python interface module. You need to have root Build the Python interface module and the PL/Python
access to be able to install the Python module at its default server-side language. You need to have root access to be able
place to install the Python module at its default place
(<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>). (<filename>/usr/lib/python<replaceable>x</>.<replaceable>y</></>).
To be able to use this option, you must have Python installed To be able to use this option, you must have Python installed
and your system needs to support shared libraries. If you and your system needs to support shared libraries. If you
@ -691,69 +799,12 @@ su - postgres
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><option>--with-java</option></term> <term><option>--with-java</option></term>
<listitem> <listitem>
<para> <para>
Build the <acronym>JDBC</acronym> driver and associated Java Build the <acronym>JDBC</acronym> driver and associated Java
packages. This option requires packages.
<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.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -830,19 +881,6 @@ su - postgres
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><option>--without-readline</option></term> <term><option>--without-readline</option></term>
<listitem> <listitem>
@ -917,20 +955,26 @@ su - postgres
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
<para> <para>
If you prefer a C or C++ compiler different from the one If you prefer a C compiler different from the one
<filename>configure</filename> picks then you can set the <filename>configure</filename> picks then you can set the
environment variables <envar>CC</> or <envar>CXX</envar>, environment variable <envar>CC</> to the program of your choice.
respectively, to the program of your choice. Similarly, you can By default, <filename>configure</filename> will pick
override the default compiler flags with the <envar>CFLAGS</envar> <filename>gcc</filename> unless this is inappropriate for the
and <envar>CXXFLAGS</envar> variables. For example: 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> <screen>
<userinput>env CC=/opt/bin/gcc CFLAGS='-O2 -pipe' ./configure</> <userinput>./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'</>
</screen> </screen>
</para> </para>
</step> </step>
<step> <step>
<title>Build</title> <title>Build</title>
@ -1057,34 +1101,40 @@ All of PostgreSQL is successfully made. Ready to install.
</screen> </screen>
</para> </para>
</formalpara> </formalpara>
</step>
</procedure>
<formalpara>
<title>Uninstall:</title>
<para> <para>
To undo the installation use the command <command>gmake To undo the installation use the command <command>gmake
uninstall</>. However, this will not remove any created directories. uninstall</>. However, this will not remove any created directories.
</para> </para>
</step> </formalpara>
</procedure>
<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> <para>
After the installation you can make room by removing the built If you perform a build and then discover that your configure
files from the source tree with the <command>gmake clean</> options were wrong, or if you change anything that configure
command. This will preserve the files made by the configure investigates (for example, software upgrades), then it's a good
program, so that you can rebuild everything with <command>gmake</> idea to do <command>gmake distclean</> before reconfiguring and
later on. To reset the source tree to the state in which it was rebuilding. Without this, your changes in configuration choices
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
may not propagate everywhere they need to. may not propagate everywhere they need to.
</para> </para>
</sect1> </sect1>
<sect1 id="install-post"> <sect1 id="install-post">
@ -1139,17 +1189,13 @@ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
building. building.
</para> </para>
<!--
<para> <para>
On Linux systems the following is the preferred method, but you On <systemitem class="osname">Cygwin</systemitem>, put the library
must have root access. Edit the file <filename>/etc/ld.so.conf</> directory on the <envar>PATH</envar> or move the
to add a line <filename>.dll</filename> files into the <filename>bin/</filename>
<programlisting> directory.
<filename>/usr/local/pgsql/lib</>
</programlisting>
Then run command <command>/sbin/ldconfig</>.
</para> </para>
-->
<para> <para>
If in doubt, refer to the manual pages of your system (perhaps If in doubt, refer to the manual pages of your system (perhaps
<command>ld.so</command> or <command>rld</command>). If you later <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> <para>
If you installed into <filename>/usr/local/pgsql</> or some other 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 add <filename>/usr/local/pgsql/bin</> (or whatever you set
<option><literal>--bindir</></> to in <xref linkend="configure">) <option><literal>--bindir</></> to in <xref linkend="configure">)
into your <envar>PATH</>. To do this, add the following to your into your <envar>PATH</>. Strictly speaking, this is not
shell start-up file, such as <filename>~/.bash_profile</> (or necessary, but it will make the use of PostgreSQL much more
<filename>/etc/profile</>, if you want it to affect every user): 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> <programlisting>
PATH=/usr/local/pgsql/bin:$PATH PATH=/usr/local/pgsql/bin:$PATH
export PATH
</programlisting> </programlisting>
If you are using <command>csh</> or <command>tcsh</>, then use this command: If you are using <command>csh</> or <command>tcsh</>, then use this command:
<programlisting> <programlisting>
@ -1216,9 +1269,11 @@ set path = ( /usr/local/pgsql/bin $path )
</indexterm> </indexterm>
To enable your system to find the <application>man</> To enable your system to find the <application>man</>
documentation, you need to add a line like the following to a 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> <programlisting>
MANPATH=/usr/local/pgsql/man:$MANPATH MANPATH=/usr/local/pgsql/man:$MANPATH
export MANPATH
</programlisting> </programlisting>
</para> </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"> <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>
<para> <para>
Alternatively you can build the driver from source. Although you Alternatively you can build the driver from source, but you
should only need to do this if you are making changes to the source should only need to do this if you are making changes to the
code. 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>
<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>
<sect2 id="jdbc-classpath"> <sect2 id="jdbc-classpath">
<title>Setting up the Class Path</title> <title>Setting up the Class Path</title>
<para> <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 <filename>postgresql.jar</filename> if you built from source, otherwise
it will likely be named <filename>jdbc7.2-1.1.jar</filename> or 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) respectively)
needs to be included in the needs to be included in the
class path, either by putting it in the <envar>CLASSPATH</envar> class path, either by putting it in the <envar>CLASSPATH</envar>
environment variable, or by using flags on the environment variable, or by using flags on the
<command>java</command> command line. By default, the jar archive <command>java</command> command line.
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.
</para> </para>
<informalexample>
<para> <para>
For instance, I have an application that uses the For instance, I have an application that uses the
<acronym>JDBC</acronym> driver to access a large database <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 Loading the driver from within the application is covered in
<xref linkend="jdbc-use">. <xref linkend="jdbc-use">.
</para> </para>
</informalexample>
</sect2> </sect2>
<sect2 id="jdbc-prepare"> <sect2 id="jdbc-prepare">
@ -183,7 +124,7 @@ java Finder
Also, the client authentication setup in the Also, the client authentication setup in the
<filename>pg_hba.conf</filename> file may need to be configured. <filename>pg_hba.conf</filename> file may need to be configured.
Refer to the <citetitle>Administrator's Guide</citetitle> for 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. ident, password, md5, and crypt authentication methods.
</para> </para>
</sect2> </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"> <chapter id="maintenance">
@ -424,14 +424,13 @@ VACUUM
<para> <para>
The simplest production-grade approach to managing log output is to The simplest production-grade approach to managing log output is to
send it all to <application>syslog</> and let <application>syslog</> send it all to <application>syslog</> and let
deal with file rotation. To do this, make sure <application>syslog</> deal with file rotation. To do this, set
<productname>PostgreSQL</> was built with the
<option>--enable-syslog</> configure option, and set
<literal>syslog</> to 2 (log to syslog only) in <literal>syslog</> to 2 (log to syslog only) in
<filename>postgresql.conf</>. Then you can send a <filename>postgresql.conf</>. Then you can send a
<literal>SIGHUP</literal> signal to the <application>syslog</> daemon <literal>SIGHUP</literal> signal to the <application>syslog</>
whenever you want to force it to start writing a new log file. daemon whenever you want to force it to start writing a new log
file.
</para> </para>
<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"> <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> </indexterm>
<para> <para>
PL/Perl is a loadable procedural language PL/Perl is a loadable procedural language that enables you to write
that enables the <ulink url="http://www.perl.com">Perl</ulink> programming <productname>PostgreSQL</productname> functions in the <ulink
language to be used to write url="http://www.perl.com">Perl</ulink> programming language.
<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.
</para> </para>
<para> <para>
On most platforms, since PL/Perl is a shared library, the To install PL/Perl in a particular database, use
<indexterm><primary>libperl</primary></indexterm> <literal>createlang plperl <replaceable>dbname</></literal>.
<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.
</para> </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> <tip>
<para> <para>
If a language is installed into <literal>template1</>, all subsequently If a language is installed into <literal>template1</>, all subsequently
created databases will have the language installed automatically. created databases will have the language installed automatically.
</para> </para>
</tip> </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"> <sect1 id="plperl-funcs">
<title>Description</title> <title>PL/Perl Functions and Arguments</title>
<sect2> <para>
<title>PL/Perl Functions and Arguments</title> 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 ' CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS '
# PL/Perl function body # PL/Perl function body
' LANGUAGE plperl; ' 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 <para>
<literal>plperlu</>. Arguments and results are handled as in any other Perl subroutine:
</para> 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> <programlisting>
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>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS ' CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
if ($_[0] > $_[1]) { return $_[0]; } if ($_[0] > $_[1]) { return $_[0]; }
return $_[1]; return $_[1];
' LANGUAGE plperl; ' LANGUAGE plperl;
</programlisting> </programlisting>
</para>
If a NULL is passed to a function, the argument value will appear <para>
as <quote>undefined</> in Perl. The above function definition will If an SQL null value is passed to a function, the argument value
not behave very nicely with NULL inputs (in fact, it will act as will appear as <quote>undefined</> in Perl. The above function
though they are zeroes). We could add <literal>WITH (isStrict)</> definition will not behave very nicely with null inputs (in fact,
to the function definition to make <productname>PostgreSQL</productname> it will act as though they are zeroes). We could add
do something more reasonable: if a NULL is passed, the <literal>STRICT</> to the function definition to make
function will not be called at all, but will just return a NULL <productname>PostgreSQL</productname> do something more reasonable:
result automatically. Alternatively, we could check for undefined if a null value is passed, the function will not be called at all,
inputs in the function body. For example, suppose that we wanted perl_max but will just return a null result automatically. Alternatively,
with one null and one non-null argument to return the non-null we could check for undefined inputs in the function body. For
argument, rather than NULL: 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 ' CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
my ($a,$b) = @_; my ($a,$b) = @_;
if (! defined $a) { if (! defined $a) {
@ -172,21 +93,21 @@ CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
if ($a > $b) { return $a; } if ($a > $b) { return $a; }
return $b; return $b;
' LANGUAGE plperl; ' LANGUAGE plperl;
</programlisting> </programlisting>
</para> </para>
<para> <para>
As shown above, As shown above, to return an SQL null value from a PL/Perl
to return a NULL from a PL/Perl function, return an undefined function, return an undefined value. This can be done whether the
value. This can be done whether the function is strict or not. function is strict or not.
</para> </para>
<para> <para>
Composite-type arguments are passed to the function as references to Composite-type arguments are passed to the function as references
hashes. The keys of the hash are the attribute names of the composite to hashes. The keys of the hash are the attribute names of the
type. Here is an example: composite type. Here is an example:
<programlisting> <programlisting>
CREATE TABLE employee ( CREATE TABLE employee (
name text, name text,
basesalary integer, basesalary integer,
@ -199,25 +120,97 @@ CREATE FUNCTION empcomp(employee) RETURNS integer AS '
' LANGUAGE plperl; ' LANGUAGE plperl;
SELECT name, empcomp(employee) FROM employee; SELECT name, empcomp(employee) FROM employee;
</programlisting> </programlisting>
</para> </para>
<para> <para>
There is not currently any support for returning a composite-type There is currently no support for returning a composite-type result
result value. value.
</para> </para>
<tip> <tip>
<para> <para>
Because the function body is passed as an SQL string literal to Because the function body is passed as an SQL string literal to
<command>CREATE FUNCTION</command>, you have to escape single <command>CREATE FUNCTION</command>, you have to escape single
quotes and backslashes within your Perl source, typically by doubling them quotes and backslashes within your Perl source, typically by
as shown in the above example. Another possible approach is to doubling them as shown in the above example. Another possible
avoid writing single quotes by using Perl's extended quoting functions approach is to avoid writing single quotes by using Perl's
(<literal>q[]</literal>, <literal>qq[]</literal>, extended quoting operators (<literal>q[]</literal>,
<literal>qw[]</literal>). <literal>qq[]</literal>, <literal>qw[]</literal>).
</para> </para>
</tip> </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> <para>
Here is an example of a function that will not work because file Here is an example of a function that will not work because file
@ -231,89 +224,66 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
</programlisting> </programlisting>
The creation of the function will succeed, but executing it will not. The creation of the function will succeed, but executing it will not.
</para> </para>
<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. <literal>plperlu</>, execution would succeed.
</para> </para>
</sect1>
</sect2> <sect1 id="plperl-missing">
<title>Missing Features</title>
<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>
<para> <para>
Access to the database itself from your Perl function can be done via The following features are currently missing from PL/Perl, but they
an experimental module <ulink would make welcome contributions:
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 <itemizedlist>
mirror sites</ulink>). This module makes available a <listitem>
<acronym>DBI</>-compliant database-handle named <para>
<varname>$pg_dbh</varname> that can be used to perform queries PL/Perl functions cannot call each other directly (because they
with normal <acronym>DBI</> syntax. 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> </para>
</sect1>
<para> </chapter>
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>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: 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"> <chapter id="plpython">
<title>PL/Python - Python Procedural Language</title> <title>PL/Python - Python Procedural Language</title>
@ -6,90 +6,42 @@
<indexterm zone="plpython"><primary>PL/Python</></> <indexterm zone="plpython"><primary>PL/Python</></>
<indexterm zone="plpython"><primary>Python</></> <indexterm zone="plpython"><primary>Python</></>
<sect1 id="plpython-intro"> <para>
<title>Introduction</title> 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> <para>
The <application>PL/Python</application> procedural language allows Users of source packages must specially enable the build of
<productname>PostgreSQL</productname> functions to be written in PL/Python during the installation process (refer to the
the <ulink url="http://www.python.org">Python</ulink> language. installation instructions for more information). Users of binary
packages might find PL/Python in a separate subpackage.
</para> </para>
</note>
<sect1 id="plpython-funcs">
<title>PL/Python Functions</title>
<para> <para>
The current version of <application>PL/Python</application> The Python code you write gets transformed into a function. E.g.,
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.,
<programlisting> <programlisting>
CREATE FUNCTION myfunc(text) RETURNS text AS CREATE FUNCTION myfunc(text) RETURNS text
'return args[0]' AS 'return args[0]'
LANGUAGE 'plpython'; LANGUAGE 'plpython';
</programlisting> </programlisting>
gets transformed into gets transformed into
<programlisting> <programlisting>
def __plpython_procedure_myfunc_23456(): def __plpython_procedure_myfunc_23456():
return args[0] return args[0]
</programlisting> </programlisting>
where 23456 is the OID of the function. where 23456 is the OID of the function.
@ -98,51 +50,68 @@ def __plpython_procedure_myfunc_23456():
<para> <para>
If you do not provide a return value, Python returns the default 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 <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>
<para> <para>
<productname>PostgreSQL</> function variables are available in the global The <productname>PostgreSQL</> function parameters are available in
<varname>args</varname> list. In the <function>myfunc</function> the global <varname>args</varname> list. In the
example, <varname>args[0]</> contains whatever was passed in as the text <function>myfunc</function> example, <varname>args[0]</> contains
argument. For <literal>myfunc2(text, integer)</literal>, <varname>args[0]</> whatever was passed in as the text argument. For
would contain the <type>text</type> variable and <varname>args[1]</varname> the <type>integer</type> variable. <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>
<para> <para>
The global dictionary SD is available to store data between The global dictionary <varname>SD</varname> is available to store
function calls. This variable is private static data. The global data between function calls. This variable is private static data.
dictionary GD is public data, available to all python functions The global dictionary <varname>GD</varname> is public data,
within a backend. Use with care. available to all Python functions within a session. Use with care.
</para> </para>
<para> <para>
Each function gets its own restricted execution object in the Each function gets its own restricted execution object in the
Python interpreter, so that global data and function arguments from Python interpreter, so that global data and function arguments from
<function>myfunc</function> are not available to <function>myfunc</function> are not available to
<function>myfunc2</function>. The exception is the data in the GD <function>myfunc2</function>. The exception is the data in the
dictionary, as mentioned above. <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>
<para> <para>
When a function is used in a trigger, the dictionary TD contains If the <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
transaction related values. The trigger tuples are in <literal>TD["new"]</> return <literal>None</literal> or <literal>"OK"</literal> from the
and/or <literal>TD["old"]</> depending on the trigger event. <literal>TD["event"]</> Python function to indicate the row is unmodified,
contains the event as a string (<literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>, or <literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to
<literal>UNKNOWN</>). TD["when"] contains one of (<literal>BEFORE</>, <literal>AFTER</>, or indicate you've modified the row.
<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)]</>.
</para> </para>
</sect1>
<para> <sect1 id="plpython-database">
If the trigger <quote>when</quote> is <literal>BEFORE</>, you may return <literal>None</literal> or <literal>"OK"</literal> <title>Database Access</title>
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>
<para> <para>
The PL/Python language module automatically imports a Python module 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 this module are available to you in the Python code as
<literal>plpy.<replaceable>foo</replaceable></literal>. At present <literal>plpy.<replaceable>foo</replaceable></literal>. At present
<literal>plpy</literal> implements the functions <literal>plpy</literal> implements the functions
<literal>plpy.debug("msg")</literal>, <literal>plpy.debug("msg")</literal>,
<literal>plpy.log("msg")</literal>, <literal>plpy.log("msg")</literal>,
<literal>plpy.info("msg")</literal>, <literal>plpy.info("msg")</literal>,
<literal>plpy.notice("msg")</literal>, <literal>plpy.notice("msg")</literal>,
<literal>plpy.warning("msg")</literal>, <literal>plpy.warning("msg")</literal>,
<literal>plpy.error("msg")</literal>, and <literal>plpy.error("msg")</literal>, and
<literal>plpy.fatal("msg")</literal>. They are mostly equivalent <literal>plpy.fatal("msg")</literal>. They are mostly equivalent
to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>. to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>
<function>plpy.error</function> and <function>plpy.fatal</function> from C code. <function>plpy.error</function> and
actually raise a Python exception which, if uncaught, causes the <function>plpy.fatal</function> actually raise a Python exception
PL/Python module to call <literal>elog(ERROR, msg)</literal> when which, if uncaught, causes the PL/Python module to call
the function handler returns from the Python interpreter. Long <literal>elog(ERROR, msg)</literal> when the function handler
jumping out of the Python interpreter is probably not good. returns from the Python interpreter. Long-jumping out of the
<literal>raise plpy.ERROR("msg")</literal> and <literal>raise Python interpreter is probably not good. <literal>raise
plpy.ERROR("msg")</literal> and <literal>raise
plpy.FATAL("msg")</literal> are equivalent to calling 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>
<para> <para>
Additionally, the <literal>plpy</literal> module provides two functions called Additionally, the <literal>plpy</literal> module provides two
<function>execute</function> and <function>prepare</function>. functions called <function>execute</function> and
Calling <function>plpy.execute</function> with a query string, and <function>prepare</function>. Calling
an optional limit argument, causes that query to be run, and the <function>plpy.execute</function> with a query string and an
result returned in a result object. The result object emulates a 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 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 <function>nrows()</function> which returns the number of rows
returned by the query, and <function>status</function> which is the returned by the query, and <function>status</function> which is the
<function>SPI_exec</function> return variable. The result object <function>SPI_exec</function> return variable. The result object
can be modified. can be modified.
</para>
<para>
For example,
<programlisting> <programlisting>
rv = plpy.execute("SELECT * FROM my_table", 5) rv = plpy.execute("SELECT * FROM my_table", 5)
</programlisting> </programlisting>
returns up to 5 rows from my_table. Ff my_table has a column returns up to 5 rows from <literal>my_table</literal>. If
my_field it would be accessed as <literal>my_table</literal> has a column
<literal>my_field</literal>, it would be accessed as
<programlisting> <programlisting>
foo = rv[i]["my_field"] foo = rv[i]["my_field"]
</programlisting> </programlisting>
</para>
<para>
The second function <function>plpy.prepare</function> is called The second function <function>plpy.prepare</function> is called
with a query string, and a list of argument types if you have bind with a query string and a list of argument types if you have bind
variables in the query. variables in the query. For example:
<programlisting> <programlisting>
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ]) plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
</programlisting> </programlisting>
text is the type of the variable you will be passing as $1. After <literal>text</literal> is the type of the variable you will be
preparing you use the function <function>plpy.execute</function> to passing as <literal>$1</literal>. After preparing a statement, you
run it. use the function <function>plpy.execute</function> to run it:
<programlisting> <programlisting>
rv = plpy.execute(plan, [ "name" ], 5) rv = plpy.execute(plan, [ "name" ], 5)
</programlisting> </programlisting>
@ -205,6 +184,17 @@ rv = plpy.execute(plan, [ "name" ], 5)
<function>plpy.execute</function>. <function>plpy.execute</function>.
</para> </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> <para>
When you prepare a plan using the PL/Python module it is When you prepare a plan using the PL/Python module it is
automatically saved. Read the SPI documentation (<xref automatically saved. Read the SPI documentation (<xref
@ -220,4 +210,21 @@ plan = plpy.prepare("SOME OTHER QUERY")
</para> </para>
</sect1> </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> </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 PostgreSQL documentation
--> -->
@ -2274,33 +2274,6 @@ $endif
<application>readline</application> feature. Read its documentation <application>readline</application> feature. Read its documentation
for further details.) for further details.)
</para> </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> </refsect3>
</refsect2> </refsect2>
</refsect1> </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"> <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 to turn this on, as it might expose programming mistakes. To use
this option, the macro <literal>USE_ASSERT_CHECKING</literal> this option, the macro <literal>USE_ASSERT_CHECKING</literal>
must be defined when <productname>PostgreSQL</productname> is must be defined when <productname>PostgreSQL</productname> is
built (see the configure option built (accomplished by the configure option
<literal>--enable-cassert</literal>). Note that <option>--enable-cassert</option>). Note that
<literal>DEBUG_ASSERTIONS</literal> defaults to on if <literal>DEBUG_ASSERTIONS</literal> defaults to on if
<productname>PostgreSQL</productname> has been built with <productname>PostgreSQL</productname> has been built with
assertions enabled. assertions enabled.
@ -1176,11 +1176,6 @@ env PGOPTIONS='-c geqo=off' psql
<systemitem>syslog</> is off. This option must be set at server <systemitem>syslog</> is off. This option must be set at server
start. start.
</para> </para>
<para>
To use <systemitem>syslog</>, the build of
<productname>PostgreSQL</productname> must be configured with
the <option>--enable-syslog</option> option.
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>