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