upstream/postgresql
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2026-04-21 14:19:26 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Cleanup pass over Tutorial and Admin Guide

Browse source
This commit is contained in:
Peter Eisentraut 2002-11-06 23:30:39 +00:00
parent d1a6aa536e
commit 9515d57d05
14 changed files with 607 additions and 560 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
doc/src/sgml/advanced.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.30 2002/10/24 17:48:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.30.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="tutorial-advanced">
@ -46,14 +46,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.30 2002/10/24 17:48:54 pe
<firstterm>view</firstterm> over the query, which gives a name to
the query that you can refer to like an ordinary table.
<programlisting>
<programlisting>
CREATE VIEW myview AS
SELECT city, temp_lo, temp_hi, prcp, date, location
FROM weather, cities
WHERE city = name;
SELECT * FROM myview;
</programlisting>
</programlisting>
</para>
<para>
@ -101,7 +101,7 @@ SELECT * FROM myview;
<para>
The new declaration of the tables would look like this:
<programlisting>
<programlisting>
CREATE TABLE cities (
city varchar(80) primary key,
location point
@ -114,23 +114,23 @@ CREATE TABLE weather (
prcp real,
date date
);
</programlisting>
</programlisting>
Now try inserting an invalid record:
<programlisting>
<programlisting>
INSERT INTO weather VALUES ('Berkeley', 45, 53, 0.0, '1994-11-28');
</programlisting>
</programlisting>
<screen>
<screen>
ERROR: &lt;unnamed&gt; referential integrity violation - key referenced from weather not found in cities
</screen>
</screen>
</para>
<para>
The behavior of foreign keys can be finely tuned to your
application. We will not go beyond this simple example in this
tutorial, but just refer you to the &cite-reference;
tutorial, but just refer you to the &cite-user;
for more information. Making correct use of
foreign keys will definitely improve the quality of your database
applications, so you are strongly encouraged to learn about them.
@ -161,7 +161,7 @@ ERROR: &lt;unnamed&gt; referential integrity violation - key referenced from we
to Bob's account. Simplifying outrageously, the SQL commands for this
might look like
<programlisting>
<programlisting>
UPDATE accounts SET balance = balance - 100.00
WHERE name = 'Alice';
UPDATE branches SET balance = balance - 100.00
@ -170,7 +170,7 @@ UPDATE accounts SET balance = balance + 100.00
WHERE name = 'Bob';
UPDATE branches SET balance = balance + 100.00
WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Bob');
</programlisting>
</programlisting>
</para>
<para>
@ -222,13 +222,13 @@ UPDATE branches SET balance = balance + 100.00
<command>BEGIN</> and <command>COMMIT</> commands. So our banking
transaction would actually look like
<programlisting>
<programlisting>
BEGIN;
UPDATE accounts SET balance = balance - 100.00
WHERE name = 'Alice';
-- etc etc
COMMIT;
</programlisting>
</programlisting>
</para>
<para>
@ -278,7 +278,7 @@ COMMIT;
implicitly when you list all cities. If you're really clever you
might invent some scheme like this:
<programlisting>
<programlisting>
CREATE TABLE capitals (
name text,
population real,
@ -296,7 +296,7 @@ CREATE VIEW cities AS
SELECT name, population, altitude FROM capitals
UNION
SELECT name, population, altitude FROM non_capitals;
</programlisting>
</programlisting>
This works OK as far as querying goes, but it gets ugly when you
need to update several rows, to name one thing.
@ -305,7 +305,7 @@ CREATE VIEW cities AS
<para>
A better solution is this:
<programlisting>
<programlisting>
CREATE TABLE cities (
name text,
population real,
@ -315,7 +315,7 @@ CREATE TABLE cities (
CREATE TABLE capitals (
state char(2)
) INHERITS (cities);
</programlisting>
</programlisting>
</para>
<para>
@ -336,11 +336,11 @@ CREATE TABLE capitals (
including state capitals, that are located at an altitude
over 500 ft.:
<programlisting>
<programlisting>
SELECT name, altitude
FROM cities
WHERE altitude &gt; 500;
</programlisting>
</programlisting>
which returns:
@ -359,11 +359,11 @@ SELECT name, altitude
all the cities that are not state capitals and
are situated at an altitude of 500 ft. or higher:
<programlisting>
<programlisting>
SELECT name, altitude
FROM ONLY cities
WHERE altitude &gt; 500;
</programlisting>
</programlisting>
<screen>
name | altitude
@ -380,7 +380,7 @@ SELECT name, altitude
<classname>cities</classname> table, and not tables below
<classname>cities</classname> in the inheritance hierarchy. Many
of the commands that we have already discussed --
<command>SELECT</command>, <command>UPDATE</command> and
<command>SELECT</command>, <command>UPDATE</command>, and
<command>DELETE</command> -- support this <literal>ONLY</literal>
notation.
</para>

51
doc/src/sgml/backup.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.23 2002/10/21 02:11:37 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.23.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="backup">
<title>Backup and Restore</title>
@ -64,7 +64,7 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
<para>
As any other <productname>PostgreSQL</> client application,
<application>pg_dump</> will by default connect with the database
user name that is equal to the current Unix user name. To override
user name that is equal to the current operating system user name. To override
this, either specify the <option>-U</option> option or set the
environment variable <envar>PGUSER</envar>. Remember that
<application>pg_dump</> connections are subject to the normal
@ -104,9 +104,9 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
</synopsis>
where <replaceable class="parameter">infile</replaceable> is what
you used as <replaceable class="parameter">outfile</replaceable>
for the pg_dump command. The database <replaceable
for the <command>pg_dump</> command. The database <replaceable
class="parameter">dbname</replaceable> will not be created by this
command, you must create it yourself from template0 before executing
command, you must create it yourself from <literal>template0</> before executing
<application>psql</> (e.g., with <literal>createdb -T template0
<replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</>
@ -129,23 +129,22 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
The ability of <application>pg_dump</> and <application>psql</> to
write to or read from pipes makes it possible to dump a database
directly from one server to another, for example
<informalexample>
<programlisting>
pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</>
</programlisting>
</informalexample>
</para>
<important>
<para>
The dumps produced by pg_dump are relative to template0. This means
that any languages, procedures, etc. added to template1 will also be
dumped by <application>pg_dump</>. As a result, when restoring, if
you are using a customized template1, you must create the empty
database from template0, as in the example above.
</para>
</important>
<important>
<para>
The dumps produced by <application>pg_dump</> are relative to
<literal>template0</>. This means that any languages, procedures,
etc. added to <literal>template1</> will also be dumped by
<application>pg_dump</>. As a result, when restoring, if you are
using a customized <literal>template1</>, you must create the
empty database from <literal>template0</>, as in the example
above.
</para>
</important>
</sect2>
@ -222,20 +221,16 @@ cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <re
acceptable in size to the underlying file system. For example, to
make chunks of 1 megabyte:
<informalexample>
<programlisting>
pg_dump <replaceable class="parameter">dbname</replaceable> | split -b 1m - <replaceable class="parameter">filename</replaceable>
</programlisting>
</informalexample>
Reload with
<informalexample>
<programlisting>
createdb <replaceable class="parameter">dbname</replaceable>
cat <replaceable class="parameter">filename</replaceable>* | psql <replaceable class="parameter">dbname</replaceable>
</programlisting>
</informalexample>
</para>
</formalpara>
@ -249,14 +244,11 @@ cat <replaceable class="parameter">filename</replaceable>* | psql <replaceable c
restored selectively. The following command dumps a database using the
custom dump format:
<informalexample>
<programlisting>
pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceable class="parameter">filename</replaceable>
</programlisting>
</informalexample>
See the <application>pg_dump</> and <application>pg_restore</> reference pages for details.
</para>
</formalpara>
@ -284,7 +276,7 @@ pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceable c
<para>
For reasons of backward compatibility, <application>pg_dump</> does
not dump large objects by default. To dump large objects you must use
either the custom or the TAR output format, and use the -b option in
either the custom or the TAR output format, and use the <option>-b</> option in
<application>pg_dump</>. See the reference pages for details.
The directory <filename>contrib/pg_dumplo</> of the
<productname>PostgreSQL</> source tree also contains a program that can
@ -308,11 +300,10 @@ pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceable c
are located, but you have probably found them already if you are
interested in this method. You can use whatever method you prefer
for doing usual file system backups, for example
<informalexample>
<programlisting>
tar -cf backup.tar /usr/local/pgsql/data
</programlisting>
</informalexample>
</para>
<para>
@ -390,11 +381,11 @@ tar -cf backup.tar /usr/local/pgsql/data
The least downtime can be achieved by installing the new server in
a different directory and running both the old and the new servers
in parallel, on different ports. Then you can use something like
<informalexample>
<programlisting>
pg_dumpall -p 5432 | psql -d template1 -p 6543
</programlisting>
</informalexample>
to transfer your data, or use an intermediate file if you want.
Then you can shut down the old server and start the new server at
the port the old one was running at. You should make sure that the
@ -410,7 +401,7 @@ pg_dumpall -p 5432 | psql -d template1 -p 6543
do the back up step before installing the new version, bring down
the server, move the old version out of the way, install the new
version, start the new server, restore the data. For example:
<informalexample>
<programlisting>
pg_dumpall > backup
pg_ctl stop
@ -421,7 +412,7 @@ initdb -D /usr/local/pgsql/data
postmaster -D /usr/local/pgsql/data
psql template1 < backup
</programlisting>
</informalexample>
See <xref linkend="runtime"> about ways to start and stop the
server and other details. The installation instructions will advise
you of strategic places to perform these steps.

29
doc/src/sgml/client-auth.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.39 2002/09/21 18:32:52 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.39.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="client-authentication">
@ -62,7 +62,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.39 2002/09/21 18:32:52
</para>
<para>
The general format of the <filename>pg_hba.conf</filename> file is of
The general format of the <filename>pg_hba.conf</filename> file is
a set of records, one per line. Blank lines are ignored, as is any
text after the <quote>#</quote> comment character. A record is made
up of a number of fields which are separated by spaces and/or tabs.
@ -305,8 +305,9 @@ hostssl <replaceable>database</replaceable> <replaceable>user</replaceable> <
<para>
If you use the map <literal>sameuser</literal>, the user
names are assumed to be identical. If not, the map name is
looked up in the <literal>$PGDATA/pg_ident.conf</literal>
file. The connection is accepted if that file contains an
looked up in the file <filename>pg_ident.conf</filename>
in the same directory as <filename>pg_hba.conf</filename>.
The connection is accepted if that file contains an
entry for this map name with the ident-supplied user name
and the requested <productname>PostgreSQL</productname> user
name.
@ -473,7 +474,7 @@ local db1,db2,@demodbs all md5
<para>
When <literal>trust</> authentication is specified,
<productname>PostgreSQL</productname> assumes that anyone who can
connect to the postmaster is authorized to access the database as
connect to the server is authorized to access the database as
whatever database user he specifies (including the database superuser).
This method should only be used when there is adequate system-level
protection on connections to the postmaster port.
@ -504,7 +505,7 @@ local db1,db2,@demodbs all md5
<para>
<literal>trust</> authentication is only suitable for TCP connections
if you trust every user on every machine that is allowed to connect
to the postmaster by the <filename>pg_hba.conf</> lines that specify
to the server by the <filename>pg_hba.conf</> lines that specify
<literal>trust</>. It is seldom reasonable to use <literal>trust</>
for any TCP connections other than those from <systemitem>localhost</> (127.0.0.1).
</para>
@ -538,14 +539,14 @@ local db1,db2,@demodbs all md5
<para>
<productname>PostgreSQL</productname> database passwords are
separate from operating system user passwords. Ordinarily, the
password for each database user is stored in the pg_shadow system
separate from operating system user passwords. The password for
each database user is stored in the <literal>pg_shadow</> system
catalog table. Passwords can be managed with the query language
commands <command>CREATE USER</command> and <command>ALTER
USER</command>, e.g., <userinput>CREATE USER foo WITH PASSWORD
'secret';</userinput>. By default, that is, if no password has been
set up, the stored password is <literal>NULL</literal> and password
authentication will always fail for that user.
'secret';</userinput>. By default, that is, if no password has
been set up, the stored password is null and
password authentication will always fail for that user.
</para>
<para>
@ -554,8 +555,8 @@ local db1,db2,@demodbs all md5
file. The file should contain user names separated by commas or one
user name per line, and be in the same directory as
<filename>pg_hba.conf</>. Mention the (base) name of the file
preceded with <literal>@</>in the <literal>USER</> column. The
<literal>DATABASE</> column can similarly accept a list of values or
preceded with <literal>@</> in the user column. The
database column can similarly accept a list of values or
a file name. You can also specify group names by preceding the group
name with <literal>+</>.
</para>
@ -715,7 +716,7 @@ local db1,db2,@demodbs all md5
Unix-domain sockets (currently <systemitem
class="osname">Linux</>, <systemitem class="osname">FreeBSD</>,
<systemitem class="osname">NetBSD</>, and <systemitem
class="osname">BSD/OS</>, ident authentication can also be applied
class="osname">BSD/OS</>), ident authentication can also be applied
to local connections. In this case, no security risk is added by
using ident authentication; indeed it is a preferable choice for
local connections on such systems.

11
doc/src/sgml/diskusage.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.6 2002/10/16 22:06:33 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.6.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="diskusage">
@ -32,7 +32,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.6 2002/10/16 22:06:33 pe
<para>
You can monitor disk space from three places: from
<application>psql</> using <command>VACUUM</> information, from
<application>psql</> using <application>contrib/dbsize</>, and from
<application>psql</> using <filename>contrib/dbsize</>, and from
the command line using <application>contrib/oid2name</>. Using
<application>psql</> on a recently vacuumed (or analyzed) database,
you can issue queries to see the disk usage of any table:
@ -94,13 +94,14 @@ play-# ORDER BY relpages DESC;
</para>
<para>
<application>dbsize</> loads functions into your database that allow
<filename>contrib/dbsize</> loads functions into your database that allow
you to find the size of a table or database from inside
<application>psql</> without the need for <command>VACUUM/ANALYZE.</>
</para>
<para>
You can also use <application>oid2name</> to show disk usage. See
<filename>README.oid2name</> for examples. It includes a script
You can also use <filename>contrib/oid2name</> to show disk usage. See
<filename>README.oid2name</> for examples. It includes a script that
shows disk usage for each database.
</para>
</sect1>

8
doc/src/sgml/install-win32.sgml
View file

@ -6,14 +6,6 @@
<secondary>on Windows</secondary>
</indexterm>
<abstract>
<para>
Build, installation, and use instructions for
<productname>PostgreSQL</productname> client libraries on
<productname>Windows</productname>
</para>
</abstract>
<para>
Although <productname>PostgreSQL</productname> is written for
Unix-like operating systems, the C client library

86
doc/src/sgml/installation.sgml
View file

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.103.2.5 2002/11/05 19:01:43 momjian Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.103.2.6 2002/11/06 23:30:39 petere Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@ -8,6 +8,13 @@
<primary>installation</primary>
</indexterm>
<para>
This <![%standalone-include;[document.]]>
<![%standalone-ignore;[chapter.]]> describes the installation of
<productname>PostgreSQL</productname> from the source code
distribution.
</para>
<sect1 id="install-short">
<title>Short Version</title>
@ -131,27 +138,30 @@ su - postgres
<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 and the header files. Since PL/Perl will be 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.
also on most platforms. This appears to be the default in
recent Perl versions, but it was not in earlier versions, and in
general it is the choice of whomever installed Perl at your
site.
</para>
<para>
If this difficulty arises in your situation, a message like this
will appear during the build to point out this fact:
If you don't have the shared library but you need one, 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 on-screen 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.
that the PL/Perl library object, <filename>plperl.so</filename>
or similar, will not be installed.) If you see this, you will
have to rebuild 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>
@ -160,17 +170,18 @@ su - postgres
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
Since PL/Python will be 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:
Python installation.
</para>
<para>
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
@ -282,7 +293,7 @@ JAVACMD=$JAVA_HOME/bin/java
<primary>yacc</primary>
</indexterm>
<acronym>GNU</> <application>Flex</> and <application>Bison</>
<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
@ -373,7 +384,7 @@ JAVACMD=$JAVA_HOME/bin/java
<primary>pg_dumpall</primary>
</indexterm>
To dump your database installation, type:
To back up your database installation, type:
<screen>
<userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
</screen>
@ -391,9 +402,16 @@ JAVACMD=$JAVA_HOME/bin/java
</para>
<para>
Make sure that you use the <command>pg_dumpall</> command
from the version you are currently running. &version;'s
<command>pg_dumpall</> should not be used on older databases.
To make the backup, you can use the <command>pg_dumpall</command>
command from the version you are currently running. For best
results, however, try to use the <command>pg_dumpall</command>
command from PostgreSQL &version;, since this version contains
bug fixes and improvements over older versions. While this
advice might seem idiosyncratic since you haven't installed the
new version yet, it is advisable to follow it if you plan to
install the new version in parallel with the old version. In
that case you can complete the installation normally and transfer
the data later. This will also decrease the downtime.
</para>
</step>
@ -453,12 +471,10 @@ JAVACMD=$JAVA_HOME/bin/java
</para>
<para>
You can also install the new version in parallel with the old one
to decrease the downtime. These topics are discussed at length in
<![%standalone-include[the <citetitle>Administrator's Guide</>,]]>
<![%standalone-ignore[<xref linkend="migration">,]]>
which you are encouraged
to read in any case.
These topics are discussed at length in <![%standalone-include[the
<citetitle>Administrator's Guide</>,]]> <![%standalone-ignore[<xref
linkend="migration">,]]> which you are encouraged to read in any
case.
</para>
</sect1>
@ -751,10 +767,6 @@ JAVACMD=$JAVA_HOME/bin/java
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
instead want to build a new complete interpreter binary, you
will have to do it manually.
</para>
</listitem>
</varlistentry>
@ -763,7 +775,7 @@ JAVACMD=$JAVA_HOME/bin/java
<term><option>--with-tcl</option></term>
<listitem>
<para>
Builds components that require Tcl/Tk, which are
Build components that require Tcl/Tk, which are
<application>libpgtcl</>, <application>pgtclsh</>,
<application>pgtksh</application>,
and <application>PL/Tcl</>. But see below about
@ -1106,7 +1118,7 @@ All of PostgreSQL is successfully made. Ready to install.
</procedure>
<formalpara>
<title>Uninstall:</title>
<title>Uninstallation:</title>
<para>
To undo the installation use the command <command>gmake
uninstall</>. However, this will not remove any created directories.
@ -1192,7 +1204,7 @@ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
<para>
On <systemitem class="osname">Cygwin</systemitem>, put the library
directory on the <envar>PATH</envar> or move the
directory in the <envar>PATH</envar> or move the
<filename>.dll</filename> files into the <filename>bin/</filename>
directory.
</para>

17
doc/src/sgml/libpq.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.98 2002/11/03 01:30:46 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.98.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="libpq">
@ -2139,22 +2139,23 @@ for information on correct values for these environment variables.
<primary>password</primary>
<secondary>.pgpass</secondary>
</indexterm>
<filename>$HOME/.pgpass</filename> is a file that can contain passwords
to be used if the connection requires a password. This file should have the
format:
<screen>
The file <filename>.pgpass</filename> in the home directory is a file
that can contain passwords to be used if the connection requires a
password. This file should have the format:
<synopsis>
<replaceable>hostname</replaceable>:<replaceable>port</replaceable>:<replaceable>database</replaceable>:<replaceable>username</replaceable>:<replaceable>password</replaceable>
</screen>
</synopsis>
Any of these may be a literal name, or <literal>*</literal>, which matches
anything. The first match will be used so put more specific entries first.
Entries with <literal>:</literal> or <literal>\</literal> should be escaped
with <literal>\</literal>.
</para>
<para>
The permissions on <filename>$HOME/.pgpass</filename> must disallow any
The permissions on <filename>.pgpass</filename> must disallow any
access to world or group; achieve this by the command
<command>chmod 0600 $HOME/.pgaccess</command>.
<command>chmod 0600 .pgaccess</command>.
If the permissions are less strict than this, the file will be ignored.
</para>
</sect1>
<sect1 id="libpq-threading">

19
doc/src/sgml/maintenance.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="maintenance">
@ -13,7 +13,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53
a regular basis to keep a <productname>PostgreSQL</productname>
installation running smoothly. The tasks discussed here are repetitive
in nature and can easily be automated using standard Unix tools such
as <filename>cron</filename> scripts. But it is the database
as <application>cron</application> scripts. But it is the database
administrator's responsibility to set up appropriate scripts, and to
check that they execute successfully.
</para>
@ -104,7 +104,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53
<command>UPDATE</> or <command>DELETE</> of a row does not
immediately remove the old <firstterm>tuple</> (version of the row).
This approach is necessary to gain the benefits of multiversion
concurrency control (see the <citetitle>User's Guide</>): the tuple
concurrency control (see the &cite-user;): the tuple
must not be deleted while it is still potentially visible to other
transactions. But eventually, an outdated or deleted tuple is no
longer of interest to any transaction. The space it occupies must be
@ -206,7 +206,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53
Although per-column tweaking of <command>ANALYZE</> frequency may not be
very productive, you may well find it worthwhile to do per-column
adjustment of the level of detail of the statistics collected by
<command>ANALYZE</>. Columns that are heavily used in WHERE clauses
<command>ANALYZE</>. Columns that are heavily used in <literal>WHERE</> clauses
and have highly irregular data distributions may require a finer-grain
data histogram than other columns. See <command>ALTER TABLE SET
STATISTICS</>.
@ -299,7 +299,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53
is exactly one billion transactions: if you wait longer, it's possible
that a tuple that was not quite old enough to be reassigned last time
is now more than two billion transactions old and has wrapped around
into the future --- ie, is lost to you. (Of course, it'll reappear
into the future --- i.e., is lost to you. (Of course, it'll reappear
after another two billion transactions, but that's no help.)
</para>
@ -311,17 +311,17 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.19 2002/09/21 18:32:53
statistics in the system table <filename>pg_database</>. In particular,
the <filename>datfrozenxid</> field of a database's
<filename>pg_database</> row is updated at the completion of any
database-wide vacuum operation (ie, <command>VACUUM</> that does not
database-wide vacuum operation (i.e., <command>VACUUM</> that does not
name a specific table). The value stored in this field is the freeze
cutoff XID that was used by that <command>VACUUM</> command. All normal
XIDs older than this cutoff XID are guaranteed to have been replaced by
<literal>FrozenXID</> within that database. A convenient way to
examine this information is to execute the query
<informalexample>
<programlisting>
SELECT datname, age(datfrozenxid) FROM pg_database;
</programlisting>
</informalexample>
The <literal>age</> column measures the number of transactions from the
cutoff XID to the current transaction's XID.
</para>
@ -336,7 +336,7 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
each database-wide <command>VACUUM</> automatically delivers a warning
if there are any <filename>pg_database</> entries showing an
<literal>age</> of more than 1.5 billion transactions, for example:
<informalexample>
<programlisting>
play=# vacuum;
WARNING: Some databases have not been vacuumed in 1613770184 transactions.
@ -344,7 +344,6 @@ WARNING: Some databases have not been vacuumed in 1613770184 transactions.
or you may have a wraparound failure.
VACUUM
</programlisting>
</informalexample>
</para>
<para>

4
doc/src/sgml/manage-ag.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.22 2002/10/24 17:48:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.22.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="managing-databases">
@ -27,7 +27,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.22 2002/10/24 17:48:54 p
database within the installation.) More accurately, a database is
a collection of schemas and the schemas contain the tables,
functions, etc. So the full hierarchy is:
server-database-schema-table (or something else instead of a
server, database, schema, table (or something else instead of a
table).
</para>

362
doc/src/sgml/monitoring.sgml
View file

@ -1,12 +1,12 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.14 2002/09/21 18:32:53 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.14.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="monitoring">
<title>Monitoring Database Activity</title>
<para>
A database administrator frequently wonders <quote>what is the system
A database administrator frequently wonders, <quote>What is the system
doing right now?</quote>
This chapter discusses how to find that out.
</para>
@ -19,7 +19,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.14 2002/09/21 18:32:53
<command>ps</> and <command>top</>. Also, once one has identified a
poorly-performing query, further investigation may be needed using
<productname>PostgreSQL</productname>'s <command>EXPLAIN</> command.
The <citetitle>User's Guide</citetitle> discusses <command>EXPLAIN</>
The &cite-user; discusses <command>EXPLAIN</>
and other methods for understanding the behavior of an individual
query.
</para>
@ -64,8 +64,8 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
The user, database, and connection source host items remain the same for
the life of the client connection, but the activity indicator changes.
The activity may be <literal>idle</> (ie, waiting for a client command),
<literal>idle in transaction</> (waiting for client inside a BEGIN block),
The activity may be <literal>idle</> (i.e., waiting for a client command),
<literal>idle in transaction</> (waiting for client inside a <command>BEGIN</> block),
or a command type name such as <literal>SELECT</>. Also,
<literal>waiting</> is attached if the server is presently waiting
on a lock held by another server process. In the above example we can infer
@ -149,7 +149,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<varname>STATS_BLOCK_LEVEL</varname>,
and <varname>STATS_ROW_LEVEL</varname>
default to <literal>false</>, no statistics are actually collected
in the default configuration! You must turn one or more of them on
in the default configuration. You must turn one or more of them on
before you will get useful results from the statistical display
functions.
</para>
@ -162,8 +162,9 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para>
Several predefined views are available to show the results of
statistics collection. Alternatively, one can build custom views
using the underlying statistics functions.
statistics collection, listed in <xref
linkend="monitoring-stats-views-table">. Alternatively, one can
build custom views using the underlying statistics functions.
</para>
<para>
@ -172,8 +173,8 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
Each individual server process transmits new access counts to the collector
just before waiting for another client command; so a query still in
progress does not affect the displayed totals. Also, the collector itself
emits new totals at most once per <varname>pgstat_stat_interval</varname> (500 milliseconds
by default). So the displayed totals lag behind actual activity.
emits new totals at most once per <varname>pgstat_stat_interval</varname> milliseconds
(500 by default). So the displayed totals lag behind actual activity.
</para>
<para>
@ -190,7 +191,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
block.
</para>
<table>
<table id="monitoring-stats-views-table">
<title>Standard Statistics Views</title>
<tgroup cols="2">
@ -204,9 +205,9 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<tbody>
<row>
<entry><structname>pg_stat_activity</></entry>
<entry>One row per server process, showing process <acronym>PID</>, database,
<entry>One row per server process, showing process <acronym>ID</>, database,
user, and current query. The current query column is only available
to superusers; for others it reads as NULL. (Note that because of
to superusers; for others it reads as null. (Note that because of
the collector's reporting delay, current query will only be up-to-date
for long-running queries.)</entry>
</row>
@ -215,7 +216,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<entry><structname>pg_stat_database</></entry>
<entry>One row per database, showing number of active backends,
total transactions committed and total rolled back in that database,
total disk blocks read, and total number of buffer hits (ie, block
total disk blocks read, and total number of buffer hits (i.e., block
read requests avoided by finding the block already in buffer cache).
</entry>
</row>
@ -230,13 +231,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<row>
<entry><structname>pg_stat_sys_tables</></entry>
<entry>Same as pg_stat_all_tables, except that only system tables
<entry>Same as <structname>pg_stat_all_tables</>, except that only system tables
are shown.</entry>
</row>
<row>
<entry><structname>pg_stat_user_tables</></entry>
<entry>Same as pg_stat_all_tables, except that only user tables
<entry>Same as <structname>pg_stat_all_tables</>, except that only user tables
are shown.</entry>
</row>
@ -244,20 +245,20 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<entry><structname>pg_stat_all_indexes</></entry>
<entry>For each index in the current database, the total number
of index scans that have used that index, the number of index tuples
read, and the number of successfully fetched heap tuples (this may
be less when there are index entries pointing to expired heap tuples).
read, and the number of successfully fetched heap tuples. (This may
be less when there are index entries pointing to expired heap tuples.)
</entry>
</row>
<row>
<entry><structname>pg_stat_sys_indexes</></entry>
<entry>Same as pg_stat_all_indexes, except that only indexes on
<entry>Same as <structname>pg_stat_all_indexes</>, except that only indexes on
system tables are shown.</entry>
</row>
<row>
<entry><structname>pg_stat_user_indexes</></entry>
<entry>Same as pg_stat_all_indexes, except that only indexes on
<entry>Same as <structname>pg_stat_all_indexes</>, except that only indexes on
user tables are shown.</entry>
</row>
@ -339,18 +340,19 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</para>
<para>
Other ways of looking at the statistics can be set up by writing queries
that use the same underlying statistics access functions as these standard
views do. The per-database access functions accept a database OID to
identify which database to report on. The per-table and per-index
functions accept a table or index OID (note that only tables and indexes
in the current
Other ways of looking at the statistics can be set up by writing
queries that use the same underlying statistics access functions as
these standard views do. These functions are listed in <xref
linkend="monitoring-stats-funcs-table">. The per-database access
functions accept a database OID to identify which database to
report on. The per-table and per-index functions accept a table or
index OID (note that only tables and indexes in the current
database can be seen with these functions). The per-backend access
functions accept a backend ID number, which ranges from one to the number
of currently active backends.
functions accept a backend ID number, which ranges from one to the
number of currently active backends.
</para>
<table>
<table id="monitoring-stats-funcs-table">
<title>Statistics Access Functions</title>
<tgroup cols="3">
@ -531,11 +533,14 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</tgroup>
</table>
<para>
Note: blocks_fetched minus blocks_hit gives the number of kernel read()
calls issued for the table, index, or database; but the actual number of
physical reads is usually lower due to kernel-level buffering.
</para>
<note>
<para>
Blocks_fetched minus blocks_hit gives the number of kernel
<function>read()</> calls issued for the table, index, or
database; but the actual number of physical reads is usually
lower due to kernel-level buffering.
</para>
</note>
<para>
The function <function>pg_stat_get_backend_idset</function> provides
@ -552,157 +557,168 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
</sect2>
</sect1>
<sect1 id="monitoring-locks">
<title>Viewing Locks</title>
<sect1 id="monitoring-locks">
<title>Viewing Locks</title>
<para>
Another useful tool for monitoring database activity is the
<literal>pg_locks</literal> system catalog. This allows the
database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be used
to:
<itemizedlist>
<listitem>
<para>
View all the locks currently outstanding, all the locks on
relations in a particular database, all the locks on a
particular relation, or all the locks held by a particular
<productname>PostgreSQL</productname> session.
</para>
</listitem>
<listitem>
<para>
View the relation in the current database with the most
ungranted locks (which might be a source of contention among
database clients).
</para>
</listitem>
<listitem>
<para>
Determine the effect of lock contention on overall database
performance, as well as the extent to which contention varies
with overall database traffic.
</para>
</listitem>
</itemizedlist>
For more information on locking and managing concurrency with
<productname>PostgreSQL</productname>, refer to the &cite-user;.
</para>
<note>
<para>
Another useful tool for monitoring database activity is the
<literal>pg_locks</literal> system catalog. This allows the
database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be
used to:
<itemizedlist>
<listitem>
<para>
View all the locks currently outstanding, all the locks on
relations in a particular database, all the locks on a
particular relation, or all the locks held by a particular
<productname>PostgreSQL</productname> backend.
</para>
</listitem>
<listitem>
<para>
View the relation in the current database with the most
un-granted locks (which might be a source of contention among
database clients).
</para>
</listitem>
<listitem>
<para>
Determine the effect of lock contention on overall database
performance, as well as the extent to which contention varies
with overall database traffic.
</para>
</listitem>
</itemizedlist>
For more information on locking and managing concurrency with
<productname>PostgreSQL</productname>, refer to the
<citetitle>Administrator's Guide</citetitle>.
When the <literal>pg_locks</literal> view is accessed, the
internal lock manager data structures are momentarily locked, and
a copy is made for the view to display. This ensures that the
view produces a consistent set of results, while not blocking
normal lock manager operations longer than necessary. Nonetheless
there could be some impact on database performance if this view is
examined often.
</para>
</note>
<note>
<para>
When the <literal>pg_locks</literal> view is accessed, the
internal lock manager data structures are momentarily locked,
and a copy is made for the view to display. This ensures that
the view produces a consistent set of results, while not blocking
normal lock manager operations longer than necessary. Nonetheless
there could be some impact on database performance if this view is
examined often.
</para>
</note>
<para>
<xref linkend="monitoring-locks-table"> shows the definition of the
<literal>pg_locks</literal> columns. The
<literal>pg_locks</literal> view contains one row per lockable
object and requested lock mode. Thus, the same lockable object may
appear many times, if multiple transactions are holding or waiting
for locks on it. A lockable object is either a relation or a
transaction ID. (Note that this view includes only table-level
locks, not row-level ones. If a transaction is waiting for a
row-level lock, it will appear in the view as waiting for the
transaction ID of the current holder of that row lock.)
</para>
<para>
The <literal>pg_locks</literal> view contains one row per lockable
object and requested lock mode. Thus, the same lockable object
may appear many times, if multiple transactions are holding or
waiting for locks on it. A lockable object is either a relation
or a transaction ID. (Note that this view includes only table-level
locks, not row-level ones. If a transaction is waiting for a
row-level lock, it will appear in the view as waiting for the
transaction ID of the current holder of that row lock.)
</para>
<table id="monitoring-locks-table">
<title>Lock Status System View</title>
<table>
<title>Lock Status System View</title>
<tgroup cols="3">
<thead>
<row>
<entry>Column Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tgroup cols="3">
<thead>
<row>
<entry>Column Name</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>relation</structfield></entry>
<entry><type>oid</type></entry>
<entry>
The OID of the locked relation, or null if the lockable object
is a transaction ID. This column can be joined with the
<literal>pg_class</literal> system catalog to get more
information on the locked relation. Note however that this
will only work for relations in the current database (those for
which the <structfield>database</structfield> column is either
the current database's OID or zero).
</entry>
</row>
<tbody>
<row>
<entry><structfield>relation</structfield></entry>
<entry><type>oid</type></entry>
<entry>The OID of the locked relation, or NULL if the lockable
object is a transaction ID. This column can be joined
with the <literal>pg_class</literal> system catalog to get more
information on the locked relation. Note however that this will
only work for relations in the current database (those for which
the <structfield>database</structfield> column is either the
current database's OID or zero).
</entry>
</row>
<row>
<entry><structfield>database</structfield></entry>
<entry><type>oid</type></entry>
<entry>
The OID of the database in which the locked relation exists, or
null if the lockable object is a transaction ID. If the lock
is on a globally-shared table, this field will be zero. This
column can be joined with the <literal>pg_database</literal>
system catalog to get more information on the locked object's
database.
</entry>
</row>
<row>
<entry><structfield>database</structfield></entry>
<entry><type>oid</type></entry>
<entry>The OID of the database in which the locked relation
exists, or NULL if the lockable object is a transaction ID.
If the lock is on a globally-shared table, this field will be
zero. This
column can be joined with the <literal>pg_database</literal>
system catalog to get more information on the locked object's
database.
</entry>
</row>
<row>
<entry><structfield>transaction</structfield></entry>
<entry><type>xid</type></entry>
<entry>
The ID of a transaction, or null if the lockable object is a
relation. Every transaction holds an exclusive lock on its
transaction ID for its entire duration. If one transaction
finds it necessary to wait specifically for another
transaction, it does so by attempting to acquire share lock on
the other transaction ID. That will succeed only when the
other transaction terminates and releases its locks.
</entry>
</row>
<row>
<entry><structfield>transaction</structfield></entry>
<entry><type>xid</type></entry>
<entry>The ID of a transaction, or NULL if the lockable object
is a relation. Every transaction holds an exclusive lock on its
transaction ID for its entire duration. If one transaction finds
it necessary to wait specifically for another transaction, it
does so by attempting to acquire share lock on the other transaction
ID. That will succeed only when the other transaction terminates
and releases its locks.
</entry>
</row>
<row>
<entry><structfield>pid</structfield></entry>
<entry><type>integer</type></entry>
<entry>
The process ID of the <productname>PostgreSQL</productname>
backend belonging to the session that has acquired or is
attempting to acquire the lock. If you have enabled the
statistics collector, this column can be joined with the
<literal>pg_stat_activity</literal> view to get more
information on the backend holding or waiting to hold the
lock.
</entry>
</row>
<row>
<entry><structfield>pid</structfield></entry>
<entry><type>int4</type></entry>
<entry>The process ID of the
<productname>PostgreSQL</productname> backend that has
acquired or is attempting to acquire the lock. If you have
enabled the statistics collector, this column can be joined
with the <literal>pg_stat_activity</literal> view to get
more information on the backend holding or waiting to hold the
lock.</entry>
</row>
<row>
<entry><structfield>mode</structfield></entry>
<entry><type>text</type></entry>
<entry>
The mode of the requested or held lock on the lockable
object. For more information on the different lock modes
available in <productname>PostgreSQL</productname>, refer to
the &cite-user;.
</entry>
</row>
<row>
<entry><structfield>mode</structfield></entry>
<entry><type>text</type></entry>
<entry>The mode of the requested or held lock on the lockable
object. For more information on the
different lock modes available in
<productname>PostgreSQL</productname>, refer to the
<citetitle>User's Guide</citetitle>.</entry>
</row>
<row>
<entry><structfield>isgranted</structfield></entry>
<entry><type>bool</type></entry>
<entry>True if this lock has been granted (is held by this
backend). False indicates that this backend is currently
waiting to acquire this lock, which implies that some other
backend is holding a conflicting lock mode on the same lockable
object. This backend will sleep until the other lock is released
(or a deadlock situation is detected). A single backend can be
waiting to acquire at most one lock at a time.</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<row>
<entry><structfield>isgranted</structfield></entry>
<entry><type>boolean</type></entry>
<entry>
True if this lock has been granted (is held by this session).
False indicates that this session is currently waiting to
acquire this lock, which implies that some other session is
holding a conflicting lock mode on the same lockable object.
This backend will sleep until the other lock is released (or a
deadlock situation is detected). A single backend can be
waiting to acquire at most one lock at a time.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file

34
doc/src/sgml/query.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27 2002/10/24 17:48:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="tutorial-sql">
@ -13,7 +13,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27 2002/10/24 17:48:54 peter
<acronym>SQL</acronym> to perform simple operations. This
tutorial is only intended to give you an introduction and is in no
way a complete tutorial on <acronym>SQL</acronym>. Numerous books
have been written on <acronym>SQL92</acronym>, including <xref
have been written on <acronym>SQL</acronym>, including <xref
linkend="MELT93"> and <xref linkend="DATE97">.
You should be aware that some <productname>PostgreSQL</productname>
language features are extensions to the standard.
@ -44,7 +44,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.27 2002/10/24 17:48:54 peter
The <literal>\i</literal> command reads in commands from the
specified file. The <literal>-s</literal> option puts you in
single step mode which pauses before sending each query to the
single step mode which pauses before sending each statement to the
server. The commands used in this section are in the file
<filename>basics.sql</filename>.
</para>
@ -502,7 +502,7 @@ SELECT *
join operator will have each of its rows in the output at least
once, whereas the table on the right will only have those rows
output that match some row of the left table. When outputting a
left-table row for which there is no right-table match, empty (NULL)
left-table row for which there is no right-table match, empty (null)
values are substituted for the right-table columns.
</para>
@ -601,7 +601,7 @@ SELECT max(temp_lo) FROM weather;
<para>
<indexterm><primary>subquery</primary></indexterm>
If we want to know what city (or cities) that reading occurred in,
If we wanted to know what city (or cities) that reading occurred in,
we might try
<programlisting>
@ -615,7 +615,7 @@ SELECT city FROM weather WHERE temp_lo = max(temp_lo); <lineannotation>WRONG
go into the aggregation stage; so it has to be evaluated before
aggregate functions are computed.)
However, as is often the case
the query can be restated to accomplish the intended result; here
the query can be restated to accomplish the intended result, here
by using a <firstterm>subquery</firstterm>:
<programlisting>
@ -630,9 +630,9 @@ SELECT city FROM weather
(1 row)
</screen>
This is OK because the sub-select is an independent computation
This is OK because the subquery is an independent computation
that computes its own aggregate separately from what is happening
in the outer select.
in the outer query.
</para>
<para>
@ -684,10 +684,18 @@ SELECT city, max(temp_lo)
<programlisting>
SELECT city, max(temp_lo)
FROM weather
WHERE city LIKE 'S%'
WHERE city LIKE 'S%'<co id="co.tutorial-agg-like">
GROUP BY city
HAVING max(temp_lo) < 40;
</programlisting>
<calloutlist>
<callout arearefs="co.tutorial-agg-like">
<para>
The <literal>LIKE</literal> operator does pattern matching and
is explained in the &cite-user;.
</para>
</callout>
</calloutlist>
</para>
<para>
@ -729,7 +737,7 @@ SELECT city, max(temp_lo)
You can update existing rows using the
<command>UPDATE</command> command.
Suppose you discover the temperature readings are
all off by 2 degrees as of November 28, you may update the
all off by 2 degrees as of November 28. You may update the
data as follows:
<programlisting>
@ -762,8 +770,8 @@ SELECT * FROM weather;
</indexterm>
<para>
Suppose you are no longer interested in the weather of Hayward,
then you can do the following to delete those rows from the table.
Suppose you are no longer interested in the weather of Hayward.
Then you can do the following to delete those rows from the table.
Deletions are performed using the <command>DELETE</command>
command:
<programlisting>
@ -786,7 +794,7 @@ SELECT * FROM weather;
</para>
<para>
One should be wary of queries of the form
One should be wary of statements of the form
<synopsis>
DELETE FROM <replaceable>tablename</replaceable>;
</synopsis>

482
doc/src/sgml/runtime.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.147.2.1 2002/11/05 23:17:45 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.147.2.2 2002/11/06 23:30:39 petere Exp $
-->
<Chapter Id="runtime">
@ -11,7 +11,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.147.2.1 2002/11/05 23:17:4
</para>
<sect1 id="postgres-user">
<title>The <productname>PostgreSQL</productname> user account</title>
<title>The <productname>PostgreSQL</productname> User Account</title>
<indexterm>
<primary>postgres user</primary>
@ -37,7 +37,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.147.2.1 2002/11/05 23:17:4
</sect1>
<sect1 id="creating-cluster">
<title>Creating a database cluster</title>
<title>Creating a Database Cluster</title>
<indexterm>
<primary>database cluster</primary>
@ -152,7 +152,7 @@ set to "C". For more information see the Administrator's Guide.
</screen>
This is intended to warn you that the currently selected locale
will cause indexes to be sorted in an order that prevents them from
being used for LIKE and regular-expression searches. If you need
being used for <literal>LIKE</> and regular-expression searches. If you need
good performance in such searches, you should set your current
locale to <literal>C</> and re-run <command>initdb</command>, e.g.,
by running <literal>initdb --lc-collate=C</literal>. The sort
@ -165,7 +165,7 @@ set to "C". For more information see the Administrator's Guide.
</sect1>
<sect1 id="postmaster-start">
<title>Starting the database server</title>
<title>Starting the Database Server</title>
<para>
<indexterm>
@ -229,7 +229,7 @@ pg_ctl start -l logfile
<para>
Normally, you will want to start the database server when the
computer boots. Auto-start scripts are operating-system specific.
computer boots. Autostart scripts are operating system-specific.
There are a few distributed with
<productname>PostgreSQL</productname> in the
<filename>/contrib/start-scripts</> directory. This may require root
@ -384,13 +384,13 @@ IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on
means your kernel's limit on the number of System V semaphores is
smaller than the number <productname>PostgreSQL</productname> wants
to create. As above, you may be able to work around the problem by
starting the postmaster with a reduced number of backend processes
starting the postmaster with a reduced number of allowed connections
(<option>-N</option> switch), but you'll eventually want to
increase the kernel limit.
</para>
<para>
If you get an <quote>illegal system call</> error, it is likely
If you get an <quote>illegal system call</> error, it is likely that
shared memory or semaphores are not supported in your kernel at
all. In that case your only option is to reconfigure the kernel to
enable these features.
@ -456,7 +456,7 @@ psql: could not connect to server: Connection refused
</sect1>
<sect1 id="runtime-config">
<Title>Run-time configuration</Title>
<Title>Run-time Configuration</Title>
<indexterm>
<primary>configuration</primary>
@ -558,7 +558,7 @@ env PGOPTIONS='-c geqo=off' psql
<title>pg_settings</title>
<para>
<structname>pg_settings</structname> virtual table allows display and update
The <structname>pg_settings</structname> virtual table allows display and update
of current session run-time parameters. There is one entry for each of the
available parameters provided by <command>SHOW ALL</command>. But it is
in a form that allows it to be joined with other relations and have a
@ -579,28 +579,25 @@ env PGOPTIONS='-c geqo=off' psql
<table>
<title>pg_settings Columns</title>
<tgroup cols=4>
<tgroup cols=3>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>name</entry>
<entry><literal>name</literal></entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>The name of a current session run-time parameter</entry>
</row>
<row>
<entry>setting</entry>
<entry><literal>setting</literal></entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>The value of a current session run-time parameter</entry>
</row>
</tbody>
@ -630,7 +627,7 @@ env PGOPTIONS='-c geqo=off' psql
<listitem>
<para>
Sets the optimizer's estimate of the cost of processing each
operator in a WHERE clause. This is measured as a fraction of
operator in a <literal>WHERE</> clause. This is measured as a fraction of
the cost of a sequential page fetch.
</para>
</listitem>
@ -860,85 +857,93 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>SERVER_MIN_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
This controls how much detail is written to the server logs. The
default is <literal>NOTICE</>. Valid values are <literal>DEBUG5</>,
This controls how much message detail is written to the server
logs. Valid values are <literal>DEBUG5</>,
<literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
<literal>DEBUG1</>, <literal>INFO</>, <literal>NOTICE</>,
<literal>WARNING</>, <literal>ERROR</>, <literal>LOG</>,
<literal>FATAL</>, and <literal>PANIC</>. Later values send less
detail to the logs. <literal>LOG</> has a different precedence
here than in <literal>CLIENT_MIN_MESSAGES</>.
<literal>WARNING</>, <literal>ERROR</>, <literal>LOG</>,
<literal>FATAL</>, and <literal>PANIC</>. Later values send
less detail to the logs. The default is <literal>NOTICE</>.
Note that <literal>LOG</> has a different precedence here than
in <literal>CLIENT_MIN_MESSAGES</>.
</para>
<para>
Here is a summary of the various message types:
<variablelist>
<varlistentry>
<term><varname>DEBUG[1-5]</varname></term>
<term><literal>DEBUG[1-5]</literal></term>
<listitem>
<para>
This provides information for use by developers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>INFO</varname></term>
<listitem>
<para>
This provides information requested by the user, e.g.
<command>SET</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>NOTICE</varname></term>
<listitem>
<para>
This provides information that may be helpful to users, e.g.
truncation of long identifiers, sequence creation as part of
<command>SERIAL</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>WARNING</varname></term>
<listitem>
<para>
This provides warnings to the user, e.g. <command>COMMIT</>
outside a transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>ERROR</varname></term>
<listitem>
<para>
Reports the error that caused the transaction to abort.
Provides information for use by developers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LOG</varname></term>
<term><literal>INFO</literal></term>
<listitem>
<para>
This reports information of interest to administrators, e.g.
Provides information implicitly requested by the user,
e.g., during <command>VACUUM VERBOSE</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>NOTICE</literal></term>
<listitem>
<para>
Provides information that may be helpful to users, e.g.,
truncation of long identifiers and index creation as part
of primary keys.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>WARNING</literal></term>
<listitem>
<para>
Provides warnings to the user, e.g., <command>COMMIT</>
outside a transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ERROR</literal></term>
<listitem>
<para>
Reports the error that caused a transaction to abort.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>LOG</literal></term>
<listitem>
<para>
Reports information of interest to administrators, e.g.,
checkpoint activity.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>FATAL</varname></term>
<term><literal>FATAL</literal></term>
<listitem>
<para>
This reports why the backend session terminated.
Reports why a backend session terminated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PANIC</varname></term>
<term><literal>PANIC</literal></term>
<listitem>
<para>
This reports why all backends restarted.
Reports why all backend sessions restarted.
</para>
</listitem>
</varlistentry>
@ -951,15 +956,15 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>CLIENT_MIN_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
This controls how much detail is written to the client. The
default is <literal>NOTICE</>. Valid values are
<literal>DEBUG5</>, <literal>DEBUG4</>, <literal>DEBUG3</>,
<literal>DEBUG2</>, <literal>DEBUG1</>, <literal>LOG</>,
<literal>NOTICE</>, <literal>WARNING</>, and <literal>ERROR</>.
Later values send less information to the user. <literal>LOG</>
has a different precedence here than in
<literal>SERVER_MIN_MESSAGES</>. Also see that section for an
explanation of the various values.
This controls how much message detail is written to the
client. Valid values are <literal>DEBUG5</>,
<literal>DEBUG4</>, <literal>DEBUG3</>, <literal>DEBUG2</>,
<literal>DEBUG1</>, <literal>LOG</>, <literal>NOTICE</>,
<literal>WARNING</>, and <literal>ERROR</>. Later values send
less information to the client. The default is
<literal>NOTICE</>. Note that <literal>LOG</> has a different
precedence here than in <literal>SERVER_MIN_MESSAGES</>. Also
see that section for an explanation of the various values.
</para>
</listitem>
</varlistentry>
@ -973,7 +978,7 @@ env PGOPTIONS='-c geqo=off' psql
to turn this on, as it might expose programming mistakes. To use
this option, the macro <literal>USE_ASSERT_CHECKING</literal>
must be defined when <productname>PostgreSQL</productname> is
built (accomplished by the configure option
built (accomplished by the <command>configure</command> option
<option>--enable-cassert</option>). Note that
<literal>DEBUG_ASSERTIONS</literal> defaults to on if
<productname>PostgreSQL</productname> has been built with
@ -990,7 +995,7 @@ env PGOPTIONS='-c geqo=off' psql
<listitem>
<para>
These flags enable various debugging output to be sent to the
server log. For each executed query, prints either the query text,
server log. For each executed query, print either the query text,
the resulting parse tree, the query rewriter output, or the execution
plan. <option>DEBUG_PRETTY_PRINT</option> indents these displays
to produce a more readable but much longer output format.
@ -1032,22 +1037,39 @@ env PGOPTIONS='-c geqo=off' psql
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LOG_DURATION</varname> (<type>boolean</type>)</term>
<listitem>
<para>
Causes the duration of every completed statement to be logged.
To use this option, enable <varname>LOG_STATEMENT</> and
<varname>LOG_PID</> so you can link the statement to the
duration using the process ID.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LOG_MIN_ERROR_STATEMENT</varname> (<type>string</type>)</term>
<listitem>
<para>
This controls which message types output the original query to
the server logs. All queries matching the setting or higher are
logged. The default is <literal>PANIC</literal> (effectively
"off"). Valid values are <literal>DEBUG5</literal>,
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>,
<literal>DEBUG2</literal>, <literal>DEBUG1</literal>,
<literal>INFO</literal>, <literal>NOTICE</literal>,
<literal>WARNING</literal>, <literal>ERROR</literal>,
<literal>FATAL</literal>, and <literal>PANIC</literal>.
This controls for which message levels the SQL statement
causing that message is to be recorded in the server log. All
statements causing a message of the level of the setting or
higher are logged. The default is <literal>PANIC</literal>
(effectively turning this feature off). Valid values are
<literal>DEBUG5</literal>, <literal>DEBUG4</literal>,
<literal>DEBUG3</literal>, <literal>DEBUG2</literal>,
<literal>DEBUG1</literal>, <literal>INFO</literal>,
<literal>NOTICE</literal>, <literal>WARNING</literal>,
<literal>ERROR</literal>, <literal>FATAL</literal>, and
<literal>PANIC</literal>. For example, if you set this to
<literal>ERROR</literal> then all SQL statements causing
errors, fatal errors, or panics will be logged.
</para>
<para>
It is recommended you enable <literal>LOG_PID</literal> as well
It is recommended you enable <varname>LOG_PID</varname> as well
so you can more easily match the error statement with the error
message.
</para>
@ -1071,18 +1093,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>LOG_STATEMENT</varname> (<type>boolean</type>)</term>
<listitem>
<para>
Prints each query received.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>LOG_DURATION</varname> (<type>boolean</type>)</term>
<listitem>
<para>
Prints the duration of every completed query. To use this option,
enable <literal>LOG_STATEMENT</> and <literal>LOG_PID</> so you
can link the original query to the duration using the process id.
Causes each SQL statement to be logged.
</para>
</listitem>
</varlistentry>
@ -1186,9 +1197,12 @@ env PGOPTIONS='-c geqo=off' psql
This option determines the <application>syslog</application>
<quote>facility</quote> to be used when
<application>syslog</application> is enabled. You may choose
from LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6,
LOCAL7; the default is LOCAL0. See also the documentation of
your system's <application>syslog</application>.
from <literal>LOCAL0</>, <literal>LOCAL1</>,
<literal>LOCAL2</>, <literal>LOCAL3</>, <literal>LOCAL4</>,
<literal>LOCAL5</>, <literal>LOCAL6</>, <literal>LOCAL7</>;
the default is <literal>LOCAL0</>. See also the
documentation of your system's
<application>syslog</application>.
</para>
</listitem>
</varlistentry>
@ -1221,12 +1235,12 @@ env PGOPTIONS='-c geqo=off' psql
</sect2>
<sect2 id="runtime-config-general">
<title>General operation</title>
<title>General Operation</title>
<para>
<variablelist>
<varlistentry>
<term><varname>AUTOCOMMIT</varname> (<type>bool</type>)</term>
<term><varname>AUTOCOMMIT</varname> (<type>boolean</type>)</term>
<indexterm><primary>autocommit</></>
<listitem>
<para>
@ -1254,7 +1268,7 @@ env PGOPTIONS='-c geqo=off' psql
Once another command is issued, a transaction block
begins and any <command>SET</>, <command>SHOW</>, or
<command>RESET</> commands are considered to be part of the
transaction, i.e. they are committed or rolled back depending
transaction, i.e., they are committed or rolled back depending
on the completion status of the transaction. To execute a
<command>SET</>, <command>SHOW</>, or <command>RESET</>
command at the start of a transaction block, use <command>BEGIN</>
@ -1276,7 +1290,7 @@ env PGOPTIONS='-c geqo=off' psql
</varlistentry>
<varlistentry>
<term><varname>AUSTRALIAN_TIMEZONES</varname> (<type>bool</type>)</term>
<term><varname>AUSTRALIAN_TIMEZONES</varname> (<type>boolean</type>)</term>
<indexterm><primary>Australian time zones</></>
<listitem>
<para>
@ -1330,19 +1344,33 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>DB_USER_NAMESPACE</varname> (<type>boolean</type>)</term>
<listitem>
<para>
This allows per-database user names. You can create users as <literal>
username@dbname</>. When <literal>username</> is passed by the client,
<literal>@</> and the database name is appended to the user name and
that database-specific user name is looked up by the server.
When creating user names containing <literal>@</>, you will need
to quote the user name.
This allows per-database user names. It is off by default.
</para>
<para>
With this option enabled, you can still create ordinary global
users. Simply append <literal>@</> when specifying the user name
in the client. The <literal>@</> will be stripped off and looked up
by the server.
If this is on, create users as <literal> username@dbname</>.
When <literal>username</> is passed by a connecting client,
<literal>@</> and the database name is appended to the user
name and that database-specific user name is looked up by the
server. Note that when you create users with names containing
<literal>@</> within the SQL environment, you will need to
quote the user name.
</para>
<para>
With this option enabled, you can still create ordinary global
users. Simply append <literal>@</> when specifying the user
name in the client. The <literal>@</> will be stripped off
before the user name is looked up by the server.
</para>
<note>
<para>
This feature is intended as a temporary measure until a
complete solution is found. At that time, this option will
be removed.
</para>
</note>
</listitem>
</varlistentry>
@ -1393,7 +1421,7 @@ env PGOPTIONS='-c geqo=off' psql
</para>
<para>
Consult the <citetitle>PostgreSQL User's Guide</citetitle> and
Consult the &cite-user; and
the command <command>SET TRANSACTION</command> for more
information.
</para>
@ -1424,11 +1452,9 @@ env PGOPTIONS='-c geqo=off' psql
distribution are installed. (Use <literal>pg_config
--pkglibdir</literal> to print the name of this directory.) For
example:
<informalexample>
<programlisting>
dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</programlisting>
</informalexample>
</para>
<para>
@ -1666,8 +1692,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<listitem>
<para>
When a password is specified in <command>CREATE USER</> or
<command>ALTER USER</> without writing either ENCRYPTED or
UNENCRYPTED, this flag determines whether the password is to be
<command>ALTER USER</> without writing either <literal>ENCRYPTED</> or
<literal>UNENCRYPTED</>, this flag determines whether the password is to be
encrypted. The default is on (encrypt the password).
</para>
</listitem>
@ -1690,37 +1716,37 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<indexterm><primary>namespaces</></>
<listitem>
<para>
This variable specifies the order in which namespaces are searched
when an object (table, data type, function, etc) is referenced by a
This variable specifies the order in which schemas are searched
when an object (table, data type, function, etc.) is referenced by a
simple name with no schema component. When there are objects of
identical names in different namespaces, the one found first
identical names in different schemas, the one found first
in the search path is used. An object that is not in any of the
namespaces in the search path can only be referenced by specifying
its containing namespace with a qualified (dotted) name.
schemas in the search path can only be referenced by specifying
its containing schema with a qualified (dotted) name.
</para>
<para>
The value for search_path has to be a comma-separated
list of namespace (schema) names. If one of the list items is
the special value <literal>$user</literal>, then the namespace
having the same name as the SESSION_USER is substituted, if there
is such a namespace. (If not, <literal>$user</literal> is ignored.)
The value for <varname>search_path</varname> has to be a comma-separated
list of schema names. If one of the list items is
the special value <literal>$user</literal>, then the schema
having the same name as the <function>SESSION_USER</> is substituted, if there
is such a schema. (If not, <literal>$user</literal> is ignored.)
</para>
<para>
The system catalog namespace, <literal>pg_catalog</>, is always
The system catalog schema, <literal>pg_catalog</>, is always
searched, whether it is mentioned in the path or not. If it is
mentioned in the path then it will be searched in the specified
order. If <literal>pg_catalog</> is not in the path then it will
be searched <emphasis>before</> searching any of the path items.
It should also be noted that the temporary-table namespace,
<literal>pg_temp_nnn</>, is implicitly searched before any of
It should also be noted that the temporary-table schema,
<literal>pg_temp_<replaceable>nnn</></>, is implicitly searched before any of
these.
</para>
<para>
When objects are created without specifying a particular target
namespace, they will be placed in the first namespace listed
schema, they will be placed in the first schema listed
in the search path. An error is reported if the search path is
empty.
</para>
@ -1728,21 +1754,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<para>
The default value for this parameter is
<literal>'$user, public'</literal> (where the second part will be
ignored if there is no namespace named <literal>public</>).
ignored if there is no schema named <literal>public</>).
This supports shared use of a database (where no users
have private namespaces, and all share use of <literal>public</>),
private per-user namespaces, and combinations of these. Other
have private schemas, and all share use of <literal>public</>),
private per-user schemas, and combinations of these. Other
effects can be obtained by altering the default search path
setting, either globally or per-user.
</para>
<para>
By default, a newly created database will contain a world-writable
namespace named <literal>public</>, but no private namespaces.
The administrator may choose to restrict permissions on
<literal>public</> or even remove it, if that suits his purposes.
</para>
<para>
<indexterm>
<primary>schemas</primary>
@ -1755,6 +1774,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
shows how the requests appearing in <varname>search_path</varname>
were resolved.
</para>
<para>
For more information on schema handling, see the &cite-user;.
</para>
</listitem>
</varlistentry>
@ -1783,10 +1806,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<term><varname>SILENT_MODE</varname> (<type>bool</type>)</term>
<listitem>
<para>
Runs postmaster silently. If this option is set, the postmaster
Runs the server silently. If this option is set, the server
will automatically run in background and any controlling ttys
are disassociated, thus no messages are written to standard
output or standard error (same effect as postmaster's -S
output or standard error (same effect as <command>postmaster</>'s <option>-S</option>
option). Unless some logging system such as
<application>syslog</> is enabled, using this option is
discouraged since it makes it impossible to see error messages.
@ -1800,14 +1823,14 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<para>
Specifies the amount of memory to be used by internal sorts and
hashes before switching to temporary disk files. The value is
specified in kilobytes, and defaults to 1024 kilobytes (1MB).
specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
Note that for a complex query, several sorts might be running in
parallel, and each one will be allowed to use as much memory as
this value specifies before it starts to put data into temporary
files. Also, each running backend could be doing one or more
sorts simultaneously, so the total memory used could be many
times the value of <varname>SORT_MEM</varname>. Sorts are used
by ORDER BY, merge joins, and CREATE INDEX.
by <literal>ORDER BY</>, merge joins, and <command>CREATE INDEX</>.
</para>
</listitem>
</varlistentry>
@ -1823,8 +1846,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
behavior you can set this variable to off, but in the long run
you are encouraged to change your applications to use the
<literal>ONLY</literal> keyword to exclude subtables. See the
SQL language reference and the <citetitle>User's
Guide</citetitle> for more information about inheritance.
SQL language reference and the &cite-user; for more information about inheritance.
</para>
</listitem>
</varlistentry>
@ -1863,7 +1885,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<para>
Sets the time zone for displaying and interpreting timestamps.
The default is to use whatever the system environment
specifies as the timezone.
specifies as the time zone.
</para>
</listitem>
</varlistentry>
@ -1877,10 +1899,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<literal><replaceable>expr</> = NULL</literal> (or <literal>NULL
= <replaceable>expr</></literal>) are treated as
<literal><replaceable>expr</> IS NULL</literal>, that is, they
return true if <replaceable>expr</> evaluates to the NULL value,
return true if <replaceable>expr</> evaluates to the null value,
and false otherwise. The correct behavior of
<literal><replaceable>expr</> = NULL</literal> is to always
return NULL (unknown). Therefore this option defaults to off.
return null (unknown). Therefore this option defaults to off.
</para>
<para>
@ -1890,11 +1912,11 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
null values, so if you use that interface to access the database you
might want to turn this option on. Since expressions of the
form <literal><replaceable>expr</> = NULL</literal> always
return NULL (using the correct interpretation) they are not
return the null value (using the correct interpretation) they are not
very useful and do not appear often in normal applications, so
this option does little harm in practice. But new users are
frequently confused about the semantics of expressions
involving NULL, so this option is not on by default.
involving null values, so this option is not on by default.
</para>
<para>
@ -1906,8 +1928,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</para>
<para>
Refer to the <citetitle>User's Guide</citetitle> for related
information.
Refer to the &cite-user; for related information.
</para>
</listitem>
</varlistentry>
@ -1917,7 +1938,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<listitem>
<para>
Specifies the directory of the Unix-domain socket on which the
<application>postmaster</application> is to listen for
server is to listen for
connections from client applications. The default is normally
<filename>/tmp</filename>, but can be changed at build time.
</para>
@ -1930,7 +1951,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<para>
Sets the group owner of the Unix domain socket. (The owning
user of the socket is always the user that starts the
postmaster.) In combination with the option
server.) In combination with the option
<option>UNIX_SOCKET_PERMISSIONS</option> this can be used as
an additional access control mechanism for this socket type.
By default this is the empty string, which uses the default
@ -1958,7 +1979,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
anyone can connect. Reasonable alternatives are
<literal>0770</literal> (only user and group, see also under
<option>UNIX_SOCKET_GROUP</option>) and <literal>0700</literal>
(only user). (Note that actually for a Unix socket, only write
(only user). (Note that actually for a Unix domain socket, only write
permission matters and there is no point in setting or revoking
read or execute permissions.)
</para>
@ -2046,8 +2067,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
enough additional transactions may become ready to commit within
the given interval. But the delay is just wasted if no other
transactions become ready to commit. Therefore, the delay is
only performed if at least COMMIT_SIBLINGS other transactions
are active at the instant that a backend has written its commit
only performed if at least <varname>COMMIT_SIBLINGS</varname> other transactions
are active at the instant that a backend process has written its commit
record.
</para>
</listitem>
@ -2079,7 +2100,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<term><varname>WAL_DEBUG</varname> (<type>integer</type>)</term>
<listitem>
<para>
If non-zero, turn on WAL-related debugging output on standard
If nonzero, turn on WAL-related debugging output on standard
error.
</para>
</listitem>
@ -2106,107 +2127,111 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</sect2>
<sect2 id="runtime-config-short">
<title>Short options</title>
<sect2 id="runtime-config-short">
<title>Short Options</title>
<para>
For convenience there are also single letter option switches
available for many parameters. They are described in the following
table.
available for many parameters. They are described in <xref
linkend="runtime-config-short-table">.
</para>
<table>
<table id="runtime-config-short-table">
<title>Short option key</title>
<tgroup cols="3">
<colspec colnum="3" align="center">
<tgroup cols="2">
<thead>
<row>
<entry>Short option</entry>
<entry>Equivalent</entry>
<entry>Remark</entry>
</row>
</thead>
<tbody>
<row>
<entry><option>-B <replaceable>x</replaceable></option></entry>
<entry><literal>shared_buffers = <replaceable>x</replaceable></></entry>
<entry></entry>
</row>
<row>
<entry><option>-d <replaceable>x</replaceable></option></entry>
<entry><literal>server_min_messages = <replaceable>DEBUGx</replaceable></></entry>
<entry></entry>
<entry><literal>server_min_messages = DEBUG<replaceable>x</replaceable></></entry>
</row>
<row>
<entry><option>-F</option></entry>
<entry><literal>fsync = off</></entry>
<entry></entry>
</row>
<row>
<entry><option>-h <replaceable>x</replaceable></option></entry>
<entry><literal>virtual_host = <replaceable>x</replaceable></></entry>
<entry></entry>
</row>
<row>
<entry><option>-i</option></entry>
<entry><literal>tcpip_socket = on</></entry>
<entry></entry>
</row>
<row>
<entry><option>-k <replaceable>x</replaceable></option></entry>
<entry><literal>unix_socket_directory = <replaceable>x</replaceable></></entry>
<entry></entry>
</row>
<row>
<entry><option>-l</option></entry>
<entry><literal>ssl = on</></entry>
<entry></entry>
</row>
<row>
<entry><option>-N <replaceable>x</replaceable></option></entry>
<entry><literal>max_connections = <replaceable>x</replaceable></></entry>
<entry></entry>
</row>
<row>
<entry><option>-p <replaceable>x</replaceable></option></entry>
<entry><literal>port = <replaceable>x</replaceable></></entry>
<entry></entry>
</row>
<row>
<entry><option>-fi</option>, <option>-fh</option>, <option>-fm</option>, <option>-fn</option>, <option>-fs</option>, <option>-ft</option></entry>
<entry><literal>enable_indexscan=off</>, <literal>enable_hashjoin=off</>,
<literal>enable_mergejoin=off</>, <literal>enable_nestloop=off</>, <literal>enable_seqscan=off</>,
<literal>enable_tidscan=off</></entry>
<entry>*</entry>
<entry>
<option>-fi</option>, <option>-fh</option>,
<option>-fm</option>, <option>-fn</option>,
<option>-fs</option>, <option>-ft</option><footnote
id="fn.runtime-config-short">
<para>
For historical reasons, these options must be passed to
the individual backend process via the <option>-o</option>
postmaster option, for example,
<screen>
$ <userinput>postmaster -o '-S 1024 -s'</userinput>
</screen>
or via <envar>PGOPTIONS</envar> from the client side, as
explained above.
</para>
</footnote>
</entry>
<entry>
<literal>enable_indexscan=off</>,
<literal>enable_hashjoin=off</>,
<literal>enable_mergejoin=off</>,
<literal>enable_nestloop=off</>,
<literal>enable_seqscan=off</>,
<literal>enable_tidscan=off</>
</entry>
</row>
<row>
<entry><option>-S <replaceable>x</replaceable></option></entry>
<entry><literal>sort_mem = <replaceable>x</replaceable></></entry>
<entry>*</entry>
</row>
<row>
<entry><option>-s</option></entry>
<entry><option>-s</option><footnoteref linkend="fn.runtime-config-short"></entry>
<entry><literal>show_statement_stats = on</></entry>
<entry>*</entry>
</row>
<row>
<entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option></entry>
<entry><option>-S <replaceable>x</replaceable></option><footnoteref linkend="fn.runtime-config-short">
</entry>
<entry><literal>sort_mem = <replaceable>x</replaceable></></entry>
</row>
<row>
<entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option><footnoteref linkend="fn.runtime-config-short"></entry>
<entry><literal>show_parser_stats=on</>, <literal>show_planner_stats=on</>, <literal>show_executor_stats=on</></entry>
<entry>*</entry>
</row>
</tbody>
</tgroup>
</table>
For historical reasons, options marked <quote>*</quote> must be
passed to the individual backend process via the
<option>-o</option> postmaster option, for example,
<screen>
$ <userinput>postmaster -o '-S 1024 -s'</userinput>
</screen>
or via <envar>PGOPTIONS</envar> from the client side, as explained
above.
</para>
</sect2>
</sect2>
</sect1>
@ -2281,7 +2306,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
<row>
<entry><varname>SHMMAX</></>
<entry>Maximum size of shared memory segment (bytes)</>
<entry>250kB + 8.2kB * <varname>shared_buffers</> + 14.2kB * <varname>max_connections</> or infinity</entry>
<entry>250kB + 8.2 kB * <varname>shared_buffers</> + 14.2 kB * <varname>max_connections</> or infinity</entry>
</row>
<row>
@ -2429,7 +2454,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
mind that shared memory is not pageable; it is locked in RAM.
To increase the number of shared buffers supported by the
postmaster, add the following to your kernel configuration
file. A <varname>SHMALL</> value of 1024 represents 4MB of
file. A <varname>SHMALL</> value of 1024 represents 4 MB of
shared memory. The following increases the maximum shared
memory area to 32 MB:
<programlisting>
@ -2442,7 +2467,7 @@ options "SHMMAX=\(SHMALL*PAGE_SIZE\)"
<para>
For those running 4.1 or later, just make the above changes,
recompile the kernel, and reboot. For those running earlier
releases, use <application>bpatch</> to find the
releases, use <command>bpatch</> to find the
<varname>sysptsize</> value in the current kernel. This is
computed dynamically at boot time.
<screen>
@ -2788,7 +2813,7 @@ default:\
<sect1 id="postmaster-shutdown">
<title>Shutting down the server</title>
<title>Shutting Down the Server</title>
<para>
There are several ways to shut down the database server. You control
@ -2879,14 +2904,16 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<para>
With SSL support compiled in, the <productname>PostgreSQL</> server
can be started with the argument <option>-l</> (ell) to enable
SSL connections. When starting in SSL mode, the server will look
for the files <filename>server.key</> and <filename>server.crt</> in
the data directory. These files should contain the server private key
and certificate respectively. These files must be set up correctly
before an SSL-enabled server can start. If the private key is protected
with a passphrase, the server will prompt for the passphrase and will
not start until it has been entered.
can be started with SSL support by setting the parameter
<varname>ssl</varname> to on in
<filename>postgresql.conf</filename>. When starting in SSL mode,
the server will look for the files <filename>server.key</> and
<filename>server.crt</> in the data directory. These files should
contain the server private key and certificate respectively. These
files must be set up correctly before an SSL-enabled server can
start. If the private key is protected with a passphrase, the
server will prompt for the passphrase and will not start until it
has been entered.
</para>
<para>
@ -2900,19 +2927,18 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
For details on how to create your server private key and certificate,
refer to the <productname>OpenSSL</> documentation. A simple
self-signed certificate can be used to get started for testing, but a
certificate signed by a <acronym>CA</> (either one of the global
certificate signed by a certificate authority (<acronym>CA</>) (either one of the global
<acronym>CAs</> or a local one) should be used in production so the
client can verify the server's identity. To create a quick
self-signed certificate, use the following
<productname>OpenSSL</productname> command:
<programlisting>
cd <replaceable>$PGDATA</replaceable>
openssl req -new -text -out server.req
</programlisting>
Fill out the information that <command>openssl</> asks for. Make sure
that you enter the local host name as Common Name; the challenge
password can be left blank. The script will generate a key that is
passphrase protected; it will not accept a pass phrase that is less
passphrase protected; it will not accept a passphrase that is less
than four characters long. To remove the passphrase (as you must if
you want automatic start-up of the server), run the commands
<programlisting>
@ -2930,7 +2956,7 @@ chmod og-rwx server.key
</sect1>
<sect1 id="ssh-tunnels">
<title>Secure TCP/IP Connections with <application>SSH</application> tunnels</title>
<title>Secure TCP/IP Connections with <application>SSH</application> Tunnels</title>
<indexterm zone="ssh-tunnels">
<primary>ssh</primary>
@ -2946,20 +2972,20 @@ chmod og-rwx server.key
</note>
<para>
One can use <productname>ssh</productname> to encrypt the network
One can use <application>SSH</application> to encrypt the network
connection between clients and a
<productname>PostgreSQL</productname> server. Done properly, this
should lead to an adequately secure network connection.
provides an adequately secure network connection.
</para>
<para>
First make sure that an <application>ssh</application> server is
First make sure that an <application>SSH</application> server is
running properly on the same machine as
<productname>PostgreSQL</productname> and that you can log in using
<command>ssh</command> as some user. Then you can establish a secure
tunnel with a command like this from the client machine:
<programlisting>
$ <userinput>ssh -L 3333:foo.com:5432 joe@foo.com</userinput>
ssh -L 3333:foo.com:5432 joe@foo.com
</programlisting>
The first number in the <option>-L</option> argument, 3333, is the
port number of your end of the tunnel; it can be chosen freely. The
@ -2982,7 +3008,7 @@ psql -h localhost -p 3333 template1
<tip>
<para>
Several other products exist that can provide secure tunnels using
Several other applications exist that can provide secure tunnels using
a procedure similar in concept to the one just described.
</para>
</tip>

10
doc/src/sgml/start.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.26 2002/10/24 17:48:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.26.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="tutorial-start">
@ -281,10 +281,10 @@ createdb: database creation failed
<listitem>
<para>
Using an existing graphical frontend tool like
<application>PgAccess</application> or
<application>ApplixWare</application> (via
<acronym>ODBC</acronym>) to create and manipulate a database.
These possibilities are not covered in this tutorial.
<application>PgAccess</application> or an office suite with
<acronym>ODBC</acronym> support to create and manipulate a
database. These possibilities are not covered in this
tutorial.
</para>
</listitem>

8
doc/src/sgml/user-manag.sgml
View file

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.17 2002/10/24 17:48:54 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.17.2.1 2002/11/06 23:30:39 petere Exp $
-->
<chapter id="user-manag">
@ -129,7 +129,7 @@ dropuser <replaceable>name</replaceable>
<para>
A password is only significant if the client authentication
method requires the user to supply a password when connecting
to the database. At present, the <option>password</>,
to the database. The <option>password</>,
<option>md5</>, and <option>crypt</> authentication methods
make use of passwords. Database passwords are separate from
operating system passwords. Specify a password upon user
@ -156,7 +156,7 @@ dropuser <replaceable>name</replaceable>
ALTER USER myname SET enable_indexscan TO off;
</programlisting>
This will save the setting (but not set it immediately) and in
subsequent connections it will appear as though <literal>SET geqo
subsequent connections it will appear as though <literal>SET enable_indexscan
TO off;</literal> had been called right before the session started.
You can still alter this setting during the session; it will only
be the default. To undo any such setting, use <literal>ALTER USER
@ -205,7 +205,7 @@ ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</repla
<literal>USAGE</>, and <literal>ALL PRIVILEGES</>. For more
information on the different types of privileges support by
<productname>PostgreSQL</productname>, refer to the
<command>GRANT</command> reference manual. The right to modify or
<command>GRANT</command> page in the &cite-reference;. The right to modify or
destroy an object is always the privilege of the owner only. To
assign privileges, the <command>GRANT</command> command is
used. So, if <literal>joe</literal> is an existing user, and