rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Another big editing pass for consistent content and presentation.

This commit is contained in:
Peter Eisentraut 2003-03-24 14:32:51 +00:00
parent e27334f405
commit d258ba01ec
38 changed files with 1321 additions and 2427 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/src/sgml/backup.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.25 2003/03/18 00:02:11 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.26 2003/03/24 14:32:50 petere Exp $
--> -->
<chapter id="backup"> <chapter id="backup">
<title>Backup and Restore</title> <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 <application>psql</> (e.g., with <literal>createdb -T template0
<replaceable class="parameter">dbname</></literal>). <replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</> <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. its reference page for more information.
</para> </para>
@ -135,7 +135,7 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
<para> <para>
The ability of <application>pg_dump</> and <application>psql</> to The ability of <application>pg_dump</> and <application>psql</> to
write to or read from pipes makes it possible to dump a database 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> <programlisting>
pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</> pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</>
</programlisting> </programlisting>
@ -179,27 +179,19 @@ pg_dumpall &gt; <replaceable>outfile</>
<sect2 id="backup-dump-large"> <sect2 id="backup-dump-large">
<title>Large Databases</title> <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> <para>
Since <productname>PostgreSQL</productname> allows tables larger Since <productname>PostgreSQL</productname> allows tables larger
than the maximum file size on your system, it can be problematic 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 be larger than the maximum size allowed by your system. As
<application>pg_dump</> writes to the standard output, you can <application>pg_dump</> can write to the standard output, you can
just use standard *nix tools to work around this possible problem. just use standard Unix tools to work around this possible problem.
</para> </para>
<formalpara> <formalpara>
<title>Use compressed dumps.</title> <title>Use compressed dumps.</title>
<para> <para>
Use your favorite compression program, for example You can use your favorite compression program, for example
<application>gzip</application>. <application>gzip</application>.
<programlisting> <programlisting>
@ -222,9 +214,10 @@ cat <replaceable class="parameter">filename</replaceable>.gz | gunzip | psql <re
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>Use <application>split</>.</title> <title>Use <command>split</>.</title>
<para> <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 acceptable in size to the underlying file system. For example, to
make chunks of 1 megabyte: make chunks of 1 megabyte:
@ -338,7 +331,7 @@ tar -cf backup.tar /usr/local/pgsql/data
<listitem> <listitem>
<para> <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 may be tempted to try to back up or restore only certain
individual tables or databases from their respective files or individual tables or databases from their respective files or
directories. This will <emphasis>not</> work because the 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 all transactions. A table file is only usable with this
information. Of course it is also impossible to restore only a information. Of course it is also impossible to restore only a
table and the associated <filename>pg_clog</filename> data 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. cluster useless.
</para> </para>
</listitem> </listitem>
@ -381,7 +374,7 @@ tar -cf backup.tar /usr/local/pgsql/data
server, using <application>pg_dump</>. (There are checks in place server, using <application>pg_dump</>. (There are checks in place
that prevent you from doing the wrong thing, so no harm can be done that prevent you from doing the wrong thing, so no harm can be done
by confusing these things.) The precise installation procedure is 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>
<para> <para>
@ -393,7 +386,7 @@ tar -cf backup.tar /usr/local/pgsql/data
pg_dumpall -p 5432 | psql -d template1 -p 6543 pg_dumpall -p 5432 | psql -d template1 -p 6543
</programlisting> </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 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 the port the old one was running at. You should make sure that the
database is not updated after you run <application>pg_dumpall</>, 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_dumpall > backup
pg_ctl stop pg_ctl stop
mv /usr/local/pgsql /usr/local/pgsql.old mv /usr/local/pgsql /usr/local/pgsql.old
cd /usr/src/postgresql-&version; cd ~/postgresql-&version;
gmake install gmake install
initdb -D /usr/local/pgsql/data initdb -D /usr/local/pgsql/data
postmaster -D /usr/local/pgsql/data postmaster -D /usr/local/pgsql/data

579
doc/src/sgml/charset.sgml
View File

@ -1,18 +1,13 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.32 2003/03/13 01:30:26 petere Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.33 2003/03/24 14:32:50 petere Exp $ -->
<chapter id="charset"> <chapter id="charset">
<title>Localization</> <title>Localization</>
<abstract> <para>
<para> This chapter describes the available localization features from the
Describes the available localization features from the point of point of view of the administrator.
view of the administrator. <productname>PostgreSQL</productname> supports localization with
</para> three approaches:
</abstract>
<para>
<productname>PostgreSQL</productname> supports localization with
three approaches:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -25,20 +20,17 @@
<listitem> <listitem>
<para> <para>
Using explicit multiple-byte character sets defined in the Providing a number of different character sets defined in the
<productname>PostgreSQL</productname> server to support languages <productname>PostgreSQL</productname> server, including
that require more characters than will fit into a single byte, multiple-byte character sets, to support storing text in all
and to provide character set recoding between client and server. kinds of languages, and providing character set recoding between
The number of supported character sets is fixed at the time the client and server.
server is compiled, and internal operations such as string
comparisons require expansion of each character into a 32-bit
word.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <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. solution for users of multiple, yet single-byte character sets.
</para> </para>
</listitem> </listitem>
@ -55,7 +47,7 @@
<firstterm>Locale</> support refers to an application respecting <firstterm>Locale</> support refers to an application respecting
cultural preferences regarding alphabets, sorting, number cultural preferences regarding alphabets, sorting, number
formatting, etc. <productname>PostgreSQL</> uses the standard ISO 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. For additional information refer to the documentation of your
system. system.
</para> </para>
@ -92,7 +84,7 @@ initdb --locale=sv_SE
<para> <para>
Occasionally it is useful to mix rules from several locales, e.g., 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 set of locale subcategories exist that control only a certain
aspect of the localization rules. aspect of the localization rules.
@ -154,7 +146,7 @@ initdb --locale=sv_SE
<para> <para>
The other locale categories can be changed as desired whenever the 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 that have the same name as the locale categories (see <xref
linkend="runtime-config"> for details). The defaults that are linkend="runtime-config"> for details). The defaults that are
chosen by <command>initdb</command> are actually only written into 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 variable <envar>LANGUAGE</envar> which overrides all other locale
settings for the purpose of setting the language of messages. If settings for the purpose of setting the language of messages. If
in doubt, please refer to the documentation of your operating in doubt, please refer to the documentation of your operating
system, in particular the system, in particular the documentation about
<citerefentry><refentrytitle>gettext</><manvolnum>3</></> manual <application>gettext</>, for more information.
page, for more information.
</para> </para>
</note> </note>
<para> <para>
To enable messages translated to the user's preferred language, To enable messages translated to the user's preferred language,
the <option>--enable-nls</option> option must be used. This <acronym>NLS</acronym> must have been enabled at build time. This
option is independent of the other locale support. choice is independent of the other locale support.
</para> </para>
</sect2> </sect2>
@ -212,7 +203,7 @@ initdb --locale=sv_SE
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Sort order in <command>ORDER BY</> queries. Sort order in queries using <command>ORDER BY</>
<indexterm><primary>ORDER BY</></> <indexterm><primary>ORDER BY</></>
</para> </para>
</listitem> </listitem>
@ -234,7 +225,7 @@ initdb --locale=sv_SE
<para> <para>
The only severe drawback of using the locale support in 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 actually need it. It should be noted in particular that selecting
a non-C locale disables index optimizations for <literal>LIKE</> and a non-C locale disables index optimizations for <literal>LIKE</> and
<literal>~</> operators, which can make a huge difference in the <literal>~</> operators, which can make a huge difference in the
@ -247,49 +238,28 @@ initdb --locale=sv_SE
<para> <para>
If locale support doesn't work in spite of the explanation above, If locale support doesn't work in spite of the explanation above,
check that the locale support in your operating system is correctly configured. check that the locale support in your operating system is
To check whether a given locale is installed and functional you correctly configured. To check what locales are installed on your
can use <application>Perl</>, for example. Perl has also support system, you may use the command <literal>locale -a</literal> if
for locales and if a locale is broken <command>perl -v</> will your operating system provides it.
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>
</para> </para>
<para> <para>
Check that your locale files are in the right location. Possible Check that <productname>PostgreSQL</> is actually using the locale
locations include: <filename>/usr/lib/locale</filename> (<systemitem class="osname">Linux</>, that you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
<systemitem class="osname">Solaris</>), <filename>/usr/share/locale</filename> (<systemitem class="osname">Linux</>), settings are determined at <command>initdb</> time and cannot be
<filename>/usr/lib/nls/loc</filename> (<systemitem class="osname">DUX 4.0</>). Check the locale changed without repeating <command>initdb</>. Other locale
man page of your system if you are not sure. 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>
<para> <para>
Check that <productname>PostgreSQL</> is actually using the locale that The directory <filename>src/test/locale</> in the source
you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</> settings are distribution contains a test suite for
determined at <application>initdb</> time and cannot be changed without <productname>PostgreSQL</>'s locale support.
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.
</para> </para>
<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 text of the error message will obviously have problems when the
server's messages are in a different language. If you create such server's messages are in a different language. If you create such
an application you need to devise a plan to cope with this 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 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. configured to send messages in English.
</para> </para>
@ -316,58 +286,41 @@ perl: warning: Falling back to the standard locale ("C").
</sect1> </sect1>
<sect1 id="multibyte"> <sect1 id="multibyte">
<title>Multibyte Support</title> <title>Character Set Support</title>
<indexterm zone="multibyte"><primary>multibyte</></> <indexterm zone="multibyte"><primary>character set</></>
<note> <para>
<title>Author</title> The character set support in <productname>PostgreSQL</productname>
allows you to store text in a variety of character sets, including
<para> single-byte character sets such as the ISO 8859 series and
Tatsuo Ishii (<email>ishii@postgresql.org</email>), multiple-byte character sets such as <acronym>EUC</> (Extended Unix
last updated 2002-07-24. Code), Unicode, and Mule internal code. All character sets can be
Check <ulink used transparently throughout the server. (If you use extension
url="http://www.sra.co.jp/people/t-ishii/PostgreSQL/">Tatsuo's functions from other sources, it depends on whether they wrote
web site</ulink> for more information. their code correctly.) The default character set is selected while
</para> initializing your <productname>PostgreSQL</productname> database
</note> cluster using <command>initdb</>. It can be overridden when you
create a database using <command>createdb</command> or by using the
<para> SQL command <command>CREATE DATABASE</>. So you can have multiple
Multibyte (<acronym>MB</acronym>) support is intended to allow databases each with a different character set.
<productname>PostgreSQL</productname> to handle </para>
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>
<para>
Multibyte support is enabled by default since
<productname>PostgreSQL</> version 7.3.
</para>
<sect2> <sect2>
<title>Supported character set encodings</title> <title>Supported Character Sets</title>
<para> <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"> <table id="charset-table">
<title>Character Set Encodings</title> <title>Server Character Sets</title>
<titleabbrev>Encodings</titleabbrev>
<tgroup cols="2"> <tgroup cols="2">
<thead> <thead>
<row> <row>
<entry>Encoding</entry> <entry>Name</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
@ -406,59 +359,59 @@ perl: warning: Falling back to the standard locale ("C").
</row> </row>
<row> <row>
<entry><literal>LATIN1</literal></entry> <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>
<row> <row>
<entry><literal>LATIN2</literal></entry> <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>
<row> <row>
<entry><literal>LATIN3</literal></entry> <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>
<row> <row>
<entry><literal>LATIN4</literal></entry> <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>
<row> <row>
<entry><literal>LATIN5</literal></entry> <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>
<row> <row>
<entry><literal>LATIN6</literal></entry> <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>
<row> <row>
<entry><literal>LATIN7</literal></entry> <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>
<row> <row>
<entry><literal>LATIN8</literal></entry> <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>
<row> <row>
<entry><literal>LATIN9</literal></entry> <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>
<row> <row>
<entry><literal>LATIN10</literal></entry> <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>
<row> <row>
<entry><literal>ISO-8859-5</literal></entry> <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>
<row> <row>
<entry><literal>ISO-8859-6</literal></entry> <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>
<row> <row>
<entry><literal>ISO-8859-7</literal></entry> <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>
<row> <row>
<entry><literal>ISO-8859-8</literal></entry> <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>
<row> <row>
<entry><literal>KOI8</literal></entry> <entry><literal>KOI8</literal></entry>
@ -474,78 +427,76 @@ perl: warning: Falling back to the standard locale ("C").
</row> </row>
<row> <row>
<entry><literal>WIN1256</literal></entry> <entry><literal>WIN1256</literal></entry>
<entry>Arabic Windows CP1256</entry> <entry>Windows CP1256 (Arabic)</entry>
</row> </row>
<row> <row>
<entry><literal>TCVN</literal></entry> <entry><literal>TCVN</literal></entry>
<entry>Vietnamese <acronym>TCVN</>-5712 (Windows CP1258)</entry> <entry><acronym>TCVN</>-5712/Windows CP1258 (Vietnamese)</entry>
</row> </row>
<row> <row>
<entry><literal>WIN874</literal></entry> <entry><literal>WIN874</literal></entry>
<entry>Thai Windows CP874</entry> <entry>Windows CP874 (Thai)</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
</para>
<important> <important>
<para> <para>
Before <productname>PostgreSQL</>7.2, <literal>LATIN5</> mistakenly Before <productname>PostgreSQL</> 7.2, <literal>LATIN5</>
meant ISO 8859-5. From 7.2 on, mistakenly meant ISO 8859-5. From 7.2 on, <literal>LATIN5</>
<literal>LATIN5</> means ISO 8859-9. If you have a <literal>LATIN5</> means ISO 8859-9. If you have a <literal>LATIN5</> database
database created on 7.1 or earlier and want to migrate to 7.2 (or created on 7.1 or earlier and want to migrate to 7.2 or later,
later), you should be very careful about this change. you should be very careful about this change.
</para> </para>
</important> </important>
<important>
<para> <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</> <productname>PostgreSQL</>
JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>, JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>,
<literal>LATIN8</>, and <literal>LATIN10</>. <literal>LATIN8</>, and <literal>LATIN10</>.
</para> </para>
</important>
</sect2> </sect2>
<sect2> <sect2>
<title>Setting the Encoding</title> <title>Setting the Character Set</title>
<para> <para>
<application>initdb</application> defines the default encoding <command>initdb</> defines the default character set
for a <productname>PostgreSQL</productname> installation. For example: for a <productname>PostgreSQL</productname> cluster. For example,
<screen> <screen>
initdb -E EUC_JP initdb -E EUC_JP
</screen> </screen>
sets the default encoding to <literal>EUC_JP</literal> (Extended Unix Code for Japanese). sets the default character set (encoding) to
Note that you can use <option>--encoding</option> instead of <option>-E</option> if you prefer <literal>EUC_JP</literal> (Extended Unix Code for Japanese). You
to type longer option strings. 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 If no <option>-E</> or <option>--encoding</option> option is
given, SQL_ASCII is used. given, <literal>SQL_ASCII</> is used.
</para> </para>
<para> <para>
You can create a database with a different encoding: You can create a database with a different character set:
<screen> <screen>
createdb -E EUC_KR korean createdb -E EUC_KR korean
</screen> </screen>
will create a database named <database>korean</database> with <literal>EUC_KR</literal> encoding. This will create a database named <literal>korean</literal> that
Another way to accomplish this is to use a SQL command: uses the character set <literal>EUC_KR</literal>. Another way to
accomplish this is to use this SQL command:
<programlisting> <programlisting>
CREATE DATABASE korean WITH ENCODING = 'EUC_KR'; CREATE DATABASE korean WITH ENCODING 'EUC_KR';
</programlisting> </programlisting>
The encoding for a database is represented as an The encoding for a database is stored in the system catalog
<firstterm>encoding column</firstterm> in the <literal>pg_database</literal>. You can see that by using the
<literal>pg_database</literal> system catalog. <option>-l</option> option or the <command>\l</command> command
You can see that by using the <option>-l</option> option or the of <command>psql</command>.
<command>\l</command> command of <command>psql</command>.
<screen> <screen>
$ <userinput>psql -l</userinput> $ <userinput>psql -l</userinput>
@ -567,27 +518,26 @@ $ <userinput>psql -l</userinput>
</sect2> </sect2>
<sect2> <sect2>
<title>Automatic encoding conversion between server and <title>Automatic Character Set Conversion Between Server and Client</title>
client</title>
<para> <para>
<productname>PostgreSQL</productname> supports an automatic <productname>PostgreSQL</productname> supports automatic
encoding conversion between server and client for some character set conversion between server and client for certain
encodings. The conversion info is stored in <literal>pg_conversion</> system character sets. The conversion information is stored in the
catalog. You can create a new conversion by using <command>CREATE <literal>pg_conversion</> system catalog. You can create a new
CONVERSION</command>. <productname>PostgreSQL</> comes with some predefined conversion by using the SQL command <command>CREATE
conversions. They are listed in <xref CONVERSION</command>. <productname>PostgreSQL</> comes with some
predefined conversions. They are listed in <xref
linkend="multibyte-translation-table">. linkend="multibyte-translation-table">.
</para> </para>
<table tocentry="1" id="multibyte-translation-table"> <table id="multibyte-translation-table">
<title>Client/Server Character Set Encodings</title> <title>Client/Server Character Set Conversions</title>
<titleabbrev>Communication Encodings</titleabbrev>
<tgroup cols="2"> <tgroup cols="2">
<thead> <thead>
<row> <row>
<entry>Server Encoding</entry> <entry>Server Character Set</entry>
<entry>Available Client Encodings</entry> <entry>Available Client Character Sets</entry>
</row> </row>
</thead> </thead>
<tbody> <tbody>
@ -784,10 +734,10 @@ $ <userinput>psql -l</userinput>
</table> </table>
<para> <para>
To enable the automatic encoding translation, you have to tell To enable the automatic character set conversion, you have to
<productname>PostgreSQL</productname> the encoding you would like tell <productname>PostgreSQL</productname> the character set
to use in the client. There are (encoding) you would like to use in the client. There are several
several ways to accomplish this. ways to accomplish this:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -811,17 +761,17 @@ $ <userinput>psql -l</userinput>
<function>PQsetClientEncoding()</function> for its purpose. <function>PQsetClientEncoding()</function> for its purpose.
<synopsis> <synopsis>
int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>) int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
</synopsis> </synopsis>
where <replaceable>conn</replaceable> is a connection to the server, where <replaceable>conn</replaceable> is a connection to the server,
and <replaceable>encoding</replaceable> is an encoding you and <replaceable>encoding</replaceable> is the encoding you
want to use. If it successfully sets the encoding, it returns 0, want to use. If the function successfully sets the encoding, it returns 0,
otherwise -1. The current encoding for this connection can be shown by otherwise -1. The current encoding for this connection can be determined by
using: using:
<synopsis> <synopsis>
int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>) int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
</synopsis> </synopsis>
Note that it returns the encoding ID, not a symbolic string Note that it returns the encoding ID, not a symbolic string
@ -829,7 +779,7 @@ int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
can use: can use:
<synopsis> <synopsis>
char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>) char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
</synopsis> </synopsis>
</para> </para>
</listitem> </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: Setting the client encoding can be done with this SQL command:
<programlisting> <programlisting>
SET CLIENT_ENCODING TO 'encoding'; SET CLIENT_ENCODING TO '<replaceable>value</>';
</programlisting> </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> <programlisting>
SET NAMES 'encoding'; SET NAMES '<replaceable>value</>';
</programlisting> </programlisting>
To query the current client encoding: To query the current client encoding:
@ -877,7 +827,7 @@ RESET CLIENT_ENCODING;
<listitem> <listitem>
<para> <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 If the <varname>client_encoding</> variable in <filename>postgresql.conf</> is set, that
client encoding is automatically selected when a connection to the client encoding is automatically selected when a connection to the
@ -888,26 +838,19 @@ RESET CLIENT_ENCODING;
</itemizedlist> </itemizedlist>
</para> </para>
</sect2>
<sect2>
<title>What happens if the translation is not possible?</title>
<para> <para>
Suppose you choose <literal>EUC_JP</literal> for the server If the conversion of a particular character is not possible --
and <literal>LATIN1</literal> for the client, suppose you chose <literal>EUC_JP</literal> for the server and
then some Japanese characters cannot be translated into <literal>LATIN1</literal>. In <literal>LATIN1</literal> for the client, then some Japanese
this case, a letter that cannot be represented in the <literal>LATIN1</literal> character set characters cannot be converted to <literal>LATIN1</literal> -- it
would be transformed as: is transformed to its hexadecimal byte values in parentheses,
e.g., <literal>(826C)</literal>.
<synopsis>
(HEXA DECIMAL)
</synopsis>
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>References</title> <title>Further Reading</title>
<para> <para>
These are good sources to start learning about various kinds of encoding These are good sources to start learning about various kinds of encoding
@ -949,209 +892,11 @@ RESET CLIENT_ENCODING;
</para> </para>
</sect2> </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>
<sect1 id="recode"> <sect1 id="recode">
<title>Single-byte character set recoding</> <title>Single-Byte Character Set Recoding</>
<!-- formerly in README.charsets, by Josef Balatka, <balatka@email.cz> -->
<para> <para>
You can set up this feature with the <option>--enable-recode</> option You can set up this feature with the <option>--enable-recode</> option
@ -1163,57 +908,57 @@ SET CLIENT_ENCODING = 'WIN1250';
<para> <para>
This method uses a file <filename>charset.conf</> file located in This method uses a file <filename>charset.conf</> file located in
the database directory (<envar>PGDATA</>). It's a typical the data directory for configuration. It's a typical
configuration text file where spaces and newlines separate items configuration text file where spaces and newlines separate fields
and records and # specifies comments. Three keywords with the and records and <literal>#</> starts a comment. Three key words with the
following syntax are recognized here: following syntax are recognized here:
<synopsis> <synopsis>
BaseCharset <replaceable>server_charset</> BaseCharset <replaceable>server_charset</>
RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</> RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
HostCharset <replaceable>host_spec</> <replaceable>host_charset</> HostCharset <replaceable>host_spec</> <replaceable>host_charset</>
</synopsis> </synopsis>
</para> </para>
<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 All character set names are only used for mapping inside of
<filename>charset.conf</> so you can freely use typing-friendly <filename>charset.conf</> so you can freely use typing-friendly
names. names.
</para> </para>
<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 server and client. The file name is relative to the
<envar>PGDATA</> directory. The table file format is very data directory. The table file format is very
simple. There are no keywords and characters are represented by a simple. There are no key words, and character mappings are represented by a
pair of decimal or hexadecimal (0x prefixed) values on single pair of decimal or hexadecimal (prefixed by <literal>0x</>) values on single
lines: lines:
<synopsis> <synopsis>
<replaceable>char_value</> <replaceable>translated_char_value</> <replaceable>char_value</> <replaceable>converted_char_value</>
</synopsis> </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>
<para> <para>
<token>HostCharset</> records define the client character set by IP <token>HostCharset</> records define the client character set by IP
address. You can use a single IP address, an IP mask range starting 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, from the given address or an IP interval (e.g., <literal>127.0.0.1</>,
192.168.1.100/24, 192.168.1.20-192.168.1.40). <literal>192.168.1.100/24</>, <literal>192.168.1.20-192.168.1.40</>).
</para> </para>
<para> <para>
The <filename>charset.conf</> file is always processed up to the The <filename>charset.conf</> file is always processed to the
end, so you can easily specify exceptions from the previous end, so you can easily specify exceptions from preceding rules.
rules. In the <filename>src/data/</> directory you will find an
example <filename>charset.conf</> and a few recoding tables.
</para> </para>
<para> <para>
As this solution is based on the client's IP address and character As this solution is based on the client's IP address there are
set mapping there are obviously some restrictions as well. You obviously some restrictions as well. You cannot use different
cannot use different encodings on the same host at the same character sets on the same host at the same time. It is also
time. It is also inconvenient when you boot your client hosts into inconvenient when you boot your client hosts into multiple
multiple operating systems. Nevertheless, when these restrictions are operating systems. Nevertheless, when these restrictions are not
not limiting and you do not need multibyte characters then it is a limiting and you do not need multibyte characters then it is a
simple and effective solution. simple and effective solution.
</para> </para>
</sect1> </sect1>

67
doc/src/sgml/diskusage.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.8 2002/11/15 03:11:16 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/diskusage.sgml,v 1.9 2003/03/24 14:32:50 petere Exp $
--> -->
<chapter id="diskusage"> <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> <para>
You can monitor disk space from three places: from You can monitor disk space from three places: from
<application>psql</> using <command>VACUUM</> information, from <application>psql</> using <command>VACUUM</> information, from
<application>psql</> using <filename>contrib/dbsize</>, and from <application>psql</> using the tools in <filename>contrib/dbsize</>, and from
the command line using <application>contrib/oid2name</>. Using the command line using the tools in <filename>contrib/oid2name</>. Using
<application>psql</> on a recently vacuumed (or analyzed) database, <application>psql</> on a recently vacuumed or analyzed database,
you can issue queries to see the disk usage of any table: you can issue queries to see the disk usage of any table:
<programlisting> <programlisting>
play=# SELECT relfilenode, relpages SELECT relfilenode, relpages FROM pg_class WHERE relname = 'customer';
play-# FROM pg_class
play-# WHERE relname = 'customer';
relfilenode | relpages relfilenode | relpages
-------------+---------- -------------+----------
16806 | 60 16806 | 60
(1 row) (1 row)
</programlisting> </programlisting>
Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
is only updated by <command>VACUUM</> and <command>ANALYZE</>.)
</para> </para>
<para> <para>
Each page is typically 8 kilobytes. (Remember, <literal>relpages</> To show the space used by <acronym>TOAST</> tables, use a query
is only updated by <command>VACUUM</> and <command>ANALYZE</>.) To like the following, substituting the <literal>relfilenode</literal>
show the space used by <acronym>TOAST</> tables, use a query based on number of the heap (determined by the query above):
the heap relfilenode shown above:
<programlisting> <programlisting>
play=# SELECT relname, relpages SELECT relname, relpages
play-# FROM pg_class FROM pg_class
play-# WHERE relname = 'pg_toast_16806' OR WHERE relname = 'pg_toast_16806' OR relname = 'pg_toast_16806_index'
play-# relname = 'pg_toast_16806_index' ORDER BY relname;
play-# ORDER BY relname;
relname | relpages relname | relpages
----------------------+---------- ----------------------+----------
pg_toast_16806 | 0 pg_toast_16806 | 0
@ -67,14 +67,15 @@ play-# ORDER BY relname;
</para> </para>
<para> <para>
You can easily display index usage too: You can easily display index sizes, too:
<programlisting> <programlisting>
play=# SELECT c2.relname, c2.relpages SELECT c2.relname, c2.relpages
play-# FROM pg_class c, pg_class c2, pg_index i FROM pg_class c, pg_class c2, pg_index i
play-# WHERE c.relname = 'customer' AND WHERE c.relname = 'customer'
play-# c.oid = i.indrelid AND AND c.oid = i.indrelid
play-# c2.oid = i.indexrelid AND c2.oid = i.indexrelid
play-# ORDER BY c2.relname; ORDER BY c2.relname;
relname | relpages relname | relpages
----------------------+---------- ----------------------+----------
customer_id_indexdex | 26 customer_id_indexdex | 26
@ -82,11 +83,11 @@ play-# ORDER BY c2.relname;
</para> </para>
<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> <programlisting>
play=# SELECT relname, relpages SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
play-# FROM pg_class
play-# ORDER BY relpages DESC;
relname | relpages relname | relpages
----------------------+---------- ----------------------+----------
bigtable | 3290 bigtable | 3290
@ -97,12 +98,12 @@ play-# ORDER BY relpages DESC;
<para> <para>
<filename>contrib/dbsize</> loads functions into your database that allow <filename>contrib/dbsize</> loads functions into your database that allow
you to find the size of a table or database from inside 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>
<para> <para>
You can also use <filename>contrib/oid2name</> to show disk usage. See 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. shows disk usage for each database.
</para> </para>
</sect1> </sect1>
@ -114,7 +115,7 @@ play-# ORDER BY relpages DESC;
The most important disk monitoring task of a database administrator 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 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 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 is the case for a default configuration) then a filled disk during
database initialization may result in corrupted or incomplete WAL database initialization may result in corrupted or incomplete WAL
files. This failure condition is detected and the database server 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 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 one place. To avoid running out of disk space, you can place the
WAL files or individual databases in other locations while creating WAL files or individual databases in other locations while creating
them. See the <application>initdb</> documentation and <xref them. See the <command>initdb</> documentation and <xref
linkend="manage-ag-alternate-locs"> for more information. linkend="manage-ag-alternate-locs"> for more information about that.
</para> </para>
<tip> <tip>

6
doc/src/sgml/func.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.146 2003/03/21 21:54:29 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.147 2003/03/24 14:32:50 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -5900,7 +5900,7 @@ SELECT TIMESTAMP 'now';
<entry><literal>255.255.255.0</literal></entry> <entry><literal>255.255.255.0</literal></entry>
</row> </row>
<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><type>inet</type></entry>
<entry>construct hostmask for network</entry> <entry>construct hostmask for network</entry>
<entry><literal>hostmask('192.168.23.20/30')</literal></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"> <indexterm zone="functions-misc">
<primary>configuration</primary> <primary>configuration</primary>
<secondary>run time</secondary> <secondary>server</secondary>
</indexterm> </indexterm>
<para> <para>

4
doc/src/sgml/install-win32.sgml
View File

@ -54,7 +54,7 @@
<term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term> <term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term>
<listitem> <listitem>
<para> <para>
Import library to link your program to <filename>libpq.dll</filename> Import library to link your programs to <filename>libpq.dll</filename>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -98,7 +98,7 @@
</para> </para>
<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 <filename>libpqdll.lib</filename> file to your project. (In Visual
C++, just right-click on the project and choose to add it.) C++, just right-click on the project and choose to add it.)
</para> </para>

75
doc/src/sgml/maintenance.sgml
View File

@ -1,17 +1,14 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.21 2003/03/24 14:32:50 petere Exp $
--> -->
<chapter id="maintenance"> <chapter id="maintenance">
<title>Routine Database Maintenance Tasks</title> <title>Routine Database Maintenance Tasks</title>
<sect1 id="maintenance-general">
<title>General Discussion</Title>
<para> <para>
There are a few routine maintenance chores that must be performed on There are a few routine maintenance chores that must be performed on
a regular basis to keep a <productname>PostgreSQL</productname> 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 in nature and can easily be automated using standard Unix tools such
as <application>cron</application> scripts. But it is the database as <application>cron</application> scripts. But it is the database
administrator's responsibility to set up appropriate scripts, and to 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 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 regular schedule. Without a recent backup, you have no chance of recovery
after a catastrophe (disk failure, fire, mistakenly dropping a critical 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 <productname>PostgreSQL</productname> are discussed at length in
<xref linkend="backup">. <xref linkend="backup">.
</para> </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. experience with the system.
</para> </para>
</sect1>
<sect1 id="routine-vacuuming"> <sect1 id="routine-vacuuming">
<title>Routine Vacuuming</title> <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> </listitem>
</orderedlist> </orderedlist>
The frequency and scope of <command>VACUUM</>s performed for each of The frequency and scope of the <command>VACUUM</> operations performed for each of
these reasons will vary depending on the needs of each installation. these reasons will vary depending on the needs of each site.
Therefore, database administrators must understand these issues and Therefore, database administrators must understand these issues and
develop an appropriate maintenance strategy. This section concentrates develop an appropriate maintenance strategy. This section concentrates
on explaining the high-level issues; for details about command syntax 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> <para>
Beginning in <productname>PostgreSQL</productname> 7.2, the standard form Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
of <command>VACUUM</> can run in parallel with normal database operations 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 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 releases, and it's not as critical to try to schedule it at low-usage
times of day. 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 return disk space to the operating system. If you need to return disk
space to the operating system you can use <command>VACUUM FULL</> --- 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 but what's the point of releasing disk space that will only have to be
allocated again soon? Moderately frequent standard <command>VACUUM</>s allocated again soon? Moderately frequent standard <command>VACUUM</> runs
are a better approach than infrequent <command>VACUUM FULL</>s for are a better approach than infrequent <command>VACUUM FULL</> runs for
maintaining heavily-updated tables. maintaining heavily-updated tables.
</para> </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 Recommended practice for most sites is to schedule a database-wide
<command>VACUUM</> once a day at a low-usage time of day, supplemented <command>VACUUM</> once a day at a low-usage time of day, supplemented
by more frequent vacuuming of heavily-updated tables if necessary. 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.) vacuum each one; the <filename>vacuumdb</> script may be helpful.)
Use plain <command>VACUUM</>, not <command>VACUUM FULL</>, for routine Use plain <command>VACUUM</>, not <command>VACUUM FULL</>, for routine
vacuuming for space recovery. 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> <para>
<productname>PostgreSQL</productname>'s MVCC transaction semantics <productname>PostgreSQL</productname>'s MVCC transaction semantics
depend on being able to compare transaction ID (<firstterm>XID</>) depend on being able to compare transaction ID (<acronym>XID</>)
numbers: a tuple with an insertion XID newer than the current numbers: a tuple with an insertion XID greater than the current
transaction's XID is <quote>in the future</> and should not be visible transaction's XID is <quote>in the future</> and should not be visible
to the current transaction. But since transaction IDs have limited size 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 than 4 billion transactions) will suffer <firstterm>transaction ID
wraparound</>: the XID counter wraps around to zero, and all of a sudden 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 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 against XID wraparound was to re-<command>initdb</> at least every 4
billion transactions. This of course was not very satisfactory for billion transactions. This of course was not very satisfactory for
high-traffic sites, so a better solution has been devised. The new 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 <command>initdb</> or any sort of restart. The price is this
maintenance requirement: <emphasis>every table in the database must maintenance requirement: <emphasis>every table in the database must
be vacuumed at least once every billion transactions</emphasis>. 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</> <command>VACUUM</>'s normal policy is to reassign <literal>FrozenXID</>
to any tuple with a normal XID more than one billion transactions in the 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 past. This policy preserves the original insertion XID until it is not
likely to be of interest anymore (in fact, most tuples will probably likely to be of interest anymore. (In fact, most tuples will probably
live and die without ever being <quote>frozen</>). With this policy, live and die without ever being <quote>frozen</>.) With this policy,
the maximum safe interval between <command>VACUUM</>s of any table the maximum safe interval between <command>VACUUM</> runs on any table
is exactly one billion transactions: if you wait longer, it's possible 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 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 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>
<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 described earlier, it's unlikely that any table would not be vacuumed
for as long as a billion transactions. But to help administrators ensure for as long as a billion transactions. But to help administrators ensure
this constraint is met, <command>VACUUM</> stores transaction ID this constraint is met, <command>VACUUM</> stores transaction ID
statistics in the system table <filename>pg_database</>. In particular, statistics in the system table <literal>pg_database</>. In particular,
the <filename>datfrozenxid</> field of a database's the <literal>datfrozenxid</> column of a database's
<filename>pg_database</> row is updated at the completion of any <literal>pg_database</> row is updated at the completion of any
database-wide vacuum operation (i.e., <command>VACUUM</> that does not database-wide vacuum operation (i.e., <command>VACUUM</> that does not
name a specific table). The value stored in this field is the freeze 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 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, database at least once every half-a-billion (500 million) transactions,
so as to provide plenty of safety margin. To help meet this rule, so as to provide plenty of safety margin. To help meet this rule,
each database-wide <command>VACUUM</> automatically delivers a warning 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: <literal>age</> of more than 1.5 billion transactions, for example:
<programlisting> <programlisting>
play=# vacuum; play=# VACUUM;
WARNING: Some databases have not been vacuumed in 1613770184 transactions. WARNING: Some databases have not been vacuumed in 1613770184 transactions.
Better vacuum them within 533713463 transactions, Better vacuum them within 533713463 transactions,
or you may have a wraparound failure. or you may have a wraparound failure.
@ -355,13 +350,13 @@ VACUUM
database will be frozen. Hence, as long as the database is not database will be frozen. Hence, as long as the database is not
modified in any way, it will not need subsequent vacuuming to avoid modified in any way, it will not need subsequent vacuuming to avoid
transaction ID wraparound problems. This technique is used by 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 It should also be used to prepare any user-created databases that
are to be marked <literal>datallowconn</> = <literal>false</> in 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 vacuum a database that you can't connect to. Note that
<command>VACUUM</command>'s automatic warning message about <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 with <literal>datallowconn</> = <literal>false</>, so as to avoid
giving false warnings about these databases; therefore it's up to giving false warnings about these databases; therefore it's up to
you to ensure that such databases are frozen correctly. you to ensure that such databases are frozen correctly.
@ -415,9 +410,9 @@ VACUUM
</para> </para>
<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 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. want to run a production server that way.
</para> </para>
@ -425,7 +420,7 @@ VACUUM
The simplest production-grade approach to managing log output is to The simplest production-grade approach to managing log output is to
send it all to <application>syslog</> and let send it all to <application>syslog</> and let
<application>syslog</> deal with file rotation. To do this, set <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 <filename>postgresql.conf</>. Then you can send a
<literal>SIGHUP</literal> signal to the <application>syslog</> <literal>SIGHUP</literal> signal to the <application>syslog</>
daemon whenever you want to force it to start writing a new log 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 On many systems, however, <application>syslog</> is not very reliable, particularly
with large log messages; it may truncate or drop messages just when 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 you need them the most. You may find it more useful to pipe the
<application>postmaster</>'s <systemitem>stderr</> to some type of <systemitem>stderr</> of the <command>postmaster</> to some type of
log rotation script. If you start the postmaster with log rotation program. If you start the server with
<application>pg_ctl</>, then the postmaster's <systemitem>stderr</> <command>pg_ctl</>, then the <systemitem>stderr</> of the <command>postmaster</command>
is already redirected to <systemitem>stdout</>, so you just need a is already redirected to <systemitem>stdout</>, so you just need a
pipe command: pipe command:
<screen> <programlisting>
<userinput>pg_ctl start | logrotate</userinput> pg_ctl start | logrotate
</screen> </programlisting>
The <productname>PostgreSQL</> distribution doesn't include a suitable 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. one is included in the Apache distribution, for example.
</para> </para>
</sect1> </sect1>

191
doc/src/sgml/monitoring.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.17 2003/03/20 18:51:16 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v 1.18 2003/03/24 14:32:50 petere Exp $
--> -->
<chapter id="monitoring"> <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> <para>
Several tools are available for monitoring database activity and Several tools are available for monitoring database activity and
analyzing performance. Most of this chapter is devoted to describing 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 but one should not neglect regular Unix monitoring programs such as
<command>ps</> and <command>top</>. Also, once one has identified a <command>ps</> and <command>top</>. Also, once one has identified a
poorly-performing query, further investigation may be needed using 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 (The appropriate invocation of <command>ps</> varies across different
platforms, as do the details of what is shown. This example is from a platforms, as do the details of what is shown. This example is from a
recent Linux system.) The first process listed here is the 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 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 processes implement the statistics collector, which will be described in
detail in the next section. (These will not be present if you have set 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), 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), <literal>idle in transaction</> (waiting for client inside a <command>BEGIN</> block),
or a command type name such as <literal>SELECT</>. Also, 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 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 that process 1003 is waiting for process 1016 to complete its transaction and
thereby release some lock or other. thereby release some lock or other.
@ -77,22 +77,19 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para> <para>
<productname>Solaris</productname> requires special handling. You must <productname>Solaris</productname> requires special handling. You must
use <command>/usr/ucb/ps</command>, rather than 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 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 <command>ps</command> status display than that provided by each
backend. If you fail to do all three things, the <command>ps</> server process. If you fail to do all three things, the <command>ps</>
output for each backend will be the original <application>postmaster</> output for each server process will be the original <command>postmaster</>
command line. command line.
</para> </para>
</tip> </tip>
</sect1> </sect1>
<sect1 id="monitoring-stats"> <sect1 id="monitoring-stats">
<title>Statistics Collector</Title> <title>The Statistics Collector</Title>
<indexterm zone="monitoring-stats"> <indexterm zone="monitoring-stats">
<primary>statistics</primary> <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 is a subsystem that supports collection and reporting of information about
server activity. Presently, the collector can count accesses to tables server activity. Presently, the collector can count accesses to tables
and indexes in both disk-block and individual-row terms. It also supports 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. processes.
</para> </para>
@ -113,13 +110,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para> <para>
Since collection of statistics adds some overhead to query execution, Since collection of statistics adds some overhead to query execution,
the system can be configured to collect or not collect information. the system can be configured to collect or not collect information.
This is controlled by configuration variables that are normally set in This is controlled by configuration parameters that are normally set in
<filename>postgresql.conf</> (see <xref linkend="runtime-config"> for <filename>postgresql.conf</>. (See <xref linkend="runtime-config"> for
details about setting configuration variables). details about setting configuration parameters.)
</para> </para>
<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 <literal>true</> for the statistics collector to
be launched at all. This is the default and recommended setting, 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 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>
<para> <para>
The variables <varname>STATS_COMMAND_STRING</varname>, The parameters <varname>stats_command_string</varname>,
<varname>STATS_BLOCK_LEVEL</varname>, <varname>stats_block_level</varname>,
and <varname>STATS_ROW_LEVEL</varname> control how much information is and <varname>stats_row_level</varname> control how much information is
actually sent to the collector, and thus determine how much run-time actually sent to the collector and thus determine how much run-time
overhead occurs. These respectively determine whether a server process overhead occurs. These respectively determine whether a server process
sends its current command string, disk-block-level access statistics, and 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 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, but it is possible to turn them on or off in individual sessions
processes using the <command>SET</> command. (To prevent ordinary users using the <command>SET</> command. (To prevent ordinary users
from hiding their activity from the administrator, only superusers are 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> </para>
<important> <note>
<para> <para>
Since the variables <varname>STATS_COMMAND_STRING</varname>, Since the parameters <varname>stats_command_string</varname>,
<varname>STATS_BLOCK_LEVEL</varname>, and <varname>stats_block_level</varname>, and
<varname>STATS_ROW_LEVEL</varname> default to <literal>false</>, <varname>stats_row_level</varname> default to <literal>false</>,
very few statistics are collected in the default very few statistics are collected in the default
configuration. Enabling one or more of these configuration configuration. Enabling one or more of these configuration
variables will significantly enhance the amount of useful data variables will significantly enhance the amount of useful data
produced by the statistics collector, at the expense of produced by the statistics collector, at the expense of
additional run-time overhead. additional run-time overhead.
</para> </para>
</important> </note>
</sect2> </sect2>
@ -181,7 +178,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para> <para>
Another important point is that when a server process is asked to display 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 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. 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 So the statistics will appear not to change as long as you continue the
current transaction. current transaction.
@ -209,9 +206,9 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<entry>One row per server process, showing process <entry>One row per server process, showing process
<acronym>ID</>, database, user, current query, and the time at <acronym>ID</>, database, user, current query, and the time at
which the current query began execution. The columns that report which the current query began execution. The columns that report
data on the current query are only available if the data on the current query are only available if the parameter
<varname>STATS_COMMAND_STRING</varname> configuration option has <varname>stats_command_string</varname> has been turned on.
been enabled. Furthermore, these columns can only be accessed by Furthermore, these columns can only be accessed by
superusers; or when the user examining the view is the same as the user 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 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 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> <row>
<entry><structname>pg_stat_database</></entry> <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 transactions committed and total rolled back in that database,
total disk blocks read, and total number of buffer hits (i.e., block total disk blocks read, and total number of buffer hits (i.e., block
read requests avoided by finding the block already in buffer cache). 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 <entry>For each table in the current database, total numbers of
sequential and index scans, total numbers of tuples returned by sequential and index scans, total numbers of tuples returned by
each type of scan, and totals of tuple insertions, updates, each type of scan, and totals of tuple insertions, updates,
and deletes.</entry> and deletions.</entry>
</row> </row>
<row> <row>
@ -360,12 +357,12 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
queries that use the same underlying statistics access functions as queries that use the same underlying statistics access functions as
these standard views do. These functions are listed in <xref these standard views do. These functions are listed in <xref
linkend="monitoring-stats-funcs-table">. The per-database access linkend="monitoring-stats-funcs-table">. The per-database access
functions accept a database OID to identify which database to functions take a database OID as argument to identify which database to
report on. The per-table and per-index functions accept a table or report on. The per-table and per-index functions take a table or
index OID (note that only tables and indexes in the current index OID. (Note that only tables and indexes in the current
database can be seen with these functions). The per-backend access database can be seen with these functions.) The per-backend access
functions accept a backend ID number, which ranges from one to the functions take a backend ID number, which ranges from one to the
number of currently active backends. number of currently active backend processes.
</para> </para>
<table id="monitoring-stats-funcs-table"> <table id="monitoring-stats-funcs-table">
@ -382,15 +379,15 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<tbody> <tbody>
<row> <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><type>integer</type></entry>
<entry> <entry>
Number of active backends in database Number of active backend processes for database
</entry> </entry>
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Transactions committed in database Transactions committed in database
@ -398,7 +395,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Transactions rolled back in database Transactions rolled back in database
@ -406,7 +403,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of disk block fetch requests for database Number of disk block fetch requests for database
@ -414,7 +411,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of disk block fetch requests found in cache for database 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>
<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><type>bigint</type></entry>
<entry> <entry>
Number of sequential scans done when argument is a table, Number of sequential scans done when argument is a table,
@ -431,7 +428,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of tuples read by sequential scans when argument is a table, 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>
<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><type>bigint</type></entry>
<entry> <entry>
Number of valid (unexpired) table tuples fetched by sequential scans Number of valid (unexpired) table tuples fetched by sequential scans
@ -450,7 +447,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of tuples inserted into table Number of tuples inserted into table
@ -458,7 +455,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of tuples updated in table Number of tuples updated in table
@ -466,7 +463,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of tuples deleted from table Number of tuples deleted from table
@ -474,7 +471,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of disk block fetch requests for table or index Number of disk block fetch requests for table or index
@ -482,7 +479,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
</row> </row>
<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><type>bigint</type></entry>
<entry> <entry>
Number of disk block requests found in cache for table or index 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>
<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><type>set of integer</type></entry>
<entry> <entry>
Set of currently active backend IDs (from 1 to N where N is the Set of currently active backend process IDs (from 1 to the
number of active backends). See usage example below number of active backend processes). See usage example in the text.
</entry> </entry>
</row> </row>
<row> <row>
<entry><function>pg_backend_pid</function>()</entry> <entry><literal><function>pg_backend_pid</function>()</literal></entry>
<entry><type>integer</type></entry> <entry><type>integer</type></entry>
<entry> <entry>
Process ID of the attached backend Process ID of the backend process attached to the current session
</entry> </entry>
</row> </row>
<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><type>integer</type></entry>
<entry> <entry>
Process ID of all backend processes Process ID of the given backend process
</entry> </entry>
</row> </row>
<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><type>oid</type></entry>
<entry> <entry>
Database ID of backend process Database ID of the given backend process
</entry> </entry>
</row> </row>
<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><type>oid</type></entry>
<entry> <entry>
User ID of backend process User ID of the given backend process
</entry> </entry>
</row> </row>
<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><type>text</type></entry>
<entry> <entry>
Current query of backend process (NULL if caller is not Active command of the given backend process (null if the
superuser, or is the same user as that of the backend being queried, current user is not a superuser nor the same user as that of
or <varname>STATS_COMMAND_STRING</varname> is not enabled) the session being queried, or
<varname>stats_command_string</varname> is not on)
</entry> </entry>
</row> </row>
<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><type>text</type></entry>
<entry> <entry>
The time at which the specified backend's currently executing query was The time at which the specified backend process' currently
initiated (NULL if caller is not superuser, or executing query was started (null if the current user is not a
<varname>STATS_COMMAND_STRING</varname> is not enabled) superuser, or <varname>stats_command_string</varname> is not
on)
</entry> </entry>
</row> </row>
<row> <row>
<entry><function>pg_stat_reset</function>()</entry> <entry><literal><function>pg_stat_reset</function>()</literal></entry>
<entry><type>boolean</type></entry> <entry><type>boolean</type></entry>
<entry> <entry>
Reset all currently collected statistics Reset all currently collected statistics
@ -564,8 +563,8 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<note> <note>
<para> <para>
<literal>blocks_fetched</literal> minus <function>pg_stat_get_db_blocks_fetched</function> minus
<literal>blocks_hit</literal> gives the number of kernel <function>pg_stat_get_db_blocks_hit</function> gives the number of kernel
<function>read()</> calls issued for the table, index, or <function>read()</> calls issued for the table, index, or
database; but the actual number of physical reads is usually database; but the actual number of physical reads is usually
lower due to kernel-level buffering. lower due to kernel-level buffering.
@ -574,13 +573,13 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<para> <para>
The function <function>pg_stat_get_backend_idset</function> provides The function <function>pg_stat_get_backend_idset</function> provides
a convenient way to generate one row for each active backend. For 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 backends: example, to show the <acronym>PID</>s and current queries of all backend processes:
<programlisting> <programlisting>
SELECT pg_stat_get_backend_pid(S.backendid) AS procpid, SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
pg_stat_get_backend_activity(S.backendid) AS current_query pg_stat_get_backend_activity(s.backendid) AS current_query
FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S; FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;
</programlisting> </programlisting>
</para> </para>
@ -592,7 +591,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<para> <para>
Another useful tool for monitoring database activity is the 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 database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be used locks in the lock manager. For example, this capability can be used
to: to:
@ -609,7 +608,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<listitem> <listitem>
<para> <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 ungranted locks (which might be a source of contention among
database clients). database clients).
</para> </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 view produces a consistent set of results, while not blocking
normal lock manager operations longer than necessary. Nonetheless normal lock manager operations longer than necessary. Nonetheless
there could be some impact on database performance if this view is there could be some impact on database performance if this view is
examined often. read often.
</para> </para>
</note> </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 <literal>pg_locks</literal> view contains one row per lockable
object and requested lock mode. Thus, the same lockable object may object and requested lock mode. Thus, the same lockable object may
appear many times, if multiple transactions are holding or waiting 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 transaction ID. (Note that this view includes only table-level
locks, not row-level ones. If a transaction is waiting for a 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 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> </para>
<table id="monitoring-locks-table"> <table id="monitoring-locks-table">
<title>Lock Status System View</title> <title><literal>pg_locks</literal> Columns</title>
<tgroup cols="3"> <tgroup cols="3">
<thead> <thead>
<row> <row>
<entry>Column Name</entry> <entry>Column Name</entry>
<entry>Type</entry> <entry>Data Type</entry>
<entry>Description</entry> <entry>Description</entry>
</row> </row>
</thead> </thead>
@ -671,7 +670,7 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<entry><type>oid</type></entry> <entry><type>oid</type></entry>
<entry> <entry>
The OID of the locked relation, or null if the lockable object 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 <literal>pg_class</literal> system catalog to get more
information on the locked relation. Note however that this information on the locked relation. Note however that this
will only work for relations in the current database (those for 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 The OID of the database in which the locked relation exists, or
null if the lockable object is a transaction ID. If the lock null if the lockable object is a transaction ID. If the lock
is on a globally-shared table, this field will be zero. This 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 system catalog to get more information on the locked object's
database. database.
</entry> </entry>
@ -712,11 +711,11 @@ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
<entry><type>integer</type></entry> <entry><type>integer</type></entry>
<entry> <entry>
The process ID of the <productname>PostgreSQL</productname> 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 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 <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. lock.
</entry> </entry>
</row> </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 False indicates that this session is currently waiting to
acquire this lock, which implies that some other session is acquire this lock, which implies that some other session is
holding a conflicting lock mode on the same lockable object. holding a conflicting lock mode on the same lockable object.
This backend will sleep until the other lock is released (or a The waiting session will sleep until the other lock is released (or a
deadlock situation is detected). A single backend can be deadlock situation is detected). A single session can be
waiting to acquire at most one lock at a time. waiting to acquire at most one lock at a time.
</entry> </entry>
</row> </row>

14
doc/src/sgml/ref/clusterdb.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.8 2003/03/20 18:53:18 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.9 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>clusterdb</command> <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>--table | -t <replaceable>table</replaceable> </arg>
<arg><replaceable>dbname</replaceable></arg> <arg><replaceable>dbname</replaceable></arg>
<sbr> <sbr>
<command>clusterdb</command> <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> <group><arg>--all</arg><arg>-a</arg></group>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -114,7 +114,7 @@ PostgreSQL documentation
<term><option>--table <replaceable class="parameter">table</replaceable></></term> <term><option>--table <replaceable class="parameter">table</replaceable></></term>
<listitem> <listitem>
<para> <para>
Clusters <replaceable class="parameter">table</replaceable> only. Cluster <replaceable class="parameter">table</replaceable> only.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -134,7 +134,7 @@ PostgreSQL documentation
<para> <para>
Specifies the host name of the machine on which the Specifies the host name of the machine on which the
server 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -145,7 +145,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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 extension on which the server
is listening for connections. is listening for connections.
</para> </para>
@ -219,7 +219,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Default connection parameters. Default connection parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

16
doc/src/sgml/ref/createdb.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.31 2003/03/18 22:19:46 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.32 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>createdb</command> <command>createdb</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg> <arg><replaceable>dbname</replaceable></arg>
<arg><replaceable>description</replaceable></arg> <arg><replaceable>description</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
@ -47,7 +47,7 @@ PostgreSQL documentation
endterm="SQL-CREATEDATABASE-title">. Thus, there is nothing endterm="SQL-CREATEDATABASE-title">. Thus, there is nothing
special about creating databases via this or other methods. This special about creating databases via this or other methods. This
means that a database server must be running at the targeted 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. the <application>libpq</application> front-end library will apply.
</para> </para>
</refsect1> </refsect1>
@ -65,7 +65,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies the name of the database to be created. The name must be 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 The default is to create a database with the same name as the
current system user. current system user.
</para> </para>
@ -98,7 +98,7 @@ PostgreSQL documentation
<term><option>--echo</></term> <term><option>--echo</></term>
<listitem> <listitem>
<para> <para>
Echo the queries that <application>createdb</application> generates Echo the commands that <application>createdb</application> generates
and sends to the server. and sends to the server.
</para> </para>
</listitem> </listitem>
@ -166,7 +166,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies the host name of the machine on which the 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -177,7 +177,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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. extension on which the server is listening for connections.
</para> </para>
</listitem> </listitem>
@ -296,7 +296,7 @@ PostgreSQL documentation
To create the database <literal>demo</literal> using the To create the database <literal>demo</literal> using the
server on host <literal>eden</>, port 5000, using the server on host <literal>eden</>, port 5000, using the
<literal>LATIN1</literal> encoding scheme with a look at the <literal>LATIN1</literal> encoding scheme with a look at the
underlying query: underlying command:
<screen> <screen>
<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput> <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
<computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput> <computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput>

19
doc/src/sgml/ref/createlang.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.30 2003/03/18 22:19:46 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/createlang.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>createlang</command> <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 choice="plain"><replaceable>langname</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg> <arg><replaceable>dbname</replaceable></arg>
<sbr> <sbr>
<command>createlang</command> <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> <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
<arg choice="plain"><replaceable>dbname</replaceable></arg> <arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
@ -85,7 +85,7 @@ PostgreSQL documentation
<term><option>--echo</></term> <term><option>--echo</></term>
<listitem> <listitem>
<para> <para>
Displays SQL commands as they are executed. Display SQL commands as they are executed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -95,8 +95,7 @@ PostgreSQL documentation
<term><option>--list</></term> <term><option>--list</></term>
<listitem> <listitem>
<para> <para>
Shows a list of already installed languages in the target database Show a list of already installed languages in the target database.
(which must be specified).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -127,7 +126,7 @@ PostgreSQL documentation
<para> <para>
Specifies the host name of the machine on which the Specifies the host name of the machine on which the
server 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -138,7 +137,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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 extension on which the server
is listening for connections. is listening for connections.
</para> </para>
@ -182,7 +181,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Default connection parameters. Default connection parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -215,7 +214,7 @@ PostgreSQL documentation
<title>Examples</title> <title>Examples</title>
<para> <para>
To install <literal>pltcl</literal> into the database To install the language <literal>pltcl</literal> into the database
<literal>template1</literal>: <literal>template1</literal>:
<screen> <screen>
<prompt>$ </prompt><userinput>createlang pltcl template1</userinput> <prompt>$ </prompt><userinput>createlang pltcl template1</userinput>

18
doc/src/sgml/ref/createuser.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.31 2003/03/18 22:19:46 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.32 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>createuser</command> <command>createuser</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>username</replaceable></arg> <arg><replaceable>username</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -78,7 +78,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
The new user is allowed to create other users. 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.) The option is poorly named.)
</para> </para>
</listitem> </listitem>
@ -120,7 +120,7 @@ PostgreSQL documentation
<term><option>--echo</></term> <term><option>--echo</></term>
<listitem> <listitem>
<para> <para>
Echo the queries that <application>createuser</application> generates Echo the commands that <application>createuser</application> generates
and sends to the server. and sends to the server.
</para> </para>
</listitem> </listitem>
@ -138,8 +138,8 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-i <replaceable class="parameter">uid</replaceable></></term> <term><option>-i <replaceable class="parameter">number</replaceable></></term>
<term><option>--sysid <replaceable class="parameter">uid</replaceable></></term> <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
<listitem> <listitem>
<para> <para>
Allows you to pick a non-default user ID for the new user. This is not Allows you to pick a non-default user ID for the new user. This is not
@ -200,7 +200,7 @@ PostgreSQL documentation
<para> <para>
Specifies the host name of the machine on which the Specifies the host name of the machine on which the
server 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -211,7 +211,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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 extension on which the server
is listening for connections. is listening for connections.
</para> </para>
@ -311,7 +311,7 @@ PostgreSQL documentation
<para> <para>
To create the same user <literal>joe</literal> using the To create the same user <literal>joe</literal> using the
server on host <literal>eden</>, port 5000, avoiding the prompts and 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> <screen>
<prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput> <prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
<computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput> <computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput>

148
doc/src/sgml/ref/current_date.sgml
View File

@ -1,148 +0,0 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.5 2002/04/21 19:02:39 thomas Exp $
Postgres documentation
-->
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_date.sgml,v 1.5 2002/04/21 19:02:39 thomas Exp $
Postgres documentation
-->
<REFENTRY ID="SQL-CURRENT-DATE">
<REFMETA>
<REFENTRYTITLE>CURRENT_DATE</REFENTRYTITLE>
<REFMISCINFO>SQL - Functions</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
CURRENT_DATE
</REFNAME>
<REFPURPOSE>
Returns the current date
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CURRENT_DATE
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CURRENT-DATE-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
None.
</REFSECT2>
<REFSECT2 ID="R2-SQL-CURRENT-DATE-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>date</replaceable>
</TERM>
<LISTITEM>
<PARA>
Returns "<replaceable class="parameter">today</replaceable>".
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CURRENT-DATE-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The niladic CURRENT_DATE function has a data type of
DATE and returns the date at the time that it is run.
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-DATE-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to SET DATESTYLE for further information about date format.
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-CURRENT-DATE-2">
<TITLE>
Usage
</TITLE>
<PARA>
Insert the date of insertion into a row:
</PARA>
<ProgramListing>
INSERT INTO films
VALUES ('TM999','Ben Hur',105,CURRENT_DATE,'Action',NULL);
</ProgramListing>
<PARA>
Display CURRENT-DATE:
</PARA>
<ProgramListing>
SELECT CURRENT_DATE AS today;
today
------------
1998-03-31
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CURRENT-DATE-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-DATE-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
Full compatibility.
</PARA>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

158
doc/src/sgml/ref/current_time.sgml
View File

@ -1,158 +0,0 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_time.sgml,v 1.6 2002/04/21 19:02:39 thomas Exp $
PostgreSQL documentation
-->
<REFENTRY ID="SQL-CURRENT-TIME">
<REFMETA>
<REFENTRYTITLE>CURRENT_TIME</REFENTRYTITLE>
<REFMISCINFO>SQL - Functions</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
CURRENT_TIME
</REFNAME>
<REFPURPOSE>
Returns the current local time
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CURRENT_TIME
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CURRENT-TIME-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
None.
</REFSECT2>
<REFSECT2 ID="R2-SQL-CURRENT-TIME-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>time</replaceable>
<LISTITEM>
<PARA>
<ReturnValue>Returns "<replaceable class="parameter">now</replaceable>"</ReturnValue>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CURRENT-TIME-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The niladic CURRENT_TIME function has a data type of
TIME and returns the local time when it is run.
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-TIME-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA> Refer to the SET TIME ZONE statement for a further description
of local time.
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-CURRENT-TIME-2">
<TITLE>
Usage
</TITLE>
<PARA>Display CURRENT_TIME:
</PARA>
<ProgramListing>
SELECT CURRENT_TIME AS now;
now
-----------
17:41:31+02
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CURRENT-TIME-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-TIME-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
SQL92 specifies some additional capabilities for CURRENT_TIME:
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>
CURRENT_TIME [ (<replaceable class="parameter">scale</replaceable>) ]</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The optional scale for CURRENT_TIME, if specified, is an
unsigned integer representing the number of digits in the
optional seconds fraction of the time value represented
by the function.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFENTRY>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

166
doc/src/sgml/ref/current_timestamp.sgml
View File

@ -1,166 +0,0 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_timestamp.sgml,v 1.6 2002/04/21 19:02:39 thomas Exp $
PostgreSQL documentation
-->
<REFENTRY ID="SQL-CURRENT-TIMESTAMP">
<REFMETA>
<REFENTRYTITLE>CURRENT_TIMESTAMP</REFENTRYTITLE>
<REFMISCINFO>SQL - Functions</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
CURRENT_TIMESTAMP
</REFNAME>
<REFPURPOSE>
Returns the current date and time
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<synopsis>
CURRENT_TIMESTAMP
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
None.
</REFSECT2>
<REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>timestamp</replaceable>
<LISTITEM>
<PARA>
Returns "<replaceable class="parameter">today</replaceable>" and "<replaceable class="parameter">now</replaceable>".
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The niladic CURRENT_TIMESTAMP function has a data type of
TIMESTAMP and returns the date and local time at which it is run.
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Refer to the SET TIME ZONE statement for a further description
of local time.
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-2">
<TITLE>
Usage
</TITLE>
<PARA>
Display CURRENT_TIMESTAMP:
</PARA>
<ProgramListing>
SELECT CURRENT_TIMESTAMP AS date_and_time;
date_and_time
----------------------
1998-03-31 07:41:21-08
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CURRENT-TIMESTAMP-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-TIMESTAMP-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
SQL92 specifies some additional capabilities for CURRENT_TIMESTAMP:
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
</TERM>
<LISTITEM>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>CURRENT_TIMESTAMP [ (<replaceable class="parameter">scale</replaceable>) ]</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The optional scale for CURRENT_TIMESTAMP, if specified, is an
unsigned integer representing the number of digits in the
optional seconds fraction of the time value represented
by the function.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</para>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

167
doc/src/sgml/ref/current_user.sgml
View File

@ -1,167 +0,0 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/current_user.sgml,v 1.7 2002/08/13 20:40:43 momjian Exp $
PostgreSQL documentation
-->
<REFENTRY ID="SQL-CURRENT-USER">
<REFMETA>
<REFENTRYTITLE>CURRENT_USER</REFENTRYTITLE>
<REFMISCINFO>SQL - Functions</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
CURRENT_USER
</REFNAME>
<REFPURPOSE>
Returns the current user name
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-04-15</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
CURRENT_USER
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-CURRENT-USER-1">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
None.
</REFSECT2>
<REFSECT2 ID="R2-SQL-CURRENT-USER-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<replaceable>username</replaceable>
</TERM>
<LISTITEM>
<PARA>
The name of the current user.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-CURRENT-USER-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
The niladic CURRENT_USER function returns a string of type "name"
whose value represents a user name identification.
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-USER-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Data type "name" is a non-standard 63-character type for storing
system identifiers.
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-CURRENT-USER-2">
<TITLE>
Usage
</TITLE>
<PARA>
Display CURRENT_USER
</PARA>
<ProgramListing>
SELECT CURRENT_USER AS who_am_i;
who_am_i
------------
jose
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-CURRENT-USER-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>
<REFSECT2 ID="R2-SQL-CURRENT-USER-4">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
SQL92 specifies some additional niladic USER functions:
</PARA>
<variablelist>
<varlistentry>
<term>CURRENT_USER / USER</term>
<listitem>
<para>
USER is a synonym for CURRENT_USER.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SESSION_USER</term>
<listitem>
<para>
The SESSION_USER function returns the SQL-session user name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SYSTEM_USER</term>
<listitem>
<para>
The SYSTEM_USER function returns the database's initial default user.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
A niladic USER function returns a SQL_TEXT character string whose
value represents a user name.
</para>
</refsect2>
</refsect1>
</REFENTRY>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

16
doc/src/sgml/ref/dropdb.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.20 2003/03/18 22:19:46 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.21 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>dropdb</command> <command>dropdb</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>dbname</replaceable></arg> <arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -57,9 +57,7 @@ PostgreSQL documentation
<term><replaceable class="parameter">dbname</replaceable></term> <term><replaceable class="parameter">dbname</replaceable></term>
<listitem> <listitem>
<para> <para>
Specifies the name of the database to be removed. The database Specifies the name of the database to be removed.
must be one of the existing <productname>PostgreSQL</productname> databases
in this installation.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -69,7 +67,7 @@ PostgreSQL documentation
<term><option>--echo</></term> <term><option>--echo</></term>
<listitem> <listitem>
<para> <para>
Echo the queries that <application>dropdb</application> generates Echo the commands that <application>dropdb</application> generates
and sends to the server. and sends to the server.
</para> </para>
</listitem> </listitem>
@ -109,7 +107,7 @@ PostgreSQL documentation
<para> <para>
Specifies the host name of the machine on which the Specifies the host name of the machine on which the
server 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -120,7 +118,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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 extension on which the server
is listening for connections. is listening for connections.
</para> </para>
@ -212,7 +210,7 @@ PostgreSQL documentation
<para> <para>
To destroy the database <literal>demo</literal> using the To destroy the database <literal>demo</literal> using the
server on host <literal>eden</literal>, port 5000, with verification and a peek server on host <literal>eden</literal>, port 5000, with verification and a peek
at the underlying query: at the underlying command:
<screen> <screen>
<prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput> <prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
<computeroutput>Database "demo" will be permanently deleted. <computeroutput>Database "demo" will be permanently deleted.

15
doc/src/sgml/ref/droplang.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.22 2003/03/18 22:19:46 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/droplang.sgml,v 1.23 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>droplang</command> <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 choice="plain"><replaceable>langname</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg> <arg><replaceable>dbname</replaceable></arg>
<sbr> <sbr>
<command>droplang</command> <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> <group choice="plain"><arg>--list</arg><arg>-l</arg></group>
<arg choice="plain"><replaceable>dbname</replaceable></arg> <arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
@ -85,7 +85,7 @@ PostgreSQL documentation
<term><option>--echo</></term> <term><option>--echo</></term>
<listitem> <listitem>
<para> <para>
Displays SQL commands as they are executed. Display SQL commands as they are executed.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -95,8 +95,7 @@ PostgreSQL documentation
<term><option>--list</></term> <term><option>--list</></term>
<listitem> <listitem>
<para> <para>
Shows a list of already installed languages in the target database Show a list of already installed languages in the target database.
(which must be specified).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -171,7 +170,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Default connection parameters. Default connection parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -204,7 +203,7 @@ PostgreSQL documentation
<title>Examples</title> <title>Examples</title>
<para> <para>
To remove <literal>pltcl</literal>: To remove the language <literal>pltcl</literal>:
<screen> <screen>
<prompt>$ </prompt><userinput>droplang pltcl dbname</userinput> <prompt>$ </prompt><userinput>droplang pltcl dbname</userinput>
</screen> </screen>

19
doc/src/sgml/ref/dropuser.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.23 2003/03/18 22:19:46 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.24 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>dropuser</command> <command>dropuser</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>username</replaceable></arg> <arg><replaceable>username</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -31,8 +31,8 @@ PostgreSQL documentation
<application>dropuser</application> removes an existing <application>dropuser</application> removes an existing
<productname>PostgreSQL</productname> user <productname>PostgreSQL</productname> user
<emphasis>and</emphasis> the databases which that user owned. <emphasis>and</emphasis> the databases which that user owned.
Only users with <literal>usesuper</literal> set in Only superusers (users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> table can destroy the <literal>pg_shadow</literal> table) can destroy
<productname>PostgreSQL</productname> users. <productname>PostgreSQL</productname> users.
</para> </para>
@ -61,7 +61,6 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies the name of the <productname>PostgreSQL</productname> user to be removed. 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. You will be prompted for a name if none is specified on the command line.
</para> </para>
</listitem> </listitem>
@ -72,7 +71,7 @@ PostgreSQL documentation
<term><option>--echo</></term> <term><option>--echo</></term>
<listitem> <listitem>
<para> <para>
Echo the queries that <application>dropuser</application> generates Echo the commands that <application>dropuser</application> generates
and sends to the server. and sends to the server.
</para> </para>
</listitem> </listitem>
@ -112,7 +111,7 @@ PostgreSQL documentation
<para> <para>
Specifies the host name of the machine on which the Specifies the host name of the machine on which the
server 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -123,7 +122,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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 extension on which the server
is listening for connections. is listening for connections.
</para> </para>
@ -219,9 +218,9 @@ PostgreSQL documentation
</para> </para>
<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 <literal>eden</literal>, port 5000, with verification and a peek at the underlying
query: command:
<screen> <screen>
<prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput> <prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
<computeroutput>User "joe" and any owned databases will be permanently deleted. <computeroutput>User "joe" and any owned databases will be permanently deleted.

14
doc/src/sgml/ref/ecpg-ref.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/ecpg-ref.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -66,7 +66,7 @@ PostgreSQL documentation
<term><option>-c</option></term> <term><option>-c</option></term>
<listitem> <listitem>
<para> <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>. works for <literal>EXEC SQL TYPE</literal>.
</para> </para>
</listitem> </listitem>
@ -101,7 +101,7 @@ PostgreSQL documentation
<term><option>-o <replaceable>filename</replaceable></option></term> <term><option>-o <replaceable>filename</replaceable></option></term>
<listitem> <listitem>
<para> <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>. its output to the given <replaceable>filename</replaceable>.
</para> </para>
</listitem> </listitem>
@ -111,9 +111,9 @@ PostgreSQL documentation
<term><option>-t</option></term> <term><option>-t</option></term>
<listitem> <listitem>
<para> <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 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. only when <command>EXEC SQL COMMIT</command> is issued.
</para> </para>
</listitem> </listitem>
@ -130,7 +130,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>---help</option></term> <term><option>--help</option></term>
<listitem> <listitem>
<para> <para>
Show a brief summary of the command usage, then exit. Show a brief summary of the command usage, then exit.
@ -165,7 +165,7 @@ PostgreSQL documentation
<para> <para>
Programs using C code with embedded SQL have to be linked against Programs using C code with embedded SQL have to be linked against
the <filename>libecpg</filename> library, for example using the 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>
<para> <para>

26
doc/src/sgml/ref/initdb.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.24 2003/01/19 00:13:29 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.25 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>initdb</command> <command>initdb</command>
<arg rep="repeat">options</arg> <arg rep="repeat"><replaceable>option</></arg>
<group choice="plain"> <group choice="plain">
<arg>--pgdata </arg> <arg>--pgdata </arg>
<arg>-D </arg> <arg>-D </arg>
@ -33,17 +33,17 @@ PostgreSQL documentation
</title> </title>
<para> <para>
<command>initdb</command> creates a new <command>initdb</command> creates a new
<productname>PostgreSQL</productname> database cluster (or database <productname>PostgreSQL</productname> database cluster. A database
system). A database cluster is a collection of databases that are cluster is a collection of databases that are managed by a single
managed by a single server instance. server instance.
</para> </para>
<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 the database data will live, generating the shared catalog tables
(tables that belong to the whole cluster rather than to any particular (tables that belong to the whole cluster rather than to any particular
database), and creating the <literal>template1</literal> 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. <literal>template1</literal> database is copied.
It contains catalog tables filled in for things like the It contains catalog tables filled in for things like the
built-in types. built-in types.
@ -99,7 +99,7 @@ PostgreSQL documentation
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term> <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
<listitem> <listitem>
<para> <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 should be stored. This is the only information required by
<command>initdb</command>, but you can avoid writing it by <command>initdb</command>, but you can avoid writing it by
setting the <envar>PGDATA</envar> environment variable, which setting the <envar>PGDATA</envar> environment variable, which
@ -117,9 +117,7 @@ PostgreSQL documentation
<para> <para>
Selects the encoding of the template database. This will also Selects the encoding of the template database. This will also
be the default encoding of any database you create later, unless you be the default encoding of any database you create later, unless you
override it there. To use the encoding feature, you must override it there. The default is <literal>SQL_ASCII</literal>.
have enabled it at build time, at which time you also select the default
for this option.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -205,7 +203,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies where <command>initdb</command> should find 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 normally not necessary. You will be told if you need to
specify their location explicitly. specify their location explicitly.
</para> </para>
@ -219,7 +217,7 @@ PostgreSQL documentation
<para> <para>
By default, when <command>initdb</command> By default, when <command>initdb</command>
determines that an error prevented it from completely creating the database 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 that it can't finish the job. This option inhibits tidying-up and is
thus useful for debugging. thus useful for debugging.
</para> </para>
@ -239,7 +237,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <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. stored; may be overridden using the <option>-D</option> option.
</para> </para>
</listitem> </listitem>

6
doc/src/sgml/ref/initlocation.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.18 2003/01/19 00:13:29 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/initlocation.sgml,v 1.19 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -47,9 +47,9 @@ PostgreSQL documentation
<screen> <screen>
<prompt>$ </prompt><userinput>export PGDATA2=/opt/postgres/data</userinput> <prompt>$ </prompt><userinput>export PGDATA2=/opt/postgres/data</userinput>
</screen> </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 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> <screen>
<prompt>$</prompt> <userinput>initlocation PGDATA2</userinput> <prompt>$</prompt> <userinput>initlocation PGDATA2</userinput>
<prompt>$</prompt> <userinput>createdb -D PGDATA2 testdb</userinput> <prompt>$</prompt> <userinput>createdb -D PGDATA2 testdb</userinput>

16
doc/src/sgml/ref/ipcclean.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.7 2002/04/21 19:02:39 thomas Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/ipcclean.sgml,v 1.8 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -36,12 +36,10 @@ PostgreSQL documentation
<para> <para>
Only the database administrator should execute this program as it Only the database administrator should execute this program as it
can cause bizarre behavior (i.e., crashes) if run during multiuser can cause bizarre behavior (i.e., crashes) if run during multiuser
execution. If this command is executed while a execution. If this command is executed while a server is running,
<application>postmaster</application> is running, the shared memory the shared memory and semaphores allocated by that server will be
and semaphores allocated by the deleted, which would have rather severe consequences for that
<application>postmaster</application> will be deleted. This will server.
result in a general failure of the backend servers started by that
<application>postmaster</application>.
</para> </para>
</refsect1> </refsect1>
@ -51,14 +49,14 @@ PostgreSQL documentation
<para> <para>
This script is a hack, but in the many years since it was written, 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. 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 itself, it is unlikely that <command>ipcclean</command> will be
improved upon in the future. improved upon in the future.
</para> </para>
<para> <para>
The script makes assumption about the format of output of the 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. utility which may not be true across different operating systems.
Therefore, it may not work on your particular OS. Therefore, it may not work on your particular OS.
</para> </para>

8
doc/src/sgml/ref/pg_config-ref.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.13 2003/01/19 00:13:29 momjian Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.14 2003/03/24 14:32:51 petere Exp $ -->
<refentry id="app-pgconfig"> <refentry id="app-pgconfig">
<refmeta> <refmeta>
@ -50,7 +50,7 @@
<listitem> <listitem>
<para> <para>
Print the location of user executables. Use this, for example, to find 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. where the <filename>pg_config</> program resides.
</para> </para>
</listitem> </listitem>
@ -130,10 +130,10 @@
<title>Notes</title> <title>Notes</title>
<para> <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 <productname>PostgreSQL</> 7.2. In prior releases, the server include files were
installed in the same location as the client headers, which could 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 package handle both cases, try the newer option first and test the
exit status to see whether it succeeded. exit status to see whether it succeeded.
</para> </para>

14
doc/src/sgml/ref/pg_controldata.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_controldata.sgml,v 1.4 2002/08/17 05:07:18 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_controldata.sgml,v 1.5 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -12,7 +12,7 @@ PostgreSQL documentation
<refnamediv> <refnamediv>
<refname>pg_controldata</refname> <refname>pg_controldata</refname>
<refpurpose>display server-wide control information</refpurpose> <refpurpose>display control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
@ -25,16 +25,16 @@ PostgreSQL documentation
<refsect1 id="R1-APP-PGCONTROLDATA-1"> <refsect1 id="R1-APP-PGCONTROLDATA-1">
<title>Description</title> <title>Description</title>
<para> <para>
<command>pg_controldata</command> returns information initialized during <command>pg_controldata</command> prints information initialized during
<application>initdb</>, such as the catalog version and server locale. <command>initdb</>, such as the catalog version and server locale.
It also shows information about write-ahead logging and checkpoint 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. database.
</para> </para>
<para> <para>
This utility may only be run by the user who installed the server because This utility may only be run by the user who initialized the cluster because
it requires read access to the <literal>datadir</>. it requires read access to the data directory.
You can specify the data directory on the command line, or use You can specify the data directory on the command line, or use
the environment variable <envar>PGDATA</>. the environment variable <envar>PGDATA</>.
</para> </para>

125
doc/src/sgml/ref/pg_ctl-ref.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.20 2003/03/20 17:37:46 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.21 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -69,17 +69,17 @@ PostgreSQL documentation
<title>Description</title> <title>Description</title>
<para> <para>
<application>pg_ctl</application> is a utility for starting, <application>pg_ctl</application> is a utility for starting,
stopping, or restarting <xref linkend="app-postmaster">, the stopping, or restarting the <productname>PostgreSQL</productname>
<productname>PostgreSQL</productname> backend server, or displaying backend server (<xref linkend="app-postmaster">), or displaying the
the status of a running postmaster. Although the postmaster can be status of a running server. Although the server can be started
started manually, <application>pg_ctl</application> encapsulates manually, <application>pg_ctl</application> encapsulates tasks such
tasks such as redirecting log output and properly detaching from the as redirecting log output and properly detaching from the terminal
terminal and process group. It also provides convenient options for and process group. It also provides convenient options for
controlled shutdown. controlled shutdown.
</para> </para>
<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 server is started in the background, and standard input is attached to
<filename>/dev/null</filename>. The standard output and standard <filename>/dev/null</filename>. The standard output and standard
error are either appended to a log file (if the <option>-l</option> 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 (not standard error). If no log file is chosen, the
standard output of <application>pg_ctl</application> should be redirected standard output of <application>pg_ctl</application> should be redirected
to a file or piped to another process, for example a log rotating program, 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 terminal (from the background) and will not leave the shell's
process group. process group.
</para> </para>
<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 the specified data directory is shut down. Three different
shutdown methods can be selected with the <option>-m</option> shutdown methods can be selected with the <option>-m</option>
option: <quote>Smart</quote> mode waits for all the clients to option: <quote>Smart</quote> mode waits for all the clients to
disconnect. This is the default. <quote>Fast</quote> mode does disconnect. This is the default. <quote>Fast</quote> mode does
not wait for clients to disconnect. All active transactions are not wait for clients to disconnect. All active transactions are
rolled back and clients are forcibly disconnected, then the 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 all server processes without a clean shutdown. This will lead to
a recovery run on restart. a recovery run on restart.
</para> </para>
<para> <para>
<option>restart</option> mode effectively executes a stop followed <option>restart</option> mode effectively executes a stop followed
by a start. This allows the changing of postmaster command line by a start. This allows changing the <command>postmaster</command>
options. command-line options.
</para> </para>
<para> <para>
<option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal, <option>reload</option> mode simply sends the
causing it to reread its configuration files <command>postmaster</command> process a <systemitem>SIGHUP</>
(<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>, signal, causing it to reread its configuration files
etc.). This allows changing of configuration-file options that do not (<filename>postgresql.conf</filename>,
require a complete restart to take effect. <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>
<para> <para>
<option>status</option> mode checks whether a postmaster is running. <option>status</option> mode checks whether a server is running in
If it is, the <acronym>PID</acronym> and the command line the specified data directory. If it is, the <acronym>PID</acronym>
options that were used to invoke it are displayed. and the command line options that were used to invoke it are
displayed.
</para> </para>
</refsect1> </refsect1>
@ -133,7 +136,7 @@ PostgreSQL documentation
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>-D <replaceable class="parameter">datadir</replaceable></term> <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the file system location of the database files. If Specifies the file system location of the database files. If
@ -144,7 +147,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-l <replaceable class="parameter">filename</replaceable></term> <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Append the server log output to Append the server log output to
@ -156,7 +159,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-m <replaceable class="parameter">mode</replaceable></term> <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the shutdown mode. <replaceable>mode</replaceable> Specifies the shutdown mode. <replaceable>mode</replaceable>
@ -168,35 +171,35 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-o <replaceable class="parameter">options</replaceable></term> <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies options to be passed directly to Specifies options to be passed directly to the
<application>postmaster</application>. <command>postmaster</command> command.
</para> </para>
<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. quotes to ensure that they are passed through as a group.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-p <replaceable class="parameter">path</replaceable></term> <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the location of the <filename>postmaster</filename> 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 directory as <command>pg_ctl</command>, or failing that, the hard-wired
installation directory. It is not necessary to use this installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-s</term> <term><option>-s</option></term>
<listitem> <listitem>
<para> <para>
Only print errors, no informational messages. Only print errors, no informational messages.
@ -205,7 +208,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-w</term> <term><option>-w</option></term>
<listitem> <listitem>
<para> <para>
Wait for the start or shutdown to complete. Times out after Wait for the start or shutdown to complete. Times out after
@ -224,7 +227,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-W</term> <term><option>-W</option></term>
<listitem> <listitem>
<para> <para>
Do not wait for start or shutdown to complete. This is the Do not wait for start or shutdown to complete. This is the
@ -276,9 +279,10 @@ PostgreSQL documentation
<term><filename>postmaster.pid</filename></term> <term><filename>postmaster.pid</filename></term>
<listitem> <listitem>
<para>The existence of this file in the data directory is used to help <para>
<application>pg_ctl</application> determine if the server is The existence of this file in the data directory is used to help
currently running or not. <application>pg_ctl</application> determine if the server is
currently running or not.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -287,11 +291,12 @@ PostgreSQL documentation
<term><filename>postmaster.opts.default</filename></term> <term><filename>postmaster.opts.default</filename></term>
<listitem> <listitem>
<para>If this file exists in the data directory, <para>
<application>pg_ctl</application> (in <option>start</option> mode) If this file exists in the data directory,
will pass the contents of the file as options to the <application>pg_ctl</application> (in <option>start</option>
<application>postmaster</application>, unless overridden mode) will pass the contents of the file as options to the
by the <option>-o</option> option. <command>postmaster</command> command, unless overridden by the
<option>-o</option> option.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -314,10 +319,10 @@ PostgreSQL documentation
<term><filename>postgresql.conf</filename></term> <term><filename>postgresql.conf</filename></term>
<listitem> <listitem>
<para>This file, located in the data directory, is parsed to <para>
find the proper port to send to the This file, located in the data directory, is parsed to find the
<application>psql</application> when the <option>-w</option> proper port to use with <application>psql</application> when the
is given in <option>start</option> mode. <option>-w</option> is given in <option>start</option> mode.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -332,7 +337,7 @@ PostgreSQL documentation
<para> <para>
Waiting for complete start is not a well-defined operation and may 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 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> </para>
</refsect1> </refsect1>
@ -341,25 +346,25 @@ PostgreSQL documentation
<title>Examples</title> <title>Examples</title>
<refsect2 id="R2-APP-PGCTL-3"> <refsect2 id="R2-APP-PGCTL-3">
<title>Starting the postmaster</title> <title>Starting the Server</title>
<para> <para>
To start up a <application>postmaster</application>: To start up a server:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput> <prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen> </screen>
</para> </para>
<para> <para>
An example of starting the <application>postmaster</application>, An example of starting the server, blocking until the server has
blocking until the postmaster comes up is: come up is:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput> <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen> </screen>
</para> </para>
<para> <para>
For a <application>postmaster</application> using port 5433, and For a server using port 5433, and
running without <function>fsync</function>, use: running without <function>fsync</function>, use:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
@ -368,32 +373,32 @@ PostgreSQL documentation
</refsect2> </refsect2>
<refsect2 id="R2-APP-PGCTL-4"> <refsect2 id="R2-APP-PGCTL-4">
<title>Stopping the postmaster</title> <title>Stopping the Server</title>
<para> <para>
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput> <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen> </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. to control <emphasis>how</emphasis> the backend shuts down.
</para> </para>
</refsect2> </refsect2>
<refsect2 id="R2-APP-PGCTL-5"> <refsect2 id="R2-APP-PGCTL-5">
<title>Restarting the postmaster</title> <title>Restarting the Server</title>
<para> <para>
This is almost equivalent to stopping the Restarting the server is almost equivalent to stopping the
<application>postmaster</application> and starting it again server and starting it again
except that <command>pg_ctl</command> saves and reuses the command line options that except that <command>pg_ctl</command> saves and reuses the command line options that
were passed to the previously running instance. To restart 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> <screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput> <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen> </screen>
</para> </para>
<para> <para>
To restart <application>postmaster</application>, To restart server,
waiting for it to shut down and to come up: waiting for it to shut down and to come up:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput> <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
@ -409,7 +414,7 @@ PostgreSQL documentation
</refsect2> </refsect2>
<refsect2 id="R2-APP-PGCTL-6"> <refsect2 id="R2-APP-PGCTL-6">
<title>Showing postmaster status</title> <title>Showing the Server Status</title>
<para> <para>
Here is a sample status output from Here is a sample status output from

116
doc/src/sgml/ref/pg_dump.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.58 2003/03/18 17:05:01 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dump.sgml,v 1.59 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -21,7 +21,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>pg_dump</command> <command>pg_dump</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg> <arg><replaceable>dbname</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -54,14 +54,6 @@ PostgreSQL documentation
architectures. architectures.
</para> </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> <para>
When used with one of the archive file formats and combined with When used with one of the archive file formats and combined with
<application>pg_restore</application>, <application>pg_dump</application> provides a <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> The most flexible output file format is the <quote>custom</quote>
format (<option>-Fc</option>). It allows for selection and format (<option>-Fc</option>). It allows for selection and
reordering of all archived items, and is compressed by default. The 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 compressed and it is not possible to reorder data when loading, but
it is otherwise quite flexible; moreover, it can be manipulated with 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>
<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 output for any warnings (printed on standard error), especially in
light of the limitations listed below. light of the limitations listed below.
</para> </para>
@ -198,7 +190,7 @@ PostgreSQL documentation
<replaceable>table</replaceable> <replaceable>table</replaceable>
(<replaceable>column</replaceable>, ...) VALUES (<replaceable>column</replaceable>, ...) VALUES
...</literal>). This will make restoration very slow, ...</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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -224,7 +216,7 @@ PostgreSQL documentation
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>p</term> <term><literal>p</></term>
<listitem> <listitem>
<para> <para>
Output a plain-text <acronym>SQL</acronym> script file (default) Output a plain-text <acronym>SQL</acronym> script file (default)
@ -233,10 +225,10 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>t</term> <term><literal>t</></term>
<listitem> <listitem>
<para> <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 <application>pg_restore</application>. Using this archive format
allows reordering and/or exclusion of schema elements allows reordering and/or exclusion of schema elements
at the time the database is restored. It is also possible to limit at the time the database is restored. It is also possible to limit
@ -246,7 +238,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>c</term> <term><literal>c</></term>
<listitem> <listitem>
<para> <para>
Output a custom archive suitable for input into 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> <term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specify the compression level to use in archive formats that support Specify the compression level to use in archive formats that
compression (currently only the custom archive format supports compression). support compression. (Currently only the custom archive
format supports compression.)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -531,9 +524,11 @@ PostgreSQL documentation
<term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the host name of the machine on which the server is 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 running. If the value begins with a slash, it is used as the
directory for the Unix domain socket. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -543,11 +538,10 @@ PostgreSQL documentation
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem> <listitem>
<para> <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 extension on which the server is listening for connections.
is listening for connections. The port number defaults to 5432, Defaults to the <envar>PGPORT</envar> environment variable, if
or the value of the <envar>PGPORT</envar> set, or a compiled-in default.
environment variable (if set).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -596,42 +590,13 @@ PostgreSQL documentation
<refsect1 id="app-pgdump-diagnostics"> <refsect1 id="app-pgdump-diagnostics">
<title>Diagnostics</title> <title>Diagnostics</title>
<msgset> <para>
<msgentry> <application>pg_dump</application> internally executes
<msg> <command>SELECT</command> statements. If you have problems running
<msgmain> <application>pg_dump</application>, make sure you are able to
<msgtext> select information from the database using, for example, <xref
<screen> linkend="app-psql">.
Connection to database 'template1' failed. </para>
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>
</refsect1> </refsect1>
@ -639,11 +604,11 @@ connectDBStart() -- connect() failed: No such file or directory
<title>Notes</title> <title>Notes</title>
<para> <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 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 truly empty database; otherwise you are likely to get errors due to
duplicate definitions of the added objects. To make an empty database 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: for example:
<programlisting> <programlisting>
CREATE DATABASE foo WITH TEMPLATE template0; CREATE DATABASE foo WITH TEMPLATE template0;
@ -657,17 +622,20 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<listitem> <listitem>
<para> <para>
When dumping a single table or as plain text, <application>pg_dump</application> 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 does not handle large objects. Large objects must be dumped with the
entirety using one of the binary archive formats. entire database using one of the non-text archive formats.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
When doing a data-only dump, <application>pg_dump</application> emits queries When a data-only dump is chosen and the option
to disable triggers on user tables before inserting the data and queries to <option>--disable-triggers</> is used,
re-enable them after the data has been inserted. If the restore is stopped <application>pg_dump</application> emits commands to disable
in the middle, the system catalogs may be left in the wrong state. 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> </para>
</listitem> </listitem>
@ -732,9 +700,9 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para> <para>
The <application>pg_dump</application> utility first appeared in 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 non-plain-text output formats were introduced in
<application>PostgreSQL</application> release <literal>7.1</literal>. <application>PostgreSQL</application> release 7.1.
</para> </para>
</refsect1> </refsect1>

37
doc/src/sgml/ref/pg_dumpall.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.37 2003/03/18 00:02:11 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_dumpall.sgml,v 1.38 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,7 +18,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>pg_dumpall</command> <command>pg_dumpall</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -63,8 +63,8 @@ PostgreSQL documentation
</para> </para>
<para> <para>
<application>pg_dumpall</application> might need to connect several <application>pg_dumpall</application> needs to connect several
times to the <productname>PostgreSQL</productname> server, asking for times to the <productname>PostgreSQL</productname> server and might be asking for
a password each time. It is convenient to have a a password each time. It is convenient to have a
<filename>$HOME/.pgpass</> file in such cases. <filename>$HOME/.pgpass</> file in such cases.
</para> </para>
@ -96,7 +96,7 @@ PostgreSQL documentation
<para> <para>
Dump data as <command>INSERT</command> commands (rather Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very 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. packages.
</para> </para>
</listitem> </listitem>
@ -184,10 +184,10 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies the host name of the machine on which the database Specifies the host name of the machine on which the database
server is running. If host begins with a slash, it is used as server is running. If the value begins with a slash, it is
the directory for the Unix domain socket. The default is used as the directory for the Unix domain socket. The default
taken from the <envar>PGHOST</envar> environment variable, if is taken from the <envar>PGHOST</envar> environment variable,
set, else a Unix domain socket connection is attempted. if set, else a Unix domain socket connection is attempted.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -196,9 +196,10 @@ PostgreSQL documentation
<term>-p <replaceable>port</replaceable></term> <term>-p <replaceable>port</replaceable></term>
<listitem> <listitem>
<para> <para>
The port number on which the server is listening. Defaults to Specifies the TCP port or local Unix domain socket file
the <envar>PGPORT</envar> environment variable, if set, or a extension on which the server is listening for connections.
compiled-in default. Defaults to the <envar>PGPORT</envar> environment variable, if
set, or a compiled-in default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -237,7 +238,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Default connection parameters. Default connection parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -254,18 +255,10 @@ PostgreSQL documentation
messages will refer to <application>pg_dump</application>. messages will refer to <application>pg_dump</application>.
</para> </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> <para>
Once restored, it is wise to run <command>ANALYZE</> on each Once restored, it is wise to run <command>ANALYZE</> on each
database so the optimizer has useful statistics. You 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. databases.
</para> </para>

39
doc/src/sgml/ref/pg_resetxlog.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.6 2002/10/02 21:30:13 tgl Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -12,7 +12,7 @@ PostgreSQL documentation
<refnamediv> <refnamediv>
<refname>pg_resetxlog</refname> <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> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
@ -30,25 +30,24 @@ PostgreSQL documentation
<refsect1 id="R1-APP-PGRESETXLOG-1"> <refsect1 id="R1-APP-PGRESETXLOG-1">
<title>Description</title> <title>Description</title>
<para> <para>
<command>pg_resetxlog</command> clears the write-ahead log and <command>pg_resetxlog</command> clears the write-ahead log (WAL) and
optionally resets some fields in the <filename>pg_control</> file. This optionally resets some other control information (stored in the
function is sometimes <filename>pg_control</> file). This function is sometimes needed
needed if these files have become corrupted. if these files have become corrupted. It should be used only as a
It should be used only as a last resort, last resort, when the server will not start due to such corruption.
when the server will not start due to such corruption.
</para> </para>
<para> <para>
After running this command, it should be possible to start the server, 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 but bear in mind that the database may contain inconsistent data due to
partially-committed transactions. You should immediately dump your data, 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. inconsistencies and repair as needed.
</para> </para>
<para> <para>
This utility can only be run by the user who installed the server, because 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. For safety reasons, you must specify the data directory on the command line.
<command>pg_resetxlog</command> does not use the environment variable <command>pg_resetxlog</command> does not use the environment variable
<envar>PGDATA</>. <envar>PGDATA</>.
@ -64,12 +63,12 @@ PostgreSQL documentation
The first three of these can be set using the switches discussed below. 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 <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 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, If you are not able to determine correct values for all these fields,
<literal>-f</> can still be used, but <literal>-f</> can still be used, but
the recovered database must be treated with even more suspicion than the recovered database must be treated with even more suspicion than
usual --- an immediate dump and reload is imperative. <emphasis>Do not</> usual: an immediate dump and reload is imperative. <emphasis>Do not</>
execute any data-modifying operations in the database before you dump, execute any data-modifying operations in the database before you dump;
as any such action is likely to make the corruption worse. as any such action is likely to make the corruption worse.
</para> </para>
@ -79,8 +78,8 @@ PostgreSQL documentation
be set manually. These are only needed when be set manually. These are only needed when
<command>pg_resetxlog</command> is unable to determine appropriate values <command>pg_resetxlog</command> is unable to determine appropriate values
by reading <filename>pg_control</>. A safe value for the by reading <filename>pg_control</>. A safe value for the
next transaction ID may be determined by looking for the largest next transaction ID may be determined by looking for the numerically largest
file name in <envar>$PGDATA</><filename>/pg_clog</>, adding one, 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 and then multiplying by 1048576. Note that the file names are in
hexadecimal. It is usually easiest to specify the switch value in hexadecimal. It is usually easiest to specify the switch value in
hexadecimal too. For example, if <filename>0011</> is the largest entry hexadecimal too. For example, if <filename>0011</> is the largest entry
@ -88,7 +87,7 @@ PostgreSQL documentation
zeroes provide the proper multiplier). zeroes provide the proper multiplier).
The WAL starting address should be The WAL starting address should be
larger than any file number currently existing in 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 have two parts. For example, if <filename>000000FF0000003A</> is the
largest entry in <filename>pg_xlog</>, <literal>-l 0xFF,0x3B</> will work. 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 There is no comparably easy way to determine a next OID that's beyond
@ -109,14 +108,14 @@ PostgreSQL documentation
<title>Notes</title> <title>Notes</title>
<para> <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 running. <command>pg_resetxlog</command> will refuse to start up if
it finds a postmaster lock file in the <literal>datadir</>. If the it finds a server lock file in the data directory. If the
<application>postmaster</> crashed then a lock file may have been left server crashed then a lock file may have been left
behind; in that case you can remove the lock file to allow behind; in that case you can remove the lock file to allow
<command>pg_resetxlog</command> to run. But before you do <command>pg_resetxlog</command> to run. But before you do
so, make doubly certain that there 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> </para>
</refsect1> </refsect1>

183
doc/src/sgml/ref/pg_restore.sgml
View File

@ -1,10 +1,6 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.36 2003/03/18 00:02:11 momjian Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.37 2003/03/24 14:32:51 petere Exp $ -->
<refentry id="APP-PGRESTORE"> <refentry id="APP-PGRESTORE">
<docinfo>
<date>2001-03-06</date>
</docinfo>
<refmeta> <refmeta>
<refentrytitle>pg_restore</refentrytitle> <refentrytitle>pg_restore</refentrytitle>
<manvolnum>1</manvolnum> <manvolnum>1</manvolnum>
@ -22,7 +18,8 @@
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>pg_restore</command> <command>pg_restore</command>
<arg rep="repeat"><replaceable>options</replaceable></arg> <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>filename</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -34,36 +31,31 @@
<application>pg_restore</application> is a utility for restoring a <application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive <productname>PostgreSQL</productname> database from an archive
created by <xref linkend="app-pgdump"> in one of the non-plain-text created by <xref linkend="app-pgdump"> in one of the non-plain-text
formats. It formats. It will issue the commands necessary to reconstruct the
will issue the commands necessary to re-generate all user-defined database to the state it was in at the time it was saved. The
types, functions, tables, indexes, aggregates, and operators, as archive files also allow <application>pg_restore</application> to
well as the data in the tables. 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>
<para> <para>
The archive files contain information for <application>pg_restore</application> can operate in two modes: If
<application>pg_restore</application> to rebuild the database, but also a database name is specified, the archive is restored directly into
allow <application>pg_restore</application> to be selective about what is the database. Large objects can only be restored by using a direct
restored, or even to reorder the items prior to being restored. The database connection. Otherwise, a script containing the SQL
archive files are designed to be portable across architectures. commands necessary to rebuild the database is created (and written
</para> to a file or standard output), similar to the ones created by the
<application>pg_dump</application> plain text format. Some of the
<para> 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. 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. <application>pg_dump</application> options.
</para> </para>
<para> <para>
Obviously, <application>pg_restore</application> cannot restore information 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 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 <application>pg_restore</application> will not be able to load the data
using <command>COPY</command> statements. using <command>COPY</command> statements.
</para> </para>
@ -73,12 +65,12 @@
<title>Options</title> <title>Options</title>
<para> <para>
<command>pg_restore</command> accepts the following command <application>pg_restore</application> accepts the following command
line arguments. line arguments.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><replaceable class="parameter">archive-name</replaceable></term> <term><replaceable class="parameter">filename</replaceable></term>
<listitem> <listitem>
<para> <para>
Specifies the location of the archive file to be restored. Specifies the location of the archive file to be restored.
@ -92,7 +84,7 @@
<term><option>--data-only</option></term> <term><option>--data-only</option></term>
<listitem> <listitem>
<para> <para>
Restore only the data, no schema (definitions). Restore only the data, not the schema (data definitions).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -113,7 +105,7 @@
<listitem> <listitem>
<para> <para>
Create the database before restoring into it. (When this 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</> used only to issue the initial <literal>CREATE DATABASE</>
command. All data is restored into the database name that command. All data is restored into the database name that
appears in the archive.) appears in the archive.)
@ -128,8 +120,7 @@
<para> <para>
Connect to database <replaceable Connect to database <replaceable
class="parameter">dbname</replaceable> and restore directly class="parameter">dbname</replaceable> and restore directly
into the database. Large objects can only be restored by using into the database.
a direct database connection.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -155,14 +146,13 @@
the format, since <application>pg_restore</application> will the format, since <application>pg_restore</application> will
determine the format automatically. If specified, it can be determine the format automatically. If specified, it can be
one of the following: one of the following:
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>t</term> <term><literal>t</></term>
<listitem> <listitem>
<para> <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 archive format allows reordering and/or exclusion of schema
elements at the time the database is restored. It is also elements at the time the database is restored. It is also
possible to limit which data is reloaded at restore time. possible to limit which data is reloaded at restore time.
@ -171,10 +161,10 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>c</term> <term><literal>c</></term>
<listitem> <listitem>
<para> <para>
Archive is in the custom format of The archive is in the custom format of
<application>pg_dump</application>. This is the most <application>pg_dump</application>. This is the most
flexible format in that it allows reordering of data load flexible format in that it allows reordering of data load
as well as schema elements. This format is also compressed as well as schema elements. This format is also compressed
@ -183,6 +173,7 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -201,8 +192,7 @@
<term><option>--index=<replaceable class="parameter">index</replaceable></option></term> <term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Restore definition for named <replaceable Restore definition of named index only.
class="parameter">index</replaceable> only.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -212,7 +202,7 @@
<term><option>--list</option></term> <term><option>--list</option></term>
<listitem> <listitem>
<para> <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 can be used with the <option>-L</option> option to restrict
and reorder the items that are restored. and reorder the items that are restored.
</para> </para>
@ -228,7 +218,7 @@
CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
order they appear in the file. Lines can be moved and may also order they appear in the file. Lines can be moved and may also
be commented out by placing a <literal>;</literal> at the be commented out by placing a <literal>;</literal> at the
start of the line. start of the line. (See below for examples.)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -268,7 +258,8 @@
<para> <para>
Prevent any attempt to restore original object Prevent any attempt to restore original object
ownership. Objects will be owned by the user name used to 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -278,7 +269,7 @@
<term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term> <term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specify a procedure or function to be restored. Restore the named function only.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -327,7 +318,8 @@
<term><option>--schema-only</option></term> <term><option>--schema-only</option></term>
<listitem> <listitem>
<para> <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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -348,7 +340,7 @@
<term><option>--table=<replaceable class="parameter">table</replaceable></option></term> <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only. Restore definition and/or data of named table only.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -358,7 +350,7 @@
<term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term> <term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only. Restore named trigger only.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -431,7 +423,7 @@
</para> </para>
<para> <para>
<command>pg_restore</command> also accepts <application>pg_restore</application> also accepts
the following command line arguments for connection parameters: the following command line arguments for connection parameters:
<variablelist> <variablelist>
@ -441,8 +433,10 @@
<listitem> <listitem>
<para> <para>
Specifies the host name of the machine on which the server is Specifies the host name of the machine on which the server is
running. If host begins with a slash, it is used as the running. If the value begins with a slash, it is used as the
directory for the Unix domain socket. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -452,11 +446,11 @@
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the Internet TCP/IP port or local Unix domain socket Specifies the TCP port or local Unix domain socket file
file extension on which the server is listening for extension on which the server is listening for connections.
connections. The port number defaults to 5432, or the value Defaults to the <envar>PGPORT</envar> environment variable, if
of the <envar>PGPORT</envar> environment variable (if set). set, or a compiled-in default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -494,7 +488,7 @@
<listitem> <listitem>
<para> <para>
Default connection parameters. Default connection parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -505,45 +499,14 @@
<refsect1 id="app-pgrestore-diagnostics"> <refsect1 id="app-pgrestore-diagnostics">
<title>Diagnostics</title> <title>Diagnostics</title>
<msgset> <para>
<msgentry> When a direct database connection is specified using the
<msg> <option>-d</option> option, <application>pg_restore</application>
<msgmain> internally executes <acronym>SQL</acronym> statements. If you have
<msgtext> problems running <application>pg_restore</application>, make sure
<screen> you are able to select information from the database using, for
Connection to database 'template1' failed. example, <application>psql</application>.
connectDBStart() -- connect() failed: No such file or directory </para>
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>
</refsect1> </refsect1>
@ -556,9 +519,9 @@ connectDBStart() -- connect() failed: No such file or directory
<application>pg_restore</application> into a truly empty database; <application>pg_restore</application> into a truly empty database;
otherwise you are likely to get errors due to duplicate definitions otherwise you are likely to get errors due to duplicate definitions
of the added objects. To make an empty database without any local 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> <programlisting>
CREATE DATABASE foo WITH TEMPLATE = template0; CREATE DATABASE foo WITH TEMPLATE template0;
</programlisting> </programlisting>
</para> </para>
@ -568,8 +531,10 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
When restoring data to a pre-existing table, <application>pg_restore</application> emits queries When restoring data to a pre-existing table and the option
to disable triggers on user tables before inserting the data then emits queries to <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 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. middle, the system catalogs may be left in the wrong state.
</para> </para>
@ -601,20 +566,6 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
<refsect1 id="app-pgrestore-examples"> <refsect1 id="app-pgrestore-examples">
<title>Examples</title> <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> <para>
To dump a database called <literal>mydb</> that contains To dump a database called <literal>mydb</> that contains
large objects to a <filename>tar</filename> file: large objects to a <filename>tar</filename> file:
@ -665,7 +616,7 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
12; 145443 TABLE hs_old postgres 12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old 13; 145443 ACL hs_old
</programlisting> </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. internal archive ID assigned to each item.
</para> </para>
@ -678,8 +629,8 @@ CREATE DATABASE foo WITH TEMPLATE = template0;
6; 145402 TABLE species_records postgres 6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres ;8; 145416 TABLE ss_old postgres
</programlisting> </programlisting>
could be used as input to <command>pg_restore</command> and would only restore could be used as input to <application>pg_restore</application> and would only restore
items 10 and 6, in that order. items 10 and 6, in that order:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput> <prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
</screen> </screen>

4
doc/src/sgml/ref/pgtclsh.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtclsh.sgml,v 1.6 2003/01/19 00:13:31 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtclsh.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>pgtclsh</command> <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> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>

4
doc/src/sgml/ref/pgtksh.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtksh.sgml,v 1.6 2003/01/19 00:13:31 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/pgtksh.sgml,v 1.7 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>pgtksh</command> <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> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>

77
doc/src/sgml/ref/postgres-ref.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.30 2003/01/19 00:13:31 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -62,7 +62,7 @@ PostgreSQL documentation
<arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg> <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
</group> </group>
<arg>-S <replaceable>sort-mem</replaceable></arg> <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>-W <replaceable>seconds</replaceable></arg>
<arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg> <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
@ -72,7 +72,7 @@ PostgreSQL documentation
<title>Description</title> <title>Description</title>
<para> <para>
The <filename>postgres</filename> executable is the actual The <command>postgres</command> executable is the actual
<productname>PostgreSQL</productname> server process that processes <productname>PostgreSQL</productname> server process that processes
queries. It is normally not called directly; instead a <xref queries. It is normally not called directly; instead a <xref
linkend="app-postmaster"> multiuser server is started. linkend="app-postmaster"> multiuser server is started.
@ -80,7 +80,7 @@ PostgreSQL documentation
<para> <para>
The second form above is how 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 linkend="app-postmaster"> (only
conceptually, since both <filename>postmaster</filename> and conceptually, since both <filename>postmaster</filename> and
<filename>postgres</filename> are in fact the same program); it <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 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 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 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 debugging the server since no realistic interprocess communication
and locking will happen. and locking will happen.
</para> </para>
<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 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 kinds of accidental damage to the system catalogs. Implicit
superuser powers are granted to the user with ID 1 in stand-alone superuser powers are granted to the user with ID 1 in stand-alone
mode. mode.
@ -113,11 +113,11 @@ PostgreSQL documentation
<title>Options</title> <title>Options</title>
<para> <para>
When <application>postgres</application> is started by a <xref When <command>postgres</command> is started by a <xref
linkend="app-postmaster"> then it linkend="app-postmaster"> then it
inherits all options set by the latter. Additionally, inherits all options set by the latter. Additionally,
<application>postgres</application>-specific options can be passed <command>postgres</command>-specific options can be passed
from the <application>postmaster</application> with the from the <command>postmaster</command> with the
<option>-o</option> switch. <option>-o</option> switch.
</para> </para>
@ -129,7 +129,7 @@ PostgreSQL documentation
variable <envar>PGOPTIONS</envar> is set, then variable <envar>PGOPTIONS</envar> is set, then
<application>libpq</>-based clients will pass that string to the <application>libpq</>-based clients will pass that string to the
server, which will interpret it as server, which will interpret it as
<application>postgres</application> command-line options. <command>postgres</command> command-line options.
</para> </para>
<refsect2> <refsect2>
@ -138,10 +138,10 @@ PostgreSQL documentation
<para> <para>
The options <option>-A</option>, <option>-B</option>, The options <option>-A</option>, <option>-B</option>,
<option>-c</option>, <option>-d</option>, <option>-D</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 as the <xref linkend="app-postmaster"> except that
<option>-d</option> <literal>0</> prevents the debugging level of <literal>-d 0</> prevents the server log level of
the postmaster from being propagated to the backend. the <command>postmaster</> from being propagated to <command>postgres</>.
</para> </para>
<variablelist> <variablelist>
@ -162,12 +162,12 @@ PostgreSQL documentation
<term><option>-o</option> <replaceable class="parameter">filename</replaceable></term> <term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
<listitem> <listitem>
<para> <para>
Sends all debugging and error output to Send all server log output to
<replaceable class="parameter">filename</replaceable>. <replaceable class="parameter">filename</replaceable>.
If the backend is running under the If <command>postgres</command> is running under the
<application>postmaster</application>, this option is ignored, <command>postmaster</command>, this option is ignored,
and the <systemitem>stderr</> inherited from the and the <systemitem>stderr</> inherited from the
<application>postmaster</application> is used. <command>postmaster</command> is used.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -176,7 +176,7 @@ PostgreSQL documentation
<term><option>-P</option></term> <term><option>-P</option></term>
<listitem> <listitem>
<para> <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 <command>REINDEX</command> command for system tables/indexes
requires this option to be used. requires this option to be used.
</para> </para>
@ -187,7 +187,7 @@ PostgreSQL documentation
<term><option>-s</option></term> <term><option>-s</option></term>
<listitem> <listitem>
<para> <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 This is useful for benchmarking or for use in tuning the number of
buffers. buffers.
</para> </para>
@ -200,7 +200,7 @@ PostgreSQL documentation
<para> <para>
Specifies the amount of memory to be used by internal sorts and hashes Specifies the amount of memory to be used by internal sorts and hashes
before resorting to temporary disk files. The value is specified in 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 several sorts and/or hashes might be running in parallel, and each one
will be allowed to use as much as will be allowed to use as much as
<replaceable class="parameter">sort-mem</replaceable> kilobytes <replaceable class="parameter">sort-mem</replaceable> kilobytes
@ -230,7 +230,7 @@ PostgreSQL documentation
<term><option>-E</option></term> <term><option>-E</option></term>
<listitem> <listitem>
<para> <para>
Echo all queries. Echo all commands.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -239,7 +239,7 @@ PostgreSQL documentation
<term><option>-N</option></term> <term><option>-N</option></term>
<listitem> <listitem>
<para> <para>
Disables use of newline as a query delimiter. Disables use of newline as a statement delimiter.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -268,6 +268,7 @@ PostgreSQL documentation
disable sequential and index scans respectively, while disable sequential and index scans respectively, while
<literal>n</literal>, <literal>m</literal>, and <literal>h</literal> <literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
disable nested-loop, merge and hash joins respectively. disable nested-loop, merge and hash joins respectively.
</para>
<note> <note>
<para> <para>
@ -277,7 +278,6 @@ PostgreSQL documentation
plan types if it has any other alternative. plan types if it has any other alternative.
</para> </para>
</note> </note>
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -295,7 +295,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Allows the structure of system tables to be modified. This is Allows the structure of system tables to be modified. This is
used by <application>initdb</application>. used by <command>initdb</command>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -304,9 +304,8 @@ PostgreSQL documentation
<term><option>-p</option> <replaceable class="parameter">database</replaceable></term> <term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
<listitem> <listitem>
<para> <para>
Indicates that this server has been started by a Indicates that this process has been started by a
<application>postmaster</application> and makes different <command>postmaster</command> and specifies the database to use.
assumptions about buffer pool management, file descriptors,
etc. etc.
</para> </para>
</listitem> </listitem>
@ -339,7 +338,7 @@ PostgreSQL documentation
<para> <para>
As soon as this option is encountered, the process sleeps for As soon as this option is encountered, the process sleeps for
the specified amount of seconds. This gives developers time 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -375,10 +374,10 @@ PostgreSQL documentation
<para> <para>
To stop a running query use the <literal>SIGINT</literal> signal. To 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 use a <literal>SIGHUP</literal> signal. The
<application>postmaster</application> uses <literal>SIGTERM</literal> <command>postmaster</command> uses <literal>SIGTERM</literal>
to tell a postgres process to quit normally and to tell a <command>postgres</command> process to quit normally and
<literal>SIGQUIT</literal> to terminate without the normal cleanup. <literal>SIGQUIT</literal> to terminate without the normal cleanup.
These <emphasis>should not</emphasis> be used by users. These <emphasis>should not</emphasis> be used by users.
</para> </para>
@ -389,17 +388,17 @@ PostgreSQL documentation
<title>Usage</title> <title>Usage</title>
<para> <para>
Start a stand-alone backend with a command like Start a stand-alone server with a command like
<screen> <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> </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. make sure that the environment variable <envar>PGDATA</> is set.
Also specify the name of the particular database you want to work in. Also specify the name of the particular database you want to work in.
</para> </para>
<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, entry terminator; there is no intelligence about semicolons,
as there is in <application>psql</>. To continue a command as there is in <application>psql</>. To continue a command
across multiple lines, you must type backslash just before each across multiple lines, you must type backslash just before each
@ -408,9 +407,9 @@ PostgreSQL documentation
<para> <para>
But if you use the <option>-N</> command line switch, then newline does 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 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. treated specially in this case.
</para> </para>
@ -422,7 +421,7 @@ PostgreSQL documentation
</para> </para>
<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). line-editing features (no command history, for example).
</para> </para>

157
doc/src/sgml/ref/postmaster.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.34 2003/01/19 00:13:31 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.35 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -41,33 +41,33 @@ PostgreSQL documentation
<title>Description</title> <title>Description</title>
<para> <para>
<application>postmaster</application> is the <command>postmaster</command> is the
<productname>PostgreSQL</productname> multiuser database server. <productname>PostgreSQL</productname> multiuser database server.
In order for a client application to access a database it connects In order for a client application to access a database it connects
(over a network or locally) to a running (over a network or locally) to a running
<application>postmaster</application>. The <command>postmaster</command>. The
<application>postmaster</application> then starts a separate server <command>postmaster</command> then starts a separate server
process (<quote><xref linkend="app-postgres"></quote>) to handle 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. manages the communication among server processes.
</para> </para>
<para> <para>
By default the <application>postmaster</application> starts in the By default the <command>postmaster</command> starts in the
foreground and prints log messages to the standard output. In foreground and prints log messages to the standard error stream. In
practical applications the <application>postmaster</application> practical applications the <command>postmaster</command>
should be started as a background process, perhaps at boot time. should be started as a background process, perhaps at boot time.
</para> </para>
<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 from exactly one database cluster. A database cluster is a
collection of databases that is stored at a common file system 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 of the database cluster files (<quote>data area</quote>). This is
done with the <option>-D</option> invocation option or the done with the <option>-D</option> invocation option or the
<envar>PGDATA</envar> environment variable; there is no default. <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 as long as they use different data areas and different
communication ports (see below). A data area is created with <xref communication ports (see below). A data area is created with <xref
linkend="app-initdb">. linkend="app-initdb">.
@ -78,17 +78,17 @@ PostgreSQL documentation
<title>Options</title> <title>Options</title>
<para> <para>
<application>postmaster</application> accepts the following <command>postmaster</command> accepts the following
command line arguments. For a detailed discussion of the options command line arguments. For a detailed discussion of the options
consult the &cite-admin;. You can also save typing most of these consult the &cite-admin;. You can also save typing most of these
options by setting up a configuration file. options by setting up a configuration file.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>-A 0|1</term> <term><option>-A 0|1</option></term>
<listitem> <listitem>
<para> <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 detect programming mistakes. This is only available if it was
enabled during compilation. If so, the default is on. enabled during compilation. If so, the default is on.
</para> </para>
@ -96,7 +96,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-B <replaceable class="parameter">nbuffers</replaceable></term> <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Sets the number of shared buffers for use by the server Sets the number of shared buffers for use by the server
@ -107,7 +107,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term> <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Sets a named run-time parameter. Consult the &cite-admin; for Sets a named run-time parameter. Consult the &cite-admin; for
@ -120,7 +120,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-d <replaceable>debug-level</replaceable></term> <term><option>-d <replaceable>debug-level</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Sets the debug level. The higher this value is set, the more Sets the debug level. The higher this value is set, the more
@ -131,7 +131,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-D <replaceable class="parameter">datadir</replaceable></term> <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the file system location of the data directory. See Specifies the file system location of the data directory. See
@ -141,12 +141,12 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-F</term> <term><option>-F</option></term>
<listitem> <listitem>
<para> <para>
Disables <function>fsync</function> calls for performance Disables <function>fsync</function> calls for performance
improvement, at the risk of data corruption in event of a 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 <literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
documentation before using this! documentation before using this!
</para> </para>
@ -158,11 +158,11 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-h <replaceable class="parameter">hostname</replaceable></term> <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the TCP/IP host name or address on which the Specifies the IP host name or address on which the
<application>postmaster</application> is to listen for <command>postmaster</command> is to listen for
connections from client applications. Defaults to connections from client applications. Defaults to
listening on all configured addresses (including listening on all configured addresses (including
<systemitem class="systemname">localhost</systemitem>). <systemitem class="systemname">localhost</systemitem>).
@ -171,7 +171,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-i</term> <term><option>-i</option></term>
<listitem> <listitem>
<para> <para>
Allows clients to connect via TCP/IP (Internet domain) 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</>. to setting <literal>tcpip_socket=true</> in <filename>postgresql.conf</>.
</para> </para>
<para> <para>
<option>--tcpip_socket=false</option> has the opposite <option>--tcpip-socket=false</option> has the opposite
effect of this option. effect of this option.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-k <replaceable class="parameter">directory</replaceable></term> <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the directory of the Unix-domain socket on which the 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 connections from client applications. The default is normally
<filename>/tmp</filename>, but can be changed at build time. <filename>/tmp</filename>, but can be changed at build time.
</para> </para>
@ -199,7 +199,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-l</term> <term><option>-l</option></term>
<listitem> <listitem>
<para> <para>
Enables secure connections using SSL. The <option>-i</option> Enables secure connections using SSL. The <option>-i</option>
@ -210,11 +210,11 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-N <replaceable class="parameter">max-connections</replaceable></term> <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Sets the maximum number of client connections that this 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 default, this value is 32, but it can be set as high as your
system will support. (Note that system will support. (Note that
<option>-B</option> is required to be at least twice <option>-B</option> is required to be at least twice
@ -226,13 +226,13 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-o <replaceable class="parameter">extra-options</replaceable></term> <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
<listitem> <listitem>
<para> <para>
The command line-style options specified in <replaceable The command line-style options specified in <replaceable
class="parameter">extra-options</replaceable> are passed to class="parameter">extra-options</replaceable> are passed to
all backend server processes started by this all server processes started by this
<application>postmaster</application>. See <xref <command>postmaster</command>. See <xref
linkend="app-postgres"> for possibilities. If the option linkend="app-postgres"> for possibilities. If the option
string contains any spaces, the entire string must be quoted. string contains any spaces, the entire string must be quoted.
</para> </para>
@ -240,11 +240,11 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-p <replaceable class="parameter">port</replaceable></term> <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the TCP/IP port or local Unix domain socket file 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. is to listen for connections from client applications.
Defaults to the value of the <envar>PGPORT</envar> environment Defaults to the value of the <envar>PGPORT</envar> environment
variable, or if <envar>PGPORT</envar> is not set, then variable, or if <envar>PGPORT</envar> is not set, then
@ -257,10 +257,10 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-S</term> <term><option>-S</option></term>
<listitem> <listitem>
<para> <para>
Specifies that the <application>postmaster</application> Specifies that the <command>postmaster</command>
process should start up in silent mode. That is, it will process should start up in silent mode. That is, it will
disassociate from the user's (controlling) terminal, start its disassociate from the user's (controlling) terminal, start its
own process group, and redirect its standard output and own process group, and redirect its standard output and
@ -270,17 +270,17 @@ PostgreSQL documentation
Using this switch discards all logging output, which is Using this switch discards all logging output, which is
probably not what you want, since it makes it very difficult probably not what you want, since it makes it very difficult
to troubleshoot problems. See below for a better way to start 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>
<para> <para>
<option>--silent_mode=false</option> has the opposite effect <option>--silent-mode=false</option> has the opposite effect
of this option. of this option.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term> <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Sets a named run-time parameter; a shorter form of Sets a named run-time parameter; a shorter form of
@ -294,17 +294,18 @@ PostgreSQL documentation
<para> <para>
Two additional command line options are available for debugging Two additional command line options are available for debugging
problems that cause a backend to die abnormally. These options problems that cause a server process to die abnormally. The
control the behavior of the <application>postmaster</application> ordinary strategy in this situation is to notify all other server
in this situation, and <emphasis>neither option is intended for processes that they must terminate and then reinitialize the
use in ordinary operation</emphasis>. 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>
<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>
<para> <para>
@ -312,10 +313,10 @@ PostgreSQL documentation
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>-n</term> <term><option>-n</option></term>
<listitem> <listitem>
<para> <para>
<application>postmaster</application> <command>postmaster</command>
will not reinitialize shared data structures. A knowledgeable system will not reinitialize shared data structures. A knowledgeable system
programmer can then use a debugger programmer can then use a debugger
to examine shared memory and semaphore state. to examine shared memory and semaphore state.
@ -324,14 +325,14 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-s</term> <term><option>-s</option></term>
<listitem> <listitem>
<para> <para>
<application>postmaster</application> <command>postmaster</command>
will stop all other backend processes by sending the signal will stop all other server processes by sending the signal
<literal>SIGSTOP</literal>, <literal>SIGSTOP</literal>,
but will not cause them to terminate. This permits system programmers 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -367,7 +368,7 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><envar>PGDATASTYLE</envar></term> <term><envar>PGDATESTYLE</envar></term>
<listitem> <listitem>
<para> <para>
@ -418,22 +419,17 @@ PostgreSQL documentation
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><computeroutput> <term><computeroutput>semget: No space left on device</computeroutput></term>
semget: No space left on device
</computeroutput></term>
<listitem> <listitem>
<para> <para>
If you see this message, you should run the If you see this message, you probably need to configure
<application>ipcclean</application> your kernel for shared memory and semaphores as described in the &cite-admin;.
command. After doing so, try starting If you run multiple instances of
<application>postmaster</application> <command>postmaster</command>
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>
on a single host, or have a kernel with particularly small shared memory 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 and/or semaphore limits, you may have to reconfigure your kernel to increase
its shared memory or semaphore parameters. its shared memory or semaphore parameters.
</para>
<tip> <tip>
<para> <para>
@ -444,18 +440,15 @@ semget: No space left on device
consumption. consumption.
</para> </para>
</tip> </tip>
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><computeroutput> <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term>
StreamServerPort: cannot bind to port
</computeroutput></term>
<listitem> <listitem>
<para> <para>
If you see this message, you should make certain that there is no 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 process already running on the same port number. The easiest way to
determine this is by using the command determine this is by using the command
<screen> <screen>
@ -471,18 +464,18 @@ StreamServerPort: cannot bind to port
<para> <para>
If you If you
are sure that no other are sure that no other
<application>postmaster</application> <command>postmaster</command>
processes are running and you still get this error, try specifying a processes are running and you still get this error, try specifying a
different port using the different port using the
<literal>-p</literal> <literal>-p</literal>
option. You may also get this error if you terminate the 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 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 simply wait a few seconds until the operating system closes the port
before trying again. Finally, you may get this error if you specify before trying again. Finally, you may get this error if you specify
a port number that your operating system considers to be reserved. a port number that your operating system considers to be reserved.
For example, many versions of Unix consider port numbers under 1024 to 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. and only permit the Unix superuser to access them.
</para> </para>
</listitem> </listitem>
@ -497,14 +490,14 @@ StreamServerPort: cannot bind to port
<para> <para>
If at all possible, <emphasis>do not</emphasis> use If at all possible, <emphasis>do not</emphasis> use
<literal>SIGKILL</literal> to kill the <literal>SIGKILL</literal> to kill the
<application>postmaster</application>. This will prevent <command>postmaster</command>. This will prevent
<application>postmaster</application> from freeing the system <command>postmaster</command> from freeing the system
resources (e.g., shared memory and semaphores) that it holds before resources (e.g., shared memory and semaphores) that it holds before
terminating. terminating.
</para> </para>
<para> <para>
To terminate the <application>postmaster</application> normally, To terminate the <command>postmaster</command> normally,
the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>, the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
or <literal>SIGQUIT</literal> can be used. The first will wait for or <literal>SIGQUIT</literal> can be used. The first will wait for
all clients to terminate before quitting, the second will all clients to terminate before quitting, the second will
@ -515,7 +508,7 @@ StreamServerPort: cannot bind to port
<para> <para>
The utility command <xref linkend="app-pg-ctl"> can be used to 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. safely and comfortably.
</para> </para>
@ -532,7 +525,7 @@ StreamServerPort: cannot bind to port
<refsect1 id="app-postmaster-examples"> <refsect1 id="app-postmaster-examples">
<title>Examples</title> <title>Examples</title>
<para> <para>
To start <application>postmaster</application> in the background To start <command>postmaster</command> in the background
using default values, type: using default values, type:
<screen> <screen>
@ -541,14 +534,14 @@ StreamServerPort: cannot bind to port
</para> </para>
<para> <para>
To start <application>postmaster</application> with a specific To start <command>postmaster</command> with a specific
port: port:
<screen> <screen>
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput> <prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
</screen> </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 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 run it as
<screen> <screen>
<prompt>$</prompt> <userinput>psql -p 1234</userinput> <prompt>$</prompt> <userinput>psql -p 1234</userinput>

350
doc/src/sgml/ref/psql-ref.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.85 2003/02/13 05:37:43 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/psql-ref.sgml,v 1.86 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -20,9 +20,9 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>psql</command> <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">dbname</replaceable>
<arg><replaceable class="parameter">user</replaceable></arg></arg> <arg><replaceable class="parameter">username</replaceable></arg></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -69,17 +69,17 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-c <replaceable class="parameter">query</replaceable></></term> <term><option>-c <replaceable class="parameter">command</replaceable></></term>
<term><option>--command <replaceable class="parameter">query</replaceable></></term> <term><option>--command <replaceable class="parameter">command</replaceable></></term>
<listitem> <listitem>
<para> <para>
Specifies that <application>psql</application> is to execute one 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. and then exit. This is useful in shell scripts.
</para> </para>
<para> <para>
<replaceable class="parameter">query</replaceable> must be either <replaceable class="parameter">command</replaceable> must be either
a query string that is completely parsable by the backend (i.e., a command string that is completely parsable by the server (i.e.,
it contains no <application>psql</application> specific features), it contains no <application>psql</application> specific features),
or it is a single backslash command. Thus you cannot mix or it is a single backslash command. Thus you cannot mix
<acronym>SQL</acronym> and <application>psql</application> <acronym>SQL</acronym> and <application>psql</application>
@ -108,7 +108,7 @@ PostgreSQL documentation
<term><option>--echo-queries</></term> <term><option>--echo-queries</></term>
<listitem> <listitem>
<para> <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 to setting the variable <varname>ECHO</varname> to
<literal>queries</literal>. <literal>queries</literal>.
</para> </para>
@ -120,7 +120,7 @@ PostgreSQL documentation
<term><option>--echo-hidden</></term> <term><option>--echo-hidden</></term>
<listitem> <listitem>
<para> <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 commands. You can use this if you wish to include similar
functionality into your own programs. This is equivalent to functionality into your own programs. This is equivalent to
setting the variable <varname>ECHO_HIDDEN</varname> from within setting the variable <varname>ECHO_HIDDEN</varname> from within
@ -135,7 +135,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Use the file <replaceable class="parameter">filename</replaceable> 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> After the file is processed, <application>psql</application>
terminates. This is in many ways equivalent to the internal terminates. This is in many ways equivalent to the internal
command <command>\i</command>. command <command>\i</command>.
@ -179,7 +179,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies the host name of the machine on which the 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 with a slash, it is used as the directory for the Unix-domain
socket. socket.
</para> </para>
@ -191,7 +191,7 @@ PostgreSQL documentation
<term><option>--html</></term> <term><option>--html</></term>
<listitem> <listitem>
<para> <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 equivalent to <literal>\pset format html</literal> or the
<command>\H</command> command. <command>\H</command> command.
</para> </para>
@ -203,7 +203,7 @@ PostgreSQL documentation
<term><option>--list</></term> <term><option>--list</></term>
<listitem> <listitem>
<para> <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 options are ignored. This is similar to the internal command
<command>\list</command>. <command>\list</command>.
</para> </para>
@ -227,9 +227,8 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <para>
Specifies the TCP/IP port or, by omission, the local Unix domain Specifies the TCP port or the local Unix domain
socket file extension on which the socket file extension on which the server is listening for
<application>postmaster</application> is listening for
connections. Defaults to the value of the <envar>PGPORT</envar> connections. Defaults to the value of the <envar>PGPORT</envar>
environment variable or, if not set, to the port specified at environment variable or, if not set, to the port specified at
compile time, usually 5432. compile time, usually 5432.
@ -284,7 +283,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Run in single-step mode. That means the user is prompted before 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. execution as well. Use this to debug scripts.
</para> </para>
</listitem> </listitem>
@ -295,7 +294,7 @@ PostgreSQL documentation
<term><option>--single-line</></term> <term><option>--single-line</></term>
<listitem> <listitem>
<para> <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. semicolon does.
</para> </para>
@ -345,7 +344,7 @@ PostgreSQL documentation
<para> <para>
This option is deprecated, as it is conceptually flawed. This option is deprecated, as it is conceptually flawed.
(Prompting for a non-default user name and prompting for a (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 things.) You are encouraged to look at the <option>-U</option> and
<option>-W</option> options instead. <option>-W</option> options instead.
</para> </para>
@ -357,7 +356,7 @@ PostgreSQL documentation
<term><option>--username <replaceable class="parameter">username</replaceable></></term> <term><option>--username <replaceable class="parameter">username</replaceable></></term>
<listitem> <listitem>
<para> <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. class="parameter">username</replaceable> instead of the default.
(You must have permission to do so, of course.) (You must have permission to do so, of course.)
</para> </para>
@ -370,7 +369,7 @@ PostgreSQL documentation
<term><option>--variable <replaceable class="parameter">assignment</replaceable></></term> <term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
<listitem> <listitem>
<para> <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 internal command. Note that you must separate name and value, if
any, by an equal sign on the command line. To unset a variable, 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, leave off the equal sign. To just set a variable without a value,
@ -386,7 +385,7 @@ PostgreSQL documentation
<term><option>--version</></term> <term><option>--version</></term>
<listitem> <listitem>
<para> <para>
Shows the <application>psql</application> version. Show the <application>psql</application> version.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -404,11 +403,11 @@ PostgreSQL documentation
<para> <para>
In the current version, <application>psql</application> 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 requests password authentication. Because this is currently based
on a hack, the automatic recognition might mysteriously fail, on a hack, the automatic recognition might mysteriously fail,
hence this option to force a prompt. If no password prompt is 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. connection attempt will fail.
</para> </para>
</listitem> </listitem>
@ -419,7 +418,7 @@ PostgreSQL documentation
<term><option>--expanded</></term> <term><option>--expanded</></term>
<listitem> <listitem>
<para> <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>. command <command>\x</command>.
</para> </para>
</listitem> </listitem>
@ -440,7 +439,7 @@ PostgreSQL documentation
<term><option>--help</></term> <term><option>--help</></term>
<listitem> <listitem>
<para> <para>
Shows help about <application>psql</application> command line Show help about <application>psql</application> command line
arguments. arguments.
</para> </para>
</listitem> </listitem>
@ -455,8 +454,8 @@ PostgreSQL documentation
<para> <para>
<application>psql</application> returns 0 to the shell if it <application>psql</application> returns 0 to the shell if it
finished normally, 1 if a fatal error of its own (out of memory, 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 file not found) occurs, 2 if the connection to the server went bad
and the session is not interactive, and 3 if an error occurred in a 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. script and the variable <varname>ON_ERROR_STOP</varname> was set.
</para> </para>
</refsect1> </refsect1>
@ -495,13 +494,13 @@ PostgreSQL documentation
<para> <para>
If the connection could not be made for any reason (e.g., insufficient 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. <application>psql</application> will return an error and terminate.
</para> </para>
</refsect2> </refsect2>
<refsect2 id="R2-APP-PSQL-4"> <refsect2 id="R2-APP-PSQL-4">
<title>Entering Queries</title> <title>Entering SQL Commands</title>
<para> <para>
In normal operation, <application>psql</application> provides a In normal operation, <application>psql</application> provides a
@ -523,16 +522,16 @@ testdb=>
</para> </para>
<para> <para>
At the prompt, the user may type in <acronym>SQL</acronym> queries. At the prompt, the user may type in <acronym>SQL</acronym> commands.
Ordinarily, input lines are sent to the backend when a Ordinarily, input lines are sent to the server when a
query-terminating semicolon is reached. An end of line does not command-terminating semicolon is reached. An end of line does not
terminate a query! Thus queries can be spread over several lines for terminate a command. Thus commands can be spread over several lines for
clarity. If the query was sent and without error, the query results clarity. If the command was sent and without error, the results of the command
are displayed on the screen. are displayed on the screen.
</para> </para>
<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 for asynchronous notification events generated by
<xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and <xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
<xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">. <xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
@ -586,18 +585,23 @@ testdb=>
</para> </para>
<para> <para>
Some commands take an <acronym>SQL</acronym> identifier Some commands take an <acronym>SQL</acronym> identifier (such as a
(such as a table name) as argument. These arguments follow the table name) as argument. These arguments follow the syntax rules
syntax rules of <acronym>SQL</acronym> regarding double quotes: an of <acronym>SQL</acronym>: Unquoted letters are forced to
identifier without double quotes is coerced to lower-case, while lowercase, while double quotes (<literal>"</>) protect letters
whitespace within double quotes is included in the argument. 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>
<para> <para>
Parsing for arguments stops when another unquoted backslash occurs. Parsing for arguments stops when another unquoted backslash occurs.
This is taken as the beginning of a new meta-command. The special This is taken as the beginning of a new meta-command. The special
sequence <literal>\\</literal> (two backslashes) marks the end of 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 any. That way <acronym>SQL</acronym> and
<application>psql</application> commands can be freely mixed on a <application>psql</application> commands can be freely mixed on a
line. But in any case, the arguments of a meta-command cannot line. But in any case, the arguments of a meta-command cannot
@ -612,8 +616,8 @@ testdb=>
<term><literal>\a</literal></term> <term><literal>\a</literal></term>
<listitem> <listitem>
<para> <para>
If the current table output format is unaligned, switch to aligned. If the current table output format is unaligned, it is switched to aligned.
If it is not unaligned, set it to unaligned. This command is If it is not unaligned, it is set to unaligned. This command is
kept for backwards compatibility. See <command>\pset</command> for a kept for backwards compatibility. See <command>\pset</command> for a
general solution. general solution.
</para> </para>
@ -624,8 +628,8 @@ testdb=>
<term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term> <term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
<listitem> <listitem>
<para> <para>
Change the current working directory to Changes the current working directory to
<replaceable>directory</replaceable>. Without argument, change <replaceable>directory</replaceable>. Without argument, changes
to the current user's home directory. to the current user's home directory.
</para> </para>
@ -641,7 +645,7 @@ testdb=>
<term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term> <term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
<listitem> <listitem>
<para> <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 query or unset any such title. This command is equivalent to
<literal>\pset title <replaceable <literal>\pset title <replaceable
class="parameter">title</replaceable></literal>. (The name of class="parameter">title</replaceable></literal>. (The name of
@ -701,10 +705,10 @@ testdb=>
<para> <para>
Performs a frontend (client) copy. This is an operation that Performs a frontend (client) copy. This is an operation that
runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY" 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, reading or writing the specified file,
<application>psql</application> reads or writes the file and <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 This means that file accessibility and privileges are those
of the local user, not the server, and no SQL superuser of the local user, not the server, and no SQL superuser
privileges are required. privileges are required.
@ -712,8 +716,8 @@ testdb=>
<para> <para>
The syntax of the command is similar to that of the The syntax of the command is similar to that of the
<acronym>SQL</acronym> <command>COPY</command> command (see its <acronym>SQL</acronym> <command>COPY</command> command. (See its
description for the details). Note that, because of this, description for the details.) Note that, because of this,
special parsing rules apply to the <command>\copy</command> special parsing rules apply to the <command>\copy</command>
command. In particular, the variable substitution rules and command. In particular, the variable substitution rules and
backslash escapes do not apply. backslash escapes do not apply.
@ -723,7 +727,7 @@ testdb=>
<para> <para>
This operation is not as efficient as the <acronym>SQL</acronym> This operation is not as efficient as the <acronym>SQL</acronym>
<command>COPY</command> command because all data must pass <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. amounts of data the other technique may be preferable.
</para> </para>
</tip> </tip>
@ -732,9 +736,9 @@ testdb=>
<para> <para>
Note the difference in interpretation of Note the difference in interpretation of
<literal>stdin</literal> and <literal>stdout</literal> between <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 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 wherever the <command>COPY</command> itself came from (for
example, a script run with the <option>-f</option> option), and example, a script run with the <option>-f</option> option), and
<literal>stdout</literal> refers to the query output stream (see <literal>stdout</literal> refers to the query output stream (see
@ -792,7 +796,7 @@ testdb=>
<para> <para>
Lists all available aggregate functions, together with the data Lists all available aggregate functions, together with the data
type they operate on. If <replaceable type they operate on. If <replaceable
class="parameter">pattern</replaceable> (a regular expression) class="parameter">pattern</replaceable>
is specified, only matching aggregates are shown. is specified, only matching aggregates are shown.
</para> </para>
</listitem> </listitem>
@ -845,16 +849,8 @@ testdb=>
<para> <para>
Descriptions for objects can be created with the Descriptions for objects can be created with the
<command>COMMENT ON</command> <acronym>SQL</acronym> command. <command>COMMENT</command> <acronym>SQL</acronym> command.
</para> </para>
<note>
<para>
<productname>PostgreSQL</productname> stores the object
descriptions in the <structname>pg_description</> system table.
</para>
</note>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -863,7 +859,7 @@ testdb=>
<term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term> <term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
<listitem> <listitem>
<para> <para>
Lists all available domains (derived types). If <replaceable Lists all available domains. If <replaceable
class="parameter">pattern</replaceable> class="parameter">pattern</replaceable>
is specified, only matching domains are shown. is specified, only matching domains are shown.
</para> </para>
@ -907,12 +903,12 @@ testdb=>
order, to obtain a listing of all the matching objects. The letter order, to obtain a listing of all the matching objects. The letter
S restricts the listing to system objects; without S, only non-system S restricts the listing to system objects; without S, only non-system
objects are shown. 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. listed with its associated description, if any.
</para> </para>
<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. specified, only objects whose name matches the pattern are listed.
</para> </para>
</listitem> </listitem>
@ -948,7 +944,7 @@ testdb=>
<listitem> <listitem>
<para> <para>
Lists available operators with their operand and return types. 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. specified, only operators whose name matches the pattern are listed.
</para> </para>
</listitem> </listitem>
@ -960,15 +956,15 @@ testdb=>
<listitem> <listitem>
<para> <para>
Produces a list of all available tables with their Produces a list of all available tables with their
associated access permissions. associated access privileges.
If a <replaceable class="parameter">pattern</replaceable> is If <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed. specified, only tables whose name matches the pattern are listed.
</para> </para>
<para> <para>
The commands <xref linkend="SQL-GRANT"> and The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE"> <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. for more information.
</para> </para>
</listitem> </listitem>
@ -991,7 +987,7 @@ testdb=>
<term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term> <term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem> <listitem>
<para> <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>. class="parameter">pattern</replaceable>.
</para> </para>
</listitem> </listitem>
@ -1063,13 +1059,13 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem> <listitem>
<para> <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. shows the current encoding.
</para> </para>
<note> <note>
<para> <para>
This command will not notice changes made directly by <command>SET 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. be sure to use it to set as well as examine the encoding.
</para> </para>
</note> </note>
@ -1083,7 +1079,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem> <listitem>
<para> <para>
Sets the field separator for unaligned query output. The default 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 <command>\pset</command> for a generic way of setting output
options. options.
</para> </para>
@ -1096,7 +1092,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem> <listitem>
<para> <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 optionally saves the output in <replaceable
class="parameter">filename</replaceable> or pipes the output class="parameter">filename</replaceable> or pipes the output
into a separate Unix shell to execute <replaceable 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> <term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
<listitem> <listitem>
<para> <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> command. If <replaceable class="parameter">command</replaceable>
is not specified, then <application>psql</application> will list is not specified, then <application>psql</application> will list
all the commands for which syntax help is available. If all the commands for which syntax help is available. If
<replaceable class="parameter">command</replaceable> is an <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. <acronym>SQL</acronym> commands is shown.
</para> </para>
@ -1169,8 +1165,8 @@ Tue Oct 26 21:40:57 CEST 1999
<term><literal>\l</literal> (or <literal>\list</literal>)</term> <term><literal>\l</literal> (or <literal>\list</literal>)</term>
<listitem> <listitem>
<para> <para>
List the names, owners, and encodings of all the databases in List the names, owners, and character set encodings of all the databases in
the server. Append a <quote>+</quote> to the command name to the server. Append a <literal>+</literal> to the command name to
see any descriptions for the databases as well. see any descriptions for the databases as well.
</para> </para>
</listitem> </listitem>
@ -1214,13 +1210,13 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem> <listitem>
<para> <para>
Stores the file into a <productname>PostgreSQL</productname> 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: comment with the object. Example:
<programlisting> <programlisting>
foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput> foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
lo_import 152801 lo_import 152801
</programlisting> </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 152801 which one ought to remember if one wants to access the
object ever again. For that reason it is recommended to always object ever again. For that reason it is recommended to always
associate a human-readable comment with every object. Those can associate a human-readable comment with every object. Those can
@ -1249,7 +1245,7 @@ lo_import 152801
<listitem> <listitem>
<para> <para>
Shows a list of all <productname>PostgreSQL</productname> 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. along with any comments provided for them.
</para> </para>
</listitem> </listitem>
@ -1291,8 +1287,7 @@ lo_import 152801
class="parameter">filename</replaceable> or pipes future results class="parameter">filename</replaceable> or pipes future results
into a separate Unix shell to execute <replaceable into a separate Unix shell to execute <replaceable
class="parameter">command</replaceable>. If no arguments are class="parameter">command</replaceable>. If no arguments are
specified, the query output will be reset to specified, the query output will be reset to the standard output.
<filename>stdout</filename>.
</para> </para>
<para> <para>
@ -1349,7 +1344,7 @@ lo_import 152801
</para> </para>
<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 line, separated by the currently active field separator. This
is intended to create output that might be intended to be read is intended to create output that might be intended to be read
in by other programs (tab-separated, comma-separated). in by other programs (tab-separated, comma-separated).
@ -1385,14 +1380,14 @@ lo_import 152801
<listitem> <listitem>
<para> <para>
Toggles between regular and expanded format. When expanded 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 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 useful if the data wouldn't fit on the screen in the normal
<quote>horizontal</quote> mode. <quote>horizontal</quote> mode.
</para> </para>
<para> <para>
Expanded mode is supported by all four output modes. Expanded mode is supported by all four output formats.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1402,7 +1397,7 @@ lo_import 152801
<listitem> <listitem>
<para> <para>
The second argument is a string that should be printed 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 anything, which can easily be mistaken for, say, an empty
string. Thus, one might choose to write <literal>\pset null string. Thus, one might choose to write <literal>\pset null
'(null)'</literal>. '(null)'</literal>.
@ -1419,7 +1414,7 @@ lo_import 152801
comma-separated output, which other programs might prefer. To comma-separated output, which other programs might prefer. To
set a tab as field separator, type <literal>\pset fieldsep set a tab as field separator, type <literal>\pset fieldsep
'\t'</literal>. The default field separator is '\t'</literal>. The default field separator is
<literal>'|'</literal> (a <quote>pipe</quote> symbol). <literal>'|'</literal> (a vertical bar).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1464,13 +1459,6 @@ lo_import 152801
can be used to give your output descriptive tags. If no can be used to give your output descriptive tags. If no
argument is given, the title is unset. argument is given, the title is unset.
</para> </para>
<note>
<para>
This formerly only affected <acronym>HTML</acronym> mode. You
can now set titles in any output format.
</para>
</note>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1512,6 +1500,9 @@ lo_import 152801
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
<para>
Illustrations on how these different formats look can be seen in Illustrations on how these different formats look can be seen in
the <xref linkend="APP-PSQL-examples" the <xref linkend="APP-PSQL-examples"
endterm="APP-PSQL-examples-title"> section. endterm="APP-PSQL-examples-title"> section.
@ -1541,7 +1532,7 @@ lo_import 152801
<term><literal>\q</literal></term> <term><literal>\q</literal></term>
<listitem> <listitem>
<para> <para>
Quit the <application>psql</application> program. Quits the <application>psql</application> program.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1608,8 +1599,9 @@ lo_import 152801
<para> <para>
Valid variable names can contain characters, digits, and Valid variable names can contain characters, digits, and
underscores. See the section about underscores. See the section <xref
<application>psql</application> variables for details. linkend="APP-PSQL-variables"
endterm="APP-PSQL-variables-title"> below for details.
</para> </para>
<para> <para>
@ -1644,7 +1636,7 @@ lo_import 152801
<term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term> <term><literal>\T</literal> <replaceable class="parameter">table_options</replaceable></term>
<listitem> <listitem>
<para> <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 <sgmltag>table</sgmltag> tag in <acronym>HTML</acronym> tabular
output mode. This command is equivalent to <literal>\pset output mode. This command is equivalent to <literal>\pset
tableattr <replaceable tableattr <replaceable
@ -1680,7 +1672,7 @@ lo_import 152801
<term><literal>\x</literal></term> <term><literal>\x</literal></term>
<listitem> <listitem>
<para> <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>. <literal>\pset expanded</literal>.
</para> </para>
</listitem> </listitem>
@ -1692,7 +1684,7 @@ lo_import 152801
<listitem> <listitem>
<para> <para>
Produces a list of all available tables with their Produces a list of all available tables with their
associated access permissions. associated access privileges.
If a <replaceable class="parameter">pattern</replaceable> is If a <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed. specified, only tables whose name matches the pattern are listed.
</para> </para>
@ -1700,13 +1692,13 @@ lo_import 152801
<para> <para>
The commands <xref linkend="SQL-GRANT"> and The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE"> <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. for more information.
</para> </para>
<para> <para>
This is an alias for <command>\dp</command> (<quote>display This is an alias for <command>\dp</command> (<quote>display
permissions</quote>). privileges</quote>).
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1729,8 +1721,7 @@ lo_import 152801
<term><literal>\?</literal></term> <term><literal>\?</literal></term>
<listitem> <listitem>
<para> <para>
Get help information about the backslash (<quote>\</quote>) Shows help information about the backslash commands.
commands.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1741,31 +1732,20 @@ lo_import 152801
<para> <para>
The various <literal>\d</> commands accept a <replaceable The various <literal>\d</> commands accept a <replaceable
class="parameter">pattern</replaceable> parameter to specify the class="parameter">pattern</replaceable> parameter to specify the
object name(s) to be displayed. Patterns are interpreted similarly object name(s) to be displayed. <literal>*</> means <quote>any
to SQL identifiers, in that unquoted letters are forced to lowercase, sequence of characters</> and <literal>?</> means <quote>any single
while double quotes (<literal>"</>) protect letters from case conversion character</>. (This notation is comparable to Unix shell file name
and allow incorporation of whitespace into the identifier. Within patterns.) Advanced users can also use regular-expression
double quotes, paired double quotes reduce to a single double quote in notations such as character classes, for example <literal>[0-9]</>
the resulting name. For example, <literal>FOO"BAR"BAZ</> is interpreted to match <quote>any digit</>. To make any of these
as <literal>fooBARbaz</>, and <literal>"A weird"" name"</> becomes pattern-matching characters be interpreted literally, surround it
<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
with double quotes. with double quotes.
</para> </para>
<para> <para>
A pattern that contains an (unquoted) dot is interpreted as a schema A pattern that contains an (unquoted) dot is interpreted as a schema
name pattern followed by an object name pattern. For example, 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>foo</> and whose table name
starts with <literal>bar</>. If no dot appears, then the pattern starts with <literal>bar</>. If no dot appears, then the pattern
matches only objects that are visible in the current schema search path. matches only objects that are visible in the current schema search path.
@ -1787,17 +1767,16 @@ lo_import 152801
<para> <para>
<application>psql</application> provides variable substitution <application>psql</application> provides variable substitution
features similar to common Unix command shells. This feature is new features similar to common Unix command shells.
and not very sophisticated, yet, but there are plans to expand it in Variables are simply name/value pairs, where the value
the future. Variables are simply name/value pairs, where the value
can be any string of any length. To set variables, use the can be any string of any length. To set variables, use the
<application>psql</application> meta-command <application>psql</application> meta-command
<command>\set</command>: <command>\set</command>:
<programlisting> <programlisting>
testdb=> <userinput>\set foo bar</userinput> testdb=> <userinput>\set foo bar</userinput>
</programlisting> </programlisting>
sets the variable <quote>foo</quote> to the value sets the variable <literal>foo</literal> to the value
<quote>bar</quote>. To retrieve the content of the variable, precede <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 the name with a colon and use it as the argument of any slash
command: command:
<programlisting> <programlisting>
@ -1840,6 +1819,8 @@ bar
consist of all upper-case letters (and possibly numbers and consist of all upper-case letters (and possibly numbers and
underscores). To ensure maximum compatibility in the future, avoid underscores). To ensure maximum compatibility in the future, avoid
such variables. A list of all specially treated variables follows. such variables. A list of all specially treated variables follows.
</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><varname>DBNAME</varname></term> <term><varname>DBNAME</varname></term>
@ -1856,13 +1837,13 @@ bar
<term><varname>ECHO</varname></term> <term><varname>ECHO</varname></term>
<listitem> <listitem>
<para> <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 entered or from a script are written to the standard output
before they are parsed or executed. To specify this on program before they are parsed or executed. To specify this on program
start-up, use the switch <option>-a</option>. If set to 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 <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>. <option>-e</option>.
</para> </para>
</listitem> </listitem>
@ -1877,7 +1858,7 @@ bar
<productname>PostgreSQL</productname> internals and provide <productname>PostgreSQL</productname> internals and provide
similar functionality in your own programs. If you set the similar functionality in your own programs. If you set the
variable to the value <literal>noexec</literal>, the queries are 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. executed.
</para> </para>
</listitem> </listitem>
@ -1887,9 +1868,7 @@ bar
<term><varname>ENCODING</varname></term> <term><varname>ENCODING</varname></term>
<listitem> <listitem>
<para> <para>
The current client multibyte encoding. If you are not set up to The current client character set encoding.
use multibyte characters, this variable will always contain
<quote>SQL_ASCII</quote>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1909,7 +1888,7 @@ bar
<note> <note>
<para> <para>
This feature was shamelessly plagiarized from This feature was shamelessly plagiarized from
<application>bash</application>. <application>Bash</application>.
</para> </para>
</note> </note>
</listitem> </listitem>
@ -1925,7 +1904,7 @@ bar
<note> <note>
<para> <para>
This feature was shamelessly plagiarized from This feature was shamelessly plagiarized from
<application>bash</application>. <application>Bash</application>.
</para> </para>
</note> </note>
</listitem> </listitem>
@ -1957,7 +1936,7 @@ bar
<note> <note>
<para> <para>
This feature was shamelessly plagiarized from This feature was shamelessly plagiarized from
<application>bash</application>. <application>Bash</application>.
</para> </para>
</note> </note>
</listitem> </listitem>
@ -1982,7 +1961,7 @@ bar
<para> <para>
If you use the <productname>PostgreSQL</productname> large If you use the <productname>PostgreSQL</productname> large
object interface to specially store data that does not fit into 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 block. (See the documentation of the large object interface for
more information.) Since <application>psql</application> has no more information.) Since <application>psql</application> has no
way to tell if you already have a transaction in progress when 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 action. This action could either be to roll back any transaction
that might already be in progress, or to commit any such that might already be in progress, or to commit any such
transaction, or to do nothing at all. In the last case you must transaction, or to do nothing at all. In the last case you must
provide your own <command>BEGIN provide your own <command>BEGIN</command>/<command>COMMIT</command> block or the
TRANSACTION</command>/<command>COMMIT</command> block or the
results will be unpredictable (usually resulting in the desired results will be unpredictable (usually resulting in the desired
action's not being performed in any case). action's not being performed in any case).
</para> </para>
<para> <para>
To choose what you want to do you set this variable to one of To choose what you want to do you set this variable to one of
<quote>rollback</quote>, <quote>commit</quote>, or <literal>rollback</literal>, <literal>commit</literal>, or
<quote>nothing</quote>. The default is to roll back the <literal>nothing</literal>. The default is to roll back the
transaction. If you just want to load one or a few objects this transaction. If you just want to load one or a few objects this
is fine. However, if you intend to transfer many large objects, is fine. However, if you intend to transfer many large objects,
it might be advisable to provide one explicit transaction block it might be advisable to provide one explicit transaction block
@ -2015,7 +1993,7 @@ bar
<listitem> <listitem>
<para> <para>
By default, if non-interactive scripts encounter an error, such 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 meta-command, processing continues. This has been the
traditional behavior of <application>psql</application> but it traditional behavior of <application>psql</application> but it
is sometimes not desirable. If this variable is set, script is sometimes not desirable. If this variable is set, script
@ -2048,9 +2026,9 @@ bar
<listitem> <listitem>
<para> <para>
These specify what the prompt <application>psql</application> 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" linkend="APP-PSQL-prompting"
endterm="APP-PSQL-prompting-title"></quote> below. endterm="APP-PSQL-prompting-title"> below.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2099,8 +2077,6 @@ bar
</variablelist> </variablelist>
</para>
</refsect3> </refsect3>
<refsect3> <refsect3>
@ -2127,7 +2103,7 @@ testdb=> <userinput>SELECT * FROM :foo;</userinput>
A popular application of this facility is to refer to the last A popular application of this facility is to refer to the last
inserted <acronym>OID</acronym> in subsequent statements to build a inserted <acronym>OID</acronym> in subsequent statements to build a
foreign key scenario. Another possible use of this mechanism is to 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. variable and then proceed as above.
<programlisting> <programlisting>
testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput> testdb=> <userinput>\set content '\'' `cat my_file.txt` '\''</userinput>
@ -2135,8 +2111,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:content);</userinput>
</programlisting> </programlisting>
One possible problem with this approach is that <filename>my_file.txt</filename> One possible problem with this approach is that <filename>my_file.txt</filename>
might contain single quotes. These need to be escaped so that 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 they don't cause a syntax error when the second line is processed. This
could be done with the program <application>sed</application>: could be done with the program <command>sed</command>:
<programlisting> <programlisting>
testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput> testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\''</userinput>
</programlisting> </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 this way: After <application>psql</application> has parsed this
line, it passes <literal>sed -e "s/'/\\\'/g" < my_file.txt</literal> 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 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 <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 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 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 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>
<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 applies: If the variable is not set, the character sequence
<quote>colon+name</quote> is not changed. In any case you can escape <quote>colon+name</quote> is not changed. In any case you can escape
a colon with a backslash to protect it from interpretation. (The a colon with a backslash to protect it from interpretation. (The
colon syntax for variables is standard <acronym>SQL</acronym> for 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 The colon syntax for array slices and type casts are
<productname>PostgreSQL</productname> extensions, hence the <productname>PostgreSQL</productname> extensions, hence the
conflict.) 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 <varname>PROMPT2</varname>, and <varname>PROMPT3</varname> contain strings
and special escape sequences that describe the appearance of the and special escape sequences that describe the appearance of the
prompt. Prompt 1 is the normal prompt that is issued when prompt. Prompt 1 is the normal prompt that is issued when
<application>psql</application> requests a new query. Prompt 2 is <application>psql</application> requests a new command. Prompt 2 is
issued when more input is expected during query input because the issued when more input is expected during command input because the
query was not terminated with a semicolon or a quote was not closed. command was not terminated with a semicolon or a quote was not closed.
Prompt 3 is issued when you run an <acronym>SQL</acronym> Prompt 3 is issued when you run an <acronym>SQL</acronym>
<command>COPY</command> command and you are expected to type in the <command>COPY</command> command and you are expected to type in the
tuples on the terminal. row values on the terminal.
</para> </para>
<para> <para>
The value of the respective prompt variable is printed literally, 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 Depending on the next character, certain other text is substituted
instead. Defined substitutions are: instead. Defined substitutions are:
@ -2212,7 +2188,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<term><literal>%m</literal></term> <term><literal>%m</literal></term>
<listitem> <listitem>
<para> <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 first dot, or <literal>[local]</literal> if the connection is
over a Unix domain socket. over a Unix domain socket.
</para> </para>
@ -2237,28 +2213,28 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
<varlistentry> <varlistentry>
<term><literal>%~</literal></term> <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> (tilde) if the database is your default database.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>%#</literal></term> <term><literal>%#</literal></term>
<listitem><para>If the current user is a database superuser, then a <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>
<varlistentry> <varlistentry>
<term><literal>%R</literal></term> <term><literal>%R</literal></term>
<listitem> <listitem>
<para> <para>
In prompt 1 normally <quote>=</quote>, but <quote>^</quote> if In prompt 1 normally <literal>=</literal>, but <literal>^</literal> if
in single-line mode, and <quote>!</quote> if the session is in single-line mode, and <literal>!</literal> if the session is
disconnected from the database (which can happen if disconnected from the database (which can happen if
<command>\connect</command> fails). In prompt 2 the sequence is <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 or a double quote, depending on whether
<application>psql</application> expects more input because the <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 <literal>/* ... */</literal> comment, or because you are inside
a quote. In prompt 3 the sequence doesn't resolve to anything. a quote. In prompt 3 the sequence doesn't resolve to anything.
</para> </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> <term><literal>%:</literal><replaceable class="parameter">name</replaceable><literal>:</literal></term>
<listitem> <listitem>
<para> <para>
The value of the <application>psql</application>, variable The value of the <application>psql</application> variable
<replaceable class="parameter">name</replaceable>. See the <replaceable class="parameter">name</replaceable>. See the
section <quote><xref linkend="APP-PSQL-variables" section <xref linkend="APP-PSQL-variables"
endterm="APP-PSQL-variables-title"></quote> for details. endterm="APP-PSQL-variables-title"> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -2330,9 +2306,7 @@ testdb=> <userinput>\set content '\'' `sed -e "s/'/\\\\\\'/g" < my_file.txt` '\'
in your home directory and is reloaded when in your home directory and is reloaded when
<application>psql</application> starts up. Tab-completion is also <application>psql</application> starts up. Tab-completion is also
supported, although the completion logic makes no claim to be an supported, although the completion logic makes no claim to be an
<acronym>SQL</acronym> parser. When available, <acronym>SQL</acronym> parser. If for some reason you do not like the tab completion, you
<application>psql</application> is automatically built to use these
features. If for some reason you do not like the tab completion, you
can turn if off by putting this in a file named can turn if off by putting this in a file named
<filename>.inputrc</filename> in your home directory: <filename>.inputrc</filename> in your home directory:
<programlisting> <programlisting>
@ -2341,7 +2315,7 @@ set disable-completion on
$endif $endif
</programlisting> </programlisting>
(This is not a <application>psql</application> but a (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.) for further details.)
</para> </para>
</refsect3> </refsect3>
@ -2471,12 +2445,12 @@ $endif
first argument of a single-letter backslash command to start first argument of a single-letter backslash command to start
directly after the command, without intervening whitespace. For directly after the command, without intervening whitespace. For
compatibility this is still supported to some extent, 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. discouraged. If you get strange messages, keep this in mind.
For example For example
<programlisting> <programlisting>
testdb=> <userinput>\foo</userinput> testdb=> <userinput>\foo</userinput>
Field separator is "oo", Field separator is "oo".
</programlisting> </programlisting>
which is perhaps not what one would expect. which is perhaps not what one would expect.
</para> </para>
@ -2494,10 +2468,11 @@ Field separator is "oo",
<listitem> <listitem>
<para> <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 the server) doesn't show the most ideal of behaviors. If you get a
message such as <quote>COPY state must be terminated message such as <errorname>COPY state must be terminated
first</quote>, simply reset the connection by entering <literal>\c first</errorname>, simply reset the connection by entering <literal>\c
- -</literal>. - -</literal>.
</para> </para>
</listitem> </listitem>
@ -2515,19 +2490,19 @@ Field separator is "oo",
<application>psql</application>. If you want to learn <application>psql</application>. If you want to learn
<acronym>SQL</acronym> or get familiar with <acronym>SQL</acronym> or get familiar with
<productname>PostgreSQL</productname>, you might wish to read the <productname>PostgreSQL</productname>, you might wish to read the
Tutorial that is included in the distribution. &cite-tutorial;.
</para> </para>
</note> </note>
<para> <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: input. Notice the changing prompt:
<programlisting> <programlisting>
testdb=> <userinput>CREATE TABLE my_table (</userinput> testdb=> <userinput>CREATE TABLE my_table (</userinput>
testdb(> <userinput> first integer not null default 0,</userinput> testdb(> <userinput> first integer not null default 0,</userinput>
testdb(> <userinput> second text</userinput> testdb(> <userinput> second text</userinput>
testdb-> <userinput>);</userinput> testdb-> <userinput>);</userinput>
CREATE CREATE TABLE
</programlisting> </programlisting>
Now look at the table definition again: Now look at the table definition again:
<programlisting> <programlisting>
@ -2539,8 +2514,7 @@ testdb=> <userinput>\d my_table</userinput>
second | text | second | text |
</programlisting> </programlisting>
At this point you decide to change the prompt to something more Now we change the prompt to something more interesting:
interesting:
<programlisting> <programlisting>
testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput> testdb=> <userinput>\set PROMPT1 '%n@%m %~%R%# '</userinput>
peter@localhost testdb=> peter@localhost testdb=>

39
doc/src/sgml/ref/vacuumdb.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.27 2002/10/11 23:03:48 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.28 2003/03/24 14:32:51 petere Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -18,12 +18,12 @@ PostgreSQL documentation
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>vacuumdb</command> <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>--full</arg><arg>-f</arg></group>
<group><arg>--verbose</arg><arg>-v</arg></group> <group><arg>--verbose</arg><arg>-v</arg></group>
<group><arg>--analyze</arg><arg>-z</arg></group> <group><arg>--analyze</arg><arg>-z</arg></group>
<arg>--table | -t '<replaceable>table</replaceable> <arg>--table | -t <replaceable>table</replaceable>
<arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>' <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>
</arg> </arg>
<arg><replaceable>dbname</replaceable></arg> <arg><replaceable>dbname</replaceable></arg>
<sbr> <sbr>
@ -78,6 +78,16 @@ PostgreSQL documentation
<application>vacuumdb</application> accepts the following command-line arguments: <application>vacuumdb</application> accepts the following command-line arguments:
<variablelist> <variablelist>
<varlistentry>
<term><option>-a</option></term>
<term><option>--all</option></term>
<listitem>
<para>
Vacuum all databases.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term> <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term>
<term><option><optional>--dbname</> <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> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term><option>-a</option></term>
<term><option>--all</option></term>
<listitem>
<para>
Vacuum all databases.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term><option>-e</></term> <term><option>-e</></term>
<term><option>--echo</></term> <term><option>--echo</></term>
@ -146,8 +145,8 @@ PostgreSQL documentation
</para> </para>
<tip> <tip>
<para> <para>
If you specify columns to vacuum, you probably have to escape the parentheses If you specify columns, you probably have to escape the parentheses
from the shell. from the shell. (See examples below.)
</para> </para>
</tip> </tip>
</listitem> </listitem>
@ -187,7 +186,7 @@ PostgreSQL documentation
<para> <para>
Specifies the host name of the machine on which the Specifies the host name of the machine on which the
server 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. as the directory for the Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -198,7 +197,7 @@ PostgreSQL documentation
<term><option>--port <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem> <listitem>
<para> <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 extension on which the server
is listening for connections. is listening for connections.
</para> </para>
@ -272,7 +271,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Default connection parameters. Default connection parameters
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>

27
doc/src/sgml/reference.sgml
View File

@ -1,5 +1,5 @@
<!-- reference.sgml <!-- 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 PostgreSQL Reference Manual
--> -->
@ -135,27 +135,6 @@ PostgreSQL Reference Manual
</reference> </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"> <reference id="reference-client">
<title>PostgreSQL Client Applications</title> <title>PostgreSQL Client Applications</title>
@ -182,9 +161,9 @@ Disable this chapter until we have more functions documented.
&pgDump; &pgDump;
&pgDumpall; &pgDumpall;
&pgRestore; &pgRestore;
&psqlRef;
&pgTclSh; &pgTclSh;
&pgTkSh; &pgTkSh;
&psqlRef;
&vacuumdb; &vacuumdb;
</reference> </reference>
@ -205,8 +184,8 @@ Disable this chapter until we have more functions documented.
&initdb; &initdb;
&initlocation; &initlocation;
&ipcclean; &ipcclean;
&pgCtl;
&pgControldata; &pgControldata;
&pgCtl;
&pgResetxlog; &pgResetxlog;
&postgres; &postgres;
&postmaster; &postmaster;

524
doc/src/sgml/runtime.sgml
View File

File diff suppressed because it is too large Load Diff

267
doc/src/sgml/wal.sgml
View File

@ -1,38 +1,28 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.22 2002/11/15 02:44:54 momjian Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/wal.sgml,v 1.23 2003/03/24 14:32:51 petere Exp $ -->
<chapter id="wal"> <chapter id="wal">
<title>Write-Ahead Logging (<acronym>WAL</acronym>)</title> <title>Write-Ahead Logging (<acronym>WAL</acronym>)</title>
<note>
<title>Author</title>
<para> <para>
Vadim Mikheev and Oliver Elphick <firstterm>Write-Ahead Logging</firstterm> (<acronym>WAL</acronym>)
</para>
</note>
<sect1 id="wal-general">
<title>General Description</Title>
<para>
<firstterm>Write Ahead Logging</firstterm> (<acronym>WAL</acronym>)
is a standard approach to transaction logging. Its detailed is a standard approach to transaction logging. Its detailed
description may be found in most (if not all) books about description may be found in most (if not all) books about
transaction processing. Briefly, <acronym>WAL</acronym>'s central transaction processing. Briefly, <acronym>WAL</acronym>'s central
concept is that changes to data files (where tables and indexes 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 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 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 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 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 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 roll-forward recovery, also known as REDO) and then changes made by
uncommitted transactions will be removed from the data pages uncommitted transactions will be removed from the data pages
(roll-backward recovery - UNDO). (roll-backward recovery, UNDO).
</para> </para>
<sect2 id="wal-benefits-now"> <sect1 id="wal-benefits-now">
<title>Immediate Benefits of <acronym>WAL</acronym></title> <title>Benefits of <acronym>WAL</acronym></title>
<para> <para>
The first obvious benefit of using <acronym>WAL</acronym> is a The first obvious benefit of using <acronym>WAL</acronym> is a
@ -54,11 +44,11 @@
<orderedlist> <orderedlist>
<listitem> <listitem>
<simpara>index tuples pointing to nonexistent table rows</simpara> <simpara>index rows pointing to nonexistent table rows</simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara>index tuples lost in split operations</simpara> <simpara>index rows lost in split operations</simpara>
</listitem> </listitem>
<listitem> <listitem>
@ -74,22 +64,22 @@
page content in the log if that is required to ensure page page content in the log if that is required to ensure page
consistency for after-crash recovery. consistency for after-crash recovery.
</para> </para>
</sect2> </sect1>
<sect2 id="wal-benefits-later"> <sect1 id="wal-benefits-later">
<title>Future Benefits</title> <title>Future Benefits</title>
<para> <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 made by aborted transactions will still occupy disk space and that
we still need a permanent <filename>pg_clog</filename> file to hold a permanent <filename>pg_clog</filename> file to hold
the status of transactions, since we are not able to re-use the status of transactions is still needed, since
transaction identifiers. Once UNDO is implemented, transaction identifiers cannot be reused. Once UNDO is implemented,
<filename>pg_clog</filename> will no longer be required to be <filename>pg_clog</filename> will no longer be required to be
permanent; it will be possible to remove permanent; it will be possible to remove
<filename>pg_clog</filename> at shutdown. (However, the urgency of <filename>pg_clog</filename> at shutdown. (However, the urgency of
this concern has decreased greatly with the adoption of a segmented 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 necessary to keep old <filename>pg_clog</filename> entries around
forever.) forever.)
</para> </para>
@ -122,7 +112,7 @@
<para> <para>
A difficulty standing in the way of realizing these benefits is that A difficulty standing in the way of realizing these benefits is that
they require saving <acronym>WAL</acronym> entries for considerable 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> transaction UNDO is wanted). The present <acronym>WAL</acronym>
format is extremely bulky since it includes many disk page format is extremely bulky since it includes many disk page
snapshots. This is not a serious concern at present, since the 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 but to achieve these future benefits some sort of compressed
<acronym>WAL</acronym> format will be needed. <acronym>WAL</acronym> format will be needed.
</para> </para>
</sect2> </sect1>
</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 id="wal-configuration"> <sect1 id="wal-configuration">
<title><acronym>WAL</acronym> Configuration</title> <title><acronym>WAL</acronym> Configuration</title>
<para> <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. affect database performance. This section explains their use.
Consult <xref linkend="runtime-config"> for details about setting Consult <xref linkend="runtime-config"> for details about setting
configuration parameters. configuration parameters.
@ -232,25 +142,25 @@
log (known as the redo record) it should start the REDO operation, log (known as the redo record) it should start the REDO operation,
since any changes made to data files before that record are already since any changes made to data files before that record are already
on disk. After a checkpoint has been made, any log segments written 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 removed. (When <acronym>WAL</acronym>-based <acronym>BAR</acronym> is
implemented, the log segments would be archived before being recycled implemented, the log segments would be archived before being recycled
or removed.) or removed.)
</para> </para>
<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 to create the next checkpoint. A checkpoint is created every
<varname>CHECKPOINT_SEGMENTS</varname> log segments, or every <varname>checkpoint_segments</varname> log segments, or every
<varname>CHECKPOINT_TIMEOUT</varname> seconds, whichever comes first. <varname>checkpoint_timeout</varname> seconds, whichever comes first.
The default settings are 3 segments and 300 seconds respectively. The default settings are 3 segments and 300 seconds respectively.
It is also possible to force a checkpoint by using the SQL command It is also possible to force a checkpoint by using the SQL command
<command>CHECKPOINT</command>. <command>CHECKPOINT</command>.
</para> </para>
<para> <para>
Reducing <varname>CHECKPOINT_SEGMENTS</varname> and/or Reducing <varname>checkpoint_segments</varname> and/or
<varname>CHECKPOINT_TIMEOUT</varname> causes checkpoints to be done <varname>checkpoint_timeout</varname> causes checkpoints to be done
more often. This allows faster after-crash recovery (since less work more often. This allows faster after-crash recovery (since less work
will need to be redone). However, one must balance this against the will need to be redone). However, one must balance this against the
increased cost of flushing dirty data pages more often. In addition, increased cost of flushing dirty data pages more often. In addition,
@ -262,15 +172,15 @@
</para> </para>
<para> <para>
There will be at least one 16MB segment file, and will normally There will be at least one 16 MB segment file, and will normally
not be more than 2 * <varname>CHECKPOINT_SEGMENTS</varname> not be more than 2 * <varname>checkpoint_segments</varname> + 1
+ 1 files. You can use this to estimate space requirements for files. You can use this to estimate space requirements for WAL.
WAL. Ordinarily, when old log segment files are no longer needed, Ordinarily, when old log segment files are no longer needed, they
they are recycled (renamed to become the next sequential future are recycled (renamed to become the next segments in the numbered
segments). If, due to a short-term peak of log output rate, there sequence). If, due to a short-term peak of log output rate, there
are more than 2 * <varname>CHECKPOINT_SEGMENTS</varname> + 1 segment files, are more than 2 * <varname>checkpoint_segments</varname> + 1
the unneeded segment files will be deleted instead of recycled until the segment files, the unneeded segment files will be deleted instead
system gets back under this limit. of recycled until the system gets back under this limit.
</para> </para>
<para> <para>
@ -282,7 +192,7 @@
to write (move to kernel cache) a few filled <acronym>WAL</acronym> to write (move to kernel cache) a few filled <acronym>WAL</acronym>
buffers. This is undesirable because <function>LogInsert</function> buffers. This is undesirable because <function>LogInsert</function>
is used on every database low level modification (for example, 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 affected data pages, so the operation needs to be as fast as
possible. What is worse, writing <acronym>WAL</acronym> buffers may possible. What is worse, writing <acronym>WAL</acronym> buffers may
also force the creation of a new log segment, which takes even more 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 not occur often enough to prevent <acronym>WAL</acronym> buffers
being written by <function>LogInsert</function>. On such systems being written by <function>LogInsert</function>. On such systems
one should increase the number of <acronym>WAL</acronym> buffers by one should increase the number of <acronym>WAL</acronym> buffers by
modifying the <filename>postgresql.conf</filename> <varname> modifying the configuration parameter <varname>wal_buffers</varname>.
WAL_BUFFERS</varname> parameter. The default number of <acronym> The default number of <acronym>
WAL</acronym> buffers is 8. Increasing this value will WAL</acronym> buffers is 8. Increasing this value will
correspondingly increase shared memory usage. correspondingly increase shared memory usage.
</para> </para>
@ -305,47 +215,122 @@
buffers to disk using the operating system <literal>sync()</> call. buffers to disk using the operating system <literal>sync()</> call.
Busy servers may fill checkpoint segment files too quickly, Busy servers may fill checkpoint segment files too quickly,
causing excessive checkpointing. If such forced checkpoints happen 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 a message, will be output to the server logs recommending increasing
<varname>CHECKPOINT_SEGMENTS</varname>. <varname>checkpoint_segments</varname>.
</para> </para>
<para> <para>
The <varname>COMMIT_DELAY</varname> parameter defines for how many The <varname>commit_delay</varname> parameter defines for how many
microseconds the backend will sleep after writing a commit microseconds the server process will sleep after writing a commit
record to the log with <function>LogInsert</function> but before record to the log with <function>LogInsert</function> but before
performing a <function>LogFlush</function>. This delay allows other 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> 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> is not enabled or if fewer than <varname>commit_siblings</varname>
other backends are not currently in active transactions; this avoids other sessons are currently in active transactions; this avoids
sleeping when it's unlikely that any other backend will commit soon. sleeping when it's unlikely that any other session will commit soon.
Note that on most platforms, the resolution of a sleep request is Note that on most platforms, the resolution of a sleep request is
ten milliseconds, so that any nonzero <varname>COMMIT_DELAY</varname> ten milliseconds, so that any nonzero <varname>commit_delay</varname>
setting between 1 and 10000 microseconds will have the same effect. setting between 1 and 10000 microseconds would have the same effect.
Good values for these parameters are not yet clear; experimentation Good values for these parameters are not yet clear; experimentation
is encouraged. is encouraged.
</para> </para>
<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 <productname>PostgreSQL</productname> will ask the kernel to force
WAL updates out to disk. WAL updates out to disk.
All the options should be the same as far as reliability goes, All the options should be the same as far as reliability goes,
but it's quite platform-specific which one will be the fastest. 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. has been turned off.
</para> </para>
<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 value will result in each <function>LogInsert</function> and
<function>LogFlush</function> <acronym>WAL</acronym> call being <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 the nonzero value is. This option may be replaced by a more
general mechanism in the future. general mechanism in the future.
</para> </para>
</sect1> </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> </chapter>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file