Skip to content

P
Postgres FD Implementation
Commit da123b7c authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Update installation instructions and put mostly everything in one place. 

Also, some editing in PL/Perl and PL/Python chapters.
parent 0db8c415
Show whitespace changes
Inline Side-by-side
Showing with 617 additions and 702 deletions
doc/src/sgml/charset.sgml
View file @ da123b7c
<!-- $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; ...@@ -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>
......
doc/src/sgml/client-auth.sgml
View file @ da123b7c
<!-- <!--
$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 ...@@ -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>
......
doc/src/sgml/installation.sgml
View file @ da123b7c
<!-- $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 ...@@ -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>
...@@ -106,41 +108,187 @@ su - postgres ...@@ -106,41 +108,187 @@ su - postgres
<listitem> <listitem>
<para> <para>
<indexterm> <indexterm>
<primary>flex</primary> <primary>installation</primary>
</indexterm> <secondary>on Windows</secondary>
<indexterm>
<primary>bison</primary>
</indexterm>
<indexterm>
<primary>yacc</primary>
</indexterm> </indexterm>
<acronym>GNU</> <application>Flex</> and <application>Bison</> are To build on <productname>Windows NT</> or <productname>Windows
needed to build from scratch, but they are 2000</> you need the <productname>Cygwin</> and
<emphasis>not</> required when building from a released source <productname>cygipc</> packages. See the file
package because pre-generated output files are included in released <filename>doc/FAQ_MSWIN</> for details.
packages. You will </para>
need these programs only when building from a CVS tree or if you </listitem>
changed the actual scanner and parser definition files. If </itemizedlist>
you need them, be sure to get <application>Flex</> 2.5.4 or </para>
later and <application>Bison</> 1.28 or later. Other <application>yacc</>
programs can sometimes be used, but doing so requires extra <para>
effort and is not recommended. Other <application>lex</> programs will The following packages are optional. They are not required in the
definitely not work. 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> </para>
</listitem> </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> <listitem>
<para> <para>
<indexterm> <indexterm>
<primary>installation</primary> <primary>flex</primary>
<secondary>on Windows</secondary> </indexterm>
<indexterm>
<primary>bison</primary>
</indexterm>
<indexterm>
<primary>yacc</primary>
</indexterm> </indexterm>
To build on <productname>Windows NT</> or <productname>Windows <acronym>GNU</> <application>Flex</> and <application>Bison</>
2000</> you need the <productname>Cygwin</> and are needed to build a CVS checkout or if you changed the actual
<productname>cygipc</> packages. See the file scanner and parser definition files. If you need them, be sure
<filename>doc/FAQ_MSWIN</> for details. 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> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -156,12 +304,13 @@ su - postgres ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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 ...@@ -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>
...@@ -920,14 +958,20 @@ su - postgres ...@@ -920,14 +958,20 @@ su - postgres
</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>
...@@ -1057,34 +1101,40 @@ All of PostgreSQL is successfully made. Ready to install. ...@@ -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> <para>
After the installation you can make room by removing the built After the installation you can make room by removing the built
files from the source tree with the <command>gmake clean</> files from the source tree with the command <command>gmake
command. This will preserve the files made by the configure clean</>. This will preserve the files made by the configure
program, so that you can rebuild everything with <command>gmake</> program, so that you can rebuild everything with <command>gmake</>
later on. To reset the source tree to the state in which it was later on. To reset the source tree to the state in which it was
distributed, use <command>gmake distclean</>. If you are going to distributed, use <command>gmake distclean</>. If you are going to
build for several platforms from the same source tree you must do build for several platforms from the same source tree you must do
this and re-configure for each build. this and re-configure for each build.
</para> </para>
</formalpara>
<para> <para>
If you perform a build and then discover that your configure options If you perform a build and then discover that your configure
were wrong, or if you change anything that configure investigates options were wrong, or if you change anything that configure
(for example, you install GNU <application>Readline</>), then it's investigates (for example, software upgrades), then it's a good
a good idea to do <command>gmake distclean</> before reconfiguring idea to do <command>gmake distclean</> before reconfiguring and
and rebuilding. Without this, your changes in configuration choices 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 ...@@ -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 ...@@ -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 ) ...@@ -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>
......
doc/src/sgml/jdbc.sgml
View file @ da123b7c
<!-- <!--
$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 ...@@ -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 ...@@ -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 ...@@ -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>
......
doc/src/sgml/maintenance.sgml
View file @ da123b7c
<!-- <!--
$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 ...@@ -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>
......
doc/src/sgml/plperl.sgml
View file @ da123b7c
<!-- <!--
$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,95 +14,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.16 2002/03/06 19:05:57 momj ...@@ -14,95 +14,14 @@ $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>
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> </para>
<tip> <tip>
...@@ -111,57 +30,59 @@ gmake install ...@@ -111,57 +30,59 @@ gmake install
created databases will have the language installed automatically. created databases will have the language installed automatically.
</para> </para>
</tip> </tip>
</sect1>
<!-- **** PL/Perl description **** -->
<sect1 id="plperl-description"> <note>
<title>Description</title> <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>
<sect2> <sect1 id="plperl-funcs">
<title>PL/Perl Functions and Arguments</title> <title>PL/Perl Functions and Arguments</title>
<para> <para>
To create a function in the PL/Perl language, use the standard syntax To create a function in the PL/Perl language, use the standard syntax:
<programlisting>
<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.
PL/PerlU is the same, except that the language should be specified as
<literal>plperlu</>.
</para> </para>
<para> <para>
The body of the function is ordinary Perl code. Arguments and Arguments and results are handled as in any other Perl subroutine:
results are handled as in any other Perl subroutine: arguments Arguments are passed in <varname>@_</varname>, and a result value
are passed in <varname>@_</varname>, and a result value is returned is returned with <literal>return</> or as the last expression
with <literal>return</> or as the last expression evaluated in the evaluated in the function. For example, a function returning the
function. For example, a function greater of two integer values could be defined as:
returning the greater of two integer values could be defined as:
<programlisting>
<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
as <quote>undefined</> in Perl. The above function definition will <para>
not behave very nicely with NULL inputs (in fact, it will act as If an SQL null value is passed to a function, the argument value
though they are zeroes). We could add <literal>WITH (isStrict)</> will appear as <quote>undefined</> in Perl. The above function
to the function definition to make <productname>PostgreSQL</productname> definition will not behave very nicely with null inputs (in fact,
do something more reasonable: if a NULL is passed, the it will act as though they are zeroes). We could add
function will not be called at all, but will just return a NULL <literal>STRICT</> to the function definition to make
result automatically. Alternatively, we could check for undefined <productname>PostgreSQL</productname> do something more reasonable:
inputs in the function body. For example, suppose that we wanted perl_max if a null value is passed, the function will not be called at all,
with one null and one non-null argument to return the non-null but will just return a null result automatically. Alternatively,
argument, rather than NULL: we could check for undefined inputs in the function body. For
example, suppose that we wanted <function>perl_max</function> with
<programlisting> one null and one non-null argument to return the non-null argument,
rather than a null value:
<programlisting>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS ' 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 ' ...@@ -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,60 +120,42 @@ CREATE FUNCTION empcomp(employee) RETURNS integer AS ' ...@@ -199,60 +120,42 @@ 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>
<para> <sect1 id="plperl-data">
Here is an example of a function that will not work because file
system operations are not allowed for security reasons:
<programlisting>
CREATE FUNCTION badfunc() RETURNS integer AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE plperl;
</programlisting>
The creation of the function will succeed, but executing it will not.
</para>
<para>
Note that if the same function was created by a superuser using language
<literal>plperlu</>, execution would succeed.
</para>
</sect2>
<sect2>
<title>Data Values in PL/Perl</title> <title>Data Values in PL/Perl</title>
<para> <para>
The argument values supplied to a PL/Perl function's script are simply The argument values supplied to a PL/Perl function's script are
the input arguments converted to text form (just as if they had been simply the input arguments converted to text form (just as if they
displayed by a SELECT statement). Conversely, the <literal>return</> had been displayed by a <literal>SELECT</literal> statement).
command will accept any string that is acceptable input format for Conversely, the <literal>return</> command will accept any string
the function's declared return type. So, the PL/Perl programmer can that is acceptable input format for the function's declared return
manipulate data values as if they were just text. type. So, the PL/Perl programmer can manipulate data values as if
they were just text.
</para> </para>
</sect1>
</sect2> <sect1 id="plperl-database">
<sect2>
<title>Database Access from PL/Perl</title> <title>Database Access from PL/Perl</title>
<para> <para>
...@@ -268,13 +171,14 @@ CREATE FUNCTION badfunc() RETURNS integer AS ' ...@@ -268,13 +171,14 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
<para> <para>
PL/Perl itself presently provides only one additional Perl command: PL/Perl itself presently provides only one additional Perl command:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<indexterm> <indexterm>
<primary>elog</primary> <primary>elog</primary>
<secondary>PL/Perl</secondary>
</indexterm> </indexterm>
<term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term> <term><function>elog</> <replaceable>level</replaceable>, <replaceable>msg</replaceable></term>
<listitem> <listitem>
<para> <para>
...@@ -287,33 +191,99 @@ CREATE FUNCTION badfunc() RETURNS integer AS ' ...@@ -287,33 +191,99 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</sect1>
</sect2> <sect1 id="plperl-trusted">
<title>Trusted and Untrusted PL/Perl</title>
<sect2> <para>
<title>Missing Features</title> 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>
PL/Perl functions cannot call each other directly (because they Here is an example of a function that will not work because file
are anonymous subroutines inside Perl). There's presently system operations are not allowed for security reasons:
no way for them to share global variables, either. <programlisting>
CREATE FUNCTION badfunc() RETURNS integer AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE plperl;
</programlisting>
The creation of the function will succeed, but executing it will not.
</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 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>
<para> <para>
PL/Perl cannot currently be used to write trigger functions. 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>
<para> <para>
DBD::PgSPI or similar capability should be integrated If the above function was created by a superuser using the language
into the standard <productname>PostgreSQL</productname> distribution. <literal>plperlu</>, execution would succeed.
</para>
</sect1>
<sect1 id="plperl-missing">
<title>Missing Features</title>
<para>
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> </para>
</listitem>
</sect2> <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> </sect1>
</chapter>
</chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:
......
doc/src/sgml/plpython.sgml
View file @ da123b7c
<!-- $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,83 +6,35 @@ ...@@ -6,83 +6,35 @@
<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">
<title>Introduction</title>
<para> <para>
The <application>PL/Python</application> procedural language allows The <application>PL/Python</application> procedural language allows
<productname>PostgreSQL</productname> functions to be written in <productname>PostgreSQL</productname> functions to be written in the
the <ulink url="http://www.python.org">Python</ulink> language. <ulink url="http://www.python.org">Python</ulink> language.
</para> </para>
<para> <para>
The current version of <application>PL/Python</application> To install PL/Python in a particular database, use
functions as a trusted language only; access to the file system and <literal>createlang plpython <replaceable>dbname</></literal>.
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>
<note>
<para> <para>
In the current version, any database error encountered while Users of source packages must specially enable the build of
running a <application>PL/Python</application> function will result PL/Python during the installation process (refer to the
in the immediate termination of that function by the server. It is installation instructions for more information). Users of binary
not possible to trap error conditions using Python <literal>try packages might find PL/Python in a separate subpackage.
... 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>
</sect1> </note>
<sect1 id="plpython-install">
<title>Installation</title>
<para> <sect1 id="plpython-funcs">
To build PL/Python, the <option>--with-python</option> option needs <title>PL/Python Functions</title>
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> <para>
The catch is that the Python distribution or the Python maintainers The Python code you write gets transformed into a function. E.g.,
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
...@@ -98,51 +50,68 @@ def __plpython_procedure_myfunc_23456(): ...@@ -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> </para>
</sect1>
<sect1 id="plpython-trigger">
<title>Trigger Functions</title>
<para> <para>
When a function is used in a trigger, the dictionary TD contains When a function is used in a trigger, the dictionary
transaction related values. The trigger tuples are in <literal>TD["new"]</> <literal>TD</literal> contains trigger-related values. The trigger
and/or <literal>TD["old"]</> depending on the trigger event. <literal>TD["event"]</> rows are in <literal>TD["new"]</> and/or <literal>TD["old"]</>
contains the event as a string (<literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>, or depending on the trigger event. <literal>TD["event"]</> contains
<literal>UNKNOWN</>). TD["when"] contains one of (<literal>BEFORE</>, <literal>AFTER</>, or the event as a string (<literal>INSERT</>, <literal>UPDATE</>,
<literal>UNKNOWN</>). <literal>TD["level"]</> contains one of <literal>ROW</>, <literal>STATEMENT</>, or <literal>DELETE</>, or <literal>UNKNOWN</>).
<literal>UNKNOWN</>. <literal>TD["name"]</> contains the trigger name, and <literal>TD["relid"]</> <literal>TD["when"]</> contains one of <literal>BEFORE</>,
contains the relation id of the table on which the trigger occurred. <literal>AFTER</>, and <literal>UNKNOWN</>.
If the trigger was called with arguments they are available <literal>TD["level"]</> contains one of <literal>ROW</>,
in <literal>TD["args"][0]</> to <literal>TD["args"][(n -1)]</>. <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>
If the trigger <quote>when</quote> is <literal>BEFORE</>, you may return <literal>None</literal> or <literal>"OK"</literal> If the <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
from the Python function to indicate the tuple is unmodified, return <literal>None</literal> or <literal>"OK"</literal> from the
<literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to indicate you've Python function to indicate the row is unmodified,
modified the tuple. <literal>"SKIP"</> to abort the event, or <literal>"MODIFIED"</> to
indicate you've modified the row.
</para> </para>
</sect1>
<sect1 id="plpython-database">
<title>Database Access</title>
<para> <para>
The PL/Python language module automatically imports a Python module The PL/Python language module automatically imports a Python module
...@@ -157,47 +126,57 @@ def __plpython_procedure_myfunc_23456(): ...@@ -157,47 +126,57 @@ def __plpython_procedure_myfunc_23456():
<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) ...@@ -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") ...@@ -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>
doc/src/sgml/ref/psql-ref.sgml
View file @ da123b7c
<!-- <!--
$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 ...@@ -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>
......
doc/src/sgml/runtime.sgml
View file @ da123b7c
<!-- <!--
$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 ...@@ -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 ...@@ -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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment