Skip to content

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

Another big editing pass for consistent content and presentation.

parent e27334f4
Hide whitespace changes
Inline Side-by-side
Showing with 1321 additions and 2427 deletions
doc/src/sgml/backup.sgml
View file @ d258ba01
<!--
$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> &lt; <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> &lt; <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 &gt; <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
......
doc/src/sgml/charset.sgml
View file @ d258ba01
<!-- $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>
......
doc/src/sgml/diskusage.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/func.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/install-win32.sgml
View file @ d258ba01
......@@ -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>
......
doc/src/sgml/maintenance.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/monitoring.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/clusterdb.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/createdb.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/createlang.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/createuser.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/current_date.sgml deleted 100644 → 0
View file @ e27334f4
<!--
$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:
-->
doc/src/sgml/ref/current_time.sgml deleted 100644 → 0
View file @ e27334f4
<!--
$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:
-->
doc/src/sgml/ref/current_timestamp.sgml deleted 100644 → 0
View file @ e27334f4
<!--
$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:
-->
doc/src/sgml/ref/current_user.sgml deleted 100644 → 0
View file @ e27334f4
<!--
$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:
-->
doc/src/sgml/ref/dropdb.sgml
View file @ d258ba01
<!--
$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.
......
doc/src/sgml/ref/droplang.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/dropuser.sgml
View file @ d258ba01
<!--
$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.
......
doc/src/sgml/ref/ecpg-ref.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/initdb.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/initlocation.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/ipcclean.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/pg_config-ref.sgml
View file @ d258ba01
<!-- $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>
......
doc/src/sgml/ref/pg_controldata.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/pg_ctl-ref.sgml
View file @ d258ba01
<!--
$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
......
doc/src/sgml/ref/pg_dump.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/pg_dumpall.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/pg_resetxlog.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/pg_restore.sgml
View file @ d258ba01
<!-- $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 &gt; 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>
......
doc/src/sgml/ref/pgtclsh.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/pgtksh.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/postgres-ref.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/postmaster.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/ref/psql-ref.sgml
View file @ d258ba01
<!--
$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>&gt;</quote>.</para></listitem>
<literal>#</literal>, otherwise a <literal>&gt;</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=>
......
doc/src/sgml/ref/vacuumdb.sgml
View file @ d258ba01
<!--
$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>
......
doc/src/sgml/reference.sgml
View file @ d258ba01
<!-- 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>
&currentDate;
&currentTime;
&currentTimestamp;
&currentUser;
</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;
......
doc/src/sgml/runtime.sgml
View file @ d258ba01
<!--
$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 &gt; logfile 2&gt;&amp;1 &amp;</userinput>
......@@ -201,29 +195,26 @@ $ <userinput>postmaster -D /usr/local/pgsql/data &gt; logfile 2&gt;&amp;1 &amp;<
</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>
=&gt; <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>&gt;= 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>&gt;= 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>&gt;= 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>
......
doc/src/sgml/wal.sgml
View file @ d258ba01
<!-- $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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment