From d258ba01ec601f655137468bd484153eb369e92d Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Mon, 24 Mar 2003 14:32:51 +0000
Subject: [PATCH] Another big editing pass for consistent content and
presentation.
---
doc/src/sgml/backup.sgml | 37 +-
doc/src/sgml/charset.sgml | 579 +++++++-----------------
doc/src/sgml/diskusage.sgml | 67 +--
doc/src/sgml/func.sgml | 6 +-
doc/src/sgml/install-win32.sgml | 4 +-
doc/src/sgml/maintenance.sgml | 75 ++-
doc/src/sgml/monitoring.sgml | 191 ++++----
doc/src/sgml/ref/clusterdb.sgml | 14 +-
doc/src/sgml/ref/createdb.sgml | 16 +-
doc/src/sgml/ref/createlang.sgml | 19 +-
doc/src/sgml/ref/createuser.sgml | 18 +-
doc/src/sgml/ref/current_date.sgml | 148 ------
doc/src/sgml/ref/current_time.sgml | 158 -------
doc/src/sgml/ref/current_timestamp.sgml | 166 -------
doc/src/sgml/ref/current_user.sgml | 167 -------
doc/src/sgml/ref/dropdb.sgml | 16 +-
doc/src/sgml/ref/droplang.sgml | 15 +-
doc/src/sgml/ref/dropuser.sgml | 19 +-
doc/src/sgml/ref/ecpg-ref.sgml | 14 +-
doc/src/sgml/ref/initdb.sgml | 26 +-
doc/src/sgml/ref/initlocation.sgml | 6 +-
doc/src/sgml/ref/ipcclean.sgml | 16 +-
doc/src/sgml/ref/pg_config-ref.sgml | 8 +-
doc/src/sgml/ref/pg_controldata.sgml | 14 +-
doc/src/sgml/ref/pg_ctl-ref.sgml | 125 ++---
doc/src/sgml/ref/pg_dump.sgml | 116 ++---
doc/src/sgml/ref/pg_dumpall.sgml | 37 +-
doc/src/sgml/ref/pg_resetxlog.sgml | 39 +-
doc/src/sgml/ref/pg_restore.sgml | 183 +++-----
doc/src/sgml/ref/pgtclsh.sgml | 4 +-
doc/src/sgml/ref/pgtksh.sgml | 4 +-
doc/src/sgml/ref/postgres-ref.sgml | 77 ++--
doc/src/sgml/ref/postmaster.sgml | 157 +++----
doc/src/sgml/ref/psql-ref.sgml | 350 +++++++-------
doc/src/sgml/ref/vacuumdb.sgml | 39 +-
doc/src/sgml/reference.sgml | 27 +-
doc/src/sgml/runtime.sgml | 524 ++++++++++-----------
doc/src/sgml/wal.sgml | 267 ++++++-----
38 files changed, 1321 insertions(+), 2427 deletions(-)
delete mode 100644 doc/src/sgml/ref/current_date.sgml
delete mode 100644 doc/src/sgml/ref/current_time.sgml
delete mode 100644 doc/src/sgml/ref/current_timestamp.sgml
delete mode 100644 doc/src/sgml/ref/current_user.sgml
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index a58945f1ef0..24ea265f23d 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.25 2003/03/18 00:02:11 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.26 2003/03/24 14:32:50 petere Exp $
-->
<chapter id="backup">
<title>Backup and Restore</title>
@@ -110,7 +110,7 @@ psql <replaceable class="parameter">dbname</replaceable> < <replaceable class
<application>psql</> (e.g., with <literal>createdb -T template0
<replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</>
- for controlling the database server location and the user names. See
+ for controlling the database server location and the user name. See
its reference page for more information.
</para>
@@ -135,7 +135,7 @@ psql <replaceable class="parameter">dbname</replaceable> < <replaceable class
<para>
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
+ directly from one server to another; for example:
<programlisting>
pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</>
</programlisting>
@@ -179,27 +179,19 @@ pg_dumpall > <replaceable>outfile</>
<sect2 id="backup-dump-large">
<title>Large Databases</title>
- <note>
- <title>Acknowledgement</title>
- <para>
- Originally written by Hannu Krosing
- (<email>hannu@trust.ee</email>) on 1999-06-19
- </para>
- </note>
-
<para>
Since <productname>PostgreSQL</productname> allows tables larger
than the maximum file size on your system, it can be problematic
- to dump the table to a file, since the resulting file will likely
+ to dump such a table to a file, since the resulting file will likely
be larger than the maximum size allowed by your system. As
- <application>pg_dump</> writes to the standard output, you can
- just use standard *nix tools to work around this possible problem.
+ <application>pg_dump</> can write to the standard output, you can
+ just use standard Unix tools to work around this possible problem.
</para>
<formalpara>
<title>Use compressed dumps.</title>
<para>
- Use your favorite compression program, for example
+ You can use your favorite compression program, for example
<application>gzip</application>.
<programlisting>
@@ -222,9 +214,10 @@ cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <re
</formalpara>
<formalpara>
- <title>Use <application>split</>.</title>
+ <title>Use <command>split</>.</title>
<para>
- This allows you to split the output into pieces that are
+ The <command>split</command> command
+ allows you to split the output into pieces that are
acceptable in size to the underlying file system. For example, to
make chunks of 1 megabyte:
@@ -338,7 +331,7 @@ tar -cf backup.tar /usr/local/pgsql/data
<listitem>
<para>
- If you have dug into the details of the file system layout you
+ If you have dug into the details of the file system layout of the data you
may be tempted to try to back up or restore only certain
individual tables or databases from their respective files or
directories. This will <emphasis>not</> work because the
@@ -348,7 +341,7 @@ tar -cf backup.tar /usr/local/pgsql/data
all transactions. A table file is only usable with this
information. Of course it is also impossible to restore only a
table and the associated <filename>pg_clog</filename> data
- because that will render all other tables in the database
+ because that would render all other tables in the database
cluster useless.
</para>
</listitem>
@@ -381,7 +374,7 @@ tar -cf backup.tar /usr/local/pgsql/data
server, using <application>pg_dump</>. (There are checks in place
that prevent you from doing the wrong thing, so no harm can be done
by confusing these things.) The precise installation procedure is
- not subject of this section, these details are in <xref linkend="installation">.
+ not subject of this section; these details are in <xref linkend="installation">.
</para>
<para>
@@ -393,7 +386,7 @@ tar -cf backup.tar /usr/local/pgsql/data
pg_dumpall -p 5432 | psql -d template1 -p 6543
</programlisting>
- to transfer your data, or use an intermediate file if you want.
+ 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
database is not updated after you run <application>pg_dumpall</>,
@@ -413,7 +406,7 @@ pg_dumpall -p 5432 | psql -d template1 -p 6543
pg_dumpall > backup
pg_ctl stop
mv /usr/local/pgsql /usr/local/pgsql.old
-cd /usr/src/postgresql-&version;
+cd ~/postgresql-&version;
gmake install
initdb -D /usr/local/pgsql/data
postmaster -D /usr/local/pgsql/data
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 9ccd8fa5e1e..5c2c2aee34c 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -1,18 +1,13 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.32 2003/03/13 01:30:26 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.33 2003/03/24 14:32:50 petere Exp $ -->
<chapter id="charset">
<title>Localization</>
- <abstract>
- <para>
- Describes the available localization features from the point of
- view of the administrator.
- </para>
- </abstract>
-
- <para>
- <productname>PostgreSQL</productname> supports localization with
- three approaches:
+ <para>
+ This chapter describes the available localization features from the
+ point of view of the administrator.
+ <productname>PostgreSQL</productname> supports localization with
+ three approaches:
<itemizedlist>
<listitem>
@@ -25,20 +20,17 @@
<listitem>
<para>
- Using explicit multiple-byte character sets defined in the
- <productname>PostgreSQL</productname> server to support languages
- that require more characters than will fit into a single byte,
- and to provide character set recoding between client and server.
- The number of supported character sets is fixed at the time the
- server is compiled, and internal operations such as string
- comparisons require expansion of each character into a 32-bit
- word.
+ Providing a number of different character sets defined in the
+ <productname>PostgreSQL</productname> server, including
+ multiple-byte character sets, to support storing text in all
+ kinds of languages, and providing character set recoding between
+ client and server.
</para>
</listitem>
<listitem>
<para>
- Single byte character recoding provides a more light-weight
+ Single-byte character recoding provides a more light-weight
solution for users of multiple, yet single-byte character sets.
</para>
</listitem>
@@ -55,7 +47,7 @@
<firstterm>Locale</> support refers to an application respecting
cultural preferences regarding alphabets, sorting, number
formatting, etc. <productname>PostgreSQL</> uses the standard ISO
- C and <acronym>POSIX</acronym>-like locale facilities provided by the server operating
+ C and <acronym>POSIX</acronym> locale facilities provided by the server operating
system. For additional information refer to the documentation of your
system.
</para>
@@ -92,7 +84,7 @@ initdb --locale=sv_SE
<para>
Occasionally it is useful to mix rules from several locales, e.g.,
- use U.S. collation rules but Spanish messages. To support that, a
+ use English collation rules but Spanish messages. To support that, a
set of locale subcategories exist that control only a certain
aspect of the localization rules.
@@ -154,7 +146,7 @@ initdb --locale=sv_SE
<para>
The other locale categories can be changed as desired whenever the
- server is started by setting the run-time configuration variables
+ server is running by setting the run-time configuration variables
that have the same name as the locale categories (see <xref
linkend="runtime-config"> for details). The defaults that are
chosen by <command>initdb</command> are actually only written into
@@ -190,16 +182,15 @@ initdb --locale=sv_SE
variable <envar>LANGUAGE</envar> which overrides all other locale
settings for the purpose of setting the language of messages. If
in doubt, please refer to the documentation of your operating
- system, in particular the
- <citerefentry><refentrytitle>gettext</><manvolnum>3</></> manual
- page, for more information.
+ system, in particular the documentation about
+ <application>gettext</>, for more information.
</para>
</note>
<para>
To enable messages translated to the user's preferred language,
- the <option>--enable-nls</option> option must be used. This
- option is independent of the other locale support.
+ <acronym>NLS</acronym> must have been enabled at build time. This
+ choice is independent of the other locale support.
</para>
</sect2>
@@ -212,7 +203,7 @@ initdb --locale=sv_SE
<itemizedlist>
<listitem>
<para>
- Sort order in <command>ORDER BY</> queries.
+ Sort order in queries using <command>ORDER BY</>
<indexterm><primary>ORDER BY</></>
</para>
</listitem>
@@ -234,7 +225,7 @@ initdb --locale=sv_SE
<para>
The only severe drawback of using the locale support in
- <productname>PostgreSQL</> is its speed. So use locale only if you
+ <productname>PostgreSQL</> is its speed. So use locales only if you
actually need it. It should be noted in particular that selecting
a non-C locale disables index optimizations for <literal>LIKE</> and
<literal>~</> operators, which can make a huge difference in the
@@ -247,49 +238,28 @@ initdb --locale=sv_SE
<para>
If locale support doesn't work in spite of the explanation above,
- check that the locale support in your operating system is correctly configured.
- To check whether a given locale is installed and functional you
- can use <application>Perl</>, for example. Perl has also support
- for locales and if a locale is broken <command>perl -v</> will
- complain something like this:
-<screen>
-<prompt>$</> <userinput>export LC_CTYPE='not_exist'</>
-<prompt>$</> <userinput>perl -v</>
-<computeroutput>
-perl: warning: Setting locale failed.
-perl: warning: Please check that your locale settings:
-LC_ALL = (unset),
-LC_CTYPE = "not_exist",
-LANG = (unset)
-are supported and installed on your system.
-perl: warning: Falling back to the standard locale ("C").
-</computeroutput>
-</screen>
+ check that the locale support in your operating system is
+ correctly configured. To check what locales are installed on your
+ system, you may use the command <literal>locale -a</literal> if
+ your operating system provides it.
</para>
<para>
- Check that your locale files are in the right location. Possible
- locations include: <filename>/usr/lib/locale</filename> (<systemitem class="osname">Linux</>,
- <systemitem class="osname">Solaris</>), <filename>/usr/share/locale</filename> (<systemitem class="osname">Linux</>),
- <filename>/usr/lib/nls/loc</filename> (<systemitem class="osname">DUX 4.0</>). Check the locale
- man page of your system if you are not sure.
+ Check that <productname>PostgreSQL</> is actually using the locale
+ that you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
+ settings are determined at <command>initdb</> time and cannot be
+ changed without repeating <command>initdb</>. Other locale
+ settings including <envar>LC_MESSAGES</> and <envar>LC_MONETARY</>
+ are initially determined by the environment the server is started
+ in. You can check the <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
+ settings of a database with the utility program
+ <command>pg_controldata</>.
</para>
<para>
- Check that <productname>PostgreSQL</> is actually using the locale that
- you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</> settings are
- determined at <application>initdb</> time and cannot be changed without
- repeating <application>initdb</>. Other locale settings including
- <envar>LC_MESSAGES</> and <envar>LC_MONETARY</> are determined by the
- environment the postmaster is started in, and can be changed with a simple
- postmaster restart. You can check the <envar>LC_COLLATE</> and
- <envar>LC_CTYPE</> settings of
- a database with the <filename>contrib/pg_controldata</> utility program.
- </para>
-
- <para>
- The directory <filename>src/test/locale</> contains a test suite
- for <productname>PostgreSQL</>'s locale support.
+ The directory <filename>src/test/locale</> in the source
+ distribution contains a test suite for
+ <productname>PostgreSQL</>'s locale support.
</para>
<para>
@@ -297,9 +267,9 @@ perl: warning: Falling back to the standard locale ("C").
text of the error message will obviously have problems when the
server's messages are in a different language. If you create such
an application you need to devise a plan to cope with this
- situation. The embedded SQL interface (<application>ecpg</>) is
+ situation. The embedded SQL interface (<application>ECPG</>) is
also affected by this problem. It is currently recommended that
- servers interfacing with <application>ecpg</> applications be
+ servers interfacing with <application>ECPG</> applications be
configured to send messages in English.
</para>
@@ -316,58 +286,41 @@ perl: warning: Falling back to the standard locale ("C").
</sect1>
- <sect1 id="multibyte">
- <title>Multibyte Support</title>
-
- <indexterm zone="multibyte"><primary>multibyte</></>
-
- <note>
- <title>Author</title>
-
- <para>
- Tatsuo Ishii (<email>ishii@postgresql.org</email>),
- last updated 2002-07-24.
- Check <ulink
- url="http://www.sra.co.jp/people/t-ishii/PostgreSQL/">Tatsuo's
- web site</ulink> for more information.
- </para>
- </note>
+ <sect1 id="multibyte">
+ <title>Character Set Support</title>
- <para>
- Multibyte (<acronym>MB</acronym>) support is intended to allow
- <productname>PostgreSQL</productname> to handle
- multiple-byte character sets such as <acronym>EUC</> (Extended Unix Code), Unicode, and
- Mule internal code. With <acronym>MB</acronym> enabled you can use multibyte
- character sets in regular expressions (regexp), LIKE, and some
- other functions. The default
- encoding system is selected while initializing your
- <productname>PostgreSQL</productname> installation using
- <application>initdb</application>. Note that this can be
- overridden when you create a database using
- <application>createdb</application> or by using the SQL command
- <command>CREATE DATABASE</>. So you can have multiple databases each with
- a different encoding system. Note that <acronym>MB</acronym> can
- handle single byte characters sets such as ISO-8859-1.
- </para>
+ <indexterm zone="multibyte"><primary>character set</></>
- <para>
- Multibyte support is enabled by default since
- <productname>PostgreSQL</> version 7.3.
- </para>
+ <para>
+ The character set support in <productname>PostgreSQL</productname>
+ allows you to store text in a variety of character sets, including
+ single-byte character sets such as the ISO 8859 series and
+ multiple-byte character sets such as <acronym>EUC</> (Extended Unix
+ Code), Unicode, and Mule internal code. All character sets can be
+ used transparently throughout the server. (If you use extension
+ functions from other sources, it depends on whether they wrote
+ their code correctly.) The default character set is selected while
+ initializing your <productname>PostgreSQL</productname> database
+ cluster using <command>initdb</>. It can be overridden when you
+ create a database using <command>createdb</command> or by using the
+ SQL command <command>CREATE DATABASE</>. So you can have multiple
+ databases each with a different character set.
+ </para>
<sect2>
- <title>Supported character set encodings</title>
+ <title>Supported Character Sets</title>
<para>
- Following encoding can be used as database encoding.
+ <xref linkend="charset-table"> shows the character sets available
+ for use in the server.
+ </para>
- <table tocentry="1">
- <title>Character Set Encodings</title>
- <titleabbrev>Encodings</titleabbrev>
+ <table id="charset-table">
+ <title>Server Character Sets</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Encoding</entry>
+ <entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
@@ -406,59 +359,59 @@ perl: warning: Falling back to the standard locale ("C").
</row>
<row>
<entry><literal>LATIN1</literal></entry>
- <entry>ISO 8859-1 <acronym>ECMA</>-94 Latin Alphabet No.1</entry>
+ <entry>ISO 8859-1/<acronym>ECMA</> 94 (Latin alphabet no.1)</entry>
</row>
<row>
<entry><literal>LATIN2</literal></entry>
- <entry>ISO 8859-2 <acronym>ECMA</>-94 Latin Alphabet No.2</entry>
+ <entry>ISO 8859-2/<acronym>ECMA</> 94 (Latin alphabet no.2)</entry>
</row>
<row>
<entry><literal>LATIN3</literal></entry>
- <entry>ISO 8859-3 <acronym>ECMA</>-94 Latin Alphabet No.3</entry>
+ <entry>ISO 8859-3/<acronym>ECMA</> 94 (Latin alphabet no.3)</entry>
</row>
<row>
<entry><literal>LATIN4</literal></entry>
- <entry>ISO 8859-4 <acronym>ECMA</>-94 Latin Alphabet No.4</entry>
+ <entry>ISO 8859-4/<acronym>ECMA</> 94 (Latin alphabet no.4)</entry>
</row>
<row>
<entry><literal>LATIN5</literal></entry>
- <entry>ISO 8859-9 <acronym>ECMA</>-128 Latin Alphabet No.5</entry>
+ <entry>ISO 8859-9/<acronym>ECMA</> 128 (Latin alphabet no.5)</entry>
</row>
<row>
<entry><literal>LATIN6</literal></entry>
- <entry>ISO 8859-10 <acronym>ECMA</>-144 Latin Alphabet No.6</entry>
+ <entry>ISO 8859-10/<acronym>ECMA</> 144 (Latin alphabet no.6)</entry>
</row>
<row>
<entry><literal>LATIN7</literal></entry>
- <entry>ISO 8859-13 Latin Alphabet No.7</entry>
+ <entry>ISO 8859-13 (Latin alphabet no.7)</entry>
</row>
<row>
<entry><literal>LATIN8</literal></entry>
- <entry>ISO 8859-14 Latin Alphabet No.8</entry>
+ <entry>ISO 8859-14 (Latin alphabet no.8)</entry>
</row>
<row>
<entry><literal>LATIN9</literal></entry>
- <entry>ISO 8859-15 Latin Alphabet No.9</entry>
+ <entry>ISO 8859-15 (Latin alphabet no.9)</entry>
</row>
<row>
<entry><literal>LATIN10</literal></entry>
- <entry>ISO 8859-16 <acronym>ASRO</> SR 14111 Latin Alphabet No.10</entry>
+ <entry>ISO 8859-16/<acronym>ASRO</> SR 14111 (Latin alphabet no.10)</entry>
</row>
<row>
<entry><literal>ISO-8859-5</literal></entry>
- <entry><acronym>ECMA</>-113 Latin/Cyrillic</entry>
+ <entry>ISO 8859-5/<acronym>ECMA</> 113 (Latin/Cyrillic)</entry>
</row>
<row>
<entry><literal>ISO-8859-6</literal></entry>
- <entry><acronym>ECMA</>-114 Latin/Arabic</entry>
+ <entry>ISO 8859-6/<acronym>ECMA</> 114 (Latin/Arabic)</entry>
</row>
<row>
<entry><literal>ISO-8859-7</literal></entry>
- <entry><acronym>ECMA</>-118 Latin/Greek</entry>
+ <entry>ISO 8859-7/<acronym>ECMA</> 118 (Latin/Greek)</entry>
</row>
<row>
<entry><literal>ISO-8859-8</literal></entry>
- <entry><acronym>ECMA</>-121 Latin/Hebrew</entry>
+ <entry>ISO 8859-8/<acronym>ECMA</> 121 (Latin/Hebrew)</entry>
</row>
<row>
<entry><literal>KOI8</literal></entry>
@@ -474,78 +427,76 @@ perl: warning: Falling back to the standard locale ("C").
</row>
<row>
<entry><literal>WIN1256</literal></entry>
- <entry>Arabic Windows CP1256</entry>
+ <entry>Windows CP1256 (Arabic)</entry>
</row>
<row>
<entry><literal>TCVN</literal></entry>
- <entry>Vietnamese <acronym>TCVN</>-5712 (Windows CP1258)</entry>
+ <entry><acronym>TCVN</>-5712/Windows CP1258 (Vietnamese)</entry>
</row>
<row>
<entry><literal>WIN874</literal></entry>
- <entry>Thai Windows CP874</entry>
+ <entry>Windows CP874 (Thai)</entry>
</row>
</tbody>
</tgroup>
</table>
- </para>
<important>
<para>
- Before <productname>PostgreSQL</>7.2, <literal>LATIN5</> mistakenly
- meant ISO 8859-5. From 7.2 on,
- <literal>LATIN5</> means ISO 8859-9. If you have a <literal>LATIN5</>
- database created on 7.1 or earlier and want to migrate to 7.2 (or
- later), you should be very careful about this change.
+ Before <productname>PostgreSQL</> 7.2, <literal>LATIN5</>
+ mistakenly meant ISO 8859-5. From 7.2 on, <literal>LATIN5</>
+ means ISO 8859-9. If you have a <literal>LATIN5</> database
+ created on 7.1 or earlier and want to migrate to 7.2 or later,
+ you should be very careful about this change.
</para>
</important>
- <important>
<para>
- Not all <acronym>API</>s supports all the encodings listed above. For example, the
+ Not all <acronym>API</>s support all the listed character sets. For example, the
<productname>PostgreSQL</>
JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>,
<literal>LATIN8</>, and <literal>LATIN10</>.
</para>
- </important>
</sect2>
<sect2>
- <title>Setting the Encoding</title>
+ <title>Setting the Character Set</title>
<para>
- <application>initdb</application> defines the default encoding
- for a <productname>PostgreSQL</productname> installation. For example:
+ <command>initdb</> defines the default character set
+ for a <productname>PostgreSQL</productname> cluster. For example,
<screen>
initdb -E EUC_JP
</screen>
- sets the default encoding to <literal>EUC_JP</literal> (Extended Unix Code for Japanese).
- Note that you can use <option>--encoding</option> instead of <option>-E</option> if you prefer
- to type longer option strings.
+ sets the default character set (encoding) to
+ <literal>EUC_JP</literal> (Extended Unix Code for Japanese). You
+ can use <option>--encoding</option> instead of
+ <option>-E</option> if you prefer to type longer option strings.
If no <option>-E</> or <option>--encoding</option> option is
- given, SQL_ASCII is used.
+ given, <literal>SQL_ASCII</> is used.
</para>
<para>
- You can create a database with a different encoding:
+ You can create a database with a different character set:
<screen>
createdb -E EUC_KR korean
</screen>
- will create a database named <database>korean</database> with <literal>EUC_KR</literal> encoding.
- Another way to accomplish this is to use a SQL command:
+ This will create a database named <literal>korean</literal> that
+ uses the character set <literal>EUC_KR</literal>. Another way to
+ accomplish this is to use this SQL command:
<programlisting>
-CREATE DATABASE korean WITH ENCODING = 'EUC_KR';
+CREATE DATABASE korean WITH ENCODING 'EUC_KR';
</programlisting>
- The encoding for a database is represented as an
- <firstterm>encoding column</firstterm> in the
- <literal>pg_database</literal> system catalog.
- You can see that by using the <option>-l</option> option or the
- <command>\l</command> command of <command>psql</command>.
+ The encoding for a database is stored in the system catalog
+ <literal>pg_database</literal>. You can see that by using the
+ <option>-l</option> option or the <command>\l</command> command
+ of <command>psql</command>.
<screen>
$ <userinput>psql -l</userinput>
@@ -567,27 +518,26 @@ $ <userinput>psql -l</userinput>
</sect2>
<sect2>
- <title>Automatic encoding conversion between server and
- client</title>
+ <title>Automatic Character Set Conversion Between Server and Client</title>
<para>
- <productname>PostgreSQL</productname> supports an automatic
- encoding conversion between server and client for some
- encodings. The conversion info is stored in <literal>pg_conversion</> system
- catalog. You can create a new conversion by using <command>CREATE
- CONVERSION</command>. <productname>PostgreSQL</> comes with some predefined
- conversions. They are listed in <xref
+ <productname>PostgreSQL</productname> supports automatic
+ character set conversion between server and client for certain
+ character sets. The conversion information is stored in the
+ <literal>pg_conversion</> system catalog. You can create a new
+ conversion by using the SQL command <command>CREATE
+ CONVERSION</command>. <productname>PostgreSQL</> comes with some
+ predefined conversions. They are listed in <xref
linkend="multibyte-translation-table">.
</para>
- <table tocentry="1" id="multibyte-translation-table">
- <title>Client/Server Character Set Encodings</title>
- <titleabbrev>Communication Encodings</titleabbrev>
+ <table id="multibyte-translation-table">
+ <title>Client/Server Character Set Conversions</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Server Encoding</entry>
- <entry>Available Client Encodings</entry>
+ <entry>Server Character Set</entry>
+ <entry>Available Client Character Sets</entry>
</row>
</thead>
<tbody>
@@ -784,10 +734,10 @@ $ <userinput>psql -l</userinput>
</table>
<para>
- To enable the automatic encoding translation, you have to tell
- <productname>PostgreSQL</productname> the encoding you would like
- to use in the client. There are
- several ways to accomplish this.
+ To enable the automatic character set conversion, you have to
+ tell <productname>PostgreSQL</productname> the character set
+ (encoding) you would like to use in the client. There are several
+ ways to accomplish this:
<itemizedlist>
<listitem>
@@ -811,17 +761,17 @@ $ <userinput>psql -l</userinput>
<function>PQsetClientEncoding()</function> for its purpose.
<synopsis>
-int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>)
+int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
</synopsis>
where <replaceable>conn</replaceable> is a connection to the server,
- and <replaceable>encoding</replaceable> is an encoding you
- want to use. If it successfully sets the encoding, it returns 0,
- otherwise -1. The current encoding for this connection can be shown by
+ and <replaceable>encoding</replaceable> is the encoding you
+ want to use. If the function successfully sets the encoding, it returns 0,
+ otherwise -1. The current encoding for this connection can be determined by
using:
<synopsis>
-int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
+int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
</synopsis>
Note that it returns the encoding ID, not a symbolic string
@@ -829,7 +779,7 @@ int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
can use:
<synopsis>
-char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
+char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
</synopsis>
</para>
</listitem>
@@ -841,13 +791,13 @@ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
Setting the client encoding can be done with this SQL command:
<programlisting>
-SET CLIENT_ENCODING TO 'encoding';
+SET CLIENT_ENCODING TO '<replaceable>value</>';
</programlisting>
- Also you can use the SQL92 syntax <literal>SET NAMES</literal> for this purpose:
+ Also you can use the more standard SQL syntax <literal>SET NAMES</literal> for this purpose:
<programlisting>
-SET NAMES 'encoding';
+SET NAMES '<replaceable>value</>';
</programlisting>
To query the current client encoding:
@@ -877,7 +827,7 @@ RESET CLIENT_ENCODING;
<listitem>
<para>
- Using client_encoding variable.
+ Using the configuration variable <varname>client_encoding</varname>.
If the <varname>client_encoding</> variable in <filename>postgresql.conf</> is set, that
client encoding is automatically selected when a connection to the
@@ -888,26 +838,19 @@ RESET CLIENT_ENCODING;
</itemizedlist>
</para>
- </sect2>
-
- <sect2>
- <title>What happens if the translation is not possible?</title>
<para>
- Suppose you choose <literal>EUC_JP</literal> for the server
- and <literal>LATIN1</literal> for the client,
- then some Japanese characters cannot be translated into <literal>LATIN1</literal>. In
- this case, a letter that cannot be represented in the <literal>LATIN1</literal> character set
- would be transformed as:
-
-<synopsis>
-(HEXA DECIMAL)
-</synopsis>
+ If the conversion of a particular character is not possible --
+ suppose you chose <literal>EUC_JP</literal> for the server and
+ <literal>LATIN1</literal> for the client, then some Japanese
+ characters cannot be converted to <literal>LATIN1</literal> -- it
+ is transformed to its hexadecimal byte values in parentheses,
+ e.g., <literal>(826C)</literal>.
</para>
</sect2>
<sect2>
- <title>References</title>
+ <title>Further Reading</title>
<para>
These are good sources to start learning about various kinds of encoding
@@ -949,209 +892,11 @@ RESET CLIENT_ENCODING;
</para>
</sect2>
- <sect2>
- <title>History</title>
-
-<literallayout class="monospaced">
-Dec 7, 2000
- * An automatic encoding translation between Unicode and other
- encodings are implemented
- * Changes above will appear in 7.1
-
-May 20, 2000
- * SJIS UDC (NEC selection IBM kanji) support contributed
- by Eiji Tokuya
- * Changes above will appear in 7.0.1
-
-Mar 22, 2000
- * Add new libpq functions PQsetClientEncoding, PQclientEncoding
- * ./configure --with-mb=EUC_JP
- now deprecated. use
- ./configure --enable-multibyte=EUC_JP
- instead
- * Add SQL_ASCII regression test case
- * Add SJIS User Defined Character (UDC) support
- * All of above will appear in 7.0
-
-July 11, 1999
- * Add support for WIN1250 (Windows Czech) as a client encoding
- (contributed by Pavel Behal)
- * fix some compiler warnings (contributed by Tomoaki Nishiyama)
-
-Mar 23, 1999
- * Add support for KOI8(KOI8-R), WIN(CP1251), ALT(CP866)
- (thanks Oleg Broytmann for testing)
- * Fix problem with MB and locale
-
-Jan 26, 1999
- * Add support for Big5 for frontend encoding
- (you need to create a database with EUC_TW to use Big5)
- * Add regression test case for EUC_TW
- (contributed by Jonah Kuo <email>jonahkuo@mail.ttn.com.tw</email>)
-
-Dec 15, 1998
- * Bugs related to SQL_ASCII support fixed
-
-Nov 5, 1998
- * 6.4 release. In this version, pg_database has "encoding"
- column that represents the database encoding
-
-Jul 22, 1998
- * determine encoding at initdb/createdb rather than compile time
- * support for PGCLIENTENCODING when issuing COPY command
- * support for SQL92 syntax "SET NAMES"
- * support for LATIN2-5
- * add UNICODE regression test case
- * new test suite for MB
- * clean up source files
-
-Jun 5, 1998
- * add support for the encoding translation between the backend
- and the frontend
- * new command SET CLIENT_ENCODING etc. added
- * add support for LATIN1 character set
- * enhance 8-bit cleanliness
-
-April 21, 1998 some enhancements/fixes
- * character_length(), position(), substring() are now aware of
- multi-byte characters
- * add octet_length()
- * add --with-mb option to configure
- * new regression tests for EUC_KR
- (contributed by Soonmyung Hong)
- * add some test cases to the EUC_JP regression test
- * fix problem in regress/regress.sh in case of System V
- * fix toupper(), tolower() to handle 8bit chars
-
-Mar 25, 1998 MB PL2 is incorporated into <productname>PostgreSQL</> 6.3.1
-
-Mar 10, 1998 PL2 released
- * add regression test for EUC_JP, EUC_CN and MULE_INTERNAL
- * add an English document (this file)
- * fix problems concerning 8-bit single byte characters
-
-Mar 1, 1998 PL1 released
-</literallayout>
- </sect2>
-
- <sect2>
- <title>WIN1250 on Windows/ODBC</title>
-
- <para>
-<!--
-[Here is a good documentation explaining how to use WIN1250 on
-Windows/ODBC from Pavel Behal]
-
-Version: 0.91 for PgSQL 6.5
-Author: Pavel Behal
-Revised by: Tatsuo Ishii
-Email: behal@opf.slu.cz
-License: The Same as <productname>PostgreSQL</>
-
-Sorry for my Eglish and C code, I'm not native :-)
-
-!!!!!!!!!!!!!!!!!!!!!!!!! NO WARRANTY !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
--->
-
- The WIN1250 character set on Windows client platforms can be used
- with <productname>PostgreSQL</productname> with locale support
- enabled.
- </para>
-
- <para>
- The following should be kept in mind:
-
- <itemizedlist>
- <listitem>
- <para>
- Success depends on proper system locales. This has been tested
- with <systemitem class="osname">Red Hat 6.0</> and <systemitem
- class="osname">Slackware 3.6</>, with the
- <literal>cs_CZ.iso8859-2</literal> locale.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Never try to set the server's database encoding to WIN1250.
- Always use LATIN2 instead since there is no WIN1250 locale
- in Unix.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The WIN1250 encoding is usable only for Windows ODBC clients. The
- characters are recoded on the fly, to be displayed and stored
- back properly.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <procedure>
- <title>WIN1250 on Windows/ODBC</title>
- <step>
- <para>
- Compile <productname>PostgreSQL</productname> with locale enabled
- and the server-side encoding set to <literal>LATIN2</literal>.
- </para>
- </step>
-
- <step>
- <para>
- Set up your installation. Do not forget to create locale
- variables in your environment. For example (this may
- not be correct for <emphasis>your</emphasis> environment):
-
-<programlisting>
-LC_ALL=cs_CZ.ISO8859-2
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- You have to start the server with locales set!
- </para>
- </step>
-
- <step>
- <para>
- Try it with the Czech language, and have it sort on a query.
- </para>
- </step>
-
- <step>
- <para>
- Install ODBC driver for <productname>PostgreSQL</productname> on your Windows machine.
- </para>
- </step>
-
- <step>
- <para>
- Set up your data source properly. Include this line in your ODBC
- configuration dialog in the field <guilabel>Connect Settings</guilabel>:
-
-<programlisting>
-SET CLIENT_ENCODING = 'WIN1250';
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- Now try it again, but in Windows with ODBC.
- </para>
- </step>
- </procedure>
- </sect2>
</sect1>
<sect1 id="recode">
- <title>Single-byte character set recoding</>
-<!-- formerly in README.charsets, by Josef Balatka, <balatka@email.cz> -->
+ <title>Single-Byte Character Set Recoding</>
<para>
You can set up this feature with the <option>--enable-recode</> option
@@ -1163,57 +908,57 @@ SET CLIENT_ENCODING = 'WIN1250';
<para>
This method uses a file <filename>charset.conf</> file located in
- the database directory (<envar>PGDATA</>). It's a typical
- configuration text file where spaces and newlines separate items
- and records and # specifies comments. Three keywords with the
+ the data directory for configuration. It's a typical
+ configuration text file where spaces and newlines separate fields
+ and records and <literal>#</> starts a comment. Three key words with the
following syntax are recognized here:
<synopsis>
-BaseCharset <replaceable>server_charset</>
-RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
-HostCharset <replaceable>host_spec</> <replaceable>host_charset</>
+BaseCharset <replaceable>server_charset</>
+RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
+HostCharset <replaceable>host_spec</> <replaceable>host_charset</>
</synopsis>
</para>
<para>
- <token>BaseCharset</> defines the encoding of the database server.
+ <token>BaseCharset</> defines the character set of the database server.
All character set names are only used for mapping inside of
<filename>charset.conf</> so you can freely use typing-friendly
names.
</para>
<para>
- <token>RecodeTable</> records specify translation tables between
+ <token>RecodeTable</> records specify conversion tables between
server and client. The file name is relative to the
- <envar>PGDATA</> directory. The table file format is very
- simple. There are no keywords and characters are represented by a
- pair of decimal or hexadecimal (0x prefixed) values on single
+ data directory. The table file format is very
+ simple. There are no key words, and character mappings are represented by a
+ pair of decimal or hexadecimal (prefixed by <literal>0x</>) values on single
lines:
<synopsis>
-<replaceable>char_value</> <replaceable>translated_char_value</>
+<replaceable>char_value</> <replaceable>converted_char_value</>
</synopsis>
+ In the <filename>src/data/</> directory in the source distribution you can find an
+ example <filename>charset.conf</> and a few recoding tables.
</para>
<para>
<token>HostCharset</> records define the client character set by IP
address. You can use a single IP address, an IP mask range starting
- from the given address or an IP interval (e.g., 127.0.0.1,
- 192.168.1.100/24, 192.168.1.20-192.168.1.40).
+ from the given address or an IP interval (e.g., <literal>127.0.0.1</>,
+ <literal>192.168.1.100/24</>, <literal>192.168.1.20-192.168.1.40</>).
</para>
<para>
- The <filename>charset.conf</> file is always processed up to the
- end, so you can easily specify exceptions from the previous
- rules. In the <filename>src/data/</> directory you will find an
- example <filename>charset.conf</> and a few recoding tables.
+ The <filename>charset.conf</> file is always processed to the
+ end, so you can easily specify exceptions from preceding rules.
</para>
<para>
- As this solution is based on the client's IP address and character
- set mapping there are obviously some restrictions as well. You
- cannot use different encodings on the same host at the same
- time. It is also inconvenient when you boot your client hosts into
- multiple operating systems. Nevertheless, when these restrictions are
- not limiting and you do not need multibyte characters then it is a
+ As this solution is based on the client's IP address there are
+ obviously some restrictions as well. You cannot use different
+ character sets on the same host at the same time. It is also
+ inconvenient when you boot your client hosts into multiple
+ operating systems. Nevertheless, when these restrictions are not
+ limiting and you do not need multibyte characters then it is a
simple and effective solution.
</para>
</sect1>
diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
index 0af7b4b3929..0660826d5d9 100644
--- a/doc/src/sgml/diskusage.sgml
+++ b/doc/src/sgml/diskusage.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.8 2002/11/15 03:11:16 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.9 2003/03/24 14:32:50 petere Exp $
-->
<chapter id="diskusage">
@@ -33,32 +33,32 @@ $Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.8 2002/11/15 03:11:16 mo
<para>
You can monitor disk space from three places: from
<application>psql</> using <command>VACUUM</> information, 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,
+ <application>psql</> using the tools in <filename>contrib/dbsize</>, and from
+ the command line using the tools in <filename>contrib/oid2name</>. Using
+ <application>psql</> on a recently vacuumed or analyzed database,
you can issue queries to see the disk usage of any table:
<programlisting>
-play=# SELECT relfilenode, relpages
-play-# FROM pg_class
-play-# WHERE relname = 'customer';
+SELECT relfilenode, relpages FROM pg_class WHERE relname = 'customer';
+
relfilenode | relpages
-------------+----------
16806 | 60
(1 row)
</programlisting>
+ Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
+ is only updated by <command>VACUUM</> and <command>ANALYZE</>.)
</para>
- <para>
- Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
- is only updated by <command>VACUUM</> and <command>ANALYZE</>.) To
- show the space used by <acronym>TOAST</> tables, use a query based on
- the heap relfilenode shown above:
+ <para>
+ To show the space used by <acronym>TOAST</> tables, use a query
+ like the following, substituting the <literal>relfilenode</literal>
+ number of the heap (determined by the query above):
<programlisting>
-play=# SELECT relname, relpages
-play-# FROM pg_class
-play-# WHERE relname = 'pg_toast_16806' OR
-play-# relname = 'pg_toast_16806_index'
-play-# ORDER BY relname;
+SELECT relname, relpages
+ FROM pg_class
+ WHERE relname = 'pg_toast_16806' OR relname = 'pg_toast_16806_index'
+ ORDER BY relname;
+
relname | relpages
----------------------+----------
pg_toast_16806 | 0
@@ -67,14 +67,15 @@ play-# ORDER BY relname;
</para>
<para>
- You can easily display index usage too:
+ You can easily display index sizes, too:
<programlisting>
-play=# SELECT c2.relname, c2.relpages
-play-# FROM pg_class c, pg_class c2, pg_index i
-play-# WHERE c.relname = 'customer' AND
-play-# c.oid = i.indrelid AND
-play-# c2.oid = i.indexrelid
-play-# ORDER BY c2.relname;
+SELECT c2.relname, c2.relpages
+ FROM pg_class c, pg_class c2, pg_index i
+ WHERE c.relname = 'customer'
+ AND c.oid = i.indrelid
+ AND c2.oid = i.indexrelid
+ ORDER BY c2.relname;
+
relname | relpages
----------------------+----------
customer_id_indexdex | 26
@@ -82,11 +83,11 @@ play-# ORDER BY c2.relname;
</para>
<para>
- It is easy to find your largest files using <application>psql</>:
+ It is easy to find your largest tables and indexes using this
+ information:
<programlisting>
-play=# SELECT relname, relpages
-play-# FROM pg_class
-play-# ORDER BY relpages DESC;
+SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
+
relname | relpages
----------------------+----------
bigtable | 3290
@@ -97,12 +98,12 @@ play-# ORDER BY relpages DESC;
<para>
<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.</>
+ <application>psql</> without the need for <command>VACUUM</> or <command>ANALYZE</>.
</para>
<para>
You can also use <filename>contrib/oid2name</> to show disk usage. See
- <filename>README.oid2name</> for examples. It includes a script that
+ <filename>README.oid2name</> in that directory for examples. It includes a script that
shows disk usage for each database.
</para>
</sect1>
@@ -114,7 +115,7 @@ play-# ORDER BY relpages DESC;
The most important disk monitoring task of a database administrator
is to make sure the disk doesn't grow full. A filled data disk may
result in subsequent corruption of database indexes, but not of the
- fundamental data tables. If the WAL files are on the same disk (as
+ tables themselves. If the WAL files are on the same disk (as
is the case for a default configuration) then a filled disk during
database initialization may result in corrupted or incomplete WAL
files. This failure condition is detected and the database server
@@ -129,8 +130,8 @@ play-# ORDER BY relpages DESC;
information of such a setup; a restore would put everything back in
one place. To avoid running out of disk space, you can place the
WAL files or individual databases in other locations while creating
- them. See the <application>initdb</> documentation and <xref
- linkend="manage-ag-alternate-locs"> for more information.
+ them. See the <command>initdb</> documentation and <xref
+ linkend="manage-ag-alternate-locs"> for more information about that.
</para>
<tip>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4e7631bd228..926a82a353e 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.146 2003/03/21 21:54:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.147 2003/03/24 14:32:50 petere Exp $
PostgreSQL documentation
-->
@@ -5900,7 +5900,7 @@ SELECT TIMESTAMP 'now';
<entry><literal>255.255.255.0</literal></entry>
</row>
<row>
- <entry><function>hostmask</function>(<type>inet</type>)</entry>
+ <entry><literal><function>hostmask</function>(<type>inet</type>)</literal></entry>
<entry><type>inet</type></entry>
<entry>construct hostmask for network</entry>
<entry><literal>hostmask('192.168.23.20/30')</literal></entry>
@@ -6477,7 +6477,7 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<indexterm zone="functions-misc">
<primary>configuration</primary>
- <secondary>run time</secondary>
+ <secondary>server</secondary>
</indexterm>
<para>
diff --git a/doc/src/sgml/install-win32.sgml b/doc/src/sgml/install-win32.sgml
index eb44c949ed3..96f85d315dd 100644
--- a/doc/src/sgml/install-win32.sgml
+++ b/doc/src/sgml/install-win32.sgml
@@ -54,7 +54,7 @@
<term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term>
<listitem>
<para>
- Import library to link your program to <filename>libpq.dll</filename>
+ Import library to link your programs to <filename>libpq.dll</filename>
</para>
</listitem>
</varlistentry>
@@ -98,7 +98,7 @@
</para>
<para>
- To use the libraries, you must add the
+ To use the library, you must add the
<filename>libpqdll.lib</filename> file to your project. (In Visual
C++, just right-click on the project and choose to add it.)
</para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index daee3b11891..a2fb9f35996 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1,17 +1,14 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.21 2003/03/24 14:32:50 petere Exp $
-->
<chapter id="maintenance">
<title>Routine Database Maintenance Tasks</title>
- <sect1 id="maintenance-general">
- <title>General Discussion</Title>
-
<para>
There are a few routine maintenance chores that must be performed on
a regular basis to keep a <productname>PostgreSQL</productname>
- installation running smoothly. The tasks discussed here are repetitive
+ server running smoothly. The tasks discussed here are repetitive
in nature and can easily be automated using standard Unix tools such
as <application>cron</application> scripts. But it is the database
administrator's responsibility to set up appropriate scripts, and to
@@ -22,7 +19,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
One obvious maintenance task is creation of backup copies of the data on a
regular schedule. Without a recent backup, you have no chance of recovery
after a catastrophe (disk failure, fire, mistakenly dropping a critical
- table, etc). The backup and recovery mechanisms available in
+ table, etc.). The backup and recovery mechanisms available in
<productname>PostgreSQL</productname> are discussed at length in
<xref linkend="backup">.
</para>
@@ -45,8 +42,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
experience with the system.
</para>
- </sect1>
-
<sect1 id="routine-vacuuming">
<title>Routine Vacuuming</title>
@@ -75,8 +70,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
</listitem>
</orderedlist>
- The frequency and scope of <command>VACUUM</>s performed for each of
- these reasons will vary depending on the needs of each installation.
+ The frequency and scope of the <command>VACUUM</> operations performed for each of
+ these reasons will vary depending on the needs of each site.
Therefore, database administrators must understand these issues and
develop an appropriate maintenance strategy. This section concentrates
on explaining the high-level issues; for details about command syntax
@@ -86,7 +81,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
<para>
Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
of <command>VACUUM</> can run in parallel with normal database operations
- (selects, inserts, updates, deletes, but not changes to table schemas).
+ (selects, inserts, updates, deletes, but not changes to table definitions).
Routine vacuuming is therefore not nearly as intrusive as it was in prior
releases, and it's not as critical to try to schedule it at low-usage
times of day.
@@ -131,8 +126,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
return disk space to the operating system. If you need to return disk
space to the operating system you can use <command>VACUUM FULL</> ---
but what's the point of releasing disk space that will only have to be
- allocated again soon? Moderately frequent standard <command>VACUUM</>s
- are a better approach than infrequent <command>VACUUM FULL</>s for
+ allocated again soon? Moderately frequent standard <command>VACUUM</> runs
+ are a better approach than infrequent <command>VACUUM FULL</> runs for
maintaining heavily-updated tables.
</para>
@@ -140,7 +135,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
Recommended practice for most sites is to schedule a database-wide
<command>VACUUM</> once a day at a low-usage time of day, supplemented
by more frequent vacuuming of heavily-updated tables if necessary.
- (If you have multiple databases in an installation, don't forget to
+ (If you have multiple databases in a cluster, don't forget to
vacuum each one; the <filename>vacuumdb</> script may be helpful.)
Use plain <command>VACUUM</>, not <command>VACUUM FULL</>, for routine
vacuuming for space recovery.
@@ -233,11 +228,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
<para>
<productname>PostgreSQL</productname>'s MVCC transaction semantics
- depend on being able to compare transaction ID (<firstterm>XID</>)
- numbers: a tuple with an insertion XID newer than the current
+ depend on being able to compare transaction ID (<acronym>XID</>)
+ numbers: a tuple with an insertion XID greater than the current
transaction's XID is <quote>in the future</> and should not be visible
to the current transaction. But since transaction IDs have limited size
- (32 bits at this writing) an installation that runs for a long time (more
+ (32 bits at this writing) a cluster that runs for a long time (more
than 4 billion transactions) will suffer <firstterm>transaction ID
wraparound</>: the XID counter wraps around to zero, and all of a sudden
transactions that were in the past appear to be in the future --- which
@@ -251,7 +246,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
against XID wraparound was to re-<command>initdb</> at least every 4
billion transactions. This of course was not very satisfactory for
high-traffic sites, so a better solution has been devised. The new
- approach allows an installation to remain up indefinitely, without
+ approach allows a server to remain up indefinitely, without
<command>initdb</> or any sort of restart. The price is this
maintenance requirement: <emphasis>every table in the database must
be vacuumed at least once every billion transactions</emphasis>.
@@ -293,9 +288,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
<command>VACUUM</>'s normal policy is to reassign <literal>FrozenXID</>
to any tuple with a normal XID more than one billion transactions in the
past. This policy preserves the original insertion XID until it is not
- likely to be of interest anymore (in fact, most tuples will probably
- live and die without ever being <quote>frozen</>). With this policy,
- the maximum safe interval between <command>VACUUM</>s of any table
+ likely to be of interest anymore. (In fact, most tuples will probably
+ live and die without ever being <quote>frozen</>.) With this policy,
+ the maximum safe interval between <command>VACUUM</> runs on any table
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
@@ -304,13 +299,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03
</para>
<para>
- Since periodic <command>VACUUM</>s are needed anyway for the reasons
+ Since periodic <command>VACUUM</> runs are needed anyway for the reasons
described earlier, it's unlikely that any table would not be vacuumed
for as long as a billion transactions. But to help administrators ensure
this constraint is met, <command>VACUUM</> stores transaction ID
- 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
+ statistics in the system table <literal>pg_database</>. In particular,
+ the <literal>datfrozenxid</> column of a database's
+ <literal>pg_database</> row is updated at the completion of any
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
@@ -334,11 +329,11 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
database at least once every half-a-billion (500 million) transactions,
so as to provide plenty of safety margin. To help meet this rule,
each database-wide <command>VACUUM</> automatically delivers a warning
- if there are any <filename>pg_database</> entries showing an
+ if there are any <literal>pg_database</> entries showing an
<literal>age</> of more than 1.5 billion transactions, for example:
<programlisting>
-play=# vacuum;
+play=# VACUUM;
WARNING: Some databases have not been vacuumed in 1613770184 transactions.
Better vacuum them within 533713463 transactions,
or you may have a wraparound failure.
@@ -355,13 +350,13 @@ VACUUM
database will be frozen. Hence, as long as the database is not
modified in any way, it will not need subsequent vacuuming to avoid
transaction ID wraparound problems. This technique is used by
- <filename>initdb</> to prepare the <filename>template0</> database.
+ <command>initdb</> to prepare the <literal>template0</> database.
It should also be used to prepare any user-created databases that
are to be marked <literal>datallowconn</> = <literal>false</> in
- <filename>pg_database</>, since there isn't any convenient way to
+ <literal>pg_database</>, since there isn't any convenient way to
vacuum a database that you can't connect to. Note that
<command>VACUUM</command>'s automatic warning message about
- unvacuumed databases will ignore <filename>pg_database</> entries
+ unvacuumed databases will ignore <literal>pg_database</> entries
with <literal>datallowconn</> = <literal>false</>, so as to avoid
giving false warnings about these databases; therefore it's up to
you to ensure that such databases are frozen correctly.
@@ -415,9 +410,9 @@ VACUUM
</para>
<para>
- If you simply direct the postmaster's <systemitem>stderr</> into a
+ If you simply direct the <systemitem>stderr</> of the <command>postmaster</command> into a
file, the only way to truncate the log file is to stop and restart
- the postmaster. This may be OK for development setups but you won't
+ the <command>postmaster</command>. This may be OK for development setups but you won't
want to run a production server that way.
</para>
@@ -425,7 +420,7 @@ VACUUM
The simplest production-grade approach to managing log output is to
send it all to <application>syslog</> and let
<application>syslog</> deal with file rotation. To do this, set
- <literal>syslog</> to 2 (log to <application>syslog</> only) in
+ the configurations parameter <literal>syslog</> to 2 (to log to <application>syslog</> only) in
<filename>postgresql.conf</>. Then you can send a
<literal>SIGHUP</literal> signal to the <application>syslog</>
daemon whenever you want to force it to start writing a new log
@@ -436,18 +431,18 @@ VACUUM
On many systems, however, <application>syslog</> is not very reliable, particularly
with large log messages; it may truncate or drop messages just when
you need them the most. You may find it more useful to pipe the
- <application>postmaster</>'s <systemitem>stderr</> to some type of
- log rotation script. If you start the postmaster with
- <application>pg_ctl</>, then the postmaster's <systemitem>stderr</>
+ <systemitem>stderr</> of the <command>postmaster</> to some type of
+ log rotation program. If you start the server with
+ <command>pg_ctl</>, then the <systemitem>stderr</> of the <command>postmaster</command>
is already redirected to <systemitem>stdout</>, so you just need a
pipe command:
-<screen>
-<userinput>pg_ctl start | logrotate</userinput>
-</screen>
+<programlisting>
+pg_ctl start | logrotate
+</programlisting>
The <productname>PostgreSQL</> distribution doesn't include a suitable
- log rotation program, but there are many available on the net;
+ log rotation program, but there are many available on the Internet;
one is included in the Apache distribution, for example.
</para>
</sect1>
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 48bbe9561bb..112cc5c35b4 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.17 2003/03/20 18:51:16 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.18 2003/03/24 14:32:50 petere Exp $
-->
<chapter id="monitoring">
@@ -14,7 +14,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.17 2003/03/20 18:51:16
<para>
Several tools are available for monitoring database activity and
analyzing performance. Most of this chapter is devoted to describing
- <productname>PostgreSQL</productname>'s <firstterm>statistics collector</>,
+ <productname>PostgreSQL</productname>'s statistics collector,
but one should not neglect regular Unix monitoring programs such as
<command>ps</> and <command>top</>. Also, once one has identified a
poorly-performing query, further investigation may be needed using
@@ -50,7 +50,7 @@ postgres 1016 0.1 2.4 6532 3080 pts/1 SN 13:19 0:00 postgres: tgl reg
(The appropriate invocation of <command>ps</> varies across different
platforms, as do the details of what is shown. This example is from a
recent Linux system.) The first process listed here is the
- <firstterm>postmaster</>, the master server process. The command arguments
+ <application>postmaster</>, the master server process. The command arguments
shown for it are the same ones given when it was launched. The next two
processes implement the statistics collector, which will be described in
detail in the next section. (These will not be present if you have set
@@ -67,7 +67,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
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
+ <literal>waiting</> is attached if the server process is presently waiting
on a lock held by another server process. In the above example we can infer
that process 1003 is waiting for process 1016 to complete its transaction and
thereby release some lock or other.
@@ -77,22 +77,19 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para>
<productname>Solaris</productname> requires special handling. You must
use <command>/usr/ucb/ps</command>, rather than
- <command>/bin/ps</command>. You also must use two <command>w</command>
+ <command>/bin/ps</command>. You also must use two <option>w</option>
flags, not just one. In addition, your original invocation of the
- <application>postmaster</application> must have a shorter
+ <command>postmaster</command> command must have a shorter
<command>ps</command> status display than that provided by each
- backend. If you fail to do all three things, the <command>ps</>
- output for each backend will be the original <application>postmaster</>
+ server process. If you fail to do all three things, the <command>ps</>
+ output for each server process will be the original <command>postmaster</>
command line.
</para>
</tip>
-
-
-
</sect1>
<sect1 id="monitoring-stats">
- <title>Statistics Collector</Title>
+ <title>The Statistics Collector</Title>
<indexterm zone="monitoring-stats">
<primary>statistics</primary>
@@ -103,7 +100,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
is a subsystem that supports collection and reporting of information about
server activity. Presently, the collector can count accesses to tables
and indexes in both disk-block and individual-row terms. It also supports
- determining the exact query currently being executed by other server
+ determining the exact command currently being executed by other server
processes.
</para>
@@ -113,13 +110,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para>
Since collection of statistics adds some overhead to query execution,
the system can be configured to collect or not collect information.
- This is controlled by configuration variables that are normally set in
- <filename>postgresql.conf</> (see <xref linkend="runtime-config"> for
- details about setting configuration variables).
+ This is controlled by configuration parameters that are normally set in
+ <filename>postgresql.conf</>. (See <xref linkend="runtime-config"> for
+ details about setting configuration parameters.)
</para>
<para>
- The variable <varname>STATS_START_COLLECTOR</varname> must be set to
+ The parameter <varname>stats_start_collector</varname> must be set to
<literal>true</> for the statistics collector to
be launched at all. This is the default and recommended setting,
but it may be turned off if you have no interest in statistics and
@@ -129,32 +126,32 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</para>
<para>
- The variables <varname>STATS_COMMAND_STRING</varname>,
- <varname>STATS_BLOCK_LEVEL</varname>,
- and <varname>STATS_ROW_LEVEL</varname> control how much information is
- actually sent to the collector, and thus determine how much run-time
+ The parameters <varname>stats_command_string</varname>,
+ <varname>stats_block_level</varname>,
+ and <varname>stats_row_level</varname> control how much information is
+ actually sent to the collector and thus determine how much run-time
overhead occurs. These respectively determine whether a server process
sends its current command string, disk-block-level access statistics, and
- row-level access statistics to the collector. Normally these variables are
+ row-level access statistics to the collector. Normally these parameters are
set in <filename>postgresql.conf</> so that they apply to all server
- processes, but it is possible to turn them on or off in individual server
- processes using the <command>SET</> command. (To prevent ordinary users
+ processes, but it is possible to turn them on or off in individual sessions
+ using the <command>SET</> command. (To prevent ordinary users
from hiding their activity from the administrator, only superusers are
- allowed to change these variables with <command>SET</>.)
+ allowed to change these parameters with <command>SET</>.)
</para>
- <important>
+ <note>
<para>
- Since the variables <varname>STATS_COMMAND_STRING</varname>,
- <varname>STATS_BLOCK_LEVEL</varname>, and
- <varname>STATS_ROW_LEVEL</varname> default to <literal>false</>,
+ Since the parameters <varname>stats_command_string</varname>,
+ <varname>stats_block_level</varname>, and
+ <varname>stats_row_level</varname> default to <literal>false</>,
very few statistics are collected in the default
configuration. Enabling one or more of these configuration
variables will significantly enhance the amount of useful data
produced by the statistics collector, at the expense of
additional run-time overhead.
</para>
- </important>
+ </note>
</sect2>
@@ -181,7 +178,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para>
Another important point is that when a server process is asked to display
any of these statistics, it first fetches the most recent totals emitted by
- the collector process. It then continues to use this snapshot for all
+ the collector process and then continues to use this snapshot for all
statistical views and functions until the end of its current transaction.
So the statistics will appear not to change as long as you continue the
current transaction.
@@ -209,9 +206,9 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<entry>One row per server process, showing process
<acronym>ID</>, database, user, current query, and the time at
which the current query began execution. The columns that report
- data on the current query are only available if the
- <varname>STATS_COMMAND_STRING</varname> configuration option has
- been enabled. Furthermore, these columns can only be accessed by
+ data on the current query are only available if the parameter
+ <varname>stats_command_string</varname> has been turned on.
+ Furthermore, these columns can only be accessed by
superusers; or when the user examining the view is the same as the user
in the row; for others it reads as null. (Note that because of the
collector's reporting delay, current query will only be up-to-date for
@@ -220,7 +217,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<row>
<entry><structname>pg_stat_database</></entry>
- <entry>One row per database, showing number of active backends,
+ <entry>One row per database, showing the number of active backend server processes,
total transactions committed and total rolled back in that database,
total disk blocks read, and total number of buffer hits (i.e., block
read requests avoided by finding the block already in buffer cache).
@@ -232,7 +229,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<entry>For each table in the current database, total numbers of
sequential and index scans, total numbers of tuples returned by
each type of scan, and totals of tuple insertions, updates,
- and deletes.</entry>
+ and deletions.</entry>
</row>
<row>
@@ -360,12 +357,12 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
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 take a database OID as argument to identify which database to
+ report on. The per-table and per-index functions take 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 take a backend ID number, which ranges from one to the
+ number of currently active backend processes.
</para>
<table id="monitoring-stats-funcs-table">
@@ -382,15 +379,15 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<tbody>
<row>
- <entry><function>pg_stat_get_db_numbackends</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_numbackends</function>(<type>oid</type>)</literal></entry>
<entry><type>integer</type></entry>
<entry>
- Number of active backends in database
+ Number of active backend processes for database
</entry>
</row>
<row>
- <entry><function>pg_stat_get_db_xact_commit</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_xact_commit</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Transactions committed in database
@@ -398,7 +395,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_db_xact_rollback</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_xact_rollback</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Transactions rolled back in database
@@ -406,7 +403,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_db_blocks_fetched</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_blocks_fetched</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block fetch requests for database
@@ -414,7 +411,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_db_blocks_hit</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_blocks_hit</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block fetch requests found in cache for database
@@ -422,7 +419,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_numscans</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_numscans</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of sequential scans done when argument is a table,
@@ -431,7 +428,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_tuples_returned</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_returned</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples read by sequential scans when argument is a table,
@@ -440,7 +437,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_tuples_fetched</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_fetched</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of valid (unexpired) table tuples fetched by sequential scans
@@ -450,7 +447,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_tuples_inserted</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_inserted</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples inserted into table
@@ -458,7 +455,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_tuples_updated</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_updated</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples updated in table
@@ -466,7 +463,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_tuples_deleted</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_deleted</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples deleted from table
@@ -474,7 +471,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_blocks_fetched</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_blocks_fetched</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block fetch requests for table or index
@@ -482,7 +479,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_blocks_hit</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_blocks_hit</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block requests found in cache for table or index
@@ -490,69 +487,71 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row>
<row>
- <entry><function>pg_stat_get_backend_idset</function>()</entry>
+ <entry><literal><function>pg_stat_get_backend_idset</function>()</literal></entry>
<entry><type>set of integer</type></entry>
<entry>
- Set of currently active backend IDs (from 1 to N where N is the
- number of active backends). See usage example below
+ Set of currently active backend process IDs (from 1 to the
+ number of active backend processes). See usage example in the text.
</entry>
</row>
<row>
- <entry><function>pg_backend_pid</function>()</entry>
+ <entry><literal><function>pg_backend_pid</function>()</literal></entry>
<entry><type>integer</type></entry>
<entry>
- Process ID of the attached backend
+ Process ID of the backend process attached to the current session
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_pid</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_pid</function>(<type>integer</type>)</literal></entry>
<entry><type>integer</type></entry>
<entry>
- Process ID of all backend processes
+ Process ID of the given backend process
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_dbid</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_dbid</function>(<type>integer</type>)</literal></entry>
<entry><type>oid</type></entry>
<entry>
- Database ID of backend process
+ Database ID of the given backend process
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_userid</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_userid</function>(<type>integer</type>)</literal></entry>
<entry><type>oid</type></entry>
<entry>
- User ID of backend process
+ User ID of the given backend process
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_activity</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_activity</function>(<type>integer</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>
- Current query of backend process (NULL if caller is not
- superuser, or is the same user as that of the backend being queried,
- or <varname>STATS_COMMAND_STRING</varname> is not enabled)
+ Active command of the given backend process (null if the
+ current user is not a superuser nor the same user as that of
+ the session being queried, or
+ <varname>stats_command_string</varname> is not on)
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_activity_start</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_activity_start</function>(<type>integer</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>
- The time at which the specified backend's currently executing query was
- initiated (NULL if caller is not superuser, or
- <varname>STATS_COMMAND_STRING</varname> is not enabled)
+ The time at which the specified backend process' currently
+ executing query was started (null if the current user is not a
+ superuser, or <varname>stats_command_string</varname> is not
+ on)
</entry>
</row>
<row>
- <entry><function>pg_stat_reset</function>()</entry>
+ <entry><literal><function>pg_stat_reset</function>()</literal></entry>
<entry><type>boolean</type></entry>
<entry>
Reset all currently collected statistics
@@ -564,8 +563,8 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<note>
<para>
- <literal>blocks_fetched</literal> minus
- <literal>blocks_hit</literal> gives the number of kernel
+ <function>pg_stat_get_db_blocks_fetched</function> minus
+ <function>pg_stat_get_db_blocks_hit</function> 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.
@@ -574,13 +573,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para>
The function <function>pg_stat_get_backend_idset</function> provides
- a convenient way to generate one row for each active backend. For
- example, to show the <acronym>PID</>s and current queries of all backends:
+ a convenient way to generate one row for each active backend process. For
+ example, to show the <acronym>PID</>s and current queries of all backend processes:
<programlisting>
-SELECT pg_stat_get_backend_pid(S.backendid) AS procpid,
- pg_stat_get_backend_activity(S.backendid) AS current_query
-FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
+SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
+ pg_stat_get_backend_activity(s.backendid) AS current_query
+ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;
</programlisting>
</para>
@@ -592,7 +591,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<para>
Another useful tool for monitoring database activity is the
- <literal>pg_locks</literal> system catalog. This allows the
+ <literal>pg_locks</literal> system table. It allows the
database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be used
to:
@@ -609,7 +608,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<listitem>
<para>
- View the relation in the current database with the most
+ Determine the relation in the current database with the most
ungranted locks (which might be a source of contention among
database clients).
</para>
@@ -636,7 +635,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
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.
+ read often.
</para>
</note>
@@ -646,7 +645,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<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
+ for locks on it. A lockable object is either a relation (e.g., a table) 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
@@ -654,13 +653,13 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
</para>
<table id="monitoring-locks-table">
- <title>Lock Status System View</title>
+ <title><literal>pg_locks</literal> Columns</title>
<tgroup cols="3">
<thead>
<row>
<entry>Column Name</entry>
- <entry>Type</entry>
+ <entry>Data Type</entry>
<entry>Description</entry>
</row>
</thead>
@@ -671,7 +670,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<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
+ is a transaction ID. This column can be joined with the column <literal>oid</> of 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
@@ -687,7 +686,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
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>
+ column can be joined with the column <literal>oid</> of the <literal>pg_database</literal>
system catalog to get more information on the locked object's
database.
</entry>
@@ -712,11 +711,11 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<entry><type>integer</type></entry>
<entry>
The process ID of the <productname>PostgreSQL</productname>
- backend belonging to the session that has acquired or is
+ server process 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
+ statistics collector, this column can be joined with the column
<literal>pg_stat_activity</literal> view to get more
- information on the backend holding or waiting to hold the
+ information on the session holding or waiting to hold the
lock.
</entry>
</row>
@@ -740,8 +739,8 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
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
+ The waiting session will sleep until the other lock is released (or a
+ deadlock situation is detected). A single session can be
waiting to acquire at most one lock at a time.
</entry>
</row>
diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index 5a7a27fcf63..4200481c1da 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.8 2003/03/20 18:53:18 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.9 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>clusterdb</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg>--table | -t <replaceable>table</replaceable> </arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
<command>clusterdb</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group><arg>--all</arg><arg>-a</arg></group>
</cmdsynopsis>
</refsynopsisdiv>
@@ -114,7 +114,7 @@ PostgreSQL documentation
<term><option>--table <replaceable class="parameter">table</replaceable></></term>
<listitem>
<para>
- Clusters <replaceable class="parameter">table</replaceable> only.
+ Cluster <replaceable class="parameter">table</replaceable> only.
</para>
</listitem>
</varlistentry>
@@ -134,7 +134,7 @@ PostgreSQL documentation
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -145,7 +145,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
@@ -219,7 +219,7 @@ PostgreSQL documentation
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 43c7046fa8e..c202c52c12b 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.31 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.32 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>createdb</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<arg><replaceable>description</replaceable></arg>
</cmdsynopsis>
@@ -47,7 +47,7 @@ PostgreSQL documentation
endterm="SQL-CREATEDATABASE-title">. Thus, there is nothing
special about creating databases via this or other methods. This
means that a database server must be running at the targeted
- port. Also, any default settings and environment variables used by
+ host. Also, any default settings and environment variables used by
the <application>libpq</application> front-end library will apply.
</para>
</refsect1>
@@ -65,7 +65,7 @@ PostgreSQL documentation
<listitem>
<para>
Specifies the name of the database to be created. The name must be
- unique among all <productname>PostgreSQL</productname> databases in this installation.
+ unique among all <productname>PostgreSQL</productname> databases in this cluster.
The default is to create a database with the same name as the
current system user.
</para>
@@ -98,7 +98,7 @@ PostgreSQL documentation
<term><option>--echo</></term>
<listitem>
<para>
- Echo the queries that <application>createdb</application> generates
+ Echo the commands that <application>createdb</application> generates
and sends to the server.
</para>
</listitem>
@@ -166,7 +166,7 @@ PostgreSQL documentation
<listitem>
<para>
Specifies the host name of the machine on which the
- server is running. If host begins with a slash, it is used
+ server is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -177,7 +177,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or the local Unix domain socket file
+ Specifies the TCP port or the local Unix domain socket file
extension on which the server is listening for connections.
</para>
</listitem>
@@ -296,7 +296,7 @@ PostgreSQL documentation
To create the database <literal>demo</literal> using the
server on host <literal>eden</>, port 5000, using the
<literal>LATIN1</literal> encoding scheme with a look at the
- underlying query:
+ underlying command:
<screen>
<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
<computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput>
diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index 72f82b74028..be86e7c1c79 100644
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.30 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>createlang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg choice="plain"><replaceable>langname</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
<command>createlang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group choice="plain"><arg>--list</arg><arg>-l</arg></group>
<arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
@@ -85,7 +85,7 @@ PostgreSQL documentation
<term><option>--echo</></term>
<listitem>
<para>
- Displays SQL commands as they are executed.
+ Display SQL commands as they are executed.
</para>
</listitem>
</varlistentry>
@@ -95,8 +95,7 @@ PostgreSQL documentation
<term><option>--list</></term>
<listitem>
<para>
- Shows a list of already installed languages in the target database
- (which must be specified).
+ Show a list of already installed languages in the target database.
</para>
</listitem>
</varlistentry>
@@ -127,7 +126,7 @@ PostgreSQL documentation
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -138,7 +137,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
@@ -182,7 +181,7 @@ PostgreSQL documentation
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
@@ -215,7 +214,7 @@ PostgreSQL documentation
<title>Examples</title>
<para>
- To install <literal>pltcl</literal> into the database
+ To install the language <literal>pltcl</literal> into the database
<literal>template1</literal>:
<screen>
<prompt>$ </prompt><userinput>createlang pltcl template1</userinput>
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index faaaa683046..eeafdb944f4 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.31 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.32 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>createuser</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>username</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -78,7 +78,7 @@ PostgreSQL documentation
<listitem>
<para>
The new user is allowed to create other users.
- (Note: Actually, this makes the new user a <firstterm>superuser</>.
+ (Note: Actually, this makes the new user a <emphasis>superuser</>.
The option is poorly named.)
</para>
</listitem>
@@ -120,7 +120,7 @@ PostgreSQL documentation
<term><option>--echo</></term>
<listitem>
<para>
- Echo the queries that <application>createuser</application> generates
+ Echo the commands that <application>createuser</application> generates
and sends to the server.
</para>
</listitem>
@@ -138,8 +138,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-i <replaceable class="parameter">uid</replaceable></></term>
- <term><option>--sysid <replaceable class="parameter">uid</replaceable></></term>
+ <term><option>-i <replaceable class="parameter">number</replaceable></></term>
+ <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
<listitem>
<para>
Allows you to pick a non-default user ID for the new user. This is not
@@ -200,7 +200,7 @@ PostgreSQL documentation
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -211,7 +211,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
@@ -311,7 +311,7 @@ PostgreSQL documentation
<para>
To create the same user <literal>joe</literal> using the
server on host <literal>eden</>, port 5000, avoiding the prompts and
- taking a look at the underlying query:
+ taking a look at the underlying command:
<screen>
<prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
<computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput>
diff --git a/doc/src/sgml/ref/current_date.sgml b/doc/src/sgml/ref/current_date.sgml
deleted file mode 100644
index 5e06c4dd70d..00000000000
--- a/doc/src/sgml/ref/current_date.sgml
+++ /dev/null
@@ -1,148 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.5 2002/04/21 19:02:39 thomas Exp $
-Postgres documentation
--->
-
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.5 2002/04/21 19:02:39 thomas Exp $
-Postgres documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-DATE">
- <REFMETA>
- <REFENTRYTITLE>CURRENT_DATE</REFENTRYTITLE>
- <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
- <REFNAME>
- CURRENT_DATE
- </REFNAME>
- <REFPURPOSE>
-Returns the current date
- </REFPURPOSE>
- <REFSYNOPSISDIV>
- <REFSYNOPSISDIVINFO>
- <DATE>1998-04-15</DATE>
- </REFSYNOPSISDIVINFO>
- <SYNOPSIS>
- CURRENT_DATE
- </SYNOPSIS>
-
- <REFSECT2 ID="R2-SQL-CURRENT-DATE-1">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Inputs
- </TITLE>
- <PARA>
-None.
- </REFSECT2>
-
- <REFSECT2 ID="R2-SQL-CURRENT-DATE-2">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Outputs
- </TITLE>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
-<replaceable>date</replaceable>
-
- </TERM>
- <LISTITEM>
- <PARA>
- Returns "<replaceable class="parameter">today</replaceable>".
- </VARIABLELIST>
- </REFSECT2>
- </REFSYNOPSISDIV>
-
- <REFSECT1 ID="R1-SQL-CURRENT-DATE-1">
- <REFSECT1INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT1INFO>
- <TITLE>
- Description
- </TITLE>
- <PARA>
- The niladic CURRENT_DATE function has a data type of
- DATE and returns the date at the time that it is run.
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-DATE-3">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Notes
- </TITLE>
- <PARA>
- Refer to SET DATESTYLE for further information about date format.
- </PARA>
- </REFSECT2>
-
- <REFSECT1 ID="R1-SQL-CURRENT-DATE-2">
- <TITLE>
- Usage
- </TITLE>
- <PARA>
- Insert the date of insertion into a row:
- </PARA>
- <ProgramListing>
- INSERT INTO films
- VALUES ('TM999','Ben Hur',105,CURRENT_DATE,'Action',NULL);
- </ProgramListing>
-
- <PARA>
- Display CURRENT-DATE:
- </PARA>
- <ProgramListing>
- SELECT CURRENT_DATE AS today;
-
- today
- ------------
- 1998-03-31
-
- </ProgramListing>
- </REFSECT1>
-
- <REFSECT1 ID="R1-SQL-CURRENT-DATE-3">
- <TITLE>
- Compatibility
- </TITLE>
- <PARA>
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-DATE-4">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- SQL92
- </TITLE>
- <PARA>
- Full compatibility.
- </PARA>
- </refsect2>
- </refsect1>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/ref/current_time.sgml b/doc/src/sgml/ref/current_time.sgml
deleted file mode 100644
index 85cd7e7da6f..00000000000
--- a/doc/src/sgml/ref/current_time.sgml
+++ /dev/null
@@ -1,158 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_time.sgml,v 1.6 2002/04/21 19:02:39 thomas Exp $
-PostgreSQL documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-TIME">
- <REFMETA>
- <REFENTRYTITLE>CURRENT_TIME</REFENTRYTITLE>
- <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
- <REFNAME>
- CURRENT_TIME
- </REFNAME>
- <REFPURPOSE>
-Returns the current local time
- </REFPURPOSE>
- <REFSYNOPSISDIV>
- <REFSYNOPSISDIVINFO>
- <DATE>1998-04-15</DATE>
- </REFSYNOPSISDIVINFO>
- <SYNOPSIS>
- CURRENT_TIME
- </SYNOPSIS>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIME-1">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Inputs
- </TITLE>
- <PARA>
-None.
-
- </REFSECT2>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIME-2">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Outputs
- </TITLE>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <replaceable>time</replaceable>
-
- <LISTITEM>
- <PARA>
- <ReturnValue>Returns "<replaceable class="parameter">now</replaceable>"</ReturnValue>
-
- </VARIABLELIST>
- </REFSECT2>
- </REFSYNOPSISDIV>
-
- <REFSECT1 ID="R1-SQL-CURRENT-TIME-1">
- <REFSECT1INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT1INFO>
- <TITLE>
- Description
- </TITLE>
- <PARA>
- The niladic CURRENT_TIME function has a data type of
- TIME and returns the local time when it is run.
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIME-3">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Notes
- </TITLE>
- <PARA> Refer to the SET TIME ZONE statement for a further description
- of local time.
- </PARA>
- </REFSECT2>
-
- <REFSECT1 ID="R1-SQL-CURRENT-TIME-2">
- <TITLE>
- Usage
- </TITLE>
- <PARA>Display CURRENT_TIME:
- </PARA>
- <ProgramListing>
- SELECT CURRENT_TIME AS now;
-
- now
- -----------
- 17:41:31+02
-
- </ProgramListing>
- </REFSECT1>
-
- <REFSECT1 ID="R1-SQL-CURRENT-TIME-3">
- <TITLE>
- Compatibility
- </TITLE>
- <PARA>
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIME-4">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- SQL92
- </TITLE>
- <PARA>
- SQL92 specifies some additional capabilities for CURRENT_TIME:
- </PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- </TERM>
- <LISTITEM>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>
- CURRENT_TIME [ (<replaceable class="parameter">scale</replaceable>) ]</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- The optional scale for CURRENT_TIME, if specified, is an
- unsigned integer representing the number of digits in the
- optional seconds fraction of the time value represented
- by the function.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/ref/current_timestamp.sgml b/doc/src/sgml/ref/current_timestamp.sgml
deleted file mode 100644
index 75782dbc72f..00000000000
--- a/doc/src/sgml/ref/current_timestamp.sgml
+++ /dev/null
@@ -1,166 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_timestamp.sgml,v 1.6 2002/04/21 19:02:39 thomas Exp $
-PostgreSQL documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-TIMESTAMP">
- <REFMETA>
- <REFENTRYTITLE>CURRENT_TIMESTAMP</REFENTRYTITLE>
- <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
- <REFNAME>
- CURRENT_TIMESTAMP
- </REFNAME>
- <REFPURPOSE>
- Returns the current date and time
- </REFPURPOSE>
-
-
- <REFSYNOPSISDIV>
- <REFSYNOPSISDIVINFO>
- <DATE>1998-04-15</DATE>
- </REFSYNOPSISDIVINFO>
- <synopsis>
- CURRENT_TIMESTAMP
- </SYNOPSIS>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-1">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Inputs
- </TITLE>
- <PARA>
-None.
-
- </REFSECT2>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-2">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Outputs
- </TITLE>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
-<replaceable>timestamp</replaceable>
-
- <LISTITEM>
- <PARA>
- Returns "<replaceable class="parameter">today</replaceable>" and "<replaceable class="parameter">now</replaceable>".
-
- </VARIABLELIST>
- </REFSECT2>
- </REFSYNOPSISDIV>
-
- <REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-1">
- <REFSECT1INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT1INFO>
- <TITLE>
- Description
- </TITLE>
- <PARA>
- The niladic CURRENT_TIMESTAMP function has a data type of
- TIMESTAMP and returns the date and local time at which it is run.
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-3">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Notes
- </TITLE>
- <PARA>
- Refer to the SET TIME ZONE statement for a further description
- of local time.
- </PARA>
-
-
- </REFSECT2>
-
- <REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-2">
- <TITLE>
- Usage
- </TITLE>
- <PARA>
- Display CURRENT_TIMESTAMP:
- </PARA>
- <ProgramListing>
- SELECT CURRENT_TIMESTAMP AS date_and_time;
-
- date_and_time
- ----------------------
- 1998-03-31 07:41:21-08
- </ProgramListing>
- </REFSECT1>
-
- <REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-3">
- <TITLE>
- Compatibility
- </TITLE>
- <PARA>
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-4">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- SQL92
- </TITLE>
- <PARA>
- SQL92 specifies some additional capabilities for CURRENT_TIMESTAMP:
- </PARA>
-
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- </TERM>
- <LISTITEM>
- <PARA>
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <ReturnValue>CURRENT_TIMESTAMP [ (<replaceable class="parameter">scale</replaceable>) ]</ReturnValue>
- </TERM>
- <LISTITEM>
- <PARA>
- The optional scale for CURRENT_TIMESTAMP, if specified, is an
- unsigned integer representing the number of digits in the
- optional seconds fraction of the time value represented
- by the function.
- </PARA>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
- </para>
- </LISTITEM>
- </VARLISTENTRY>
- </VARIABLELIST>
- </refsect2>
- </refsect1>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/ref/current_user.sgml b/doc/src/sgml/ref/current_user.sgml
deleted file mode 100644
index 630728da9dd..00000000000
--- a/doc/src/sgml/ref/current_user.sgml
+++ /dev/null
@@ -1,167 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_user.sgml,v 1.7 2002/08/13 20:40:43 momjian Exp $
-PostgreSQL documentation
--->
-
-<REFENTRY ID="SQL-CURRENT-USER">
- <REFMETA>
- <REFENTRYTITLE>CURRENT_USER</REFENTRYTITLE>
- <REFMISCINFO>SQL - Functions</REFMISCINFO>
- </REFMETA>
- <REFNAMEDIV>
- <REFNAME>
- CURRENT_USER
- </REFNAME>
- <REFPURPOSE>
- Returns the current user name
- </REFPURPOSE>
- <REFSYNOPSISDIV>
- <REFSYNOPSISDIVINFO>
- <DATE>1998-04-15</DATE>
- </REFSYNOPSISDIVINFO>
- <SYNOPSIS>
- CURRENT_USER
- </SYNOPSIS>
-
- <REFSECT2 ID="R2-SQL-CURRENT-USER-1">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Inputs
- </TITLE>
- <PARA>
-
-None.
- </REFSECT2>
-
- <REFSECT2 ID="R2-SQL-CURRENT-USER-2">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Outputs
- </TITLE>
- <PARA>
-
- <VARIABLELIST>
- <VARLISTENTRY>
- <TERM>
- <replaceable>username</replaceable>
- </TERM>
- <LISTITEM>
- <PARA>
-The name of the current user.
-
- </VARIABLELIST>
- </REFSECT2>
- </REFSYNOPSISDIV>
-
- <REFSECT1 ID="R1-SQL-CURRENT-USER-1">
- <REFSECT1INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT1INFO>
- <TITLE>
- Description
- </TITLE>
- <PARA>
- The niladic CURRENT_USER function returns a string of type "name"
- whose value represents a user name identification.
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-USER-3">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- Notes
- </TITLE>
- <PARA>
- Data type "name" is a non-standard 63-character type for storing
- system identifiers.
- </PARA>
- </REFSECT2>
-
- <REFSECT1 ID="R1-SQL-CURRENT-USER-2">
- <TITLE>
- Usage
- </TITLE>
- <PARA>
- Display CURRENT_USER
- </PARA>
- <ProgramListing>
- SELECT CURRENT_USER AS who_am_i;
-
- who_am_i
- ------------
- jose
- </ProgramListing>
- </REFSECT1>
-
- <REFSECT1 ID="R1-SQL-CURRENT-USER-3">
- <TITLE>
- Compatibility
- </TITLE>
- <PARA>
- </PARA>
-
- <REFSECT2 ID="R2-SQL-CURRENT-USER-4">
- <REFSECT2INFO>
- <DATE>1998-04-15</DATE>
- </REFSECT2INFO>
- <TITLE>
- SQL92
- </TITLE>
- <PARA>
- SQL92 specifies some additional niladic USER functions:
- </PARA>
- <variablelist>
- <varlistentry>
- <term>CURRENT_USER / USER</term>
- <listitem>
- <para>
- USER is a synonym for CURRENT_USER.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>SESSION_USER</term>
- <listitem>
- <para>
- The SESSION_USER function returns the SQL-session user name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>SYSTEM_USER</term>
- <listitem>
- <para>
- The SYSTEM_USER function returns the database's initial default user.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- A niladic USER function returns a SQL_TEXT character string whose
- value represents a user name.
- </para>
- </refsect2>
- </refsect1>
-</REFENTRY>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"../reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:"/usr/lib/sgml/catalog"
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml
index 302d5128259..107718d5aca 100644
--- a/doc/src/sgml/ref/dropdb.sgml
+++ b/doc/src/sgml/ref/dropdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.20 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.21 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>dropdb</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -57,9 +57,7 @@ PostgreSQL documentation
<term><replaceable class="parameter">dbname</replaceable></term>
<listitem>
<para>
- Specifies the name of the database to be removed. The database
- must be one of the existing <productname>PostgreSQL</productname> databases
- in this installation.
+ Specifies the name of the database to be removed.
</para>
</listitem>
</varlistentry>
@@ -69,7 +67,7 @@ PostgreSQL documentation
<term><option>--echo</></term>
<listitem>
<para>
- Echo the queries that <application>dropdb</application> generates
+ Echo the commands that <application>dropdb</application> generates
and sends to the server.
</para>
</listitem>
@@ -109,7 +107,7 @@ PostgreSQL documentation
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -120,7 +118,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
@@ -212,7 +210,7 @@ PostgreSQL documentation
<para>
To destroy the database <literal>demo</literal> using the
server on host <literal>eden</literal>, port 5000, with verification and a peek
- at the underlying query:
+ at the underlying command:
<screen>
<prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
<computeroutput>Database "demo" will be permanently deleted.
diff --git a/doc/src/sgml/ref/droplang.sgml b/doc/src/sgml/ref/droplang.sgml
index a7163520bbe..6bddf1a5ba5 100644
--- a/doc/src/sgml/ref/droplang.sgml
+++ b/doc/src/sgml/ref/droplang.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.22 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.23 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>droplang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg choice="plain"><replaceable>langname</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
<command>droplang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group choice="plain"><arg>--list</arg><arg>-l</arg></group>
<arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
@@ -85,7 +85,7 @@ PostgreSQL documentation
<term><option>--echo</></term>
<listitem>
<para>
- Displays SQL commands as they are executed.
+ Display SQL commands as they are executed.
</para>
</listitem>
</varlistentry>
@@ -95,8 +95,7 @@ PostgreSQL documentation
<term><option>--list</></term>
<listitem>
<para>
- Shows a list of already installed languages in the target database
- (which must be specified).
+ Show a list of already installed languages in the target database.
</para>
</listitem>
</varlistentry>
@@ -171,7 +170,7 @@ PostgreSQL documentation
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
@@ -204,7 +203,7 @@ PostgreSQL documentation
<title>Examples</title>
<para>
- To remove <literal>pltcl</literal>:
+ To remove the language <literal>pltcl</literal>:
<screen>
<prompt>$ </prompt><userinput>droplang pltcl dbname</userinput>
</screen>
diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml
index 53e371c439f..67536993e56 100644
--- a/doc/src/sgml/ref/dropuser.sgml
+++ b/doc/src/sgml/ref/dropuser.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.23 2003/03/18 22:19:46 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.24 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>dropuser</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>username</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -31,8 +31,8 @@ PostgreSQL documentation
<application>dropuser</application> removes an existing
<productname>PostgreSQL</productname> user
<emphasis>and</emphasis> the databases which that user owned.
- Only users with <literal>usesuper</literal> set in
- the <literal>pg_shadow</literal> table can destroy
+ Only superusers (users with <literal>usesuper</literal> set in
+ the <literal>pg_shadow</literal> table) can destroy
<productname>PostgreSQL</productname> users.
</para>
@@ -61,7 +61,6 @@ PostgreSQL documentation
<listitem>
<para>
Specifies the name of the <productname>PostgreSQL</productname> user to be removed.
- This name must exist in the <productname>PostgreSQL</productname> installation.
You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
@@ -72,7 +71,7 @@ PostgreSQL documentation
<term><option>--echo</></term>
<listitem>
<para>
- Echo the queries that <application>dropuser</application> generates
+ Echo the commands that <application>dropuser</application> generates
and sends to the server.
</para>
</listitem>
@@ -112,7 +111,7 @@ PostgreSQL documentation
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -123,7 +122,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
@@ -219,9 +218,9 @@ PostgreSQL documentation
</para>
<para>
- To remove user <literal>joe</literal> using the postmaster on host
+ To remove user <literal>joe</literal> using the server on host
<literal>eden</literal>, port 5000, with verification and a peek at the underlying
- query:
+ command:
<screen>
<prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
<computeroutput>User "joe" and any owned databases will be permanently deleted.
diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml
index a38d731b944..995fe88aca0 100644
--- a/doc/src/sgml/ref/ecpg-ref.sgml
+++ b/doc/src/sgml/ref/ecpg-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -66,7 +66,7 @@ PostgreSQL documentation
<term><option>-c</option></term>
<listitem>
<para>
- Automatically generate C code from SQL code. Currently, this
+ Automatically generate certain C code from SQL code. Currently, this
works for <literal>EXEC SQL TYPE</literal>.
</para>
</listitem>
@@ -101,7 +101,7 @@ PostgreSQL documentation
<term><option>-o <replaceable>filename</replaceable></option></term>
<listitem>
<para>
- Specifies that <application>ecpg</application> should write all
+ Specifies that <command>ecpg</command> should write all
its output to the given <replaceable>filename</replaceable>.
</para>
</listitem>
@@ -111,9 +111,9 @@ PostgreSQL documentation
<term><option>-t</option></term>
<listitem>
<para>
- Turn on autocommit of transactions. In this mode, each query is
+ Turn on autocommit of transactions. In this mode, each SQL command is
automatically committed unless it is inside an explicit
- transaction block. In the default mode, queries are committed
+ transaction block. In the default mode, commands are committed
only when <command>EXEC SQL COMMIT</command> is issued.
</para>
</listitem>
@@ -130,7 +130,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>---help</option></term>
+ <term><option>--help</option></term>
<listitem>
<para>
Show a brief summary of the command usage, then exit.
@@ -165,7 +165,7 @@ PostgreSQL documentation
<para>
Programs using C code with embedded SQL have to be linked against
the <filename>libecpg</filename> library, for example using the
- flags <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
+ linker options <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
</para>
<para>
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 7d63df874d9..5009fa1ff9e 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>initdb</command>
- <arg rep="repeat">options</arg>
+ <arg rep="repeat"><replaceable>option</></arg>
<group choice="plain">
<arg>--pgdata </arg>
<arg>-D </arg>
@@ -33,17 +33,17 @@ PostgreSQL documentation
</title>
<para>
<command>initdb</command> creates a new
- <productname>PostgreSQL</productname> database cluster (or database
- system). A database cluster is a collection of databases that are
- managed by a single server instance.
+ <productname>PostgreSQL</productname> database cluster. A database
+ cluster is a collection of databases that are managed by a single
+ server instance.
</para>
<para>
- Creating a database system consists of creating the directories in which
+ Creating a database cluster consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that belong to the whole cluster rather than to any particular
database), and creating the <literal>template1</literal>
- database. When you create a new database, everything in the
+ database. When you later create a new database, everything in the
<literal>template1</literal> database is copied.
It contains catalog tables filled in for things like the
built-in types.
@@ -99,7 +99,7 @@ PostgreSQL documentation
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
<listitem>
<para>
- This option specifies the directory where the database system
+ This option specifies the directory where the database cluster
should be stored. This is the only information required by
<command>initdb</command>, but you can avoid writing it by
setting the <envar>PGDATA</envar> environment variable, which
@@ -117,9 +117,7 @@ PostgreSQL documentation
<para>
Selects the encoding of the template database. This will also
be the default encoding of any database you create later, unless you
- override it there. To use the encoding feature, you must
- have enabled it at build time, at which time you also select the default
- for this option.
+ override it there. The default is <literal>SQL_ASCII</literal>.
</para>
</listitem>
</varlistentry>
@@ -205,7 +203,7 @@ PostgreSQL documentation
<listitem>
<para>
Specifies where <command>initdb</command> should find
- its input files to initialize the database system. This is
+ its input files to initialize the database cluster. This is
normally not necessary. You will be told if you need to
specify their location explicitly.
</para>
@@ -219,7 +217,7 @@ PostgreSQL documentation
<para>
By default, when <command>initdb</command>
determines that an error prevented it from completely creating the database
- system, it removes any files it may have created before discovering
+ cluster, it removes any files it may have created before discovering
that it can't finish the job. This option inhibits tidying-up and is
thus useful for debugging.
</para>
@@ -239,7 +237,7 @@ PostgreSQL documentation
<listitem>
<para>
- Specifies the directory where the database system is to be
+ Specifies the directory where the database cluster is to be
stored; may be overridden using the <option>-D</option> option.
</para>
</listitem>
diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml
index 01c018a3b46..1b62aeeba05 100644
--- a/doc/src/sgml/ref/initlocation.sgml
+++ b/doc/src/sgml/ref/initlocation.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.18 2003/01/19 00:13:29 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.19 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -47,9 +47,9 @@ PostgreSQL documentation
<screen>
<prompt>$ </prompt><userinput>export PGDATA2=/opt/postgres/data</userinput>
</screen>
- Stop and start postmaster so it sees the <envar>PGDATA2</envar>
+ Stop and start <command>postmaster</> so it sees the <envar>PGDATA2</envar>
environment variable. The system must be configured so the
- postmaster sees <envar>PGDATA2</envar> every time it starts. Finally:
+ <command>postmaster</> sees <envar>PGDATA2</envar> every time it starts. Finally:
<screen>
<prompt>$</prompt> <userinput>initlocation PGDATA2</userinput>
<prompt>$</prompt> <userinput>createdb -D PGDATA2 testdb</userinput>
diff --git a/doc/src/sgml/ref/ipcclean.sgml b/doc/src/sgml/ref/ipcclean.sgml
index 76eee6f1077..85ca334c178 100644
--- a/doc/src/sgml/ref/ipcclean.sgml
+++ b/doc/src/sgml/ref/ipcclean.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.7 2002/04/21 19:02:39 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.8 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -36,12 +36,10 @@ PostgreSQL documentation
<para>
Only the database administrator should execute this program as it
can cause bizarre behavior (i.e., crashes) if run during multiuser
- execution. If this command is executed while a
- <application>postmaster</application> is running, the shared memory
- and semaphores allocated by the
- <application>postmaster</application> will be deleted. This will
- result in a general failure of the backend servers started by that
- <application>postmaster</application>.
+ execution. If this command is executed while a server is running,
+ the shared memory and semaphores allocated by that server will be
+ deleted, which would have rather severe consequences for that
+ server.
</para>
</refsect1>
@@ -51,14 +49,14 @@ PostgreSQL documentation
<para>
This script is a hack, but in the many years since it was written,
no one has come up with an equally effective and portable solution.
- Since the <application>postmaster</application> can now clean up by
+ Since the <command>postmaster</command> can now clean up by
itself, it is unlikely that <command>ipcclean</command> will be
improved upon in the future.
</para>
<para>
The script makes assumption about the format of output of the
- <application>ipcs</application>
+ <command>ipcs</command>
utility which may not be true across different operating systems.
Therefore, it may not work on your particular OS.
</para>
diff --git a/doc/src/sgml/ref/pg_config-ref.sgml b/doc/src/sgml/ref/pg_config-ref.sgml
index 9b26e2f5275..755faa429c5 100644
--- a/doc/src/sgml/ref/pg_config-ref.sgml
+++ b/doc/src/sgml/ref/pg_config-ref.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.13 2003/01/19 00:13:29 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.14 2003/03/24 14:32:51 petere Exp $ -->
<refentry id="app-pgconfig">
<refmeta>
@@ -50,7 +50,7 @@
<listitem>
<para>
Print the location of user executables. Use this, for example, to find
- the <application>psql</> program. This is normally also the location
+ the <command>psql</> program. This is normally also the location
where the <filename>pg_config</> program resides.
</para>
</listitem>
@@ -130,10 +130,10 @@
<title>Notes</title>
<para>
- The option <option>--includedir-server</option> is new in
+ The option <option>--includedir-server</option> was new in
<productname>PostgreSQL</> 7.2. In prior releases, the server include files were
installed in the same location as the client headers, which could
- be queried with the <option>--includedir</option>. To make your
+ be queried with the option <option>--includedir</option>. To make your
package handle both cases, try the newer option first and test the
exit status to see whether it succeeded.
</para>
diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml
index 2fa44e3c10e..314022eb925 100644
--- a/doc/src/sgml/ref/pg_controldata.sgml
+++ b/doc/src/sgml/ref/pg_controldata.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_controldata.sgml,v 1.4 2002/08/17 05:07:18 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_controldata.sgml,v 1.5 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -12,7 +12,7 @@ PostgreSQL documentation
<refnamediv>
<refname>pg_controldata</refname>
- <refpurpose>display server-wide control information</refpurpose>
+ <refpurpose>display control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -25,16 +25,16 @@ PostgreSQL documentation
<refsect1 id="R1-APP-PGCONTROLDATA-1">
<title>Description</title>
<para>
- <command>pg_controldata</command> returns information initialized during
- <application>initdb</>, such as the catalog version and server locale.
+ <command>pg_controldata</command> prints information initialized during
+ <command>initdb</>, such as the catalog version and server locale.
It also shows information about write-ahead logging and checkpoint
- processing. This information is server-wide, and not specific to any one
+ processing. This information is cluster-wide, and not specific to any one
database.
</para>
<para>
- This utility may only be run by the user who installed the server because
- it requires read access to the <literal>datadir</>.
+ This utility may only be run by the user who initialized the cluster because
+ it requires read access to the data directory.
You can specify the data directory on the command line, or use
the environment variable <envar>PGDATA</>.
</para>
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml
index f9043ff5025..c74f9d603b5 100644
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.20 2003/03/20 17:37:46 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.21 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -69,17 +69,17 @@ PostgreSQL documentation
<title>Description</title>
<para>
<application>pg_ctl</application> is a utility for starting,
- stopping, or restarting <xref linkend="app-postmaster">, the
- <productname>PostgreSQL</productname> backend server, or displaying
- the status of a running postmaster. Although the postmaster can be
- started manually, <application>pg_ctl</application> encapsulates
- tasks such as redirecting log output and properly detaching from the
- terminal and process group. It also provides convenient options for
+ stopping, or restarting the <productname>PostgreSQL</productname>
+ backend server (<xref linkend="app-postmaster">), or displaying the
+ status of a running server. Although the server can be started
+ manually, <application>pg_ctl</application> encapsulates tasks such
+ as redirecting log output and properly detaching from the terminal
+ and process group. It also provides convenient options for
controlled shutdown.
</para>
<para>
- In <option>start</option> mode, a new postmaster is launched. The
+ In <option>start</option> mode, a new server is launched. The
server is started in the background, and standard input is attached to
<filename>/dev/null</filename>. The standard output and standard
error are either appended to a log file (if the <option>-l</option>
@@ -87,42 +87,45 @@ PostgreSQL documentation
standard output (not standard error). If no log file is chosen, the
standard output of <application>pg_ctl</application> should be redirected
to a file or piped to another process, for example a log rotating program,
- otherwise the postmaster will write its output to the controlling
+ otherwise <command>postmaster</command> will write its output to the controlling
terminal (from the background) and will not leave the shell's
process group.
</para>
<para>
- In <option>stop</option> mode, the postmaster that is running in
+ In <option>stop</option> mode, the server that is running in
the specified data directory is shut down. Three different
shutdown methods can be selected with the <option>-m</option>
option: <quote>Smart</quote> mode waits for all the clients to
disconnect. This is the default. <quote>Fast</quote> mode does
not wait for clients to disconnect. All active transactions are
rolled back and clients are forcibly disconnected, then the
- database is shut down. <quote>Immediate</quote> mode will abort
+ server is shut down. <quote>Immediate</quote> mode will abort
all server processes without a clean shutdown. This will lead to
a recovery run on restart.
</para>
<para>
<option>restart</option> mode effectively executes a stop followed
- by a start. This allows the changing of postmaster command line
- options.
+ by a start. This allows changing the <command>postmaster</command>
+ command-line options.
</para>
<para>
- <option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
- causing it to reread its configuration files
- (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
- etc.). This allows changing of configuration-file options that do not
- require a complete restart to take effect.
+ <option>reload</option> mode simply sends the
+ <command>postmaster</command> process a <systemitem>SIGHUP</>
+ signal, causing it to reread its configuration files
+ (<filename>postgresql.conf</filename>,
+ <filename>pg_hba.conf</filename>, etc.). This allows changing of
+ configuration-file options that do not require a complete restart
+ to take effect.
</para>
<para>
- <option>status</option> mode checks whether a postmaster is running.
- If it is, the <acronym>PID</acronym> and the command line
- options that were used to invoke it are displayed.
+ <option>status</option> mode checks whether a server is running in
+ the specified data directory. If it is, the <acronym>PID</acronym>
+ and the command line options that were used to invoke it are
+ displayed.
</para>
</refsect1>
@@ -133,7 +136,7 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term>-D <replaceable class="parameter">datadir</replaceable></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
Specifies the file system location of the database files. If
@@ -144,7 +147,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-l <replaceable class="parameter">filename</replaceable></term>
+ <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
Append the server log output to
@@ -156,7 +159,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-m <replaceable class="parameter">mode</replaceable></term>
+ <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
<listitem>
<para>
Specifies the shutdown mode. <replaceable>mode</replaceable>
@@ -168,35 +171,35 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-o <replaceable class="parameter">options</replaceable></term>
+ <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
<listitem>
<para>
- Specifies options to be passed directly to
- <application>postmaster</application>.
+ Specifies options to be passed directly to the
+ <command>postmaster</command> command.
</para>
<para>
- The parameters are usually surrounded by single or double
+ The options are usually surrounded by single or double
quotes to ensure that they are passed through as a group.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-p <replaceable class="parameter">path</replaceable></term>
+ <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
<listitem>
<para>
Specifies the location of the <filename>postmaster</filename>
- executable. By default the postmaster is taken from the same
+ executable. By default the <filename>postmaster</filename> executable is taken from the same
directory as <command>pg_ctl</command>, or failing that, the hard-wired
installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors
- that the postmaster was not found.
+ that the <filename>postmaster</filename> executable was not found.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-s</term>
+ <term><option>-s</option></term>
<listitem>
<para>
Only print errors, no informational messages.
@@ -205,7 +208,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-w</term>
+ <term><option>-w</option></term>
<listitem>
<para>
Wait for the start or shutdown to complete. Times out after
@@ -224,7 +227,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-W</term>
+ <term><option>-W</option></term>
<listitem>
<para>
Do not wait for start or shutdown to complete. This is the
@@ -276,9 +279,10 @@ PostgreSQL documentation
<term><filename>postmaster.pid</filename></term>
<listitem>
- <para>The existence of this file in the data directory is used to help
- <application>pg_ctl</application> determine if the server is
- currently running or not.
+ <para>
+ The existence of this file in the data directory is used to help
+ <application>pg_ctl</application> determine if the server is
+ currently running or not.
</para>
</listitem>
</varlistentry>
@@ -287,11 +291,12 @@ PostgreSQL documentation
<term><filename>postmaster.opts.default</filename></term>
<listitem>
- <para>If this file exists in the data directory,
- <application>pg_ctl</application> (in <option>start</option> mode)
- will pass the contents of the file as options to the
- <application>postmaster</application>, unless overridden
- by the <option>-o</option> option.
+ <para>
+ If this file exists in the data directory,
+ <application>pg_ctl</application> (in <option>start</option>
+ mode) will pass the contents of the file as options to the
+ <command>postmaster</command> command, unless overridden by the
+ <option>-o</option> option.
</para>
</listitem>
</varlistentry>
@@ -314,10 +319,10 @@ PostgreSQL documentation
<term><filename>postgresql.conf</filename></term>
<listitem>
- <para>This file, located in the data directory, is parsed to
- find the proper port to send to the
- <application>psql</application> when the <option>-w</option>
- is given in <option>start</option> mode.
+ <para>
+ This file, located in the data directory, is parsed to find the
+ proper port to use with <application>psql</application> when the
+ <option>-w</option> is given in <option>start</option> mode.
</para>
</listitem>
</varlistentry>
@@ -332,7 +337,7 @@ PostgreSQL documentation
<para>
Waiting for complete start is not a well-defined operation and may
fail if access control is set up so that a local client cannot
- connect without manual interaction (e.g. password authentication).
+ connect without manual interaction (e.g., password authentication).
</para>
</refsect1>
@@ -341,25 +346,25 @@ PostgreSQL documentation
<title>Examples</title>
<refsect2 id="R2-APP-PGCTL-3">
- <title>Starting the postmaster</title>
+ <title>Starting the Server</title>
<para>
- To start up a <application>postmaster</application>:
+ To start up a server:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
</para>
<para>
- An example of starting the <application>postmaster</application>,
- blocking until the postmaster comes up is:
+ An example of starting the server, blocking until the server has
+ come up is:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
</para>
<para>
- For a <application>postmaster</application> using port 5433, and
+ For a server using port 5433, and
running without <function>fsync</function>, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
@@ -368,32 +373,32 @@ PostgreSQL documentation
</refsect2>
<refsect2 id="R2-APP-PGCTL-4">
- <title>Stopping the postmaster</title>
+ <title>Stopping the Server</title>
<para>
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
- stops the postmaster. Using the <option>-m</option> switch allows one
+ stops the server. Using the <option>-m</option> switch allows one
to control <emphasis>how</emphasis> the backend shuts down.
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-5">
- <title>Restarting the postmaster</title>
+ <title>Restarting the Server</title>
<para>
- This is almost equivalent to stopping the
- <application>postmaster</application> and starting it again
+ Restarting the server is almost equivalent to stopping the
+ server and starting it again
except that <command>pg_ctl</command> saves and reuses the command line options that
were passed to the previously running instance. To restart
- the <application>postmaster</application> in the simplest form:
+ the server in the simplest form, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
</para>
<para>
- To restart <application>postmaster</application>,
+ To restart server,
waiting for it to shut down and to come up:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
@@ -409,7 +414,7 @@ PostgreSQL documentation
</refsect2>
<refsect2 id="R2-APP-PGCTL-6">
- <title>Showing postmaster status</title>
+ <title>Showing the Server Status</title>
<para>
Here is a sample status output from
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 85fba6e812e..0c279db427c 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.58 2003/03/18 17:05:01 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.59 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_dump</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -54,14 +54,6 @@ PostgreSQL documentation
architectures.
</para>
- <para>
- <application>pg_dump</application> will save the information necessary to
- re-generate all user-defined types, functions, tables, indexes,
- aggregates, and operators. In addition, all the data is copied out
- in text format so that it can be readily copied in again, as well
- as imported into tools for editing.
- </para>
-
<para>
When used with one of the archive file formats and combined with
<application>pg_restore</application>, <application>pg_dump</application> provides a
@@ -73,14 +65,14 @@ PostgreSQL documentation
The most flexible output file format is the <quote>custom</quote>
format (<option>-Fc</option>). It allows for selection and
reordering of all archived items, and is compressed by default. The
- <filename>tar</filename> format (<option>-Ft</option>) is not
+ <application>tar</application> format (<option>-Ft</option>) is not
compressed and it is not possible to reorder data when loading, but
it is otherwise quite flexible; moreover, it can be manipulated with
- other tools such as <filename>tar</filename>.
+ other tools such as <command>tar</command>.
</para>
<para>
- While running <command>pg_dump</command>, one should examine the
+ While running <application>pg_dump</application>, one should examine the
output for any warnings (printed on standard error), especially in
light of the limitations listed below.
</para>
@@ -198,7 +190,7 @@ PostgreSQL documentation
<replaceable>table</replaceable>
(<replaceable>column</replaceable>, ...) VALUES
...</literal>). This will make restoration very slow,
- but it is necessary if you desire to rearrange column ordering.
+ but it is necessary if you desire to rearrange the column ordering.
</para>
</listitem>
</varlistentry>
@@ -224,7 +216,7 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term>p</term>
+ <term><literal>p</></term>
<listitem>
<para>
Output a plain-text <acronym>SQL</acronym> script file (default)
@@ -233,10 +225,10 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>t</term>
+ <term><literal>t</></term>
<listitem>
<para>
- Output a <filename>tar</filename> archive suitable for input into
+ Output a <command>tar</command> archive suitable for input into
<application>pg_restore</application>. Using this archive format
allows reordering and/or exclusion of schema elements
at the time the database is restored. It is also possible to limit
@@ -246,7 +238,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>c</term>
+ <term><literal>c</></term>
<listitem>
<para>
Output a custom archive suitable for input into
@@ -514,8 +506,9 @@ PostgreSQL documentation
<term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
<listitem>
<para>
- Specify the compression level to use in archive formats that support
- compression (currently only the custom archive format supports compression).
+ Specify the compression level to use in archive formats that
+ support compression. (Currently only the custom archive
+ format supports compression.)
</para>
</listitem>
</varlistentry>
@@ -531,9 +524,11 @@ PostgreSQL documentation
<term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
<listitem>
<para>
- Specifies the host name of the machine on which the server is
- running. If the host name begins with a slash, it is used as the
- directory for the Unix domain socket.
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <envar>PGHOST</envar> environment variable, if set,
+ else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
@@ -543,11 +538,10 @@ PostgreSQL documentation
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the server
- is listening for connections. The port number defaults to 5432,
- or the value of the <envar>PGPORT</envar>
- environment variable (if set).
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
@@ -596,42 +590,13 @@ PostgreSQL documentation
<refsect1 id="app-pgdump-diagnostics">
<title>Diagnostics</title>
- <msgset>
- <msgentry>
- <msg>
- <msgmain>
- <msgtext>
-<screen>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
- Is the postmaster running locally
- and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-</screen>
- </msgtext>
- </msgmain>
- </msg>
-
- <msgexplan>
- <para>
- <application>pg_dump</application> could not connect to the
- PostgreSQL server on the specified host and port. If you see this
- message, ensure that the server is running on the proper host and
- that you have specified the proper port.
- </para>
- </msgexplan>
- </msgentry>
-
- </msgset>
-
- <note>
- <para>
- <application>pg_dump</application> internally executes
- <command>SELECT</command> statements. If you have problems running
- <application>pg_dump</application>,
- make sure you are able to select information from the database using, for
- example, <xref linkend="app-psql">.
- </para>
- </note>
+ <para>
+ <application>pg_dump</application> internally executes
+ <command>SELECT</command> statements. If you have problems running
+ <application>pg_dump</application>, make sure you are able to
+ select information from the database using, for example, <xref
+ linkend="app-psql">.
+ </para>
</refsect1>
@@ -639,11 +604,11 @@ connectDBStart() -- connect() failed: No such file or directory
<title>Notes</title>
<para>
- If your installation has any local additions to the template1 database,
+ If your database cluster has any local additions to the <literal>template1</> database,
be careful to restore the output of <application>pg_dump</application> into a
truly empty database; otherwise you are likely to get errors due to
duplicate definitions of the added objects. To make an empty database
- without any local additions, copy from template0 not template1,
+ without any local additions, copy from <literal>template0</> not <literal>template1</>,
for example:
<programlisting>
CREATE DATABASE foo WITH TEMPLATE template0;
@@ -657,17 +622,20 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<listitem>
<para>
When dumping a single table or as plain text, <application>pg_dump</application>
- does not handle large objects. Large objects must be dumped in their
- entirety using one of the binary archive formats.
+ does not handle large objects. Large objects must be dumped with the
+ entire database using one of the non-text archive formats.
</para>
</listitem>
<listitem>
<para>
- When doing a data-only dump, <application>pg_dump</application> emits queries
- to disable triggers on user tables before inserting the data and queries to
- re-enable them after the data has been inserted. If the restore is stopped
- in the middle, the system catalogs may be left in the wrong state.
+ When a data-only dump is chosen and the option
+ <option>--disable-triggers</> is used,
+ <application>pg_dump</application> emits commands to disable
+ triggers on user tables before inserting the data and commands
+ to re-enable them after the data has been inserted. If the
+ restore is stopped in the middle, the system catalogs may be
+ left in the wrong state.
</para>
</listitem>
@@ -732,9 +700,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para>
The <application>pg_dump</application> utility first appeared in
- <application>Postgres95</application> release <literal>0.02</literal>. The
+ <application>Postgres95</application> release 0.02. The
non-plain-text output formats were introduced in
- <application>PostgreSQL</application> release <literal>7.1</literal>.
+ <application>PostgreSQL</application> release 7.1.
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index b584bb447ab..f33c81dd870 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.37 2003/03/18 00:02:11 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.38 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_dumpall</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -63,8 +63,8 @@ PostgreSQL documentation
</para>
<para>
- <application>pg_dumpall</application> might need to connect several
- times to the <productname>PostgreSQL</productname> server, asking for
+ <application>pg_dumpall</application> needs to connect several
+ times to the <productname>PostgreSQL</productname> server and might be asking for
a password each time. It is convenient to have a
<filename>$HOME/.pgpass</> file in such cases.
</para>
@@ -96,7 +96,7 @@ PostgreSQL documentation
<para>
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very
- slow, but it makes the output more portable to other RDBMS
+ slow, but it makes the output more portable to other SQL database
packages.
</para>
</listitem>
@@ -184,10 +184,10 @@ PostgreSQL documentation
<listitem>
<para>
Specifies the host name of the machine on which the database
- server is running. If host begins with a slash, it is used as
- the directory for the Unix domain socket. The default is
- taken from the <envar>PGHOST</envar> environment variable, if
- set, else a Unix domain socket connection is attempted.
+ server is running. If the value begins with a slash, it is
+ used as the directory for the Unix domain socket. The default
+ is taken from the <envar>PGHOST</envar> environment variable,
+ if set, else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
@@ -196,9 +196,10 @@ PostgreSQL documentation
<term>-p <replaceable>port</replaceable></term>
<listitem>
<para>
- The port number on which the server is listening. Defaults to
- the <envar>PGPORT</envar> environment variable, if set, or a
- compiled-in default.
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
@@ -237,7 +238,7 @@ PostgreSQL documentation
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
@@ -254,18 +255,10 @@ PostgreSQL documentation
messages will refer to <application>pg_dump</application>.
</para>
- <para>
- <application>pg_dumpall</application> will need to connect several
- times to the <productname>PostgreSQL</productname> server. If password
- authentication is configured, it will ask for a password each time. In
- that case it would be convenient to set up a <filename>.pgpass</>
- password file.
- </para>
-
<para>
Once restored, it is wise to run <command>ANALYZE</> on each
database so the optimizer has useful statistics. You
- can also run <command>vacuumdb -a -z</> to <command>ANALYZE</> all
+ can also run <command>vacuumdb -a -z</> to analyze all
databases.
</para>
diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetxlog.sgml
index 61fce46a17d..a125b5f17a8 100644
--- a/doc/src/sgml/ref/pg_resetxlog.sgml
+++ b/doc/src/sgml/ref/pg_resetxlog.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.6 2002/10/02 21:30:13 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -12,7 +12,7 @@ PostgreSQL documentation
<refnamediv>
<refname>pg_resetxlog</refname>
- <refpurpose>reset write-ahead log and pg_control contents</refpurpose>
+ <refpurpose>reset the write-ahead log and other control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -30,25 +30,24 @@ PostgreSQL documentation
<refsect1 id="R1-APP-PGRESETXLOG-1">
<title>Description</title>
<para>
- <command>pg_resetxlog</command> clears the write-ahead log and
- optionally resets some fields in the <filename>pg_control</> file. This
- function is sometimes
- needed if these files have become corrupted.
- It should be used only as a last resort,
- when the server will not start due to such corruption.
+ <command>pg_resetxlog</command> clears the write-ahead log (WAL) and
+ optionally resets some other control information (stored in the
+ <filename>pg_control</> file). This function is sometimes needed
+ if these files have become corrupted. It should be used only as a
+ last resort, when the server will not start due to such corruption.
</para>
<para>
After running this command, it should be possible to start the server,
but bear in mind that the database may contain inconsistent data due to
partially-committed transactions. You should immediately dump your data,
- run <application>initdb</>, and reload. After reload, check for
+ run <command>initdb</>, and reload. After reload, check for
inconsistencies and repair as needed.
</para>
<para>
This utility can only be run by the user who installed the server, because
- it requires read/write access to the <literal>datadir</>.
+ it requires read/write access to the data directory.
For safety reasons, you must specify the data directory on the command line.
<command>pg_resetxlog</command> does not use the environment variable
<envar>PGDATA</>.
@@ -64,12 +63,12 @@ PostgreSQL documentation
The first three of these can be set using the switches discussed below.
<command>pg_resetxlog</command>'s own environment is the source for its
guess at the locale fields; take care that <envar>LANG</> and so forth
- match the environment that <application>initdb</> was run in.
+ match the environment that <command>initdb</> was run in.
If you are not able to determine correct values for all these fields,
<literal>-f</> can still be used, but
the recovered database must be treated with even more suspicion than
- usual --- an immediate dump and reload is imperative. <emphasis>Do not</>
- execute any data-modifying operations in the database before you dump,
+ usual: an immediate dump and reload is imperative. <emphasis>Do not</>
+ execute any data-modifying operations in the database before you dump;
as any such action is likely to make the corruption worse.
</para>
@@ -79,8 +78,8 @@ PostgreSQL documentation
be set manually. These are only needed when
<command>pg_resetxlog</command> is unable to determine appropriate values
by reading <filename>pg_control</>. A safe value for the
- next transaction ID may be determined by looking for the largest
- file name in <envar>$PGDATA</><filename>/pg_clog</>, adding one,
+ next transaction ID may be determined by looking for the numerically largest
+ file name in the directory <filename>pg_clog</> under the data directory, adding one,
and then multiplying by 1048576. Note that the file names are in
hexadecimal. It is usually easiest to specify the switch value in
hexadecimal too. For example, if <filename>0011</> is the largest entry
@@ -88,7 +87,7 @@ PostgreSQL documentation
zeroes provide the proper multiplier).
The WAL starting address should be
larger than any file number currently existing in
- <envar>$PGDATA</><filename>/pg_xlog</>. These also are in hex, and
+ the directory <filename>pg_xlog</> under the data directory. The addresses are also in hexadecimal and
have two parts. For example, if <filename>000000FF0000003A</> is the
largest entry in <filename>pg_xlog</>, <literal>-l 0xFF,0x3B</> will work.
There is no comparably easy way to determine a next OID that's beyond
@@ -109,14 +108,14 @@ PostgreSQL documentation
<title>Notes</title>
<para>
- This command must not be used when the <application>postmaster</> is
+ This command must not be used when the server is
running. <command>pg_resetxlog</command> will refuse to start up if
- it finds a postmaster lock file in the <literal>datadir</>. If the
- <application>postmaster</> crashed then a lock file may have been left
+ it finds a server lock file in the data directory. If the
+ server crashed then a lock file may have been left
behind; in that case you can remove the lock file to allow
<command>pg_resetxlog</command> to run. But before you do
so, make doubly certain that there
- is no postmaster nor any backend server process still alive.
+ is no <command>postmaster</command> nor any backend server process still alive.
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 427cbd45514..f1b90871d19 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -1,10 +1,6 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.36 2003/03/18 00:02:11 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.37 2003/03/24 14:32:51 petere Exp $ -->
<refentry id="APP-PGRESTORE">
- <docinfo>
- <date>2001-03-06</date>
- </docinfo>
-
<refmeta>
<refentrytitle>pg_restore</refentrytitle>
<manvolnum>1</manvolnum>
@@ -22,7 +18,8 @@
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_restore</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
+ <arg><replaceable>filename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -34,36 +31,31 @@
<application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive
created by <xref linkend="app-pgdump"> in one of the non-plain-text
- formats. It
- will issue the commands necessary to re-generate all user-defined
- types, functions, tables, indexes, aggregates, and operators, as
- well as the data in the tables.
- </para>
-
- <para>
- The archive files contain information for
- <application>pg_restore</application> to rebuild the database, but also
- allow <application>pg_restore</application> to be selective about what is
- restored, or even to reorder the items prior to being restored. The
- archive files are designed to be portable across architectures.
+ formats. It will issue the commands necessary to reconstruct the
+ database to the state it was in at the time it was saved. The
+ archive files also allow <application>pg_restore</application> to
+ be selective about what is restored, or even to reorder the items
+ prior to being restored. The archive files are designed to be
+ portable across architectures.
</para>
<para>
- <application>pg_restore</application> can operate in two modes: If a
- database name is specified, the archive is restored directly into
- the database. Otherwise, a script containing the SQL commands
- necessary to rebuild the database is created (and written to a file
- or standard output), similar to the ones created by the
- <application>pg_dump</application> plain text format. Some of the options
- controlling the script output are therefore analogous to
+ <application>pg_restore</application> can operate in two modes: If
+ a database name is specified, the archive is restored directly into
+ the database. Large objects can only be restored by using a direct
+ database connection. Otherwise, a script containing the SQL
+ commands necessary to rebuild the database is created (and written
+ to a file or standard output), similar to the ones created by the
+ <application>pg_dump</application> plain text format. Some of the
+ options controlling the script output are therefore analogous to
<application>pg_dump</application> options.
</para>
<para>
Obviously, <application>pg_restore</application> cannot restore information
- that is not present in the archive file; for instance, if the
+ that is not present in the archive file. For instance, if the
archive was made using the <quote>dump data as
- <command>INSERT</command>s</quote> option,
+ <command>INSERT</command> commands</quote> option,
<application>pg_restore</application> will not be able to load the data
using <command>COPY</command> statements.
</para>
@@ -73,12 +65,12 @@
<title>Options</title>
<para>
- <command>pg_restore</command> accepts the following command
+ <application>pg_restore</application> accepts the following command
line arguments.
<variablelist>
<varlistentry>
- <term><replaceable class="parameter">archive-name</replaceable></term>
+ <term><replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Specifies the location of the archive file to be restored.
@@ -92,7 +84,7 @@
<term><option>--data-only</option></term>
<listitem>
<para>
- Restore only the data, no schema (definitions).
+ Restore only the data, not the schema (data definitions).
</para>
</listitem>
</varlistentry>
@@ -113,7 +105,7 @@
<listitem>
<para>
Create the database before restoring into it. (When this
- switch appears, the database named with <option>-d</option> is
+ option is used, the database named with <option>-d</option> is
used only to issue the initial <literal>CREATE DATABASE</>
command. All data is restored into the database name that
appears in the archive.)
@@ -128,8 +120,7 @@
<para>
Connect to database <replaceable
class="parameter">dbname</replaceable> and restore directly
- into the database. Large objects can only be restored by using
- a direct database connection.
+ into the database.
</para>
</listitem>
</varlistentry>
@@ -155,14 +146,13 @@
the format, since <application>pg_restore</application> will
determine the format automatically. If specified, it can be
one of the following:
- </para>
<variablelist>
<varlistentry>
- <term>t</term>
+ <term><literal>t</></term>
<listitem>
<para>
- Archive is a <filename>tar</filename> archive. Using this
+ The archive is a <command>tar</command> archive. Using this
archive format allows reordering and/or exclusion of schema
elements at the time the database is restored. It is also
possible to limit which data is reloaded at restore time.
@@ -171,10 +161,10 @@
</varlistentry>
<varlistentry>
- <term>c</term>
+ <term><literal>c</></term>
<listitem>
<para>
- Archive is in the custom format of
+ The archive is in the custom format of
<application>pg_dump</application>. This is the most
flexible format in that it allows reordering of data load
as well as schema elements. This format is also compressed
@@ -183,6 +173,7 @@
</listitem>
</varlistentry>
</variablelist>
+ </para>
</listitem>
</varlistentry>
@@ -201,8 +192,7 @@
<term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
<listitem>
<para>
- Restore definition for named <replaceable
- class="parameter">index</replaceable> only.
+ Restore definition of named index only.
</para>
</listitem>
</varlistentry>
@@ -212,7 +202,7 @@
<term><option>--list</option></term>
<listitem>
<para>
- List the contents of the archive. The output of this command
+ List the contents of the archive. The output of this operation
can be used with the <option>-L</option> option to restrict
and reorder the items that are restored.
</para>
@@ -228,7 +218,7 @@
CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
order they appear in the file. Lines can be moved and may also
be commented out by placing a <literal>;</literal> at the
- start of the line.
+ start of the line. (See below for examples.)
</para>
</listitem>
</varlistentry>
@@ -268,7 +258,8 @@
<para>
Prevent any attempt to restore original object
ownership. Objects will be owned by the user name used to
- attach to the database.
+ attach to the database. See also under <option>-R</option> and
+ <option>-X use-set-session-authorization</option>.
</para>
</listitem>
</varlistentry>
@@ -278,7 +269,7 @@
<term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
<listitem>
<para>
- Specify a procedure or function to be restored.
+ Restore the named function only.
</para>
</listitem>
</varlistentry>
@@ -327,7 +318,8 @@
<term><option>--schema-only</option></term>
<listitem>
<para>
- Restore the schema (definitions), no data. Sequence values will be reset.
+ Restore only the schema (data defintions), not the data.
+ Sequence values will be reset.
</para>
</listitem>
</varlistentry>
@@ -348,7 +340,7 @@
<term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
<listitem>
<para>
- Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only.
+ Restore definition and/or data of named table only.
</para>
</listitem>
</varlistentry>
@@ -358,7 +350,7 @@
<term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
<listitem>
<para>
- Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only.
+ Restore named trigger only.
</para>
</listitem>
</varlistentry>
@@ -431,7 +423,7 @@
</para>
<para>
- <command>pg_restore</command> also accepts
+ <application>pg_restore</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
@@ -441,8 +433,10 @@
<listitem>
<para>
Specifies the host name of the machine on which the server is
- running. If host begins with a slash, it is used as the
- directory for the Unix domain socket.
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <envar>PGHOST</envar> environment variable, if set,
+ else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
@@ -452,11 +446,11 @@
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket
- file extension on which the server is listening for
- connections. The port number defaults to 5432, or the value
- of the <envar>PGPORT</envar> environment variable (if set).
- </para>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
+ </para>
</listitem>
</varlistentry>
@@ -494,7 +488,7 @@
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
@@ -505,45 +499,14 @@
<refsect1 id="app-pgrestore-diagnostics">
<title>Diagnostics</title>
- <msgset>
- <msgentry>
- <msg>
- <msgmain>
- <msgtext>
-<screen>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
- Is the postmaster running locally
- and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-</screen>
- </msgtext>
- </msgmain>
- </msg>
-
- <msgexplan>
- <para>
- <application>pg_restore</application> could not attach to the
- <productname>PostgreSQL</> server process on the specified
- host and port. If you see this message, ensure that the
- server is running on the proper host and that you have
- specified the proper port. If your site uses an
- authentication system, ensure that you have obtained the
- required authentication credentials.
- </para>
- </msgexplan>
- </msgentry>
- </msgset>
-
- <note>
- <para>
- When a direct database connection is specified using the -d
- option, <application>pg_restore</application> internally executes
- <acronym>SQL</acronym> statements. If you have problems running
- <application>pg_restore</application>, make sure you are able to select
- information from the database using, for example,
- <application>psql</application>.
- </para>
- </note>
+ <para>
+ When a direct database connection is specified using the
+ <option>-d</option> option, <application>pg_restore</application>
+ internally executes <acronym>SQL</acronym> statements. If you have
+ problems running <application>pg_restore</application>, make sure
+ you are able to select information from the database using, for
+ example, <application>psql</application>.
+ </para>
</refsect1>
@@ -556,9 +519,9 @@ connectDBStart() -- connect() failed: No such file or directory
<application>pg_restore</application> into a truly empty database;
otherwise you are likely to get errors due to duplicate definitions
of the added objects. To make an empty database without any local
- additions, copy from template0 not template1, for example:
+ additions, copy from <literal>template0</> not <literal>template1</>, for example:
<programlisting>
-CREATE DATABASE foo WITH TEMPLATE = template0;
+CREATE DATABASE foo WITH TEMPLATE template0;
</programlisting>
</para>
@@ -568,8 +531,10 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
<itemizedlist>
<listitem>
<para>
- When restoring data to a pre-existing table, <application>pg_restore</application> emits queries
- to disable triggers on user tables before inserting the data then emits queries to
+ When restoring data to a pre-existing table and the option
+ <option>--disable-triggers</> is used,
+ <application>pg_restore</application> emits commands
+ to disable triggers on user tables before inserting the data then emits commands to
re-enable them after the data has been inserted. If the restore is stopped in the
middle, the system catalogs may be left in the wrong state.
</para>
@@ -601,20 +566,6 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
<refsect1 id="app-pgrestore-examples">
<title>Examples</title>
- <para>
- To dump a database:
-<screen>
-<prompt>$</prompt> <userinput>pg_dump mydb > db.out</userinput>
-</screen>
- </para>
-
- <para>
- To reload this database:
-<screen>
-<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
-</screen>
- </para>
-
<para>
To dump a database called <literal>mydb</> that contains
large objects to a <filename>tar</filename> file:
@@ -665,7 +616,7 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>
- Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
+ Semicolons start a comment, and the numbers at the start of lines refer to the
internal archive ID assigned to each item.
</para>
@@ -678,8 +629,8 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
- could be used as input to <command>pg_restore</command> and would only restore
- items 10 and 6, in that order.
+ could be used as input to <application>pg_restore</application> and would only restore
+ items 10 and 6, in that order:
<screen>
<prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
</screen>
diff --git a/doc/src/sgml/ref/pgtclsh.sgml b/doc/src/sgml/ref/pgtclsh.sgml
index 21ac402ff39..d915ffe00de 100644
--- a/doc/src/sgml/ref/pgtclsh.sgml
+++ b/doc/src/sgml/ref/pgtclsh.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtclsh.sgml,v 1.6 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtclsh.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pgtclsh</command>
- <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>arguments</replaceable></arg></arg>
+ <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/pgtksh.sgml b/doc/src/sgml/ref/pgtksh.sgml
index b0689259788..5d2513afbaf 100644
--- a/doc/src/sgml/ref/pgtksh.sgml
+++ b/doc/src/sgml/ref/pgtksh.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtksh.sgml,v 1.6 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtksh.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pgtksh</command>
- <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>arguments</replaceable></arg></arg>
+ <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index 7b282eb295a..8d1bc512ebf 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.30 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -62,7 +62,7 @@ PostgreSQL documentation
<arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
</group>
<arg>-S <replaceable>sort-mem</replaceable></arg>
- <arg>-v <replaceable>protocol-version</replaceable></arg>
+ <arg>-v <replaceable>protocol</replaceable></arg>
<arg>-W <replaceable>seconds</replaceable></arg>
<arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
</cmdsynopsis>
@@ -72,7 +72,7 @@ PostgreSQL documentation
<title>Description</title>
<para>
- The <filename>postgres</filename> executable is the actual
+ The <command>postgres</command> executable is the actual
<productname>PostgreSQL</productname> server process that processes
queries. It is normally not called directly; instead a <xref
linkend="app-postmaster"> multiuser server is started.
@@ -80,7 +80,7 @@ PostgreSQL documentation
<para>
The second form above is how
- <application>postgres</application> is invoked by the <xref
+ <command>postgres</command> is invoked by the <xref
linkend="app-postmaster"> (only
conceptually, since both <filename>postmaster</filename> and
<filename>postgres</filename> are in fact the same program); it
@@ -94,15 +94,15 @@ PostgreSQL documentation
When invoked in interactive mode from the shell, the user can enter
queries and the results will be printed to the screen, but in a
form that is more useful for developers than end users. But note
- that running a single-user backend is not truly suitable for
+ that running a single-user server is not truly suitable for
debugging the server since no realistic interprocess communication
and locking will happen.
</para>
<para>
- When running a stand-alone backend, the session user will be set to
+ When running a stand-alone server, the session user will be set to
the user with ID 1. This user does not actually have to exist, so
- a stand-alone backend can be used to manually recover from certain
+ a stand-alone server can be used to manually recover from certain
kinds of accidental damage to the system catalogs. Implicit
superuser powers are granted to the user with ID 1 in stand-alone
mode.
@@ -113,11 +113,11 @@ PostgreSQL documentation
<title>Options</title>
<para>
- When <application>postgres</application> is started by a <xref
+ When <command>postgres</command> is started by a <xref
linkend="app-postmaster"> then it
inherits all options set by the latter. Additionally,
- <application>postgres</application>-specific options can be passed
- from the <application>postmaster</application> with the
+ <command>postgres</command>-specific options can be passed
+ from the <command>postmaster</command> with the
<option>-o</option> switch.
</para>
@@ -129,7 +129,7 @@ PostgreSQL documentation
variable <envar>PGOPTIONS</envar> is set, then
<application>libpq</>-based clients will pass that string to the
server, which will interpret it as
- <application>postgres</application> command-line options.
+ <command>postgres</command> command-line options.
</para>
<refsect2>
@@ -138,10 +138,10 @@ PostgreSQL documentation
<para>
The options <option>-A</option>, <option>-B</option>,
<option>-c</option>, <option>-d</option>, <option>-D</option>,
- <option>-F</option>, and <option>--name</> have the same meanings
+ <option>-F</option>, and <option>--<replaceable>name</></option> have the same meanings
as the <xref linkend="app-postmaster"> except that
- <option>-d</option> <literal>0</> prevents the debugging level of
- the postmaster from being propagated to the backend.
+ <literal>-d 0</> prevents the server log level of
+ the <command>postmaster</> from being propagated to <command>postgres</>.
</para>
<variablelist>
@@ -162,12 +162,12 @@ PostgreSQL documentation
<term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
- Sends all debugging and error output to
+ Send all server log output to
<replaceable class="parameter">filename</replaceable>.
- If the backend is running under the
- <application>postmaster</application>, this option is ignored,
+ If <command>postgres</command> is running under the
+ <command>postmaster</command>, this option is ignored,
and the <systemitem>stderr</> inherited from the
- <application>postmaster</application> is used.
+ <command>postmaster</command> is used.
</para>
</listitem>
</varlistentry>
@@ -176,7 +176,7 @@ PostgreSQL documentation
<term><option>-P</option></term>
<listitem>
<para>
- Ignore system indexes while scanning/updating system tuples. The
+ Ignore system indexes while scanning/updating system tables. The
<command>REINDEX</command> command for system tables/indexes
requires this option to be used.
</para>
@@ -187,7 +187,7 @@ PostgreSQL documentation
<term><option>-s</option></term>
<listitem>
<para>
- Print time information and other statistics at the end of each query.
+ Print time information and other statistics at the end of each command.
This is useful for benchmarking or for use in tuning the number of
buffers.
</para>
@@ -200,7 +200,7 @@ PostgreSQL documentation
<para>
Specifies the amount of memory to be used by internal sorts and hashes
before resorting to temporary disk files. The value is specified in
- kilobytes, and defaults to 512 kilobytes. Note that for a complex query,
+ kilobytes, and defaults to 1024. Note that for a complex query,
several sorts and/or hashes might be running in parallel, and each one
will be allowed to use as much as
<replaceable class="parameter">sort-mem</replaceable> kilobytes
@@ -230,7 +230,7 @@ PostgreSQL documentation
<term><option>-E</option></term>
<listitem>
<para>
- Echo all queries.
+ Echo all commands.
</para>
</listitem>
</varlistentry>
@@ -239,7 +239,7 @@ PostgreSQL documentation
<term><option>-N</option></term>
<listitem>
<para>
- Disables use of newline as a query delimiter.
+ Disables use of newline as a statement delimiter.
</para>
</listitem>
</varlistentry>
@@ -268,6 +268,7 @@ PostgreSQL documentation
disable sequential and index scans respectively, while
<literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
disable nested-loop, merge and hash joins respectively.
+ </para>
<note>
<para>
@@ -277,7 +278,6 @@ PostgreSQL documentation
plan types if it has any other alternative.
</para>
</note>
- </para>
</listitem>
</varlistentry>
@@ -295,7 +295,7 @@ PostgreSQL documentation
<listitem>
<para>
Allows the structure of system tables to be modified. This is
- used by <application>initdb</application>.
+ used by <command>initdb</command>.
</para>
</listitem>
</varlistentry>
@@ -304,9 +304,8 @@ PostgreSQL documentation
<term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
<listitem>
<para>
- Indicates that this server has been started by a
- <application>postmaster</application> and makes different
- assumptions about buffer pool management, file descriptors,
+ Indicates that this process has been started by a
+ <command>postmaster</command> and specifies the database to use.
etc.
</para>
</listitem>
@@ -339,7 +338,7 @@ PostgreSQL documentation
<para>
As soon as this option is encountered, the process sleeps for
the specified amount of seconds. This gives developers time
- to attach a debugger to the backend process.
+ to attach a debugger to the server process.
</para>
</listitem>
</varlistentry>
@@ -375,10 +374,10 @@ PostgreSQL documentation
<para>
To stop a running query use the <literal>SIGINT</literal> signal. To
- tell <application>postgres</application> to reread the config file,
+ tell <command>postgres</command> to reread the configuration file,
use a <literal>SIGHUP</literal> signal. The
- <application>postmaster</application> uses <literal>SIGTERM</literal>
- to tell a postgres process to quit normally and
+ <command>postmaster</command> uses <literal>SIGTERM</literal>
+ to tell a <command>postgres</command> process to quit normally and
<literal>SIGQUIT</literal> to terminate without the normal cleanup.
These <emphasis>should not</emphasis> be used by users.
</para>
@@ -389,17 +388,17 @@ PostgreSQL documentation
<title>Usage</title>
<para>
- Start a stand-alone backend with a command like
+ Start a stand-alone server with a command like
<screen>
-<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
+<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
</screen>
- Provide the correct path to the database area with <option>-D</>, or
+ Provide the correct path to the database directory with <option>-D</>, or
make sure that the environment variable <envar>PGDATA</> is set.
Also specify the name of the particular database you want to work in.
</para>
<para>
- Normally, the stand-alone backend treats newline as the command
+ Normally, the stand-alone server treats newline as the command
entry terminator; there is no intelligence about semicolons,
as there is in <application>psql</>. To continue a command
across multiple lines, you must type backslash just before each
@@ -408,9 +407,9 @@ PostgreSQL documentation
<para>
But if you use the <option>-N</> command line switch, then newline does
- not terminate command entry. The backend will read the standard input
+ not terminate command entry. In this case, the server will read the standard input
until the end-of-file (<acronym>EOF</>) marker, then
- process the input as a single query string. Backslash-newline is not
+ process the input as a single command string. Backslash-newline is not
treated specially in this case.
</para>
@@ -422,7 +421,7 @@ PostgreSQL documentation
</para>
<para>
- Note that the stand-alone backend does not provide sophisticated
+ Note that the stand-alone server does not provide sophisticated
line-editing features (no command history, for example).
</para>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index e22c5b9d16b..36bd38f8c1f 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.34 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.35 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -41,33 +41,33 @@ PostgreSQL documentation
<title>Description</title>
<para>
- <application>postmaster</application> is the
+ <command>postmaster</command> is the
<productname>PostgreSQL</productname> multiuser database server.
In order for a client application to access a database it connects
(over a network or locally) to a running
- <application>postmaster</application>. The
- <application>postmaster</application> then starts a separate server
+ <command>postmaster</command>. The
+ <command>postmaster</command> then starts a separate server
process (<quote><xref linkend="app-postgres"></quote>) to handle
- the connection. The <application>postmaster</application> also
+ the connection. The <command>postmaster</command> also
manages the communication among server processes.
</para>
<para>
- By default the <application>postmaster</application> starts in the
- foreground and prints log messages to the standard output. In
- practical applications the <application>postmaster</application>
+ By default the <command>postmaster</command> starts in the
+ foreground and prints log messages to the standard error stream. In
+ practical applications the <command>postmaster</command>
should be started as a background process, perhaps at boot time.
</para>
<para>
- One <application>postmaster</application> always manages the data
+ One <command>postmaster</command> always manages the data
from exactly one database cluster. A database cluster is a
collection of databases that is stored at a common file system
- location. When the postmaster starts it needs to know the location
+ location. When the <command>postmaster</command> starts it needs to know the location
of the database cluster files (<quote>data area</quote>). This is
done with the <option>-D</option> invocation option or the
<envar>PGDATA</envar> environment variable; there is no default.
- More than one postmaster process can run on a system at one time,
+ More than one <command>postmaster</command> process can run on a system at one time,
as long as they use different data areas and different
communication ports (see below). A data area is created with <xref
linkend="app-initdb">.
@@ -78,17 +78,17 @@ PostgreSQL documentation
<title>Options</title>
<para>
- <application>postmaster</application> accepts the following
+ <command>postmaster</command> accepts the following
command line arguments. For a detailed discussion of the options
consult the &cite-admin;. You can also save typing most of these
options by setting up a configuration file.
<variablelist>
<varlistentry>
- <term>-A 0|1</term>
+ <term><option>-A 0|1</option></term>
<listitem>
<para>
- Enables run-time assert checks, which is a debugging aid to
+ Enables run-time assertion checks, which is a debugging aid to
detect programming mistakes. This is only available if it was
enabled during compilation. If so, the default is on.
</para>
@@ -96,7 +96,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-B <replaceable class="parameter">nbuffers</replaceable></term>
+ <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
<listitem>
<para>
Sets the number of shared buffers for use by the server
@@ -107,7 +107,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+ <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem>
<para>
Sets a named run-time parameter. Consult the &cite-admin; for
@@ -120,7 +120,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-d <replaceable>debug-level</replaceable></term>
+ <term><option>-d <replaceable>debug-level</replaceable></option></term>
<listitem>
<para>
Sets the debug level. The higher this value is set, the more
@@ -131,7 +131,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-D <replaceable class="parameter">datadir</replaceable></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
Specifies the file system location of the data directory. See
@@ -141,12 +141,12 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-F</term>
+ <term><option>-F</option></term>
<listitem>
<para>
Disables <function>fsync</function> calls for performance
improvement, at the risk of data corruption in event of a
- system crash. This parameter corresponds to setting
+ system crash. This option corresponds to setting
<literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
documentation before using this!
</para>
@@ -158,11 +158,11 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-h <replaceable class="parameter">hostname</replaceable></term>
+ <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
<listitem>
<para>
- Specifies the TCP/IP host name or address on which the
- <application>postmaster</application> is to listen for
+ Specifies the IP host name or address on which the
+ <command>postmaster</command> is to listen for
connections from client applications. Defaults to
listening on all configured addresses (including
<systemitem class="systemname">localhost</systemitem>).
@@ -171,7 +171,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-i</term>
+ <term><option>-i</option></term>
<listitem>
<para>
Allows clients to connect via TCP/IP (Internet domain)
@@ -180,18 +180,18 @@ PostgreSQL documentation
to setting <literal>tcpip_socket=true</> in <filename>postgresql.conf</>.
</para>
<para>
- <option>--tcpip_socket=false</option> has the opposite
+ <option>--tcpip-socket=false</option> has the opposite
effect of this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-k <replaceable class="parameter">directory</replaceable></term>
+ <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
<listitem>
<para>
Specifies the directory of the Unix-domain socket on which the
- <application>postmaster</application> is to listen for
+ <command>postmaster</command> is to listen for
connections from client applications. The default is normally
<filename>/tmp</filename>, but can be changed at build time.
</para>
@@ -199,7 +199,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-l</term>
+ <term><option>-l</option></term>
<listitem>
<para>
Enables secure connections using SSL. The <option>-i</option>
@@ -210,11 +210,11 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-N <replaceable class="parameter">max-connections</replaceable></term>
+ <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
<listitem>
<para>
Sets the maximum number of client connections that this
- <application>postmaster</application> will accept. By
+ <command>postmaster</command> will accept. By
default, this value is 32, but it can be set as high as your
system will support. (Note that
<option>-B</option> is required to be at least twice
@@ -226,13 +226,13 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-o <replaceable class="parameter">extra-options</replaceable></term>
+ <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
<listitem>
<para>
The command line-style options specified in <replaceable
class="parameter">extra-options</replaceable> are passed to
- all backend server processes started by this
- <application>postmaster</application>. See <xref
+ all server processes started by this
+ <command>postmaster</command>. See <xref
linkend="app-postgres"> for possibilities. If the option
string contains any spaces, the entire string must be quoted.
</para>
@@ -240,11 +240,11 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-p <replaceable class="parameter">port</replaceable></term>
+ <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
Specifies the TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the <command>postmaster</command>
is to listen for connections from client applications.
Defaults to the value of the <envar>PGPORT</envar> environment
variable, or if <envar>PGPORT</envar> is not set, then
@@ -257,10 +257,10 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-S</term>
+ <term><option>-S</option></term>
<listitem>
<para>
- Specifies that the <application>postmaster</application>
+ Specifies that the <command>postmaster</command>
process should start up in silent mode. That is, it will
disassociate from the user's (controlling) terminal, start its
own process group, and redirect its standard output and
@@ -270,17 +270,17 @@ PostgreSQL documentation
Using this switch discards all logging output, which is
probably not what you want, since it makes it very difficult
to troubleshoot problems. See below for a better way to start
- the <application>postmaster</application> in the background.
+ the <command>postmaster</command> in the background.
</para>
<para>
- <option>--silent_mode=false</option> has the opposite effect
+ <option>--silent-mode=false</option> has the opposite effect
of this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+ <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem>
<para>
Sets a named run-time parameter; a shorter form of
@@ -294,17 +294,18 @@ PostgreSQL documentation
<para>
Two additional command line options are available for debugging
- problems that cause a backend to die abnormally. These options
- control the behavior of the <application>postmaster</application>
- in this situation, and <emphasis>neither option is intended for
- use in ordinary operation</emphasis>.
+ problems that cause a server process to die abnormally. The
+ ordinary strategy in this situation is to notify all other server
+ processes that they must terminate and then reinitialize the
+ shared memory and semaphores. This is because an errant server
+ process could have corrupted some shared state before terminating.
+ These options select alternative behaviors of the
+ <command>postmaster</command> in this situation.
+ <emphasis>Neither option is intended for use in ordinary
+ operation.</emphasis>
</para>
<para>
- The ordinary strategy for this situation is to notify all other
- backends that they must terminate and then reinitialize the shared
- memory and semaphores. This is because an errant backend could
- have corrupted some shared state before terminating.
</para>
<para>
@@ -312,10 +313,10 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term>-n</term>
+ <term><option>-n</option></term>
<listitem>
<para>
- <application>postmaster</application>
+ <command>postmaster</command>
will not reinitialize shared data structures. A knowledgeable system
programmer can then use a debugger
to examine shared memory and semaphore state.
@@ -324,14 +325,14 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term>-s</term>
+ <term><option>-s</option></term>
<listitem>
<para>
- <application>postmaster</application>
- will stop all other backend processes by sending the signal
+ <command>postmaster</command>
+ will stop all other server processes by sending the signal
<literal>SIGSTOP</literal>,
but will not cause them to terminate. This permits system programmers
- to collect core dumps from all backend processes by hand.
+ to collect core dumps from all server processes by hand.
</para>
</listitem>
</varlistentry>
@@ -367,7 +368,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><envar>PGDATASTYLE</envar></term>
+ <term><envar>PGDATESTYLE</envar></term>
<listitem>
<para>
@@ -418,22 +419,17 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term><computeroutput>
-semget: No space left on device
- </computeroutput></term>
+ <term><computeroutput>semget: No space left on device</computeroutput></term>
<listitem>
<para>
- If you see this message, you should run the
- <application>ipcclean</application>
- command. After doing so, try starting
- <application>postmaster</application>
- again. If this still doesn't work, you probably need to configure
- your kernel for shared memory and semaphores as described in the
- installation notes. If you run multiple instances of
- <application>postmaster</application>
+ If you see this message, you probably need to configure
+ your kernel for shared memory and semaphores as described in the &cite-admin;.
+ If you run multiple instances of
+ <command>postmaster</command>
on a single host, or have a kernel with particularly small shared memory
and/or semaphore limits, you may have to reconfigure your kernel to increase
its shared memory or semaphore parameters.
+ </para>
<tip>
<para>
@@ -444,18 +440,15 @@ semget: No space left on device
consumption.
</para>
</tip>
- </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><computeroutput>
-StreamServerPort: cannot bind to port
- </computeroutput></term>
+ <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term>
<listitem>
<para>
If you see this message, you should make certain that there is no
- other <application>postmaster</application>
+ other <command>postmaster</command>
process already running on the same port number. The easiest way to
determine this is by using the command
<screen>
@@ -471,18 +464,18 @@ StreamServerPort: cannot bind to port
<para>
If you
are sure that no other
- <application>postmaster</application>
+ <command>postmaster</command>
processes are running and you still get this error, try specifying a
different port using the
<literal>-p</literal>
option. You may also get this error if you terminate the
- <application>postmaster</application>
+ <command>postmaster</command>
and immediately restart it using the same port; in this case, you must
simply wait a few seconds until the operating system closes the port
before trying again. Finally, you may get this error if you specify
a port number that your operating system considers to be reserved.
For example, many versions of Unix consider port numbers under 1024 to
- be <firstterm>trusted</firstterm>
+ be <quote>trusted</quote>
and only permit the Unix superuser to access them.
</para>
</listitem>
@@ -497,14 +490,14 @@ StreamServerPort: cannot bind to port
<para>
If at all possible, <emphasis>do not</emphasis> use
<literal>SIGKILL</literal> to kill the
- <application>postmaster</application>. This will prevent
- <application>postmaster</application> from freeing the system
+ <command>postmaster</command>. This will prevent
+ <command>postmaster</command> from freeing the system
resources (e.g., shared memory and semaphores) that it holds before
terminating.
</para>
<para>
- To terminate the <application>postmaster</application> normally,
+ To terminate the <command>postmaster</command> normally,
the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
or <literal>SIGQUIT</literal> can be used. The first will wait for
all clients to terminate before quitting, the second will
@@ -515,7 +508,7 @@ StreamServerPort: cannot bind to port
<para>
The utility command <xref linkend="app-pg-ctl"> can be used to
- start and shut down the <application>postmaster</application>
+ start and shut down the <command>postmaster</command>
safely and comfortably.
</para>
@@ -532,7 +525,7 @@ StreamServerPort: cannot bind to port
<refsect1 id="app-postmaster-examples">
<title>Examples</title>
<para>
- To start <application>postmaster</application> in the background
+ To start <command>postmaster</command> in the background
using default values, type:
<screen>
@@ -541,14 +534,14 @@ StreamServerPort: cannot bind to port
</para>
<para>
- To start <application>postmaster</application> with a specific
+ To start <command>postmaster</command> with a specific
port:
<screen>
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
</screen>
- This command will start up <application>postmaster</application>
+ This command will start up <command>postmaster</command>
communicating through the port 1234. In order to connect to this
- <application>postmaster</application> using <application>psql</>, you would need to
+ <command>postmaster</command> using <application>psql</>, you would need to
run it as
<screen>
<prompt>$</prompt> <userinput>psql -p 1234</userinput>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 181d967cbb9..f2cf072edc7 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.85 2003/02/13 05:37:43 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.86 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -20,9 +20,9 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>psql</command>
- <arg><replaceable class="parameter">options</replaceable></arg>
+ <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
<arg><replaceable class="parameter">dbname</replaceable>
- <arg><replaceable class="parameter">user</replaceable></arg></arg>
+ <arg><replaceable class="parameter">username</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -69,17 +69,17 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-c <replaceable class="parameter">query</replaceable></></term>
- <term><option>--command <replaceable class="parameter">query</replaceable></></term>
+ <term><option>-c <replaceable class="parameter">command</replaceable></></term>
+ <term><option>--command <replaceable class="parameter">command</replaceable></></term>
<listitem>
<para>
Specifies that <application>psql</application> is to execute one
- query string, <replaceable class="parameter">query</replaceable>,
+ command string, <replaceable class="parameter">command</replaceable>,
and then exit. This is useful in shell scripts.
</para>
<para>
- <replaceable class="parameter">query</replaceable> must be either
- a query string that is completely parsable by the backend (i.e.,
+ <replaceable class="parameter">command</replaceable> must be either
+ a command string that is completely parsable by the server (i.e.,
it contains no <application>psql</application> specific features),
or it is a single backslash command. Thus you cannot mix
<acronym>SQL</acronym> and <application>psql</application>
@@ -108,7 +108,7 @@ PostgreSQL documentation
<term><option>--echo-queries</></term>
<listitem>
<para>
- Show all queries that are sent to the backend. This is equivalent
+ Show all commands that are sent to the server. This is equivalent
to setting the variable <varname>ECHO</varname> to
<literal>queries</literal>.
</para>
@@ -120,7 +120,7 @@ PostgreSQL documentation
<term><option>--echo-hidden</></term>
<listitem>
<para>
- Echoes the actual queries generated by \d and other backslash
+ Echo the actual queries generated by <command>\d</command> and other backslash
commands. You can use this if you wish to include similar
functionality into your own programs. This is equivalent to
setting the variable <varname>ECHO_HIDDEN</varname> from within
@@ -135,7 +135,7 @@ PostgreSQL documentation
<listitem>
<para>
Use the file <replaceable class="parameter">filename</replaceable>
- as the source of queries instead of reading queries interactively.
+ as the source of commands instead of reading commands interactively.
After the file is processed, <application>psql</application>
terminates. This is in many ways equivalent to the internal
command <command>\i</command>.
@@ -179,7 +179,7 @@ PostgreSQL documentation
<listitem>
<para>
Specifies the host name of the machine on which the
- <application>postmaster</application> is running. If host begins
+ server is running. If the value begins
with a slash, it is used as the directory for the Unix-domain
socket.
</para>
@@ -191,7 +191,7 @@ PostgreSQL documentation
<term><option>--html</></term>
<listitem>
<para>
- Turns on <acronym>HTML</acronym> tabular output. This is
+ Turn on <acronym>HTML</acronym> tabular output. This is
equivalent to <literal>\pset format html</literal> or the
<command>\H</command> command.
</para>
@@ -203,7 +203,7 @@ PostgreSQL documentation
<term><option>--list</></term>
<listitem>
<para>
- Lists all available databases, then exits. Other non-connection
+ List all available databases, then exits. Other non-connection
options are ignored. This is similar to the internal command
<command>\list</command>.
</para>
@@ -227,9 +227,8 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the TCP/IP port or, by omission, the local Unix domain
- socket file extension on which the
- <application>postmaster</application> is listening for
+ Specifies the TCP port or the local Unix domain
+ socket file extension on which the server is listening for
connections. Defaults to the value of the <envar>PGPORT</envar>
environment variable or, if not set, to the port specified at
compile time, usually 5432.
@@ -284,7 +283,7 @@ PostgreSQL documentation
<listitem>
<para>
Run in single-step mode. That means the user is prompted before
- each query is sent to the backend, with the option to cancel
+ each command is sent to the server, with the option to cancel
execution as well. Use this to debug scripts.
</para>
</listitem>
@@ -295,7 +294,7 @@ PostgreSQL documentation
<term><option>--single-line</></term>
<listitem>
<para>
- Runs in single-line mode where a newline terminates a query, as a
+ Runs in single-line mode where a newline terminates an SQL command, as a
semicolon does.
</para>
@@ -345,7 +344,7 @@ PostgreSQL documentation
<para>
This option is deprecated, as it is conceptually flawed.
(Prompting for a non-default user name and prompting for a
- password because the backend requires it are really two different
+ password because the server requires it are really two different
things.) You are encouraged to look at the <option>-U</option> and
<option>-W</option> options instead.
</para>
@@ -357,7 +356,7 @@ PostgreSQL documentation
<term><option>--username <replaceable class="parameter">username</replaceable></></term>
<listitem>
<para>
- Connects to the database as the user <replaceable
+ Connect to the database as the user <replaceable
class="parameter">username</replaceable> instead of the default.
(You must have permission to do so, of course.)
</para>
@@ -370,7 +369,7 @@ PostgreSQL documentation
<term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
<listitem>
<para>
- Performs a variable assignment, like the <command>\set</command>
+ Perform a variable assignment, like the <command>\set</command>
internal command. Note that you must separate name and value, if
any, by an equal sign on the command line. To unset a variable,
leave off the equal sign. To just set a variable without a value,
@@ -386,7 +385,7 @@ PostgreSQL documentation
<term><option>--version</></term>
<listitem>
<para>
- Shows the <application>psql</application> version.
+ Show the <application>psql</application> version.
</para>
</listitem>
</varlistentry>
@@ -404,11 +403,11 @@ PostgreSQL documentation
<para>
In the current version, <application>psql</application>
- automatically issues a password prompt whenever the backend
+ automatically issues a password prompt whenever the server
requests password authentication. Because this is currently based
on a hack, the automatic recognition might mysteriously fail,
hence this option to force a prompt. If no password prompt is
- issued and the backend requires password authentication the
+ issued and the server requires password authentication the
connection attempt will fail.
</para>
</listitem>
@@ -419,7 +418,7 @@ PostgreSQL documentation
<term><option>--expanded</></term>
<listitem>
<para>
- Turns on extended row format mode. This is equivalent to the
+ Turn on the extended table formatting mode. This is equivalent to the
command <command>\x</command>.
</para>
</listitem>
@@ -440,7 +439,7 @@ PostgreSQL documentation
<term><option>--help</></term>
<listitem>
<para>
- Shows help about <application>psql</application> command line
+ Show help about <application>psql</application> command line
arguments.
</para>
</listitem>
@@ -455,8 +454,8 @@ PostgreSQL documentation
<para>
<application>psql</application> returns 0 to the shell if it
finished normally, 1 if a fatal error of its own (out of memory,
- file not found) occurs, 2 if the connection to the backend went bad
- and the session is not interactive, and 3 if an error occurred in a
+ file not found) occurs, 2 if the connection to the server went bad
+ and the session was not interactive, and 3 if an error occurred in a
script and the variable <varname>ON_ERROR_STOP</varname> was set.
</para>
</refsect1>
@@ -495,13 +494,13 @@ PostgreSQL documentation
<para>
If the connection could not be made for any reason (e.g., insufficient
- privileges, postmaster is not running on the server, etc.),
+ privileges, server is not running on the targeted host, etc.),
<application>psql</application> will return an error and terminate.
</para>
</refsect2>
<refsect2 id="R2-APP-PSQL-4">
- <title>Entering Queries</title>
+ <title>Entering SQL Commands</title>
<para>
In normal operation, <application>psql</application> provides a
@@ -523,16 +522,16 @@ testdb=>
</para>
<para>
- At the prompt, the user may type in <acronym>SQL</acronym> queries.
- Ordinarily, input lines are sent to the backend when a
- query-terminating semicolon is reached. An end of line does not
- terminate a query! Thus queries can be spread over several lines for
- clarity. If the query was sent and without error, the query results
+ At the prompt, the user may type in <acronym>SQL</acronym> commands.
+ Ordinarily, input lines are sent to the server when a
+ command-terminating semicolon is reached. An end of line does not
+ terminate a command. Thus commands can be spread over several lines for
+ clarity. If the command was sent and without error, the results of the command
are displayed on the screen.
</para>
<para>
- Whenever a query is executed, <application>psql</application> also polls
+ Whenever a command is executed, <application>psql</application> also polls
for asynchronous notification events generated by
<xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
<xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
@@ -586,18 +585,23 @@ testdb=>
</para>
<para>
- Some commands take an <acronym>SQL</acronym> identifier
- (such as a table name) as argument. These arguments follow the
- syntax rules of <acronym>SQL</acronym> regarding double quotes: an
- identifier without double quotes is coerced to lower-case, while
- whitespace within double quotes is included in the argument.
+ Some commands take an <acronym>SQL</acronym> identifier (such as a
+ table name) as argument. These arguments follow the syntax rules
+ of <acronym>SQL</acronym>: Unquoted letters are forced to
+ lowercase, while double quotes (<literal>"</>) protect letters
+ from case conversion and allow incorporation of whitespace into
+ the identifier. Within double quotes, paired double quotes reduce
+ to a single double quote in the resulting name. For example,
+ <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>,
+ and <literal>"A weird"" name"</> becomes <literal>A weird"
+ name</>.
</para>
<para>
Parsing for arguments stops when another unquoted backslash occurs.
This is taken as the beginning of a new meta-command. The special
sequence <literal>\\</literal> (two backslashes) marks the end of
- arguments and continues parsing <acronym>SQL</acronym> queries, if
+ arguments and continues parsing <acronym>SQL</acronym> commands, if
any. That way <acronym>SQL</acronym> and
<application>psql</application> commands can be freely mixed on a
line. But in any case, the arguments of a meta-command cannot
@@ -612,8 +616,8 @@ testdb=>
<term><literal>\a</literal></term>
<listitem>
<para>
- If the current table output format is unaligned, switch to aligned.
- If it is not unaligned, set it to unaligned. This command is
+ If the current table output format is unaligned, it is switched to aligned.
+ If it is not unaligned, it is set to unaligned. This command is
kept for backwards compatibility. See <command>\pset</command> for a
general solution.
</para>
@@ -624,8 +628,8 @@ testdb=>
<term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
<listitem>
<para>
- Change the current working directory to
- <replaceable>directory</replaceable>. Without argument, change
+ Changes the current working directory to
+ <replaceable>directory</replaceable>. Without argument, changes
to the current user's home directory.
</para>
@@ -641,7 +645,7 @@ testdb=>
<term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
<listitem>
<para>
- Set the title of any tables being printed as the result of a
+ Sets the title of any tables being printed as the result of a
query or unset any such title. This command is equivalent to
<literal>\pset title <replaceable
class="parameter">title</replaceable></literal>. (The name of
@@ -701,10 +705,10 @@ testdb=>
<para>
Performs a frontend (client) copy. This is an operation that
runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
- endterm="SQL-COPY-title"> command, but instead of the backend's
+ endterm="SQL-COPY-title"> command, but instead of the server
reading or writing the specified file,
<application>psql</application> reads or writes the file and
- routes the data between the backend and the local file system.
+ routes the data between the server and the local file system.
This means that file accessibility and privileges are those
of the local user, not the server, and no SQL superuser
privileges are required.
@@ -712,8 +716,8 @@ testdb=>
<para>
The syntax of the command is similar to that of the
- <acronym>SQL</acronym> <command>COPY</command> command (see its
- description for the details). Note that, because of this,
+ <acronym>SQL</acronym> <command>COPY</command> command. (See its
+ description for the details.) Note that, because of this,
special parsing rules apply to the <command>\copy</command>
command. In particular, the variable substitution rules and
backslash escapes do not apply.
@@ -723,7 +727,7 @@ testdb=>
<para>
This operation is not as efficient as the <acronym>SQL</acronym>
<command>COPY</command> command because all data must pass
- through the client/server IP or socket connection. For large
+ through the client/server connection. For large
amounts of data the other technique may be preferable.
</para>
</tip>
@@ -732,9 +736,9 @@ testdb=>
<para>
Note the difference in interpretation of
<literal>stdin</literal> and <literal>stdout</literal> between
- frontend and backend copies: in a frontend copy these always
+ client and server copies: in a client copy these always
refer to <application>psql</application>'s input and output
- stream. On a backend copy <literal>stdin</literal> comes from
+ stream. On a server copy <literal>stdin</literal> comes from
wherever the <command>COPY</command> itself came from (for
example, a script run with the <option>-f</option> option), and
<literal>stdout</literal> refers to the query output stream (see
@@ -792,7 +796,7 @@ testdb=>
<para>
Lists all available aggregate functions, together with the data
type they operate on. If <replaceable
- class="parameter">pattern</replaceable> (a regular expression)
+ class="parameter">pattern</replaceable>
is specified, only matching aggregates are shown.
</para>
</listitem>
@@ -845,16 +849,8 @@ testdb=>
<para>
Descriptions for objects can be created with the
- <command>COMMENT ON</command> <acronym>SQL</acronym> command.
+ <command>COMMENT</command> <acronym>SQL</acronym> command.
</para>
-
- <note>
- <para>
- <productname>PostgreSQL</productname> stores the object
- descriptions in the <structname>pg_description</> system table.
- </para>
- </note>
-
</listitem>
</varlistentry>
@@ -863,7 +859,7 @@ testdb=>
<term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
<listitem>
<para>
- Lists all available domains (derived types). If <replaceable
+ Lists all available domains. If <replaceable
class="parameter">pattern</replaceable>
is specified, only matching domains are shown.
</para>
@@ -907,12 +903,12 @@ testdb=>
order, to obtain a listing of all the matching objects. The letter
S restricts the listing to system objects; without S, only non-system
objects are shown.
- If <quote>+</quote> is appended to the command name, each object is
+ If <literal>+</literal> is appended to the command name, each object is
listed with its associated description, if any.
</para>
<para>
- If a <replaceable class="parameter">pattern</replaceable> is
+ If <replaceable class="parameter">pattern</replaceable> is
specified, only objects whose name matches the pattern are listed.
</para>
</listitem>
@@ -948,7 +944,7 @@ testdb=>
<listitem>
<para>
Lists available operators with their operand and return types.
- If a <replaceable class="parameter">pattern</replaceable> is
+ If <replaceable class="parameter">pattern</replaceable> is
specified, only operators whose name matches the pattern are listed.
</para>
</listitem>
@@ -960,15 +956,15 @@ testdb=>
<listitem>
<para>
Produces a list of all available tables with their
- associated access permissions.
- If a <replaceable class="parameter">pattern</replaceable> is
+ associated access privileges.
+ If <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed.
</para>
<para>
The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE">
- are used to set access permissions. See <xref linkend="SQL-GRANT">
+ are used to set access privileges. See <xref linkend="SQL-GRANT">
for more information.
</para>
</listitem>
@@ -991,7 +987,7 @@ testdb=>
<term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
- Lists all database users, or only those that match <replaceable
+ Lists all database users or only those that match <replaceable
class="parameter">pattern</replaceable>.
</para>
</listitem>
@@ -1063,13 +1059,13 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
- Sets the client encoding. Without an argument, this command
+ Sets the client character set encoding. Without an argument, this command
shows the current encoding.
</para>
<note>
<para>
This command will not notice changes made directly by <command>SET
- CLIENT_ENCODING</>. If you use <literal>\encoding</literal>,
+ client_encoding</>. If you use <command>\encoding</command>,
be sure to use it to set as well as examine the encoding.
</para>
</note>
@@ -1083,7 +1079,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Sets the field separator for unaligned query output. The default
- is pipe (<literal>|</literal>). See also
+ is the vertical bar (<literal>|</literal>). See also
<command>\pset</command> for a generic way of setting output
options.
</para>
@@ -1096,7 +1092,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
- Sends the current query input buffer to the backend and
+ Sends the current query input buffer to the server and
optionally saves the output in <replaceable
class="parameter">filename</replaceable> or pipes the output
into a separate Unix shell to execute <replaceable
@@ -1112,12 +1108,12 @@ Tue Oct 26 21:40:57 CEST 1999
<term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
<listitem>
<para>
- Give syntax help on the specified <acronym>SQL</acronym>
+ Gives syntax help on the specified <acronym>SQL</acronym>
command. If <replaceable class="parameter">command</replaceable>
is not specified, then <application>psql</application> will list
all the commands for which syntax help is available. If
<replaceable class="parameter">command</replaceable> is an
- asterisk (<quote>*</quote>), then syntax help on all
+ asterisk (<literal>*</literal>), then syntax help on all
<acronym>SQL</acronym> commands is shown.
</para>
@@ -1169,8 +1165,8 @@ Tue Oct 26 21:40:57 CEST 1999
<term><literal>\l</literal> (or <literal>\list</literal>)</term>
<listitem>
<para>
- List the names, owners, and encodings of all the databases in
- the server. Append a <quote>+</quote> to the command name to
+ List the names, owners, and character set encodings of all the databases in
+ the server. Append a <literal>+</literal> to the command name to
see any descriptions for the databases as well.
</para>
</listitem>
@@ -1214,13 +1210,13 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Stores the file into a <productname>PostgreSQL</productname>
- <quote>large object</quote>. Optionally, it associates the given
+ large object. Optionally, it associates the given
comment with the object. Example:
<programlisting>
foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
lo_import 152801
</programlisting>
- The response indicates that the large object received object id
+ The response indicates that the large object received object ID
152801 which one ought to remember if one wants to access the
object ever again. For that reason it is recommended to always
associate a human-readable comment with every object. Those can
@@ -1249,7 +1245,7 @@ lo_import 152801
<listitem>
<para>
Shows a list of all <productname>PostgreSQL</productname>
- <quote>large objects</quote> currently stored in the database,
+ large objects currently stored in the database,
along with any comments provided for them.
</para>
</listitem>
@@ -1291,8 +1287,7 @@ lo_import 152801
class="parameter">filename</replaceable> or pipes future results
into a separate Unix shell to execute <replaceable
class="parameter">command</replaceable>. If no arguments are
- specified, the query output will be reset to
- <filename>stdout</filename>.
+ specified, the query output will be reset to the standard output.
</para>
<para>
@@ -1349,7 +1344,7 @@ lo_import 152801
</para>
<para>
- <quote>Unaligned</quote> writes all fields of a tuple on a
+ <quote>Unaligned</quote> writes all columns of a row on a
line, separated by the currently active field separator. This
is intended to create output that might be intended to be read
in by other programs (tab-separated, comma-separated).
@@ -1385,14 +1380,14 @@ lo_import 152801
<listitem>
<para>
Toggles between regular and expanded format. When expanded
- format is enabled, all output has two columns with the field
+ format is enabled, all output has two columns with the column
name on the left and the data on the right. This mode is
useful if the data wouldn't fit on the screen in the normal
<quote>horizontal</quote> mode.
</para>
<para>
- Expanded mode is supported by all four output modes.
+ Expanded mode is supported by all four output formats.
</para>
</listitem>
</varlistentry>
@@ -1402,7 +1397,7 @@ lo_import 152801
<listitem>
<para>
The second argument is a string that should be printed
- whenever a field is null. The default is not to print
+ whenever a column is null. The default is not to print
anything, which can easily be mistaken for, say, an empty
string. Thus, one might choose to write <literal>\pset null
'(null)'</literal>.
@@ -1419,7 +1414,7 @@ lo_import 152801
comma-separated output, which other programs might prefer. To
set a tab as field separator, type <literal>\pset fieldsep
'\t'</literal>. The default field separator is
- <literal>'|'</literal> (a <quote>pipe</quote> symbol).
+ <literal>'|'</literal> (a vertical bar).
</para>
</listitem>
</varlistentry>
@@ -1464,13 +1459,6 @@ lo_import 152801
can be used to give your output descriptive tags. If no
argument is given, the title is unset.
</para>
-
- <note>
- <para>
- This formerly only affected <acronym>HTML</acronym> mode. You
- can now set titles in any output format.
- </para>
- </note>
</listitem>
</varlistentry>
@@ -1512,6 +1500,9 @@ lo_import 152801
</listitem>
</varlistentry>
</variablelist>
+ </para>
+
+ <para>
Illustrations on how these different formats look can be seen in
the <xref linkend="APP-PSQL-examples"
endterm="APP-PSQL-examples-title"> section.
@@ -1541,7 +1532,7 @@ lo_import 152801
<term><literal>\q</literal></term>
<listitem>
<para>
- Quit the <application>psql</application> program.
+ Quits the <application>psql</application> program.
</para>
</listitem>
</varlistentry>
@@ -1608,8 +1599,9 @@ lo_import 152801
<para>
Valid variable names can contain characters, digits, and
- underscores. See the section about
- <application>psql</application> variables for details.
+ underscores. See the section <xref
+ linkend="APP-PSQL-variables"
+ endterm="APP-PSQL-variables-title"> below for details.
</para>
<para>
@@ -1644,7 +1636,7 @@ lo_import 152801
<term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
<listitem>
<para>
- Allows you to specify options to be placed within the
+ Allows you to specify attributes to be placed within the
<sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
output mode. This command is equivalent to <literal>\pset
tableattr <replaceable
@@ -1680,7 +1672,7 @@ lo_import 152801
<term><literal>\x</literal></term>
<listitem>
<para>
- Toggles extended row format mode. As such it is equivalent to
+ Toggles extended table formatting mode. As such it is equivalent to
<literal>\pset expanded</literal>.
</para>
</listitem>
@@ -1692,7 +1684,7 @@ lo_import 152801
<listitem>
<para>
Produces a list of all available tables with their
- associated access permissions.
+ associated access privileges.
If a <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed.
</para>
@@ -1700,13 +1692,13 @@ lo_import 152801
<para>
The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE">
- are used to set access permissions. See <xref linkend="SQL-GRANT">
+ are used to set access privileges. See <xref linkend="SQL-GRANT">
for more information.
</para>
<para>
This is an alias for <command>\dp</command> (<quote>display
- permissions</quote>).
+ privileges</quote>).
</para>
</listitem>
</varlistentry>
@@ -1729,8 +1721,7 @@ lo_import 152801
<term><literal>\?</literal></term>
<listitem>
<para>
- Get help information about the backslash (<quote>\</quote>)
- commands.
+ Shows help information about the backslash commands.
</para>
</listitem>
</varlistentry>
@@ -1741,31 +1732,20 @@ lo_import 152801
<para>
The various <literal>\d</> commands accept a <replaceable
class="parameter">pattern</replaceable> parameter to specify the
- object name(s) to be displayed. Patterns are interpreted similarly
- to SQL identifiers, in that unquoted letters are forced to lowercase,
- while double quotes (<literal>"</>) protect letters from case conversion
- and allow incorporation of whitespace into the identifier. Within
- double quotes, paired double quotes reduce to a single double quote in
- the resulting name. For example, <literal>FOO"BAR"BAZ</> is interpreted
- as <literal>fooBARbaz</>, and <literal>"A weird"" name"</> becomes
- <literal>A weird" name</>.
- </para>
-
- <para>
- More interestingly, <literal>\d</> patterns allow the use of
- <literal>*</> to mean <quote>any sequence of characters</>, and
- <literal>?</> to mean <quote>any single character</>. (This notation
- is comparable to Unix shell filename patterns.) Advanced users can
- also use regular-expression notations such as character classes, for
- example <literal>[0-9]</> to match <quote>any digit</>. To make any of
- these pattern-matching characters be interpreted literally, surround it
+ object name(s) to be displayed. <literal>*</> means <quote>any
+ sequence of characters</> and <literal>?</> means <quote>any single
+ character</>. (This notation is comparable to Unix shell file name
+ patterns.) Advanced users can also use regular-expression
+ notations such as character classes, for example <literal>[0-9]</>
+ to match <quote>any digit</>. To make any of these
+ pattern-matching characters be interpreted literally, surround it
with double quotes.
</para>
<para>
A pattern that contains an (unquoted) dot is interpreted as a schema
name pattern followed by an object name pattern. For example,
- <literal> \dt foo*.bar*</> displays all tables in schemas whose name
+ <literal>\dt foo*.bar*</> displays all tables in schemas whose name
starts with <literal>foo</> and whose table name
starts with <literal>bar</>. If no dot appears, then the pattern
matches only objects that are visible in the current schema search path.
@@ -1787,17 +1767,16 @@ lo_import 152801
<para>
<application>psql</application> provides variable substitution
- features similar to common Unix command shells. This feature is new
- and not very sophisticated, yet, but there are plans to expand it in
- the future. Variables are simply name/value pairs, where the value
+ features similar to common Unix command shells.
+ Variables are simply name/value pairs, where the value
can be any string of any length. To set variables, use the
<application>psql</application> meta-command
<command>\set</command>:
<programlisting>
testdb=> <userinput>\set foo bar</userinput>
</programlisting>
- sets the variable <quote>foo</quote> to the value
- <quote>bar</quote>. To retrieve the content of the variable, precede
+ sets the variable <literal>foo</literal> to the value
+ <literal>bar</literal>. To retrieve the content of the variable, precede
the name with a colon and use it as the argument of any slash
command:
<programlisting>
@@ -1840,6 +1819,8 @@ bar
consist of all upper-case letters (and possibly numbers and
underscores). To ensure maximum compatibility in the future, avoid
such variables. A list of all specially treated variables follows.
+ </para>
+
<variablelist>
<varlistentry>
<term><varname>DBNAME</varname></term>
@@ -1856,13 +1837,13 @@ bar
<term><varname>ECHO</varname></term>
<listitem>
<para>
- If set to <quote><literal>all</literal></quote>, all lines
+ If set to <literal>all</literal>, all lines
entered or from a script are written to the standard output
before they are parsed or executed. To specify this on program
start-up, use the switch <option>-a</option>. If set to
- <quote><literal>queries</literal></quote>,
+ <literal>queries</literal>,
<application>psql</application> merely prints all queries as
- they are sent to the backend. The option for this is
+ they are sent to the server. The option for this is
<option>-e</option>.
</para>
</listitem>
@@ -1877,7 +1858,7 @@ bar
<productname>PostgreSQL</productname> internals and provide
similar functionality in your own programs. If you set the
variable to the value <literal>noexec</literal>, the queries are
- just shown but are not actually sent to the backend and
+ just shown but are not actually sent to the server and
executed.
</para>
</listitem>
@@ -1887,9 +1868,7 @@ bar
<term><varname>ENCODING</varname></term>
<listitem>
<para>
- The current client multibyte encoding. If you are not set up to
- use multibyte characters, this variable will always contain
- <quote>SQL_ASCII</quote>.
+ The current client character set encoding.
</para>
</listitem>
</varlistentry>
@@ -1909,7 +1888,7 @@ bar
<note>
<para>
This feature was shamelessly plagiarized from
- <application>bash</application>.
+ <application>Bash</application>.
</para>
</note>
</listitem>
@@ -1925,7 +1904,7 @@ bar
<note>
<para>
This feature was shamelessly plagiarized from
- <application>bash</application>.
+ <application>Bash</application>.
</para>
</note>
</listitem>
@@ -1957,7 +1936,7 @@ bar
<note>
<para>
This feature was shamelessly plagiarized from
- <application>bash</application>.
+ <application>Bash</application>.
</para>
</note>
</listitem>
@@ -1982,7 +1961,7 @@ bar
<para>
If you use the <productname>PostgreSQL</productname> large
object interface to specially store data that does not fit into
- one tuple, all the operations must be contained in a transaction
+ one row, all the operations must be contained in a transaction
block. (See the documentation of the large object interface for
more information.) Since <application>psql</application> has no
way to tell if you already have a transaction in progress when
@@ -1992,16 +1971,15 @@ bar
action. This action could either be to roll back any transaction
that might already be in progress, or to commit any such
transaction, or to do nothing at all. In the last case you must
- provide your own <command>BEGIN
- TRANSACTION</command>/<command>COMMIT</command> block or the
+ provide your own <command>BEGIN</command>/<command>COMMIT</command> block or the
results will be unpredictable (usually resulting in the desired
action's not being performed in any case).
</para>
<para>
To choose what you want to do you set this variable to one of
- <quote>rollback</quote>, <quote>commit</quote>, or
- <quote>nothing</quote>. The default is to roll back the
+ <literal>rollback</literal>, <literal>commit</literal>, or
+ <literal>nothing</literal>. The default is to roll back the
transaction. If you just want to load one or a few objects this
is fine. However, if you intend to transfer many large objects,
it might be advisable to provide one explicit transaction block
@@ -2015,7 +1993,7 @@ bar
<listitem>
<para>
By default, if non-interactive scripts encounter an error, such
- as a malformed <acronym>SQL</acronym> query or internal
+ as a malformed <acronym>SQL</acronym> command or internal
meta-command, processing continues. This has been the
traditional behavior of <application>psql</application> but it
is sometimes not desirable. If this variable is set, script
@@ -2048,9 +2026,9 @@ bar
<listitem>
<para>
These specify what the prompt <application>psql</application>
- issues is supposed to look like. See <quote><xref
+ issues is supposed to look like. See <xref
linkend="APP-PSQL-prompting"
- endterm="APP-PSQL-prompting-title"></quote> below.
+ endterm="APP-PSQL-prompting-title"> below.
</para>
</listitem>
</varlistentry>
@@ -2099,8 +2077,6 @@ bar
</variablelist>
- </para>
-
</refsect3>
<refsect3>
@@ -2127,7 +2103,7 @@ testdb=> <userinput>SELECT * FROM :foo;</userinput>
A popular application of this facility is to refer to the last
inserted <acronym>OID</acronym> in subsequent statements to build a
foreign key scenario. Another possible use of this mechanism is to
- copy the contents of a file into a field. First load the file into a
+ copy the contents of a file into a table column. First load the file into a
variable and then proceed as above.
<programlisting>
testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
@@ -2135,8 +2111,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
</programlisting>
One possible problem with this approach is that <filename>my_file.txt</filename>
might contain single quotes. These need to be escaped so that
- they don't cause a syntax error when the third line is processed. This
- could be done with the program <application>sed</application>:
+ they don't cause a syntax error when the second line is processed. This
+ could be done with the program <command>sed</command>:
<programlisting>
testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
</programlisting>
@@ -2144,9 +2120,9 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
this way: After <application>psql</application> has parsed this
line, it passes <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal>
to the shell. The shell will do its own thing inside the double
- quotes and execute <filename>sed</filename> with the arguments
+ quotes and execute <command>sed</command> with the arguments
<literal>-e</literal> and <literal>s/'/\\'/g</literal>. When
- <application>sed</application> parses this it will replace the two
+ <command>sed</command> parses this it will replace the two
backslashes with a single one and then do the substitution. Perhaps
at one point you thought it was great that all Unix commands use the
same escape character. And this is ignoring the fact that you might
@@ -2157,12 +2133,12 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
</para>
<para>
- Since colons may legally appear in queries, the following rule
+ Since colons may legally appear in SQL commands, the following rule
applies: If the variable is not set, the character sequence
<quote>colon+name</quote> is not changed. In any case you can escape
a colon with a backslash to protect it from interpretation. (The
colon syntax for variables is standard <acronym>SQL</acronym> for
- embedded query languages, such as <application>ecpg</application>.
+ embedded query languages, such as <application>ECPG</application>.
The colon syntax for array slices and type casts are
<productname>PostgreSQL</productname> extensions, hence the
conflict.)
@@ -2179,17 +2155,17 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<varname>PROMPT2</varname>, and <varname>PROMPT3</varname> contain strings
and special escape sequences that describe the appearance of the
prompt. Prompt 1 is the normal prompt that is issued when
- <application>psql</application> requests a new query. Prompt 2 is
- issued when more input is expected during query input because the
- query was not terminated with a semicolon or a quote was not closed.
+ <application>psql</application> requests a new command. Prompt 2 is
+ issued when more input is expected during command input because the
+ command was not terminated with a semicolon or a quote was not closed.
Prompt 3 is issued when you run an <acronym>SQL</acronym>
<command>COPY</command> command and you are expected to type in the
- tuples on the terminal.
+ row values on the terminal.
</para>
<para>
The value of the respective prompt variable is printed literally,
- except where a percent sign (<quote>%</quote>) is encountered.
+ except where a percent sign (<literal>%</literal>) is encountered.
Depending on the next character, certain other text is substituted
instead. Defined substitutions are:
@@ -2212,7 +2188,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<term><literal>%m</literal></term>
<listitem>
<para>
- The host name of the database server, truncated after the
+ The host name of the database server, truncated at the
first dot, or <literal>[local]</literal> if the connection is
over a Unix domain socket.
</para>
@@ -2237,28 +2213,28 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<varlistentry>
<term><literal>%~</literal></term>
- <listitem><para>Like <literal>%/</literal>, but the output is <quote>~</quote>
+ <listitem><para>Like <literal>%/</literal>, but the output is <literal>~</literal>
(tilde) if the database is your default database.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>%#</literal></term>
<listitem><para>If the current user is a database superuser, then a
- <quote>#</quote>, otherwise a <quote>></quote>.</para></listitem>
+ <literal>#</literal>, otherwise a <literal>></literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>%R</literal></term>
<listitem>
<para>
- In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if
- in single-line mode, and <quote>!</quote> if the session is
+ In prompt 1 normally <literal>=</literal>, but <literal>^</literal> if
+ in single-line mode, and <literal>!</literal> if the session is
disconnected from the database (which can happen if
<command>\connect</command> fails). In prompt 2 the sequence is
- replaced by <quote>-</quote>, <quote>*</quote>, a single quote,
+ replaced by <literal>-</literal>, <literal>*</literal>, a single quote,
or a double quote, depending on whether
<application>psql</application> expects more input because the
- query wasn't terminated yet, because you are inside a
+ command wasn't terminated yet, because you are inside a
<literal>/* ... */</literal> comment, or because you are inside
a quote. In prompt 3 the sequence doesn't resolve to anything.
</para>
@@ -2284,10 +2260,10 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
<listitem>
<para>
- The value of the <application>psql</application>, variable
+ The value of the <application>psql</application> variable
<replaceable class="parameter">name</replaceable>. See the
- section <quote><xref linkend="APP-PSQL-variables"
- endterm="APP-PSQL-variables-title"></quote> for details.
+ section <xref linkend="APP-PSQL-variables"
+ endterm="APP-PSQL-variables-title"> for details.
</para>
</listitem>
</varlistentry>
@@ -2330,9 +2306,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
in your home directory and is reloaded when
<application>psql</application> starts up. Tab-completion is also
supported, although the completion logic makes no claim to be an
- <acronym>SQL</acronym> parser. When available,
- <application>psql</application> is automatically built to use these
- features. If for some reason you do not like the tab completion, you
+ <acronym>SQL</acronym> parser. If for some reason you do not like the tab completion, you
can turn if off by putting this in a file named
<filename>.inputrc</filename> in your home directory:
<programlisting>
@@ -2341,7 +2315,7 @@ set disable-completion on
$endif
</programlisting>
(This is not a <application>psql</application> but a
- <application>readline</application> feature. Read its documentation
+ <application>Readline</application> feature. Read its documentation
for further details.)
</para>
</refsect3>
@@ -2471,12 +2445,12 @@ $endif
first argument of a single-letter backslash command to start
directly after the command, without intervening whitespace. For
compatibility this is still supported to some extent,
- but I am not going to explain the details here as this use is
+ but were are not going to explain the details here as this use is
discouraged. If you get strange messages, keep this in mind.
For example
<programlisting>
testdb=> <userinput>\foo</userinput>
-Field separator is "oo",
+Field separator is "oo".
</programlisting>
which is perhaps not what one would expect.
</para>
@@ -2494,10 +2468,11 @@ Field separator is "oo",
<listitem>
<para>
- Pressing Control-C during a <quote>copy in</quote> (data sent to
+ Pressing <keycombo action="simul"><keycap>Control</><keycap>C</></>
+ during a <quote>copy in</quote> (data sent to
the server) doesn't show the most ideal of behaviors. If you get a
- message such as <quote>COPY state must be terminated
- first</quote>, simply reset the connection by entering <literal>\c
+ message such as <errorname>COPY state must be terminated
+ first</errorname>, simply reset the connection by entering <literal>\c
- -</literal>.
</para>
</listitem>
@@ -2515,19 +2490,19 @@ Field separator is "oo",
<application>psql</application>. If you want to learn
<acronym>SQL</acronym> or get familiar with
<productname>PostgreSQL</productname>, you might wish to read the
- Tutorial that is included in the distribution.
+ &cite-tutorial;.
</para>
</note>
<para>
- The first example shows how to spread a query over several lines of
+ The first example shows how to spread a command over several lines of
input. Notice the changing prompt:
<programlisting>
testdb=> <userinput>CREATE TABLE my_table (</userinput>
testdb(> <userinput> first integer not null default 0,</userinput>
testdb(> <userinput> second text</userinput>
testdb-> <userinput>);</userinput>
-CREATE
+CREATE TABLE
</programlisting>
Now look at the table definition again:
<programlisting>
@@ -2539,8 +2514,7 @@ testdb=> <userinput>\d my_table</userinput>
second | text |
</programlisting>
- At this point you decide to change the prompt to something more
- interesting:
+ Now we change the prompt to something more interesting:
<programlisting>
testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput>
peter@localhost testdb=>
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 0eecf8f3c71..84583e9aea3 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.27 2002/10/11 23:03:48 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.28 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation
-->
@@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>vacuumdb</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group><arg>--full</arg><arg>-f</arg></group>
<group><arg>--verbose</arg><arg>-v</arg></group>
<group><arg>--analyze</arg><arg>-z</arg></group>
- <arg>--table | -t '<replaceable>table</replaceable>
- <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>'
+ <arg>--table | -t <replaceable>table</replaceable>
+ <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>
</arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
@@ -78,6 +78,16 @@ PostgreSQL documentation
<application>vacuumdb</application> accepts the following command-line arguments:
<variablelist>
+ <varlistentry>
+ <term><option>-a</option></term>
+ <term><option>--all</option></term>
+ <listitem>
+ <para>
+ Vacuum all databases.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term>
<term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></option></term>
@@ -93,17 +103,6 @@ PostgreSQL documentation
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>-a</option></term>
- <term><option>--all</option></term>
- <listitem>
- <para>
- Vacuum all databases.
- </para>
- </listitem>
- </varlistentry>
-
-
<varlistentry>
<term><option>-e</></term>
<term><option>--echo</></term>
@@ -146,8 +145,8 @@ PostgreSQL documentation
</para>
<tip>
<para>
- If you specify columns to vacuum, you probably have to escape the parentheses
- from the shell.
+ If you specify columns, you probably have to escape the parentheses
+ from the shell. (See examples below.)
</para>
</tip>
</listitem>
@@ -187,7 +186,7 @@ PostgreSQL documentation
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
@@ -198,7 +197,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
@@ -272,7 +271,7 @@ PostgreSQL documentation
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index 3486ca41823..84221dc2157 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,5 +1,5 @@
<!-- reference.sgml
-$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.42 2003/03/20 07:02:07 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.43 2003/03/24 14:32:50 petere Exp $
PostgreSQL Reference Manual
-->
@@ -135,27 +135,6 @@ PostgreSQL Reference Manual
</reference>
-<!--
-Disable this chapter until we have more functions documented.
-- thomas 1998-10-27
-
- <reference id="sql-functions">
- <title>SQL Functions</title>
-
- <partintro>
- <para>
- This part provides reference information for the
- <acronym>SQL</acronym> functions supported by
- <productname>PostgreSQL</productname>.
- </para>
-
- ¤tDate;
- ¤tTime;
- ¤tTimestamp;
- ¤tUser;
- </reference>
--->
-
<reference id="reference-client">
<title>PostgreSQL Client Applications</title>
@@ -182,9 +161,9 @@ Disable this chapter until we have more functions documented.
&pgDump;
&pgDumpall;
&pgRestore;
- &psqlRef;
&pgTclSh;
&pgTkSh;
+ &psqlRef;
&vacuumdb;
</reference>
@@ -205,8 +184,8 @@ Disable this chapter until we have more functions documented.
&initdb;
&initlocation;
&ipcclean;
- &pgCtl;
&pgControldata;
+ &pgCtl;
&pgResetxlog;
&postgres;
&postmaster;
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 0f53895fdcd..8a0c9915275 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.172 2003/03/20 04:51:44 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.173 2003/03/24 14:32:50 petere Exp $
-->
<Chapter Id="runtime">
@@ -22,7 +22,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.172 2003/03/20 04:51:44 mo
it is advisable to run <productname>PostgreSQL</productname> under a
separate user account. This user account should only own the data
that is managed by the server, and should not be shared with other
- daemons. (For example, using the user <quote>nobody</quote> is a bad
+ daemons. (For example, using the user <literal>nobody</literal> is a bad
idea.) It is not advisable to install executables owned by
this user because compromised systems could then modify their own
binaries.
@@ -83,11 +83,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.172 2003/03/20 04:51:44 mo
<tip>
<para>
- <indexterm>
- <primary><envar>PGDATA</envar></primary>
- </indexterm>
As an alternative to the <option>-D</option> option, you can set
the environment variable <envar>PGDATA</envar>.
+ <indexterm><primary><envar>PGDATA</envar></primary></indexterm>
</para>
</tip>
@@ -128,16 +126,14 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
password to the database superuser. After <command>initdb</command>,
modify the <filename>pg_hba.conf</filename> file to use <literal>md5</> or
<literal>password</> instead of <literal>trust</> authentication
- <emphasis>before</> you start the server for the first time. (Other,
+ <emphasis>before</> you start the server for the first time. (Other
approaches include using <literal>ident</literal> authentication or
file system permissions to restrict connections. See <xref
linkend="client-authentication"> for more information.)
</para>
<para>
- <indexterm><primary>locale</></>
- <indexterm><primary>LC_COLLATE</></>
- <command>initdb</command> also initializes the default locale for
+ <command>initdb</command> also initializes the default locale<indexterm><primary>locale</></> for
the database cluster. Normally, it will just take the locale
settings in the environment and apply them to the initialized
database. It is possible to specify a different locale for the
@@ -168,12 +164,10 @@ set to "C". For more information see the Administrator's Guide.
<title>Starting the Database Server</title>
<para>
- <indexterm>
- <primary>postmaster</primary>
- </indexterm>
Before anyone can access the database, you must start the database
- server. The database server is called
- <firstterm>postmaster</firstterm>. The postmaster must know where to
+ server. The database server program is called
+ <command>postmaster</command>.<indexterm><primary>postmaster</></>
+ The <command>postmaster</command> must know where to
find the data it is supposed to use. This is done with the
<option>-D</option> option. Thus, the simplest way to start the
server is:
@@ -188,7 +182,7 @@ $ <userinput>postmaster -D /usr/local/pgsql/data</userinput>
</para>
<para>
- To start the <application>postmaster</application> in the
+ To start the <command>postmaster</command> in the
background, use the usual shell syntax:
<screen>
$ <userinput>postmaster -D /usr/local/pgsql/data > logfile 2>&1 &</userinput>
@@ -201,29 +195,26 @@ $ <userinput>postmaster -D /usr/local/pgsql/data > logfile 2>&1 &<
</para>
<para>
- <indexterm>
- <primary>TCP/IP</primary>
- </indexterm>
- The postmaster also takes a number of other command line options. For
- more information, see the reference page and <xref
- linkend="runtime-config"> below. In particular, in order for the
- server to accept TCP/IP connections (rather than just Unix domain
- socket ones), you must specify the <option>-i</option> option.
+ The <command>postmaster</command> also takes a number of other
+ command line options. For more information, see the reference page
+ and <xref linkend="runtime-config"> below. In particular, in order
+ for the server to accept
+ TCP/IP<indexterm><primary>TCP/IP</primary></indexterm> connections
+ (rather than just Unix-domain socket ones), you must specify the
+ <option>-i</option> option.
</para>
<para>
- <indexterm>
- <primary>pg_ctl</primary>
- </indexterm>
This shell syntax can get tedious quickly. Therefore the shell
- script wrapper <application>pg_ctl</application> is provided to
- simplify some tasks. For example:
+ script wrapper
+ <command>pg_ctl</command><indexterm><primary>pg_ctl</primary></indexterm>
+ is provided to simplify some tasks. For example:
<programlisting>
pg_ctl start -l logfile
</programlisting>
will start the server in the background and put the output into the
named log file. The <option>-D</option> option has the same meaning
- here as in the postmaster. <application>pg_ctl</application> is also
+ here as in the <command>postmaster</command>. <command>pg_ctl</command> is also
capable of stopping the server.
</para>
@@ -232,7 +223,7 @@ pg_ctl start -l logfile
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
+ <filename>contrib/start-scripts</> directory. This may require root
privileges.
</para>
@@ -305,14 +296,14 @@ fi
<listitem>
<para>
On <productname>Solaris</productname>, create a file called
- <filename>/etc/init.d/postgresql</filename> which should contain
+ <filename>/etc/init.d/postgresql</filename> that contains
the following line:
<indexterm><primary>Solaris</></>
<programlisting>
su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgsql/data"
</programlisting>
Then, create a symbolic link to it in <filename>/etc/rc3.d</> as
- <literal>S99postgresql</>.
+ <filename>S99postgresql</>.
</para>
</listitem>
</itemizedlist>
@@ -320,44 +311,47 @@ su - postgres -c "/usr/local/pgsql/bin/pg_ctl start -l logfile -D /usr/local/pgs
</para>
<para>
- While the <application>postmaster</application> is running, its
- <acronym>PID</acronym> is in the file
+ While the <command>postmaster</command> is running, its
+ <acronym>PID</acronym> is stored in the file
<filename>postmaster.pid</filename> in the data directory. This is
- used to prevent multiple postmasters running in the same data
- directory, and can also be used for shutting down the postmaster.
+ used to prevent multiple <command>postmaster</command> processes
+ running in the same data directory and can also be used for
+ shutting down the <command>postmaster</command> process.
</para>
<sect2 id="postmaster-start-failures">
<title>Server Start-up Failures</title>
<para>
- There are several common reasons the postmaster might fail to
- start. Check the postmaster's log file, or start it by hand
- (without redirecting standard output or standard error) and see
- what error messages appear. Some of the error messages are
- self-explanatory, but some are not, as shown below:
+ There are several common reasons the server might fail to
+ start. Check the server's log file, or start it by hand (without
+ redirecting standard output or standard error) and see what error
+ messages appear. Below we explain some of the most common error
+ messages in more detail.
</para>
<para>
<screen>
FATAL: StreamServerPort: bind() failed: Address already in use
- Is another postmaster already running on that port?
+ Is another postmaster already running on port 5432?
+ If not, wait a few seconds an retry.
</screen>
This usually means just what it suggests: you tried to start
- another postmaster on the same port where one is already running.
+ another <command>postmaster</command> on the same port where one is already running.
However, if the kernel error message is not <computeroutput>Address
already in use</computeroutput> or some variant of that, there may
- be a different problem. For example, trying to start a postmaster
+ be a different problem. For example, trying to start a <command>postmaster</command>
on a reserved port number may draw something like:
<screen>
$ <userinput>postmaster -i -p 666</userinput>
FATAL: StreamServerPort: bind() failed: Permission denied
- Is another postmaster already running on that port?
+ Is another postmaster already running on port 666?
+ If not, wait a few seconds an retry.
</screen>
</para>
<para>
- A message like:
+ A message like
<screen>
IpcMemoryCreate: shmget(key=5440001, size=83918612, 01600) failed: Invalid argument
FATAL 1: ShmemCreate: cannot create region
@@ -367,16 +361,16 @@ FATAL 1: ShmemCreate: cannot create region
is trying to create (83918612 bytes in this example). Or it could
mean that you do not have System-V-style shared memory support
configured into your kernel at all. As a temporary workaround, you
- can try starting the postmaster with a smaller-than-normal number
+ can try starting the server with a smaller-than-normal number
of buffers (<option>-B</option> switch). You will eventually want
to reconfigure your kernel to increase the allowed shared memory
- size. You may see this message when trying to start multiple
- postmasters on the same machine if their total space requested
+ size. You may also see this message when trying to start multiple
+ servers on the same machine if their total space requested
exceeds the kernel limit.
</para>
<para>
- An error like:
+ An error like
<screen>
IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on device
</screen>
@@ -385,7 +379,7 @@ IpcSemaphoreCreate: semget(key=5440026, num=16, 01600) failed: No space left on
class="osname">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 allowed connections
+ server with a reduced number of allowed connections
(<option>-N</option> switch), but you'll eventually want to
increase the kernel limit.
</para>
@@ -422,14 +416,13 @@ psql: could not connect to server: Connection refused
</screen>
This is the generic <quote>I couldn't find a server to talk
to</quote> failure. It looks like the above when TCP/IP
- communication is attempted. A common mistake is to forget the
- <option>-i</option> option to allow the postmaster to accept TCP/IP
- connections.
+ communication is attempted. A common mistake is to forget to
+ configure the server to allow TCP/IP connections.
</para>
<para>
- Alternatively, you'll get this when attempting Unix-socket
- communication to a local postmaster:
+ Alternatively, you'll get this when attempting Unix-domain socket
+ communication to a local server:
<screen>
psql: could not connect to server: Connection refused
Is the server running locally and accepting
@@ -439,14 +432,14 @@ psql: could not connect to server: Connection refused
<para>
The last line is useful in verifying that the client is trying to
- connect to the right place. If there is in fact no postmaster
+ connect to the right place. If there is in fact no server
running there, the kernel error message will typically be either
<computeroutput>Connection refused</computeroutput> or
<computeroutput>No such file or directory</computeroutput>, as
illustrated. (It is important to realize that
<computeroutput>Connection refused</computeroutput> in this context
- does <emphasis>not</emphasis> mean that the postmaster got your
- connection request and rejected it -- that case will produce a
+ does <emphasis>not</emphasis> mean that the server got your
+ connection request and rejected it. That case will produce a
different message, as shown in <xref
linkend="client-authentication-problems">.) Other error messages
such as <computeroutput>Connection timed out</computeroutput> may
@@ -493,7 +486,7 @@ search_path = '$user, public'
</programlisting>
As you see, options are one per line. The equal sign between name
and value is optional. Whitespace is insignificant and blank lines
- are ignored. Hash marks (<quote>#</quote>) introduce comments
+ are ignored. Hash marks (<literal>#</literal>) introduce comments
anywhere. Parameter values that are not simple identifiers or
numbers should be single-quoted.
</para>
@@ -502,28 +495,27 @@ search_path = '$user, public'
<indexterm>
<primary>SIGHUP</primary>
</indexterm>
- The configuration file is reread whenever the postmaster receives a
+ The configuration file is reread whenever the <command>postmaster</command> process receives a
<systemitem>SIGHUP</> signal (which is most easily sent by means of
- <literal>pg_ctl reload</>). The postmaster also propagates this
- signal to all currently running backend processes so that existing
+ <literal>pg_ctl reload</>). The <command>postmaster</command> also propagates this
+ signal to all currently running server processes so that existing
sessions also get the new value. Alternatively, you can send the
- signal to a single backend process directly.
+ signal to a single server process directly.
</para>
<para>
A second way to set these configuration parameters is to give them
- as a command line option to the postmaster, such as:
+ as a command line option to the <command>postmaster</command>, such as:
<programlisting>
postmaster -c log_connections=yes -c syslog=2
</programlisting>
- which would have the same effect as the previous example.
Command-line options override any conflicting settings in
<filename>postgresql.conf</filename>.
</para>
<para>
Occasionally it is also useful to give a command line option to
- one particular backend session only. The environment variable
+ one particular session only. The environment variable
<envar>PGOPTIONS</envar> can be used for this purpose on the
client side:
<programlisting>
@@ -539,7 +531,7 @@ env PGOPTIONS='-c geqo=off' psql
Some options can be changed in individual SQL sessions with the
<command>SET</command> command, for example:
<screen>
-=> <userinput>SET ENABLE_SEQSCAN TO OFF;</userinput>
+SET ENABLE_SEQSCAN TO OFF;
</screen>
See the SQL command language reference for details on the syntax.
</para>
@@ -549,22 +541,21 @@ env PGOPTIONS='-c geqo=off' psql
a user or a database. Whenever a session is started, the default
settings for the user and database involved are loaded. The
commands <literal>ALTER DATABASE</literal> and <literal>ALTER
- USER</literal>, respectively, are used to configure these settings.
- Such per-database settings override anything received from the postmaster
- or the configuration file, and in turn are overridden by per-user
+ USER</literal>, respectively, are used to configure these
+ settings. Such per-database settings override anything received
+ from the <command>postmaster</command> command-line or the
+ configuration file, and in turn are overridden by per-user
settings.
</para>
- <sect2 id="catalog-pg-settings">
- <title>pg_settings</title>
-
- <para>
- 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
- selection criteria applied.
- </para>
+ <para>
+ The virtual table <structname>pg_settings</structname> allows
+ displaying and updating session run-time parameters. It contains one
+ row for each configuration parameter; the columns are shown in
+ <xref linkend="runtime-pgsettings-table">. This form allows the
+ configuration data to be joined with other tables and have a
+ selection criteria applied.
+ </para>
<para>
An <command>UPDATE</command> performed on <structname>pg_settings</structname>
@@ -577,14 +568,14 @@ env PGOPTIONS='-c geqo=off' psql
overridden by another <command>UPDATE</command> or <command>SET</command>.
</para>
- <table>
- <title>pg_settings Columns</title>
+ <table id="runtime-pgsettings-table">
+ <title><literal>pg_settings</> Columns</title>
<tgroup cols=3>
<thead>
<row>
<entry>Name</entry>
- <entry>Type</entry>
+ <entry>Data Type</entry>
<entry>Description</entry>
</row>
</thead>
@@ -593,30 +584,27 @@ env PGOPTIONS='-c geqo=off' psql
<row>
<entry><literal>name</literal></entry>
<entry><type>text</type></entry>
- <entry>The name of a current session run-time parameter</entry>
+ <entry>The name of the run-time configuration parameter</entry>
</row>
<row>
<entry><literal>setting</literal></entry>
<entry><type>text</type></entry>
- <entry>The value of a current session run-time parameter</entry>
+ <entry>The current value of the run-time configuration parameter</entry>
</row>
</tbody>
</tgroup>
</table>
- </sect2>
-
<sect2 id="runtime-config-optimizer">
<title>Planner and Optimizer Tuning</title>
- <para>
<variablelist>
<varlistentry>
<term><varname>CPU_INDEX_TUPLE_COST</varname> (<type>floating point</type>)</term>
<listitem>
<para>
- Sets the query optimizer's estimate of the cost of processing
+ Sets the query planner's estimate of the cost of processing
each index tuple during an index scan. This is measured as a
fraction of the cost of a sequential page fetch.
</para>
@@ -627,7 +615,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>CPU_OPERATOR_COST</varname> (<type>floating point</type>)</term>
<listitem>
<para>
- Sets the optimizer's estimate of the cost of processing each
+ Sets the planner's estimate of the cost of processing each
operator in a <literal>WHERE</> clause. This is measured as a fraction of
the cost of a sequential page fetch.
</para>
@@ -638,7 +626,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>CPU_TUPLE_COST</varname> (<type>floating point</type>)</term>
<listitem>
<para>
- Sets the query optimizer's estimate of the cost of processing
+ Sets the query planner's estimate of the cost of processing
each tuple during a query. This is measured as a fraction of
the cost of a sequential page fetch.
</para>
@@ -662,7 +650,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>EFFECTIVE_CACHE_SIZE</varname> (<type>floating point</type>)</term>
<listitem>
<para>
- Sets the optimizer's assumption about the effective size of the
+ Sets the planner's assumption about the effective size of the
disk cache (that is, the portion of the kernel's disk cache that
will be used for <productname>PostgreSQL</productname> data
files). This is measured in disk pages, which are normally 8 kB
@@ -818,7 +806,7 @@ env PGOPTIONS='-c geqo=off' psql
algorithm: The pool size is the number of individuals in one
population. Valid values are between 128 and 1024. If it is set
to 0 (the default) a pool size of 2^(QS+1), where QS is the
- number of FROM items in the query, is taken. The effort is used
+ number of <literal>FROM</> items in the query, is taken. The effort is used
to calculate a default for generations. Valid values are between
1 and 80, 40 being the default. Generations specifies the number
of iterations in the algorithm. The number must be a positive
@@ -868,7 +856,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>RANDOM_PAGE_COST</varname> (<type>floating point</type>)</term>
<listitem>
<para>
- Sets the query optimizer's estimate of the cost of a
+ Sets the query planner's estimate of the cost of a
nonsequentially fetched disk page. This is measured as a
multiple of the cost of a sequential page fetch. A higher
value makes it more likely a sequential scan will be used,
@@ -877,12 +865,11 @@ env PGOPTIONS='-c geqo=off' psql
</listitem>
</varlistentry>
</variablelist>
- </para>
<note>
<para>
Unfortunately, there is no well-defined method for determining
- ideal values for the family of <quote>COST</quote> variables that
+ ideal values for the family of <quote>cost</quote> variables that
were just described. You are encouraged to experiment and share
your findings.
</para>
@@ -893,24 +880,24 @@ env PGOPTIONS='-c geqo=off' psql
<sect2 id="logging">
<title>Logging and Debugging</title>
- <para>
<variablelist>
<varlistentry>
<term><varname>CLIENT_MIN_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
- This controls how much message detail is written to the
+ This controls which message levels are send to the client.
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>WARNING</>, and <literal>ERROR</>. Each level
+ includes all the levels that follow it. The later the level,
+ the fewer messages are sent. The default is
<literal>NOTICE</>. Note that <literal>LOG</> has a different
- precedence here than in <literal>LOG_MIN_MESSAGES</>.
+ rank here than in <literal>LOG_MIN_MESSAGES</>.
</para>
<para>
- Here is a summary of the various message types:
+ Here is a list of the various message types:
<variablelist>
<varlistentry>
<term><literal>DEBUG[1-5]</literal></term>
@@ -936,7 +923,7 @@ env PGOPTIONS='-c geqo=off' psql
<listitem>
<para>
Provides information that may be helpful to users, e.g.,
- truncation of long identifiers and index creation as part
+ truncation of long identifiers and the creation of indexes as part
of primary keys.
</para>
</listitem>
@@ -947,7 +934,7 @@ env PGOPTIONS='-c geqo=off' psql
<listitem>
<para>
Provides warnings to the user, e.g., <command>COMMIT</>
- outside a transaction.
+ outside a transaction block.
</para>
</listitem>
</varlistentry>
@@ -956,7 +943,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><literal>ERROR</literal></term>
<listitem>
<para>
- Reports the error that caused a transaction to abort.
+ Reports an error that caused the current transaction to abort.
</para>
</listitem>
</varlistentry>
@@ -975,7 +962,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><literal>FATAL</literal></term>
<listitem>
<para>
- Reports why a backend session terminated.
+ Reports an error that caused the current session to abort.
</para>
</listitem>
</varlistentry>
@@ -984,7 +971,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><literal>PANIC</literal></term>
<listitem>
<para>
- Reports why all backend sessions restarted.
+ Reports an error that caused all sessions to abort.
</para>
</listitem>
</varlistentry>
@@ -1018,14 +1005,15 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>DEBUG_PRETTY_PRINT</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- These flags enable various debugging output to be sent to the
- server log. For each executed query, print the resulting parse
+ These options enable various debugging output to be sent to the
+ server log. For each executed query, they print 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.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term><varname>EXPLAIN_PRETTY_PRINT</varname> (<type>boolean</type>)</term>
<listitem>
@@ -1106,16 +1094,17 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>LOG_MIN_MESSAGES</varname> (<type>string</type>)</term>
<listitem>
<para>
- 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. The default is <literal>NOTICE</>.
- Note that <literal>LOG</> has a different precedence here than
- in <literal>CLIENT_MIN_MESSAGES</>. Also see that section for
- an explanation of the various values.
+ This controls which message levels are written to the server
+ log. 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</>. Each level includes all the levels that
+ follow it. The later the level, the fewer messages are sent
+ to the log. The default is <literal>NOTICE</>. Note that
+ <literal>LOG</> has a different rank here than in
+ <literal>CLIENT_MIN_MESSAGES</>. Also see that section for an
+ explanation of the various values.
</para>
</listitem>
@@ -1125,8 +1114,8 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>LOG_PID</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- Prefixes each server message in the log file with the process ID of
- the backend process. This is useful to sort out which messages
+ Prefixes each message in the server log file with the process ID of
+ the server process. This is useful to sort out which messages
pertain to which connection. The default is off. This parameter
does not affect messages logged via <application>syslog</>, which always contain
the process ID.
@@ -1185,8 +1174,8 @@ env PGOPTIONS='-c geqo=off' psql
<listitem>
<para>
Enables the collection of statistics on the currently
- executing command of each backend, along with the time at
- which that query began execution. This option is off by
+ executing command of each session, along with the time at
+ which that command began execution. This option is off by
default. Note that even when enabled, this information is only
visible to the superuser, so it should not represent a
security risk. This data can be accessed via the
@@ -1201,7 +1190,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>STATS_ROW_LEVEL</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- Enables the collection of block-level and row-level statistics
+ These enable the collection of block-level and row-level statistics
on database activity, respectively. These options are off by
default. This data can be accessed via the
<structname>pg_stat</structname> and
@@ -1293,13 +1282,11 @@ env PGOPTIONS='-c geqo=off' psql
</listitem>
</varlistentry>
</variablelist>
- </para>
</sect2>
<sect2 id="runtime-config-general">
<title>General Operation</title>
- <para>
<variablelist>
<varlistentry>
<term><varname>AUTOCOMMIT</varname> (<type>boolean</type>)</term>
@@ -1356,10 +1343,11 @@ env PGOPTIONS='-c geqo=off' psql
<indexterm><primary>Australian time zones</></>
<listitem>
<para>
- If set to true, <literal>CST</literal>, <literal>EST</literal>,
- and <literal>SAT</literal> are interpreted as Australian
- time zones rather than as North American Central/Eastern
- time zones and Saturday. The default is false.
+ If set to true, <literal>ACST</literal>,
+ <literal>CST</literal>, <literal>EST</literal>, and
+ <literal>SAT</literal> are interpreted as Australian time
+ zones rather than as North/South American time zones and
+ Saturday. The default is false.
</para>
</listitem>
</varlistentry>
@@ -1384,7 +1372,7 @@ env PGOPTIONS='-c geqo=off' psql
<indexterm><primary>character set encoding</></>
<listitem>
<para>
- Sets the client-side encoding for multibyte character sets.
+ Sets the client-side encoding (character set).
The default is to use the database encoding.
</para>
</listitem>
@@ -1395,8 +1383,8 @@ env PGOPTIONS='-c geqo=off' psql
<indexterm><primary>date style</></>
<listitem>
<para>
- Sets the display format for dates, as well as the rules for
- interpreting ambiguous input dates.
+ Sets the display format for date and time values, as well as the rules for
+ interpreting ambiguous date input values.
The default is <literal>ISO, US</>.
</para>
</listitem>
@@ -1410,7 +1398,7 @@ env PGOPTIONS='-c geqo=off' psql
</para>
<para>
- If this is on, create users as <literal> username@dbname</>.
+ If this is on, you should 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
@@ -1454,14 +1442,14 @@ env PGOPTIONS='-c geqo=off' psql
check for deadlock is relatively slow, so the server doesn't run
it every time it waits for a lock. We (optimistically?) assume
that deadlocks are not common in production applications and
- just wait on the lock for a while before starting check for a
+ just wait on the lock for a while before starting the check for a
deadlock. Increasing this value reduces the amount of time
wasted in needless deadlock checks, but slows down reporting of
real deadlock errors. The default is 1000 (i.e., one second),
which is probably about the smallest value you would want in
practice. On a heavily loaded server you might want to raise it.
Ideally the setting should exceed your typical transaction time,
- so as to improve the odds that the lock will be released before
+ so as to improve the odds that a lock will be released before
the waiter decides to check for deadlock.
</para>
</listitem>
@@ -1504,7 +1492,7 @@ env PGOPTIONS='-c geqo=off' psql
</para>
<para>
- The value for dynamic_library_path has to be a colon-separated
+ The value for <varname>DYNAMIC_LIBRARY_PATH</varname> has to be a colon-separated
list of absolute directory names. If a directory name starts
with the special value <literal>$libdir</literal>, the
compiled-in <productname>PostgreSQL</productname> package
@@ -1577,10 +1565,10 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<term><varname>FSYNC</varname> (<type>boolean</type>)</term>
<listitem>
<para>
- If this option is on, the <productname>PostgreSQL</> backend
+ If this option is on, the <productname>PostgreSQL</> server
will use the <function>fsync()</> system call in several places
to make sure that updates are physically written to disk. This
- insures that a database installation will recover to a
+ insures that a database cluster will recover to a
consistent state after an operating system or hardware crash.
(Crashes of the database server itself are <emphasis>not</>
related to this.)
@@ -1599,20 +1587,22 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</para>
<para>
- For the above reasons, some administrators always leave it off,
- some turn it off only for bulk loads, where there is a clear
- restart point if something goes wrong, and some leave it on just
- to be on the safe side. Because it is always safe, the default
- is on. If you trust your operating system, your hardware, and
- your utility company (or better your UPS), you might want to
- disable <varname>fsync</varname>.
+ For the above reasons, everyone can decide for himself what to
+ do with the <varname>fsync</> option. Some administrators
+ always leave it off, some turn it off only for bulk loads,
+ where there is a clear restart point if something goes wrong,
+ and some leave it on just to be on the safe side. The default
+ is on so that you are on the safe side. If you trust your
+ operating system, your hardware, and your utility company (or
+ better your battery backup), you can consider disabling
+ <varname>fsync</varname>.
</para>
<para>
- It should be noted that the performance penalty of doing
- <function>fsync</>s is considerably less in
+ It should be noted that the performance penalty of having
+ <varname>fsync</> on considerably less in
<productname>PostgreSQL</> version 7.1 and later. If you
- previously suppressed <function>fsync</>s for performance
+ previously suppressed <function>fsync</> for performance
reasons, you may wish to reconsider your choice.
</para>
@@ -1649,7 +1639,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<listitem>
<para>
Sets the locale to use for formatting monetary amounts, for
- example with the <function>to_char()</function> family of
+ example with the <function>to_char</function> family of
functions. Acceptable values are system-dependent; see <xref
linkend="locale"> for more information. If this variable is
set to the empty string (which is the default) then the value
@@ -1708,7 +1698,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
Sets the maximum expression nesting depth of the parser. The
default value is high enough for any normal query, but you can
raise it if needed. (But if you raise it too high, you run
- the risk of backend crashes due to stack overflow.)
+ the risk of server crashes due to stack overflow.)
</para>
</listitem>
</varlistentry>
@@ -1717,7 +1707,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<term><varname>MAX_FILES_PER_PROCESS</varname> (<type>integer</type>)</term>
<listitem>
<para>
- Sets the maximum number of simultaneously open files in each
+ Sets the maximum number of simultaneously open files allowed to each
server subprocess. The default is 1000. The limit actually used
by the code is the smaller of this setting and the result of
<literal>sysconf(_SC_OPEN_MAX)</literal>. Therefore, on systems
@@ -1782,7 +1772,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<para>
When a password is specified in <command>CREATE USER</> or
<command>ALTER USER</> without writing either <literal>ENCRYPTED</> or
- <literal>UNENCRYPTED</>, this flag determines whether the password is to be
+ <literal>UNENCRYPTED</>, this option determines whether the password is to be
encrypted. The default is on (encrypt the password).
</para>
</listitem>
@@ -1845,7 +1835,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<varlistentry>
<term><varname>SEARCH_PATH</varname> (<type>string</type>)</term>
<indexterm><primary>search_path</></>
- <indexterm><primary>namespaces</></>
+ <indexterm><primary>path</><secondary>for schemas</></>
<listitem>
<para>
This variable specifies the order in which schemas are searched
@@ -1861,7 +1851,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
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
+ having the name returned by <function>SESSION_USER</> is substituted, if there
is such a schema. (If not, <literal>$user</literal> is ignored.)
</para>
@@ -1895,10 +1885,6 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</para>
<para>
- <indexterm>
- <primary>schemas</primary>
- <secondary>current schema</secondary>
- </indexterm>
The current effective value of the search path can be examined
via the SQL function <function>current_schemas()</>. This is not
quite the same as examining the value of
@@ -1948,12 +1934,12 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
</varlistentry>
<varlistentry>
- <term><varname>SILENT_MODE</varname> (<type>bool</type>)</term>
+ <term><varname>SILENT_MODE</varname> (<type>boolean</type>)</term>
<listitem>
<para>
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
+ will automatically run in background and any controlling terminals
+ are disassociated. Thus, no messages are written to standard
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
@@ -1966,24 +1952,24 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<term><varname>SORT_MEM</varname> (<type>integer</type>)</term>
<listitem>
<para>
- Specifies the amount of memory to be used by internal sorts and
+ Specifies the amount of memory to be used by internal sort operations and
hash tables before switching to temporary disk files. The value is
specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
- Note that for a complex query, several sorts or hashes might be
+ Note that for a complex query, several sort or hash operations might be
running in parallel; 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
+ files. Also, several running sessions could be doing
+ sort operations simultaneously. So the total memory used could be many
+ times the value of <varname>SORT_MEM</varname>. Sort operations are used
by <literal>ORDER BY</>, merge joins, and <command>CREATE INDEX</>.
Hash tables are used in hash joins, hash-based aggregation, and
- hash-based processing of <literal>IN</> sub-selects.
+ hash-based processing of <literal>IN</> subqueries.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>SQL_INHERITANCE</varname> (<type>bool</type>)</term>
+ <term><varname>SQL_INHERITANCE</varname> (<type>boolean</type>)</term>
<indexterm><primary>inheritance</></>
<listitem>
<para>
@@ -1992,7 +1978,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
not included in versions prior to 7.1. If you need the old
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
+ <literal>ONLY</literal> key word to exclude subtables. See the
SQL language reference and the &cite-user; for more information about inheritance.
</para>
</listitem>
@@ -2024,7 +2010,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
ever be active simultaneously. Whenever the number of active
concurrent connections is at least <varname>max_connections</> minus
<varname>superuser_reserved_connections</varname>, new connections
- will be accepted only from superuser accounts.
+ will be accepted only for superusers.
</para>
<para>
@@ -2052,7 +2038,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<indexterm><primary>time zone</></>
<listitem>
<para>
- Sets the time zone for displaying and interpreting timestamps.
+ Sets the time zone for displaying and interpreting time stamps.
The default is to use whatever the system environment
specifies as the time zone.
</para>
@@ -2121,7 +2107,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
Sets the group owner of the Unix domain socket. (The owning
user of the socket is always the user that starts the
server.) In combination with the option
- <option>UNIX_SOCKET_PERMISSIONS</option> this can be used as
+ <varname>UNIX_SOCKET_PERMISSIONS</varname> 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
group for the current user. This option can only be set at
@@ -2147,7 +2133,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
The default permissions are <literal>0777</literal>, meaning
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>
+ <varname>UNIX_SOCKET_GROUP</varname>) and <literal>0700</literal>
(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.)
@@ -2181,17 +2167,15 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<term><varname>VIRTUAL_HOST</varname> (<type>string</type>)</term>
<listitem>
<para>
- Specifies the TCP/IP host name or address on which the
- <application>postmaster</application> is to listen for
- connections from client applications. Defaults to listening on
- all configured addresses (including <systemitem
- class="systemname">localhost</>).
+ Specifies the host name or IP address on which the server is
+ to listen for connections from client applications. The
+ default is to listening on all configured addresses (including
+ <systemitem class="systemname">localhost</>).
</para>
</listitem>
</varlistentry>
</variablelist>
- </para>
</sect2>
<sect2 id="runtime-config-wal">
@@ -2248,7 +2232,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
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 <varname>COMMIT_SIBLINGS</varname> other transactions
- are active at the instant that a backend process has written its commit
+ are active at the instant that a server process has written its commit
record.
</para>
</listitem>
@@ -2281,8 +2265,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 nonzero, turn on WAL-related debugging output on standard
- error.
+ If nonzero, turn on WAL-related debugging output to the server log.
</para>
</listitem>
</varlistentry>
@@ -2295,7 +2278,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
values are
<literal>FSYNC</> (call <function>fsync()</> at each commit),
<literal>FDATASYNC</> (call <function>fdatasync()</> at each commit),
- <literal>OPEN_SYNC</> (write WAL files with <function>open()</> option <symbol>O_SYNC</>), or
+ <literal>OPEN_SYNC</> (write WAL files with <function>open()</> option <symbol>O_SYNC</>), and
<literal>OPEN_DATASYNC</> (write WAL files with <function>open()</> option <symbol>O_DSYNC</>).
Not all of these choices are available on all platforms.
This option can only be set at server start or in the
@@ -2312,8 +2295,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
<title>Short Options</title>
<para>
- For convenience there are also single letter option switches
- available for many parameters. They are described in <xref
+ For convenience there are also single letter command-line option switches
+ available for some parameters. They are described in <xref
linkend="runtime-config-short-table">.
</para>
@@ -2373,8 +2356,8 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
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,
+ the individual server process via the <option>-o</option>
+ <command>postmaster</command> option, for example,
<screen>
$ <userinput>postmaster -o '-S 1024 -s'</userinput>
</screen>
@@ -2454,14 +2437,14 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
<para>
The complete lack of these facilities is usually manifested by an
- <errorname>Illegal system call</> error upon postmaster start. In
+ <errorname>Illegal system call</> error upon server start. In
that case there's nothing left to do but to reconfigure your
- kernel -- <productname>PostgreSQL</> won't work without them.
+ kernel. <productname>PostgreSQL</> won't work without them.
</para>
<para>
When <productname>PostgreSQL</> exceeds one of the various hard
- <acronym>IPC</> limits, the postmaster will refuse to start and
+ <acronym>IPC</> limits, the server will refuse to start and
should leave an instructive error message describing the problem
encountered and what to do about it. (See also <xref
linkend="postmaster-start-failures">.) The relevant kernel
@@ -2489,7 +2472,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
<row>
<entry><varname>SHMMAX</></>
<entry>Maximum size of shared memory segment (bytes)</>
- <entry>250kB + 8.2 kB * <varname>shared_buffers</> + 14.2 kB * <varname>max_connections</> or infinity</entry>
+ <entry>250 kB + 8.2 kB * <varname>shared_buffers</> + 14.2 kB * <varname>max_connections</> up to infinity</entry>
</row>
<row>
@@ -2519,19 +2502,19 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
<row>
<entry><varname>SEMMNI</></>
<entry>Maximum number of semaphore identifiers (i.e., sets)</>
- <entry><literal>>= ceil(max_connections / 16)</literal></>
+ <entry>at least <literal>ceil(max_connections / 16)</literal></>
</row>
<row>
<entry><varname>SEMMNS</></>
<entry>Maximum number of semaphores system-wide</>
- <entry><literal>ceil(max_connections / 16) * 17</literal> + room for other applications</>
+ <entry><literal>ceil(max_connections / 16) * 17</literal> plus room for other applications</>
</row>
<row>
<entry><varname>SEMMSL</></>
<entry>Maximum number of semaphores per set</>
- <entry>>= 17</>
+ <entry>at least 17</>
</row>
<row>
@@ -2543,7 +2526,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
<row>
<entry><varname>SEMVMX</></>
<entry>Maximum value of semaphore</>
- <entry>>= 255 (The default is often 32767, don't change unless asked to.)</>
+ <entry>at least 255 (The default is often 32767, don't change unless asked to.)</>
</row>
</tbody>
@@ -2593,8 +2576,8 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
exist on the system at one time. Hence this parameter must be at
least <literal>ceil(max_connections / 16)</>. Lowering the number
of allowed connections is a temporary workaround for failures,
- which are usually confusingly worded <quote><errorname>No space
- left on device</></>, from the function <function>semget()</>.
+ which are usually confusingly worded <errorname>No space
+ left on device</>, from the function <function>semget</>.
</para>
<para>
@@ -2622,8 +2605,6 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
for <productname>PostgreSQL</>.
</para>
-
- <para>
<variablelist>
<varlistentry>
@@ -2635,8 +2616,8 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
<para>
By default, only 4 MB of shared memory is supported. Keep in
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
+ To increase the amount of shared memory supported by your
+ system, add the following to your kernel configuration
file. A <varname>SHMALL</> value of 1024 represents 4 MB of
shared memory. The following increases the maximum shared
memory area to 32 MB:
@@ -2644,22 +2625,22 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
options "SHMALL=8192"
options "SHMMAX=\(SHMALL*PAGE_SIZE\)"
</programlisting>
+ For those running 4.1 or later, just make the above changes,
+ recompile the kernel, and reboot.
</para>
</formalpara>
<para>
- For those running 4.1 or later, just make the above changes,
- recompile the kernel, and reboot. For those running earlier
- releases, use <command>bpatch</> to find the
- <varname>sysptsize</> value in the current kernel. This is
- computed dynamically at boot time.
+ For those running earlier releases, use <command>bpatch</> to
+ find the <varname>sysptsize</> value in the current
+ kernel. This is computed dynamically at boot time.
<screen>
$ <userinput>bpatch -r sysptsize</>
<computeroutput>0x9 = 9</>
</screen>
Next, add <varname>SYSPTSIZE</> as a hard-coded value in the
kernel configuration file. Increase the value you found using
- <application>bpatch</>. Add 1 for every additional 4 MB of
+ <command>bpatch</>. Add 1 for every additional 4 MB of
shared memory you desire.
<programlisting>
options "SYSPTSIZE=16"
@@ -2670,21 +2651,16 @@ options "SYSPTSIZE=16"
<formalpara>
<title>Semaphores</>
<para>
- You may need to increase the number of semaphores. By default,
- <productname>PostgreSQL</> allocates 34 semaphores, which is
- over half the default system total of 60.
- </para>
- </formalpara>
-
- <para>
- Set the values you want in your kernel configuration file, e.g.:
+ You may need to increase the number of semaphores. By
+ default, <productname>PostgreSQL</> allocates 34 semaphores,
+ which is over half the default system total of 60. Set the
+ values you want in your kernel configuration file, e.g.:
<programlisting>
options "SEMMNI=40"
options "SEMMNS=240"
-options "SEMUME=40"
-options "SEMMNU=120"
</programlisting>
- </para>
+ </para>
+ </formalpara>
</listitem>
</varlistentry>
@@ -2719,7 +2695,7 @@ options SEMMAP=256
<literal>option</literal> singular.)
</para>
<para>
- You might also want to use the <application>sysctl</> setting to
+ You might also want to use the <command>sysctl</> setting to
lock shared memory into RAM and prevent it from being paged out
to swap, e.g. <literal>kern.ipc.shm_use_phys</>.
</para>
@@ -2766,18 +2742,16 @@ options SEMMAP=256
</para>
<para>
- Alternatively, you can use
- <citerefentry><refentrytitle>sysctl</refentrytitle>
- <manvolnum>8</manvolnum></citerefentry>, if available, to
- control these parameters. Look for a file called
- <filename>/etc/sysctl.conf</filename> and add lines like the
- following to it:
+ Alternatively, you can use <command>sysctl</command>, if
+ available, to control these parameters. Look for a file
+ called <filename>/etc/sysctl.conf</filename> and add lines
+ like the following to it:
<programlisting>
kernel.shmall = 134217728
kernel.shmmax = 134217728
</programlisting>
This file is usually processed at boot time, but
- <application>sysctl</application> can also be called
+ <command>sysctl</command> can also be called
explicitly later.
</para>
@@ -2806,8 +2780,6 @@ sysctl -w kern.sysv.shmmni
sysctl -w kern.sysv.shmseg
sysctl -w kern.sysv.shmall
</programlisting>
- These values have the same meanings on <productname>MacOS</> X
- as those listed for previous operating systems.
</para>
</listitem>
</varlistentry>
@@ -2820,18 +2792,18 @@ sysctl -w kern.sysv.shmall
<para>
In the default configuration, only 512 kB of shared memory per
segment is allowed, which is about enough for <option>-B 24 -N
- 12</>. To increase the setting, first change directory to
+ 12</>. To increase the setting, first change to the directory
<filename>/etc/conf/cf.d</>. To display the current value of
- <varname>SHMMAX</>, in bytes, run
+ <varname>SHMMAX</>, run
<programlisting>
./configure -y SHMMAX
</programlisting>
- To set a new value for <varname>SHMMAX</>, run:
+ To set a new value for <varname>SHMMAX</>, run
<programlisting>
./configure SHMMAX=<replaceable>value</>
</programlisting>
where <replaceable>value</> is the new value you want to use
- (in bytes). After setting <varname>SHMMAX</>, rebuild the kernel
+ (in bytes). After setting <varname>SHMMAX</>, rebuild the kernel:
<programlisting>
./link_unix
</programlisting>
@@ -2887,14 +2859,14 @@ set semsys:seminfo_semmsl=32
/etc/conf/bin/idtune -g SHMMAX
</programlisting>
which displays the current, default, minimum, and maximum
- values, in bytes. To set a new value for <varname>SHMMAX</>,
- run:
+ values. To set a new value for <varname>SHMMAX</>,
+ run
<programlisting>
/etc/conf/bin/idtune SHMMAX <replaceable>value</>
</programlisting>
where <replaceable>value</> is the new value you want to use
(in bytes). After setting <varname>SHMMAX</>, rebuild the
- kernel
+ kernel:
<programlisting>
/etc/conf/bin/idbuild -B
</programlisting>
@@ -2905,7 +2877,6 @@ set semsys:seminfo_semmsl=32
</variablelist>
- </para>
</sect2>
@@ -2927,9 +2898,8 @@ set semsys:seminfo_semmsl=32
(Bourne shells) or <command>limit</command> (<application>csh</>) is
used to control the resource limits from the command line. On
BSD-derived systems the file <filename>/etc/login.conf</filename>
- controls the various resource limits set during login. See
- <citerefentry><refentrytitle>login.conf</refentrytitle>
- <manvolnum>5</manvolnum></citerefentry> for details. The relevant
+ controls the various resource limits set during login. See the
+ operating system documentation for details. The relevant
parameters are <varname>maxproc</varname>,
<varname>openfiles</varname>, and <varname>datasize</varname>. For
example:
@@ -3007,10 +2977,10 @@ default:\
<term><systemitem>SIGTERM</systemitem></term>
<listitem>
<para>
- After receiving <systemitem>SIGTERM</systemitem>, the postmaster
- disallows new connections, but lets existing backends end their
- work normally. It shuts down only after all of the backends
- terminate normally. This is <firstterm>Smart
+ After receiving <systemitem>SIGTERM</systemitem>, the server
+ disallows new connections, but lets existing sessions end their
+ work normally. It shuts down only after all of the sessions
+ terminate normally. This is the <firstterm>Smart
Shutdown</firstterm>.
</para>
</listitem>
@@ -3020,10 +2990,10 @@ default:\
<term><systemitem>SIGINT</systemitem></term>
<listitem>
<para>
- The postmaster disallows new connections and sends all existing
- backends <systemitem>SIGTERM</systemitem>, which will cause them
+ The server disallows new connections and sends all existing
+ server processes <systemitem>SIGTERM</systemitem>, which will cause them
to abort their current transactions and exit promptly. It then
- waits for the backends to exit and finally shuts down. This is
+ waits for the server processes to exit and finally shuts down. This is the
<firstterm>Fast Shutdown</firstterm>.
</para>
</listitem>
@@ -3032,10 +3002,11 @@ default:\
<varlistentry>
<term><systemitem>SIGQUIT</systemitem></term>
<listitem>
- <para> This is <firstterm>Immediate Shutdown</firstterm>, which
- will cause the postmaster to send a
- <systemitem>SIGQUIT</systemitem> to all backends and exit
- immediately (without properly shutting itself down). The backends
+ <para>
+ This is the <firstterm>Immediate Shutdown</firstterm>, which
+ will cause the <command>postmaster</command> process to send a
+ <systemitem>SIGQUIT</systemitem> to all child processes and exit
+ immediately (without properly shutting itself down). The child processes
likewise exit immediately upon receiving
<systemitem>SIGQUIT</systemitem>. This will lead to recovery (by
replaying the WAL log) upon next start-up. This is recommended
@@ -3044,18 +3015,20 @@ default:\
</listitem>
</varlistentry>
</variablelist>
+ </para>
<important>
<para>
It is best not to use <systemitem>SIGKILL</systemitem> to shut down
- the postmaster. This will prevent the postmaster from releasing
+ the server. This will prevent the server from releasing
shared memory and semaphores, which may then have to be done by
manually.
</para>
</important>
- The <acronym>PID</> of the postmaster process can be found using the
- <application>ps</application> program, or from the file
+ <para>
+ The <acronym>PID</> of the <command>postmaster</command> process can be found using the
+ <command>ps</command> program, or from the file
<filename>postmaster.pid</filename> in the data directory. So for
example, to do a fast shutdown:
<screen>
@@ -3063,9 +3036,9 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
</screen>
</para>
<para>
- The program <application>pg_ctl</application> is a shell script
+ The program <command>pg_ctl</command> is a shell script
that provides a more convenient interface for shutting down the
- postmaster.
+ server.
</para>
</sect1>
@@ -3079,21 +3052,21 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<para>
<productname>PostgreSQL</> has native support for using
<acronym>SSL</> connections to encrypt client/server communications
- for increased security. This requires
- <productname>OpenSSL</productname> be installed on both client and
- server systems and support enabled at build time (see <xref
- linkend="installation">).
+ for increased security. This requires that
+ <productname>OpenSSL</productname> is installed on both client and
+ server systems and that support in <productname>PostgreSQL</> is
+ enabled at build time (see <xref linkend="installation">).
</para>
<para>
With <acronym>SSL</> support compiled in, the
<productname>PostgreSQL</> server can be started with
- <acronym>SSL</> support by setting the parameter
+ <acronym>SSL</> enabled by setting the parameter
<varname>ssl</varname> to on in <filename>postgresql.conf</>. When
starting in <acronym>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
+ data directory, which should contain the server private key
+ and certificate, respectively. These files must be set up correctly
before an <acronym>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.
@@ -3101,7 +3074,7 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
<para>
The server will listen for both standard and <acronym>SSL</>
- connections on the same TCP/IP port, and will negotiate with any
+ connections on the same TCP port, and will negotiate with any
connecting client on whether to use <acronym>SSL</>. See <xref
linkend="client-authentication"> about how to force the server to
require use of <acronym>SSL</> for certain connections.
@@ -3120,8 +3093,8 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
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
+ that you enter the local host name as <quote>Common Name</>; the challenge
+ password can be left blank. The programm will generate a key that is
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
@@ -3146,15 +3119,6 @@ chmod og-rwx server.key
<primary>ssh</primary>
</indexterm>
- <note>
- <title>Acknowledgement</title>
- <para>
- Idea taken from an email by Gene Selkov, Jr.
- (<email>selkovjr@mcs.anl.gov</>) written on 1999-09-08 in response
- to a question from Eric Marsden.
- </para>
- </note>
-
<para>
One can use <application>SSH</application> to encrypt the network
connection between clients and a
@@ -3164,8 +3128,8 @@ chmod og-rwx server.key
<para>
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
+ running properly on the same machine as the
+ <productname>PostgreSQL</productname> server 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>
@@ -3173,7 +3137,7 @@ 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
- second number, 5432, is the remote end of the tunnel -- the port
+ second number, 5432, is the remote end of the tunnel: the port
number your server is using. The name or the address in between
the port numbers is the host with the database server you are going
to connect to. In order to connect to the database server using
@@ -3185,7 +3149,7 @@ psql -h localhost -p 3333 template1
user <literal>joe@foo.com</literal> and it will use whatever
authentication procedure was set up for this user. In order for the
tunnel setup to succeed you must be allowed to connect via
- <command>ssh</command> as <systemitem>joe@foo.com</systemitem>, just
+ <command>ssh</command> as <literal>joe@foo.com</literal>, just
as if you had attempted to use <command>ssh</command> to set up a
terminal session.
</para>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 2589ab8163b..279364a65d8 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -1,38 +1,28 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.22 2002/11/15 02:44:54 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.23 2003/03/24 14:32:51 petere Exp $ -->
<chapter id="wal">
<title>Write-Ahead Logging (<acronym>WAL</acronym>)</title>
- <note>
- <title>Author</title>
<para>
- Vadim Mikheev and Oliver Elphick
- </para>
- </note>
-
- <sect1 id="wal-general">
- <title>General Description</Title>
-
- <para>
- <firstterm>Write Ahead Logging</firstterm> (<acronym>WAL</acronym>)
+ <firstterm>Write-Ahead Logging</firstterm> (<acronym>WAL</acronym>)
is a standard approach to transaction logging. Its detailed
description may be found in most (if not all) books about
transaction processing. Briefly, <acronym>WAL</acronym>'s central
concept is that changes to data files (where tables and indexes
- reside) must be written only after those changes have been logged -
+ reside) must be written only after those changes have been logged,
that is, when log records have been flushed to permanent
- storage. When we follow this procedure, we do not need to flush
+ storage. If we follow this procedure, we do not need to flush
data pages to disk on every transaction commit, because we know
that in the event of a crash we will be able to recover the
database using the log: any changes that have not been applied to
the data pages will first be redone from the log records (this is
roll-forward recovery, also known as REDO) and then changes made by
uncommitted transactions will be removed from the data pages
- (roll-backward recovery - UNDO).
+ (roll-backward recovery, UNDO).
</para>
- <sect2 id="wal-benefits-now">
- <title>Immediate Benefits of <acronym>WAL</acronym></title>
+ <sect1 id="wal-benefits-now">
+ <title>Benefits of <acronym>WAL</acronym></title>
<para>
The first obvious benefit of using <acronym>WAL</acronym> is a
@@ -54,11 +44,11 @@
<orderedlist>
<listitem>
- <simpara>index tuples pointing to nonexistent table rows</simpara>
+ <simpara>index rows pointing to nonexistent table rows</simpara>
</listitem>
<listitem>
- <simpara>index tuples lost in split operations</simpara>
+ <simpara>index rows lost in split operations</simpara>
</listitem>
<listitem>
@@ -74,22 +64,22 @@
page content in the log if that is required to ensure page
consistency for after-crash recovery.
</para>
- </sect2>
+ </sect1>
- <sect2 id="wal-benefits-later">
+ <sect1 id="wal-benefits-later">
<title>Future Benefits</title>
<para>
- UNDO operation is not implemented. This means that changes
+ The UNDO operation is not implemented. This means that changes
made by aborted transactions will still occupy disk space and that
- we still need a permanent <filename>pg_clog</filename> file to hold
- the status of transactions, since we are not able to re-use
- transaction identifiers. Once UNDO is implemented,
+ a permanent <filename>pg_clog</filename> file to hold
+ the status of transactions is still needed, since
+ transaction identifiers cannot be reused. Once UNDO is implemented,
<filename>pg_clog</filename> will no longer be required to be
permanent; it will be possible to remove
<filename>pg_clog</filename> at shutdown. (However, the urgency of
this concern has decreased greatly with the adoption of a segmented
- storage method for <filename>pg_clog</filename> --- it is no longer
+ storage method for <filename>pg_clog</filename>: it is no longer
necessary to keep old <filename>pg_clog</filename> entries around
forever.)
</para>
@@ -122,7 +112,7 @@
<para>
A difficulty standing in the way of realizing these benefits is that
they require saving <acronym>WAL</acronym> entries for considerable
- periods of time (eg, as long as the longest possible transaction if
+ periods of time (e.g., as long as the longest possible transaction if
transaction UNDO is wanted). The present <acronym>WAL</acronym>
format is extremely bulky since it includes many disk page
snapshots. This is not a serious concern at present, since the
@@ -130,93 +120,13 @@
but to achieve these future benefits some sort of compressed
<acronym>WAL</acronym> format will be needed.
</para>
- </sect2>
- </sect1>
-
- <sect1 id="wal-implementation">
- <title>Implementation</title>
-
- <para>
- <acronym>WAL</acronym> is automatically enabled from release 7.1
- onwards. No action is required from the administrator with the
- exception of ensuring that the additional disk-space requirements
- of the <acronym>WAL</acronym> logs are met, and that any necessary
- tuning is done (see <xref linkend="wal-configuration">).
- </para>
-
- <para>
- <acronym>WAL</acronym> logs are stored in the directory
- <Filename><replaceable>$PGDATA</replaceable>/pg_xlog</Filename>, as
- a set of segment files, each 16 MB in size. Each segment is
- divided into 8 kB pages. The log record headers are described in
- <filename>access/xlog.h</filename>; record content is dependent on
- the type of event that is being logged. Segment files are given
- ever-increasing numbers as names, starting at
- <filename>0000000000000000</filename>. The numbers do not wrap, at
- present, but it should take a very long time to exhaust the
- available stock of numbers.
- </para>
-
- <para>
- The <acronym>WAL</acronym> buffers and control structure are in
- shared memory, and are handled by the backends; they are protected
- by lightweight locks. The demand on shared memory is dependent on the
- number of buffers. The default size of the <acronym>WAL</acronym>
- buffers is 8 buffers of 8 kB each, or 64 kB total.
- </para>
-
- <para>
- It is of advantage if the log is located on another disk than the
- main database files. This may be achieved by moving the directory,
- <filename>pg_xlog</filename>, to another location (while the
- postmaster is shut down, of course) and creating a symbolic link
- from the original location in <replaceable>$PGDATA</replaceable> to
- the new location.
- </para>
-
- <para>
- The aim of <acronym>WAL</acronym>, to ensure that the log is
- written before database records are altered, may be subverted by
- disk drives that falsely report a successful write to the kernel,
- when, in fact, they have only cached the data and not yet stored it
- on the disk. A power failure in such a situation may still lead to
- irrecoverable data corruption. Administrators should try to ensure
- that disks holding <productname>PostgreSQL</productname>'s
- log files do not make such false reports.
- </para>
-
- <sect2 id="wal-recovery">
- <title>Database Recovery with <acronym>WAL</acronym></title>
-
- <para>
- After a checkpoint has been made and the log flushed, the
- checkpoint's position is saved in the file
- <filename>pg_control</filename>. Therefore, when recovery is to be
- done, the backend first reads <filename>pg_control</filename> and
- then the checkpoint record; then it performs the REDO operation by
- scanning forward from the log position indicated in the checkpoint
- record.
- Because the entire content of data pages is saved in the log on the
- first page modification after a checkpoint, all pages changed since
- the checkpoint will be restored to a consistent state.
- </para>
-
- <para>
- Using <filename>pg_control</filename> to get the checkpoint
- position speeds up the recovery process, but to handle possible
- corruption of <filename>pg_control</filename>, we should actually
- implement the reading of existing log segments in reverse order --
- newest to oldest -- in order to find the last checkpoint. This has
- not been implemented, yet.
- </para>
- </sect2>
- </sect1>
+ </sect1>
<sect1 id="wal-configuration">
<title><acronym>WAL</acronym> Configuration</title>
<para>
- There are several <acronym>WAL</acronym>-related parameters that
+ There are several <acronym>WAL</acronym>-related configuration parameters that
affect database performance. This section explains their use.
Consult <xref linkend="runtime-config"> for details about setting
configuration parameters.
@@ -232,25 +142,25 @@
log (known as the redo record) it should start the REDO operation,
since any changes made to data files before that record are already
on disk. After a checkpoint has been made, any log segments written
- before the undo records are no longer needed and can be recycled or
+ before the redo records are no longer needed and can be recycled or
removed. (When <acronym>WAL</acronym>-based <acronym>BAR</acronym> is
implemented, the log segments would be archived before being recycled
or removed.)
</para>
<para>
- The postmaster spawns a special backend process every so often
+ The server spawns a special process every so often
to create the next checkpoint. A checkpoint is created every
- <varname>CHECKPOINT_SEGMENTS</varname> log segments, or every
- <varname>CHECKPOINT_TIMEOUT</varname> seconds, whichever comes first.
+ <varname>checkpoint_segments</varname> log segments, or every
+ <varname>checkpoint_timeout</varname> seconds, whichever comes first.
The default settings are 3 segments and 300 seconds respectively.
It is also possible to force a checkpoint by using the SQL command
<command>CHECKPOINT</command>.
</para>
<para>
- Reducing <varname>CHECKPOINT_SEGMENTS</varname> and/or
- <varname>CHECKPOINT_TIMEOUT</varname> causes checkpoints to be done
+ Reducing <varname>checkpoint_segments</varname> and/or
+ <varname>checkpoint_timeout</varname> causes checkpoints to be done
more often. This allows faster after-crash recovery (since less work
will need to be redone). However, one must balance this against the
increased cost of flushing dirty data pages more often. In addition,
@@ -262,15 +172,15 @@
</para>
<para>
- There will be at least one 16MB segment file, and will normally
- not be more than 2 * <varname>CHECKPOINT_SEGMENTS</varname>
- + 1 files. You can use this to estimate space requirements for
- WAL. Ordinarily, when old log segment files are no longer needed,
- they are recycled (renamed to become the next sequential future
- segments). If, due to a short-term peak of log output rate, there
- are more than 2 * <varname>CHECKPOINT_SEGMENTS</varname> + 1 segment files,
- the unneeded segment files will be deleted instead of recycled until the
- system gets back under this limit.
+ There will be at least one 16 MB segment file, and will normally
+ not be more than 2 * <varname>checkpoint_segments</varname> + 1
+ files. You can use this to estimate space requirements for WAL.
+ Ordinarily, when old log segment files are no longer needed, they
+ are recycled (renamed to become the next segments in the numbered
+ sequence). If, due to a short-term peak of log output rate, there
+ are more than 2 * <varname>checkpoint_segments</varname> + 1
+ segment files, the unneeded segment files will be deleted instead
+ of recycled until the system gets back under this limit.
</para>
<para>
@@ -282,7 +192,7 @@
to write (move to kernel cache) a few filled <acronym>WAL</acronym>
buffers. This is undesirable because <function>LogInsert</function>
is used on every database low level modification (for example,
- tuple insertion) at a time when an exclusive lock is held on
+ row insertion) at a time when an exclusive lock is held on
affected data pages, so the operation needs to be as fast as
possible. What is worse, writing <acronym>WAL</acronym> buffers may
also force the creation of a new log segment, which takes even more
@@ -294,8 +204,8 @@
not occur often enough to prevent <acronym>WAL</acronym> buffers
being written by <function>LogInsert</function>. On such systems
one should increase the number of <acronym>WAL</acronym> buffers by
- modifying the <filename>postgresql.conf</filename> <varname>
- WAL_BUFFERS</varname> parameter. The default number of <acronym>
+ modifying the configuration parameter <varname>wal_buffers</varname>.
+ The default number of <acronym>
WAL</acronym> buffers is 8. Increasing this value will
correspondingly increase shared memory usage.
</para>
@@ -305,47 +215,122 @@
buffers to disk using the operating system <literal>sync()</> call.
Busy servers may fill checkpoint segment files too quickly,
causing excessive checkpointing. If such forced checkpoints happen
- more frequently than <varname>CHECKPOINT_WARNING</varname> seconds,
+ more frequently than <varname>checkpoint_warning</varname> seconds,
a message, will be output to the server logs recommending increasing
- <varname>CHECKPOINT_SEGMENTS</varname>.
+ <varname>checkpoint_segments</varname>.
</para>
<para>
- The <varname>COMMIT_DELAY</varname> parameter defines for how many
- microseconds the backend will sleep after writing a commit
+ The <varname>commit_delay</varname> parameter defines for how many
+ microseconds the server process will sleep after writing a commit
record to the log with <function>LogInsert</function> but before
performing a <function>LogFlush</function>. This delay allows other
- backends to add their commit records to the log so as to have all
+ server processes to add their commit records to the log so as to have all
of them flushed with a single log sync. No sleep will occur if <varname>fsync</varname>
- is not enabled or if fewer than <varname>COMMIT_SIBLINGS</varname>
- other backends are not currently in active transactions; this avoids
- sleeping when it's unlikely that any other backend will commit soon.
+ is not enabled or if fewer than <varname>commit_siblings</varname>
+ other sessons are currently in active transactions; this avoids
+ sleeping when it's unlikely that any other session will commit soon.
Note that on most platforms, the resolution of a sleep request is
- ten milliseconds, so that any nonzero <varname>COMMIT_DELAY</varname>
- setting between 1 and 10000 microseconds will have the same effect.
+ ten milliseconds, so that any nonzero <varname>commit_delay</varname>
+ setting between 1 and 10000 microseconds would have the same effect.
Good values for these parameters are not yet clear; experimentation
is encouraged.
</para>
<para>
- The <varname>WAL_SYNC_METHOD</varname> parameter determines how
+ The <varname>wal_sync_method</varname> parameter determines how
<productname>PostgreSQL</productname> will ask the kernel to force
WAL updates out to disk.
All the options should be the same as far as reliability goes,
but it's quite platform-specific which one will be the fastest.
- Note that this parameter is irrelevant if <varname>FSYNC</varname>
+ Note that this parameter is irrelevant if <varname>fsync</varname>
has been turned off.
</para>
<para>
- Setting the <varname>WAL_DEBUG</varname> parameter to any nonzero
+ Setting the <varname>wal_debug</varname> parameter to any nonzero
value will result in each <function>LogInsert</function> and
<function>LogFlush</function> <acronym>WAL</acronym> call being
- logged to standard error. At present, it makes no difference what
+ logged to the server log. At present, it makes no difference what
the nonzero value is. This option may be replaced by a more
general mechanism in the future.
</para>
</sect1>
+
+ <sect1 id="wal-internals">
+ <title>Internals</title>
+
+ <para>
+ <acronym>WAL</acronym> is automatically enabled; no action is
+ required from the administrator except ensuring that the additional
+ disk-space requirements of the <acronym>WAL</acronym> logs are met,
+ and that any necessary tuning is done (see <xref
+ linkend="wal-configuration">).
+ </para>
+
+ <para>
+ <acronym>WAL</acronym> logs are stored in the directory
+ <filename>pg_xlog</filename> under the data directory, as a set of
+ segment files, each 16 MB in size. Each segment is divided into 8
+ kB pages. The log record headers are described in
+ <filename>access/xlog.h</filename>; the record content is dependent
+ on the type of event that is being logged. Segment files are given
+ ever-increasing numbers as names, starting at
+ <filename>0000000000000000</filename>. The numbers do not wrap, at
+ present, but it should take a very long time to exhaust the
+ available stock of numbers.
+ </para>
+
+ <para>
+ The <acronym>WAL</acronym> buffers and control structure are in
+ shared memory and are handled by the server child processes; they
+ are protected by lightweight locks. The demand on shared memory is
+ dependent on the number of buffers. The default size of the
+ <acronym>WAL</acronym> buffers is 8 buffers of 8 kB each, or 64 kB
+ total.
+ </para>
+
+ <para>
+ It is of advantage if the log is located on another disk than the
+ main database files. This may be achieved by moving the directory
+ <filename>pg_xlog</filename> to another location (while the server
+ is shut down, of course) and creating a symbolic link from the
+ original location in the main data directory to the new location.
+ </para>
+
+ <para>
+ The aim of <acronym>WAL</acronym>, to ensure that the log is
+ written before database records are altered, may be subverted by
+ disk drives that falsely report a successful write to the kernel,
+ when, in fact, they have only cached the data and not yet stored it
+ on the disk. A power failure in such a situation may still lead to
+ irrecoverable data corruption. Administrators should try to ensure
+ that disks holding <productname>PostgreSQL</productname>'s
+ <acronym>WAL</acronym> log files do not make such false reports.
+ </para>
+
+ <para>
+ After a checkpoint has been made and the log flushed, the
+ checkpoint's position is saved in the file
+ <filename>pg_control</filename>. Therefore, when recovery is to be
+ done, the server first reads <filename>pg_control</filename> and
+ then the checkpoint record; then it performs the REDO operation by
+ scanning forward from the log position indicated in the checkpoint
+ record. Because the entire content of data pages is saved in the
+ log on the first page modification after a checkpoint, all pages
+ changed since the checkpoint will be restored to a consistent
+ state.
+ </para>
+
+ <para>
+ Using <filename>pg_control</filename> to get the checkpoint
+ position speeds up the recovery process, but to handle possible
+ corruption of <filename>pg_control</filename>, we should actually
+ implement the reading of existing log segments in reverse order --
+ newest to oldest -- in order to find the last checkpoint. This has
+ not been implemented, yet.
+ </para>
+ </sect1>
</chapter>
<!-- Keep this comment at the end of the file
--
GitLab