<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.25 2003/03/18 00:02:11 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/backup.sgml,v 2.26 2003/03/24 14:32:50 petere Exp $
-->
<chapter id="backup">
<title>Backup and Restore</title>
<application>psql</> (e.g., with <literal>createdb -T template0
<replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</>
- for controlling the database server location and the user names. See
+ for controlling the database server location and the user name. See
its reference page for more information.
</para>
<para>
The ability of <application>pg_dump</> and <application>psql</> to
write to or read from pipes makes it possible to dump a database
- directly from one server to another, for example
+ directly from one server to another; for example:
<programlisting>
pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>host2</> <replaceable>dbname</>
</programlisting>
<sect2 id="backup-dump-large">
<title>Large Databases</title>
- <note>
- <title>Acknowledgement</title>
- <para>
- Originally written by Hannu Krosing
- </para>
- </note>
-
<para>
Since <productname>PostgreSQL</productname> allows tables larger
than the maximum file size on your system, it can be problematic
- to dump the table to a file, since the resulting file will likely
+ to dump such a table to a file, since the resulting file will likely
be larger than the maximum size allowed by your system. As
- <application>pg_dump</> writes to the standard output, you can
- just use standard *nix tools to work around this possible problem.
+ <application>pg_dump</> can write to the standard output, you can
+ just use standard Unix tools to work around this possible problem.
</para>
<formalpara>
<title>Use compressed dumps.</title>
<para>
- Use your favorite compression program, for example
+ You can use your favorite compression program, for example
<application>gzip</application>.
<programlisting>
</formalpara>
<formalpara>
- <title>Use <application>split</>.</title>
+ <title>Use <command>split</>.</title>
<para>
- This allows you to split the output into pieces that are
+ The <command>split</command> command
+ allows you to split the output into pieces that are
acceptable in size to the underlying file system. For example, to
make chunks of 1 megabyte:
<listitem>
<para>
- If you have dug into the details of the file system layout you
+ If you have dug into the details of the file system layout of the data you
may be tempted to try to back up or restore only certain
individual tables or databases from their respective files or
directories. This will <emphasis>not</> work because the
all transactions. A table file is only usable with this
information. Of course it is also impossible to restore only a
table and the associated <filename>pg_clog</filename> data
- because that will render all other tables in the database
+ because that would render all other tables in the database
cluster useless.
</para>
</listitem>
server, using <application>pg_dump</>. (There are checks in place
that prevent you from doing the wrong thing, so no harm can be done
by confusing these things.) The precise installation procedure is
- not subject of this section, these details are in <xref linkend="installation">.
+ not subject of this section; these details are in <xref linkend="installation">.
</para>
<para>
pg_dumpall -p 5432 | psql -d template1 -p 6543
</programlisting>
- to transfer your data, or use an intermediate file if you want.
+ to transfer your data. Or use an intermediate file if you want.
Then you can shut down the old server and start the new server at
the port the old one was running at. You should make sure that the
database is not updated after you run <application>pg_dumpall</>,
pg_dumpall > backup
pg_ctl stop
mv /usr/local/pgsql /usr/local/pgsql.old
-cd /usr/src/postgresql-&version;
+cd ~/postgresql-&version;
gmake install
initdb -D /usr/local/pgsql/data
postmaster -D /usr/local/pgsql/data
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.32 2003/03/13 01:30:26 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v 2.33 2003/03/24 14:32:50 petere Exp $ -->
<chapter id="charset">
<title>Localization</>
- <abstract>
- <para>
- Describes the available localization features from the point of
- view of the administrator.
- </para>
- </abstract>
-
- <para>
- <productname>PostgreSQL</productname> supports localization with
- three approaches:
+ <para>
+ This chapter describes the available localization features from the
+ point of view of the administrator.
+ <productname>PostgreSQL</productname> supports localization with
+ three approaches:
<itemizedlist>
<listitem>
<listitem>
<para>
- Using explicit multiple-byte character sets defined in the
- <productname>PostgreSQL</productname> server to support languages
- that require more characters than will fit into a single byte,
- and to provide character set recoding between client and server.
- The number of supported character sets is fixed at the time the
- server is compiled, and internal operations such as string
- comparisons require expansion of each character into a 32-bit
- word.
+ Providing a number of different character sets defined in the
+ <productname>PostgreSQL</productname> server, including
+ multiple-byte character sets, to support storing text in all
+ kinds of languages, and providing character set recoding between
+ client and server.
</para>
</listitem>
<listitem>
<para>
- Single byte character recoding provides a more light-weight
+ Single-byte character recoding provides a more light-weight
solution for users of multiple, yet single-byte character sets.
</para>
</listitem>
<firstterm>Locale</> support refers to an application respecting
cultural preferences regarding alphabets, sorting, number
formatting, etc. <productname>PostgreSQL</> uses the standard ISO
- C and <acronym>POSIX</acronym>-like locale facilities provided by the server operating
+ C and <acronym>POSIX</acronym> locale facilities provided by the server operating
system. For additional information refer to the documentation of your
system.
</para>
<para>
Occasionally it is useful to mix rules from several locales, e.g.,
- use U.S. collation rules but Spanish messages. To support that, a
+ use English collation rules but Spanish messages. To support that, a
set of locale subcategories exist that control only a certain
aspect of the localization rules.
<para>
The other locale categories can be changed as desired whenever the
- server is started by setting the run-time configuration variables
+ server is running by setting the run-time configuration variables
that have the same name as the locale categories (see <xref
linkend="runtime-config"> for details). The defaults that are
chosen by <command>initdb</command> are actually only written into
variable <envar>LANGUAGE</envar> which overrides all other locale
settings for the purpose of setting the language of messages. If
in doubt, please refer to the documentation of your operating
- system, in particular the
- <citerefentry><refentrytitle>gettext</><manvolnum>3</></> manual
- page, for more information.
+ system, in particular the documentation about
+ <application>gettext</>, for more information.
</para>
</note>
<para>
To enable messages translated to the user's preferred language,
- the <option>--enable-nls</option> option must be used. This
- option is independent of the other locale support.
+ <acronym>NLS</acronym> must have been enabled at build time. This
+ choice is independent of the other locale support.
</para>
</sect2>
<itemizedlist>
<listitem>
<para>
- Sort order in <command>ORDER BY</> queries.
+ Sort order in queries using <command>ORDER BY</>
<indexterm><primary>ORDER BY</></>
</para>
</listitem>
<para>
The only severe drawback of using the locale support in
- <productname>PostgreSQL</> is its speed. So use locale only if you
+ <productname>PostgreSQL</> is its speed. So use locales only if you
actually need it. It should be noted in particular that selecting
a non-C locale disables index optimizations for <literal>LIKE</> and
<literal>~</> operators, which can make a huge difference in the
<para>
If locale support doesn't work in spite of the explanation above,
- check that the locale support in your operating system is correctly configured.
- To check whether a given locale is installed and functional you
- can use <application>Perl</>, for example. Perl has also support
- for locales and if a locale is broken <command>perl -v</> will
- complain something like this:
-<screen>
-<prompt>$</> <userinput>export LC_CTYPE='not_exist'</>
-<prompt>$</> <userinput>perl -v</>
-<computeroutput>
-perl: warning: Setting locale failed.
-perl: warning: Please check that your locale settings:
-LC_ALL = (unset),
-LC_CTYPE = "not_exist",
-LANG = (unset)
-are supported and installed on your system.
-perl: warning: Falling back to the standard locale ("C").
-</computeroutput>
-</screen>
+ check that the locale support in your operating system is
+ correctly configured. To check what locales are installed on your
+ system, you may use the command <literal>locale -a</literal> if
+ your operating system provides it.
</para>
<para>
- Check that your locale files are in the right location. Possible
- locations include: <filename>/usr/lib/locale</filename> (<systemitem class="osname">Linux</>,
- <systemitem class="osname">Solaris</>), <filename>/usr/share/locale</filename> (<systemitem class="osname">Linux</>),
- <filename>/usr/lib/nls/loc</filename> (<systemitem class="osname">DUX 4.0</>). Check the locale
- man page of your system if you are not sure.
+ Check that <productname>PostgreSQL</> is actually using the locale
+ that you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
+ settings are determined at <command>initdb</> time and cannot be
+ changed without repeating <command>initdb</>. Other locale
+ settings including <envar>LC_MESSAGES</> and <envar>LC_MONETARY</>
+ are initially determined by the environment the server is started
+ in. You can check the <envar>LC_COLLATE</> and <envar>LC_CTYPE</>
+ settings of a database with the utility program
+ <command>pg_controldata</>.
</para>
<para>
- Check that <productname>PostgreSQL</> is actually using the locale that
- you think it is. <envar>LC_COLLATE</> and <envar>LC_CTYPE</> settings are
- determined at <application>initdb</> time and cannot be changed without
- repeating <application>initdb</>. Other locale settings including
- <envar>LC_MESSAGES</> and <envar>LC_MONETARY</> are determined by the
- environment the postmaster is started in, and can be changed with a simple
- postmaster restart. You can check the <envar>LC_COLLATE</> and
- <envar>LC_CTYPE</> settings of
- a database with the <filename>contrib/pg_controldata</> utility program.
- </para>
-
- <para>
- The directory <filename>src/test/locale</> contains a test suite
- for <productname>PostgreSQL</>'s locale support.
+ The directory <filename>src/test/locale</> in the source
+ distribution contains a test suite for
+ <productname>PostgreSQL</>'s locale support.
</para>
<para>
text of the error message will obviously have problems when the
server's messages are in a different language. If you create such
an application you need to devise a plan to cope with this
- situation. The embedded SQL interface (<application>ecpg</>) is
+ situation. The embedded SQL interface (<application>ECPG</>) is
also affected by this problem. It is currently recommended that
- servers interfacing with <application>ecpg</> applications be
+ servers interfacing with <application>ECPG</> applications be
configured to send messages in English.
</para>
</sect1>
- <sect1 id="multibyte">
- <title>Multibyte Support</title>
-
- <indexterm zone="multibyte"><primary>multibyte</></>
-
- <note>
- <title>Author</title>
-
- <para>
- last updated 2002-07-24.
- Check <ulink
- url="http://www.sra.co.jp/people/t-ishii/PostgreSQL/">Tatsuo's
- web site</ulink> for more information.
- </para>
- </note>
+ <sect1 id="multibyte">
+ <title>Character Set Support</title>
- <para>
- Multibyte (<acronym>MB</acronym>) support is intended to allow
- <productname>PostgreSQL</productname> to handle
- multiple-byte character sets such as <acronym>EUC</> (Extended Unix Code), Unicode, and
- Mule internal code. With <acronym>MB</acronym> enabled you can use multibyte
- character sets in regular expressions (regexp), LIKE, and some
- other functions. The default
- encoding system is selected while initializing your
- <productname>PostgreSQL</productname> installation using
- <application>initdb</application>. Note that this can be
- overridden when you create a database using
- <application>createdb</application> or by using the SQL command
- <command>CREATE DATABASE</>. So you can have multiple databases each with
- a different encoding system. Note that <acronym>MB</acronym> can
- handle single byte characters sets such as ISO-8859-1.
- </para>
+ <indexterm zone="multibyte"><primary>character set</></>
- <para>
- Multibyte support is enabled by default since
- <productname>PostgreSQL</> version 7.3.
- </para>
+ <para>
+ The character set support in <productname>PostgreSQL</productname>
+ allows you to store text in a variety of character sets, including
+ single-byte character sets such as the ISO 8859 series and
+ multiple-byte character sets such as <acronym>EUC</> (Extended Unix
+ Code), Unicode, and Mule internal code. All character sets can be
+ used transparently throughout the server. (If you use extension
+ functions from other sources, it depends on whether they wrote
+ their code correctly.) The default character set is selected while
+ initializing your <productname>PostgreSQL</productname> database
+ cluster using <command>initdb</>. It can be overridden when you
+ create a database using <command>createdb</command> or by using the
+ SQL command <command>CREATE DATABASE</>. So you can have multiple
+ databases each with a different character set.
+ </para>
<sect2>
- <title>Supported character set encodings</title>
+ <title>Supported Character Sets</title>
<para>
- Following encoding can be used as database encoding.
+ <xref linkend="charset-table"> shows the character sets available
+ for use in the server.
+ </para>
- <table tocentry="1">
- <title>Character Set Encodings</title>
- <titleabbrev>Encodings</titleabbrev>
+ <table id="charset-table">
+ <title>Server Character Sets</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Encoding</entry>
+ <entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
</row>
<row>
<entry><literal>LATIN1</literal></entry>
- <entry>ISO 8859-1 <acronym>ECMA</>-94 Latin Alphabet No.1</entry>
+ <entry>ISO 8859-1/<acronym>ECMA</> 94 (Latin alphabet no.1)</entry>
</row>
<row>
<entry><literal>LATIN2</literal></entry>
- <entry>ISO 8859-2 <acronym>ECMA</>-94 Latin Alphabet No.2</entry>
+ <entry>ISO 8859-2/<acronym>ECMA</> 94 (Latin alphabet no.2)</entry>
</row>
<row>
<entry><literal>LATIN3</literal></entry>
- <entry>ISO 8859-3 <acronym>ECMA</>-94 Latin Alphabet No.3</entry>
+ <entry>ISO 8859-3/<acronym>ECMA</> 94 (Latin alphabet no.3)</entry>
</row>
<row>
<entry><literal>LATIN4</literal></entry>
- <entry>ISO 8859-4 <acronym>ECMA</>-94 Latin Alphabet No.4</entry>
+ <entry>ISO 8859-4/<acronym>ECMA</> 94 (Latin alphabet no.4)</entry>
</row>
<row>
<entry><literal>LATIN5</literal></entry>
- <entry>ISO 8859-9 <acronym>ECMA</>-128 Latin Alphabet No.5</entry>
+ <entry>ISO 8859-9/<acronym>ECMA</> 128 (Latin alphabet no.5)</entry>
</row>
<row>
<entry><literal>LATIN6</literal></entry>
- <entry>ISO 8859-10 <acronym>ECMA</>-144 Latin Alphabet No.6</entry>
+ <entry>ISO 8859-10/<acronym>ECMA</> 144 (Latin alphabet no.6)</entry>
</row>
<row>
<entry><literal>LATIN7</literal></entry>
- <entry>ISO 8859-13 Latin Alphabet No.7</entry>
+ <entry>ISO 8859-13 (Latin alphabet no.7)</entry>
</row>
<row>
<entry><literal>LATIN8</literal></entry>
- <entry>ISO 8859-14 Latin Alphabet No.8</entry>
+ <entry>ISO 8859-14 (Latin alphabet no.8)</entry>
</row>
<row>
<entry><literal>LATIN9</literal></entry>
- <entry>ISO 8859-15 Latin Alphabet No.9</entry>
+ <entry>ISO 8859-15 (Latin alphabet no.9)</entry>
</row>
<row>
<entry><literal>LATIN10</literal></entry>
- <entry>ISO 8859-16 <acronym>ASRO</> SR 14111 Latin Alphabet No.10</entry>
+ <entry>ISO 8859-16/<acronym>ASRO</> SR 14111 (Latin alphabet no.10)</entry>
</row>
<row>
<entry><literal>ISO-8859-5</literal></entry>
- <entry><acronym>ECMA</>-113 Latin/Cyrillic</entry>
+ <entry>ISO 8859-5/<acronym>ECMA</> 113 (Latin/Cyrillic)</entry>
</row>
<row>
<entry><literal>ISO-8859-6</literal></entry>
- <entry><acronym>ECMA</>-114 Latin/Arabic</entry>
+ <entry>ISO 8859-6/<acronym>ECMA</> 114 (Latin/Arabic)</entry>
</row>
<row>
<entry><literal>ISO-8859-7</literal></entry>
- <entry><acronym>ECMA</>-118 Latin/Greek</entry>
+ <entry>ISO 8859-7/<acronym>ECMA</> 118 (Latin/Greek)</entry>
</row>
<row>
<entry><literal>ISO-8859-8</literal></entry>
- <entry><acronym>ECMA</>-121 Latin/Hebrew</entry>
+ <entry>ISO 8859-8/<acronym>ECMA</> 121 (Latin/Hebrew)</entry>
</row>
<row>
<entry><literal>KOI8</literal></entry>
</row>
<row>
<entry><literal>WIN1256</literal></entry>
- <entry>Arabic Windows CP1256</entry>
+ <entry>Windows CP1256 (Arabic)</entry>
</row>
<row>
<entry><literal>TCVN</literal></entry>
- <entry>Vietnamese <acronym>TCVN</>-5712 (Windows CP1258)</entry>
+ <entry><acronym>TCVN</>-5712/Windows CP1258 (Vietnamese)</entry>
</row>
<row>
<entry><literal>WIN874</literal></entry>
- <entry>Thai Windows CP874</entry>
+ <entry>Windows CP874 (Thai)</entry>
</row>
</tbody>
</tgroup>
</table>
- </para>
<important>
<para>
- Before <productname>PostgreSQL</>7.2, <literal>LATIN5</> mistakenly
- meant ISO 8859-5. From 7.2 on,
- <literal>LATIN5</> means ISO 8859-9. If you have a <literal>LATIN5</>
- database created on 7.1 or earlier and want to migrate to 7.2 (or
- later), you should be very careful about this change.
+ Before <productname>PostgreSQL</> 7.2, <literal>LATIN5</>
+ mistakenly meant ISO 8859-5. From 7.2 on, <literal>LATIN5</>
+ means ISO 8859-9. If you have a <literal>LATIN5</> database
+ created on 7.1 or earlier and want to migrate to 7.2 or later,
+ you should be very careful about this change.
</para>
</important>
- <important>
<para>
- Not all <acronym>API</>s supports all the encodings listed above. For example, the
+ Not all <acronym>API</>s support all the listed character sets. For example, the
<productname>PostgreSQL</>
JDBC driver does not support <literal>MULE_INTERNAL</>, <literal>LATIN6</>,
<literal>LATIN8</>, and <literal>LATIN10</>.
</para>
- </important>
</sect2>
<sect2>
- <title>Setting the Encoding</title>
+ <title>Setting the Character Set</title>
<para>
- <application>initdb</application> defines the default encoding
- for a <productname>PostgreSQL</productname> installation. For example:
+ <command>initdb</> defines the default character set
+ for a <productname>PostgreSQL</productname> cluster. For example,
<screen>
initdb -E EUC_JP
</screen>
- sets the default encoding to <literal>EUC_JP</literal> (Extended Unix Code for Japanese).
- Note that you can use <option>--encoding</option> instead of <option>-E</option> if you prefer
- to type longer option strings.
+ sets the default character set (encoding) to
+ <literal>EUC_JP</literal> (Extended Unix Code for Japanese). You
+ can use <option>--encoding</option> instead of
+ <option>-E</option> if you prefer to type longer option strings.
If no <option>-E</> or <option>--encoding</option> option is
- given, SQL_ASCII is used.
+ given, <literal>SQL_ASCII</> is used.
</para>
<para>
- You can create a database with a different encoding:
+ You can create a database with a different character set:
<screen>
createdb -E EUC_KR korean
</screen>
- will create a database named <database>korean</database> with <literal>EUC_KR</literal> encoding.
- Another way to accomplish this is to use a SQL command:
+ This will create a database named <literal>korean</literal> that
+ uses the character set <literal>EUC_KR</literal>. Another way to
+ accomplish this is to use this SQL command:
<programlisting>
-CREATE DATABASE korean WITH ENCODING = 'EUC_KR';
+CREATE DATABASE korean WITH ENCODING 'EUC_KR';
</programlisting>
- The encoding for a database is represented as an
- <firstterm>encoding column</firstterm> in the
- <literal>pg_database</literal> system catalog.
- You can see that by using the <option>-l</option> option or the
- <command>\l</command> command of <command>psql</command>.
+ The encoding for a database is stored in the system catalog
+ <literal>pg_database</literal>. You can see that by using the
+ <option>-l</option> option or the <command>\l</command> command
+ of <command>psql</command>.
<screen>
$ <userinput>psql -l</userinput>
</sect2>
<sect2>
- <title>Automatic encoding conversion between server and
- client</title>
+ <title>Automatic Character Set Conversion Between Server and Client</title>
<para>
- <productname>PostgreSQL</productname> supports an automatic
- encoding conversion between server and client for some
- encodings. The conversion info is stored in <literal>pg_conversion</> system
- catalog. You can create a new conversion by using <command>CREATE
- CONVERSION</command>. <productname>PostgreSQL</> comes with some predefined
- conversions. They are listed in <xref
+ <productname>PostgreSQL</productname> supports automatic
+ character set conversion between server and client for certain
+ character sets. The conversion information is stored in the
+ <literal>pg_conversion</> system catalog. You can create a new
+ conversion by using the SQL command <command>CREATE
+ CONVERSION</command>. <productname>PostgreSQL</> comes with some
+ predefined conversions. They are listed in <xref
linkend="multibyte-translation-table">.
</para>
- <table tocentry="1" id="multibyte-translation-table">
- <title>Client/Server Character Set Encodings</title>
- <titleabbrev>Communication Encodings</titleabbrev>
+ <table id="multibyte-translation-table">
+ <title>Client/Server Character Set Conversions</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Server Encoding</entry>
- <entry>Available Client Encodings</entry>
+ <entry>Server Character Set</entry>
+ <entry>Available Client Character Sets</entry>
</row>
</thead>
<tbody>
</table>
<para>
- To enable the automatic encoding translation, you have to tell
- <productname>PostgreSQL</productname> the encoding you would like
- to use in the client. There are
- several ways to accomplish this.
+ To enable the automatic character set conversion, you have to
+ tell <productname>PostgreSQL</productname> the character set
+ (encoding) you would like to use in the client. There are several
+ ways to accomplish this:
<itemizedlist>
<listitem>
<function>PQsetClientEncoding()</function> for its purpose.
<synopsis>
-int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>)
+int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
</synopsis>
where <replaceable>conn</replaceable> is a connection to the server,
- and <replaceable>encoding</replaceable> is an encoding you
- want to use. If it successfully sets the encoding, it returns 0,
- otherwise -1. The current encoding for this connection can be shown by
+ and <replaceable>encoding</replaceable> is the encoding you
+ want to use. If the function successfully sets the encoding, it returns 0,
+ otherwise -1. The current encoding for this connection can be determined by
using:
<synopsis>
-int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>)
+int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
</synopsis>
Note that it returns the encoding ID, not a symbolic string
can use:
<synopsis>
-char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>)
+char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
</synopsis>
</para>
</listitem>
Setting the client encoding can be done with this SQL command:
<programlisting>
-SET CLIENT_ENCODING TO 'encoding';
+SET CLIENT_ENCODING TO '<replaceable>value</>';
</programlisting>
- Also you can use the SQL92 syntax <literal>SET NAMES</literal> for this purpose:
+ Also you can use the more standard SQL syntax <literal>SET NAMES</literal> for this purpose:
<programlisting>
-SET NAMES 'encoding';
+SET NAMES '<replaceable>value</>';
</programlisting>
To query the current client encoding:
<listitem>
<para>
- Using client_encoding variable.
+ Using the configuration variable <varname>client_encoding</varname>.
If the <varname>client_encoding</> variable in <filename>postgresql.conf</> is set, that
client encoding is automatically selected when a connection to the
</itemizedlist>
</para>
- </sect2>
-
- <sect2>
- <title>What happens if the translation is not possible?</title>
<para>
- Suppose you choose <literal>EUC_JP</literal> for the server
- and <literal>LATIN1</literal> for the client,
- then some Japanese characters cannot be translated into <literal>LATIN1</literal>. In
- this case, a letter that cannot be represented in the <literal>LATIN1</literal> character set
- would be transformed as:
-
-<synopsis>
-(HEXA DECIMAL)
-</synopsis>
+ If the conversion of a particular character is not possible --
+ suppose you chose <literal>EUC_JP</literal> for the server and
+ <literal>LATIN1</literal> for the client, then some Japanese
+ characters cannot be converted to <literal>LATIN1</literal> -- it
+ is transformed to its hexadecimal byte values in parentheses,
+ e.g., <literal>(826C)</literal>.
</para>
</sect2>
<sect2>
- <title>References</title>
+ <title>Further Reading</title>
<para>
These are good sources to start learning about various kinds of encoding
</para>
</sect2>
- <sect2>
- <title>History</title>
-
-<literallayout class="monospaced">
-Dec 7, 2000
- * An automatic encoding translation between Unicode and other
- encodings are implemented
- * Changes above will appear in 7.1
-
-May 20, 2000
- * SJIS UDC (NEC selection IBM kanji) support contributed
- by Eiji Tokuya
- * Changes above will appear in 7.0.1
-
-Mar 22, 2000
- * Add new libpq functions PQsetClientEncoding, PQclientEncoding
- * ./configure --with-mb=EUC_JP
- now deprecated. use
- ./configure --enable-multibyte=EUC_JP
- instead
- * Add SQL_ASCII regression test case
- * Add SJIS User Defined Character (UDC) support
- * All of above will appear in 7.0
-
-July 11, 1999
- * Add support for WIN1250 (Windows Czech) as a client encoding
- (contributed by Pavel Behal)
- * fix some compiler warnings (contributed by Tomoaki Nishiyama)
-
-Mar 23, 1999
- * Add support for KOI8(KOI8-R), WIN(CP1251), ALT(CP866)
- (thanks Oleg Broytmann for testing)
- * Fix problem with MB and locale
-
-Jan 26, 1999
- * Add support for Big5 for frontend encoding
- (you need to create a database with EUC_TW to use Big5)
- * Add regression test case for EUC_TW
-
-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
-License: The Same as <productname>PostgreSQL</>
-
-Sorry for my Eglish and C code, I'm not native :-)
-
-!!!!!!!!!!!!!!!!!!!!!!!!! NO WARRANTY !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
--->
-
- The WIN1250 character set on Windows client platforms can be used
- with <productname>PostgreSQL</productname> with locale support
- enabled.
- </para>
-
- <para>
- The following should be kept in mind:
-
- <itemizedlist>
- <listitem>
- <para>
- Success depends on proper system locales. This has been tested
- with <systemitem class="osname">Red Hat 6.0</> and <systemitem
- class="osname">Slackware 3.6</>, with the
- <literal>cs_CZ.iso8859-2</literal> locale.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Never try to set the server's database encoding to WIN1250.
- Always use LATIN2 instead since there is no WIN1250 locale
- in Unix.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The WIN1250 encoding is usable only for Windows ODBC clients. The
- characters are recoded on the fly, to be displayed and stored
- back properly.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <procedure>
- <title>WIN1250 on Windows/ODBC</title>
- <step>
- <para>
- Compile <productname>PostgreSQL</productname> with locale enabled
- and the server-side encoding set to <literal>LATIN2</literal>.
- </para>
- </step>
-
- <step>
- <para>
- Set up your installation. Do not forget to create locale
- variables in your environment. For example (this may
- not be correct for <emphasis>your</emphasis> environment):
-
-<programlisting>
-LC_ALL=cs_CZ.ISO8859-2
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- You have to start the server with locales set!
- </para>
- </step>
-
- <step>
- <para>
- Try it with the Czech language, and have it sort on a query.
- </para>
- </step>
-
- <step>
- <para>
- Install ODBC driver for <productname>PostgreSQL</productname> on your Windows machine.
- </para>
- </step>
-
- <step>
- <para>
- Set up your data source properly. Include this line in your ODBC
- configuration dialog in the field <guilabel>Connect Settings</guilabel>:
-
-<programlisting>
-SET CLIENT_ENCODING = 'WIN1250';
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- Now try it again, but in Windows with ODBC.
- </para>
- </step>
- </procedure>
- </sect2>
</sect1>
<sect1 id="recode">
- <title>Single-byte character set recoding</>
+ <title>Single-Byte Character Set Recoding</>
<para>
You can set up this feature with the <option>--enable-recode</> option
<para>
This method uses a file <filename>charset.conf</> file located in
- the database directory (<envar>PGDATA</>). It's a typical
- configuration text file where spaces and newlines separate items
- and records and # specifies comments. Three keywords with the
+ the data directory for configuration. It's a typical
+ configuration text file where spaces and newlines separate fields
+ and records and <literal>#</> starts a comment. Three key words with the
following syntax are recognized here:
<synopsis>
-BaseCharset <replaceable>server_charset</>
-RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
-HostCharset <replaceable>host_spec</> <replaceable>host_charset</>
+BaseCharset <replaceable>server_charset</>
+RecodeTable <replaceable>from_charset</> <replaceable>to_charset</> <replaceable>file_name</>
+HostCharset <replaceable>host_spec</> <replaceable>host_charset</>
</synopsis>
</para>
<para>
- <token>BaseCharset</> defines the encoding of the database server.
+ <token>BaseCharset</> defines the character set of the database server.
All character set names are only used for mapping inside of
<filename>charset.conf</> so you can freely use typing-friendly
names.
</para>
<para>
- <token>RecodeTable</> records specify translation tables between
+ <token>RecodeTable</> records specify conversion tables between
server and client. The file name is relative to the
- <envar>PGDATA</> directory. The table file format is very
- simple. There are no keywords and characters are represented by a
- pair of decimal or hexadecimal (0x prefixed) values on single
+ data directory. The table file format is very
+ simple. There are no key words, and character mappings are represented by a
+ pair of decimal or hexadecimal (prefixed by <literal>0x</>) values on single
lines:
<synopsis>
-<replaceable>char_value</> <replaceable>translated_char_value</>
+<replaceable>char_value</> <replaceable>converted_char_value</>
</synopsis>
+ In the <filename>src/data/</> directory in the source distribution you can find an
+ example <filename>charset.conf</> and a few recoding tables.
</para>
<para>
<token>HostCharset</> records define the client character set by IP
address. You can use a single IP address, an IP mask range starting
- from the given address or an IP interval (e.g., 127.0.0.1,
- 192.168.1.100/24, 192.168.1.20-192.168.1.40).
+ from the given address or an IP interval (e.g., <literal>127.0.0.1</>,
+ <literal>192.168.1.100/24</>, <literal>192.168.1.20-192.168.1.40</>).
</para>
<para>
- The <filename>charset.conf</> file is always processed up to the
- end, so you can easily specify exceptions from the previous
- rules. In the <filename>src/data/</> directory you will find an
- example <filename>charset.conf</> and a few recoding tables.
+ The <filename>charset.conf</> file is always processed to the
+ end, so you can easily specify exceptions from preceding rules.
</para>
<para>
- As this solution is based on the client's IP address and character
- set mapping there are obviously some restrictions as well. You
- cannot use different encodings on the same host at the same
- time. It is also inconvenient when you boot your client hosts into
- multiple operating systems. Nevertheless, when these restrictions are
- not limiting and you do not need multibyte characters then it is a
+ As this solution is based on the client's IP address there are
+ obviously some restrictions as well. You cannot use different
+ character sets on the same host at the same time. It is also
+ inconvenient when you boot your client hosts into multiple
+ operating systems. Nevertheless, when these restrictions are not
+ limiting and you do not need multibyte characters then it is a
simple and effective solution.
</para>
</sect1>
<!--
-$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">
<para>
You can monitor disk space from three places: from
<application>psql</> using <command>VACUUM</> information, from
- <application>psql</> using <filename>contrib/dbsize</>, and from
- the command line using <application>contrib/oid2name</>. Using
- <application>psql</> on a recently vacuumed (or analyzed) database,
+ <application>psql</> using the tools in <filename>contrib/dbsize</>, and from
+ the command line using the tools in <filename>contrib/oid2name</>. Using
+ <application>psql</> on a recently vacuumed or analyzed database,
you can issue queries to see the disk usage of any table:
<programlisting>
-play=# SELECT relfilenode, relpages
-play-# FROM pg_class
-play-# WHERE relname = 'customer';
+SELECT relfilenode, relpages FROM pg_class WHERE relname = 'customer';
+
relfilenode | relpages
-------------+----------
16806 | 60
(1 row)
</programlisting>
+ Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
+ is only updated by <command>VACUUM</> and <command>ANALYZE</>.)
</para>
- <para>
- Each page is typically 8 kilobytes. (Remember, <literal>relpages</>
- is only updated by <command>VACUUM</> and <command>ANALYZE</>.) To
- show the space used by <acronym>TOAST</> tables, use a query based on
- the heap relfilenode shown above:
+ <para>
+ To show the space used by <acronym>TOAST</> tables, use a query
+ like the following, substituting the <literal>relfilenode</literal>
+ number of the heap (determined by the query above):
<programlisting>
-play=# SELECT relname, relpages
-play-# FROM pg_class
-play-# WHERE relname = 'pg_toast_16806' OR
-play-# relname = 'pg_toast_16806_index'
-play-# ORDER BY relname;
+SELECT relname, relpages
+ FROM pg_class
+ WHERE relname = 'pg_toast_16806' OR relname = 'pg_toast_16806_index'
+ ORDER BY relname;
+
relname | relpages
----------------------+----------
pg_toast_16806 | 0
</para>
<para>
- You can easily display index usage too:
+ You can easily display index sizes, too:
<programlisting>
-play=# SELECT c2.relname, c2.relpages
-play-# FROM pg_class c, pg_class c2, pg_index i
-play-# WHERE c.relname = 'customer' AND
-play-# c.oid = i.indrelid AND
-play-# c2.oid = i.indexrelid
-play-# ORDER BY c2.relname;
+SELECT c2.relname, c2.relpages
+ FROM pg_class c, pg_class c2, pg_index i
+ WHERE c.relname = 'customer'
+ AND c.oid = i.indrelid
+ AND c2.oid = i.indexrelid
+ ORDER BY c2.relname;
+
relname | relpages
----------------------+----------
customer_id_indexdex | 26
</para>
<para>
- It is easy to find your largest files using <application>psql</>:
+ It is easy to find your largest tables and indexes using this
+ information:
<programlisting>
-play=# SELECT relname, relpages
-play-# FROM pg_class
-play-# ORDER BY relpages DESC;
+SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
+
relname | relpages
----------------------+----------
bigtable | 3290
<para>
<filename>contrib/dbsize</> loads functions into your database that allow
you to find the size of a table or database from inside
- <application>psql</> without the need for <command>VACUUM/ANALYZE.</>
+ <application>psql</> without the need for <command>VACUUM</> or <command>ANALYZE</>.
</para>
<para>
You can also use <filename>contrib/oid2name</> to show disk usage. See
- <filename>README.oid2name</> for examples. It includes a script that
+ <filename>README.oid2name</> in that directory for examples. It includes a script that
shows disk usage for each database.
</para>
</sect1>
The most important disk monitoring task of a database administrator
is to make sure the disk doesn't grow full. A filled data disk may
result in subsequent corruption of database indexes, but not of the
- fundamental data tables. If the WAL files are on the same disk (as
+ tables themselves. If the WAL files are on the same disk (as
is the case for a default configuration) then a filled disk during
database initialization may result in corrupted or incomplete WAL
files. This failure condition is detected and the database server
information of such a setup; a restore would put everything back in
one place. To avoid running out of disk space, you can place the
WAL files or individual databases in other locations while creating
- them. See the <application>initdb</> documentation and <xref
- linkend="manage-ag-alternate-locs"> for more information.
+ them. See the <command>initdb</> documentation and <xref
+ linkend="manage-ag-alternate-locs"> for more information about that.
</para>
<tip>
<!--
-$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
-->
<entry><literal>255.255.255.0</literal></entry>
</row>
<row>
- <entry><function>hostmask</function>(<type>inet</type>)</entry>
+ <entry><literal><function>hostmask</function>(<type>inet</type>)</literal></entry>
<entry><type>inet</type></entry>
<entry>construct hostmask for network</entry>
<entry><literal>hostmask('192.168.23.20/30')</literal></entry>
<indexterm zone="functions-misc">
<primary>configuration</primary>
- <secondary>run time</secondary>
+ <secondary>server</secondary>
</indexterm>
<para>
<term><filename>interfaces\libpq\Release\libpqdll.lib</filename></term>
<listitem>
<para>
- Import library to link your program to <filename>libpq.dll</filename>
+ Import library to link your programs to <filename>libpq.dll</filename>
</para>
</listitem>
</varlistentry>
</para>
<para>
- To use the libraries, you must add the
+ To use the library, you must add the
<filename>libpqdll.lib</filename> file to your project. (In Visual
C++, just right-click on the project and choose to add it.)
</para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.20 2002/11/11 20:14:03 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v 1.21 2003/03/24 14:32:50 petere Exp $
-->
<chapter id="maintenance">
<title>Routine Database Maintenance Tasks</title>
- <sect1 id="maintenance-general">
- <title>General Discussion</Title>
-
<para>
There are a few routine maintenance chores that must be performed on
a regular basis to keep a <productname>PostgreSQL</productname>
- installation running smoothly. The tasks discussed here are repetitive
+ server running smoothly. The tasks discussed here are repetitive
in nature and can easily be automated using standard Unix tools such
as <application>cron</application> scripts. But it is the database
administrator's responsibility to set up appropriate scripts, and to
One obvious maintenance task is creation of backup copies of the data on a
regular schedule. Without a recent backup, you have no chance of recovery
after a catastrophe (disk failure, fire, mistakenly dropping a critical
- table, etc). The backup and recovery mechanisms available in
+ table, etc.). The backup and recovery mechanisms available in
<productname>PostgreSQL</productname> are discussed at length in
<xref linkend="backup">.
</para>
experience with the system.
</para>
- </sect1>
-
<sect1 id="routine-vacuuming">
<title>Routine Vacuuming</title>
</listitem>
</orderedlist>
- The frequency and scope of <command>VACUUM</>s performed for each of
- these reasons will vary depending on the needs of each installation.
+ The frequency and scope of the <command>VACUUM</> operations performed for each of
+ these reasons will vary depending on the needs of each site.
Therefore, database administrators must understand these issues and
develop an appropriate maintenance strategy. This section concentrates
on explaining the high-level issues; for details about command syntax
<para>
Beginning in <productname>PostgreSQL</productname> 7.2, the standard form
of <command>VACUUM</> can run in parallel with normal database operations
- (selects, inserts, updates, deletes, but not changes to table schemas).
+ (selects, inserts, updates, deletes, but not changes to table definitions).
Routine vacuuming is therefore not nearly as intrusive as it was in prior
releases, and it's not as critical to try to schedule it at low-usage
times of day.
return disk space to the operating system. If you need to return disk
space to the operating system you can use <command>VACUUM FULL</> ---
but what's the point of releasing disk space that will only have to be
- allocated again soon? Moderately frequent standard <command>VACUUM</>s
- are a better approach than infrequent <command>VACUUM FULL</>s for
+ allocated again soon? Moderately frequent standard <command>VACUUM</> runs
+ are a better approach than infrequent <command>VACUUM FULL</> runs for
maintaining heavily-updated tables.
</para>
Recommended practice for most sites is to schedule a database-wide
<command>VACUUM</> once a day at a low-usage time of day, supplemented
by more frequent vacuuming of heavily-updated tables if necessary.
- (If you have multiple databases in an installation, don't forget to
+ (If you have multiple databases in a cluster, don't forget to
vacuum each one; the <filename>vacuumdb</> script may be helpful.)
Use plain <command>VACUUM</>, not <command>VACUUM FULL</>, for routine
vacuuming for space recovery.
<para>
<productname>PostgreSQL</productname>'s MVCC transaction semantics
- depend on being able to compare transaction ID (<firstterm>XID</>)
- numbers: a tuple with an insertion XID newer than the current
+ depend on being able to compare transaction ID (<acronym>XID</>)
+ numbers: a tuple with an insertion XID greater than the current
transaction's XID is <quote>in the future</> and should not be visible
to the current transaction. But since transaction IDs have limited size
- (32 bits at this writing) an installation that runs for a long time (more
+ (32 bits at this writing) a cluster that runs for a long time (more
than 4 billion transactions) will suffer <firstterm>transaction ID
wraparound</>: the XID counter wraps around to zero, and all of a sudden
transactions that were in the past appear to be in the future --- which
against XID wraparound was to re-<command>initdb</> at least every 4
billion transactions. This of course was not very satisfactory for
high-traffic sites, so a better solution has been devised. The new
- approach allows an installation to remain up indefinitely, without
+ approach allows a server to remain up indefinitely, without
<command>initdb</> or any sort of restart. The price is this
maintenance requirement: <emphasis>every table in the database must
be vacuumed at least once every billion transactions</emphasis>.
<command>VACUUM</>'s normal policy is to reassign <literal>FrozenXID</>
to any tuple with a normal XID more than one billion transactions in the
past. This policy preserves the original insertion XID until it is not
- likely to be of interest anymore (in fact, most tuples will probably
- live and die without ever being <quote>frozen</>). With this policy,
- the maximum safe interval between <command>VACUUM</>s of any table
+ likely to be of interest anymore. (In fact, most tuples will probably
+ live and die without ever being <quote>frozen</>.) With this policy,
+ the maximum safe interval between <command>VACUUM</> runs on any table
is exactly one billion transactions: if you wait longer, it's possible
that a tuple that was not quite old enough to be reassigned last time
is now more than two billion transactions old and has wrapped around
</para>
<para>
- Since periodic <command>VACUUM</>s are needed anyway for the reasons
+ Since periodic <command>VACUUM</> runs are needed anyway for the reasons
described earlier, it's unlikely that any table would not be vacuumed
for as long as a billion transactions. But to help administrators ensure
this constraint is met, <command>VACUUM</> stores transaction ID
- statistics in the system table <filename>pg_database</>. In particular,
- the <filename>datfrozenxid</> field of a database's
- <filename>pg_database</> row is updated at the completion of any
+ statistics in the system table <literal>pg_database</>. In particular,
+ the <literal>datfrozenxid</> column of a database's
+ <literal>pg_database</> row is updated at the completion of any
database-wide vacuum operation (i.e., <command>VACUUM</> that does not
name a specific table). The value stored in this field is the freeze
cutoff XID that was used by that <command>VACUUM</> command. All normal
database at least once every half-a-billion (500 million) transactions,
so as to provide plenty of safety margin. To help meet this rule,
each database-wide <command>VACUUM</> automatically delivers a warning
- if there are any <filename>pg_database</> entries showing an
+ if there are any <literal>pg_database</> entries showing an
<literal>age</> of more than 1.5 billion transactions, for example:
<programlisting>
-play=# vacuum;
+play=# VACUUM;
WARNING: Some databases have not been vacuumed in 1613770184 transactions.
Better vacuum them within 533713463 transactions,
or you may have a wraparound failure.
database will be frozen. Hence, as long as the database is not
modified in any way, it will not need subsequent vacuuming to avoid
transaction ID wraparound problems. This technique is used by
- <filename>initdb</> to prepare the <filename>template0</> database.
+ <command>initdb</> to prepare the <literal>template0</> database.
It should also be used to prepare any user-created databases that
are to be marked <literal>datallowconn</> = <literal>false</> in
- <filename>pg_database</>, since there isn't any convenient way to
+ <literal>pg_database</>, since there isn't any convenient way to
vacuum a database that you can't connect to. Note that
<command>VACUUM</command>'s automatic warning message about
- unvacuumed databases will ignore <filename>pg_database</> entries
+ unvacuumed databases will ignore <literal>pg_database</> entries
with <literal>datallowconn</> = <literal>false</>, so as to avoid
giving false warnings about these databases; therefore it's up to
you to ensure that such databases are frozen correctly.
</para>
<para>
- If you simply direct the postmaster's <systemitem>stderr</> into a
+ If you simply direct the <systemitem>stderr</> of the <command>postmaster</command> into a
file, the only way to truncate the log file is to stop and restart
- the postmaster. This may be OK for development setups but you won't
+ the <command>postmaster</command>. This may be OK for development setups but you won't
want to run a production server that way.
</para>
The simplest production-grade approach to managing log output is to
send it all to <application>syslog</> and let
<application>syslog</> deal with file rotation. To do this, set
-
<literal>syslog</> to 2 (log to <application>syslog</> only) in
+
the configurations parameter <literal>syslog</> to 2 (to log to <application>syslog</> only) in
<filename>postgresql.conf</>. Then you can send a
<literal>SIGHUP</literal> signal to the <application>syslog</>
daemon whenever you want to force it to start writing a new log
On many systems, however, <application>syslog</> is not very reliable, particularly
with large log messages; it may truncate or drop messages just when
you need them the most. You may find it more useful to pipe the
- <application>postmaster</>'s <systemitem>stderr</> to some type of
- log rotation script. If you start the postmaster with
- <application>pg_ctl</>, then the postmaster's <systemitem>stderr</>
+ <systemitem>stderr</> of the <command>postmaster</> to some type of
+ log rotation program. If you start the server with
+ <command>pg_ctl</>, then the <systemitem>stderr</> of the <command>postmaster</command>
is already redirected to <systemitem>stdout</>, so you just need a
pipe command:
-<screen>
-<userinput>pg_ctl start | logrotate</userinput>
-</screen>
+<programlisting>
+pg_ctl start | logrotate
+</programlisting>
The <productname>PostgreSQL</> distribution doesn't include a suitable
- log rotation program, but there are many available on the net;
+ log rotation program, but there are many available on the Internet;
one is included in the Apache distribution, for example.
</para>
</sect1>
<!--
-$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">
<para>
Several tools are available for monitoring database activity and
analyzing performance. Most of this chapter is devoted to describing
- <productname>PostgreSQL</productname>'s <firstterm>statistics collector</>,
+ <productname>PostgreSQL</productname>'s statistics collector,
but one should not neglect regular Unix monitoring programs such as
<command>ps</> and <command>top</>. Also, once one has identified a
poorly-performing query, further investigation may be needed using
(The appropriate invocation of <command>ps</> varies across different
platforms, as do the details of what is shown. This example is from a
recent Linux system.) The first process listed here is the
- <firstterm>postmaster</>, the master server process. The command arguments
+ <application>postmaster</>, the master server process. The command arguments
shown for it are the same ones given when it was launched. The next two
processes implement the statistics collector, which will be described in
detail in the next section. (These will not be present if you have set
The activity may be <literal>idle</> (i.e., waiting for a client command),
<literal>idle in transaction</> (waiting for client inside a <command>BEGIN</> block),
or a command type name such as <literal>SELECT</>. Also,
- <literal>waiting</> is attached if the server is presently waiting
+ <literal>waiting</> is attached if the server process is presently waiting
on a lock held by another server process. In the above example we can infer
that process 1003 is waiting for process 1016 to complete its transaction and
thereby release some lock or other.
<para>
<productname>Solaris</productname> requires special handling. You must
use <command>/usr/ucb/ps</command>, rather than
- <command>/bin/ps</command>. You also must use two <command>w</command>
+ <command>/bin/ps</command>. You also must use two <option>w</option>
flags, not just one. In addition, your original invocation of the
- <application>postmaster</application> must have a shorter
+ <command>postmaster</command> command must have a shorter
<command>ps</command> status display than that provided by each
- backend. If you fail to do all three things, the <command>ps</>
- output for each backend will be the original <application>postmaster</>
+ server process. If you fail to do all three things, the <command>ps</>
+ output for each server process will be the original <command>postmaster</>
command line.
</para>
</tip>
-
-
-
</sect1>
<sect1 id="monitoring-stats">
- <title>Statistics Collector</Title>
+ <title>The Statistics Collector</Title>
<indexterm zone="monitoring-stats">
<primary>statistics</primary>
is a subsystem that supports collection and reporting of information about
server activity. Presently, the collector can count accesses to tables
and indexes in both disk-block and individual-row terms. It also supports
- determining the exact query currently being executed by other server
+ determining the exact command currently being executed by other server
processes.
</para>
<para>
Since collection of statistics adds some overhead to query execution,
the system can be configured to collect or not collect information.
- This is controlled by configuration variables that are normally set in
- <filename>postgresql.conf</> (see <xref linkend="runtime-config"> for
- details about setting configuration variables).
+ This is controlled by configuration parameters that are normally set in
+ <filename>postgresql.conf</>. (See <xref linkend="runtime-config"> for
+ details about setting configuration parameters.)
</para>
<para>
- The variable <varname>STATS_START_COLLECTOR</varname> must be set to
+ The parameter <varname>stats_start_collector</varname> must be set to
<literal>true</> for the statistics collector to
be launched at all. This is the default and recommended setting,
but it may be turned off if you have no interest in statistics and
</para>
<para>
- The variables <varname>STATS_COMMAND_STRING</varname>,
- <varname>STATS_BLOCK_LEVEL</varname>,
- and <varname>STATS_ROW_LEVEL</varname> control how much information is
- actually sent to the collector, and thus determine how much run-time
+ The parameters <varname>stats_command_string</varname>,
+ <varname>stats_block_level</varname>,
+ and <varname>stats_row_level</varname> control how much information is
+ actually sent to the collector and thus determine how much run-time
overhead occurs. These respectively determine whether a server process
sends its current command string, disk-block-level access statistics, and
- row-level access statistics to the collector. Normally these variables are
+ row-level access statistics to the collector. Normally these parameters are
set in <filename>postgresql.conf</> so that they apply to all server
- processes, but it is possible to turn them on or off in individual server
- processes using the <command>SET</> command. (To prevent ordinary users
+ processes, but it is possible to turn them on or off in individual sessions
+ using the <command>SET</> command. (To prevent ordinary users
from hiding their activity from the administrator, only superusers are
- allowed to change these variables with <command>SET</>.)
+ allowed to change these parameters with <command>SET</>.)
</para>
- <important>
+ <note>
<para>
- Since the variables <varname>STATS_COMMAND_STRING</varname>,
- <varname>STATS_BLOCK_LEVEL</varname>, and
- <varname>STATS_ROW_LEVEL</varname> default to <literal>false</>,
+ Since the parameters <varname>stats_command_string</varname>,
+ <varname>stats_block_level</varname>, and
+ <varname>stats_row_level</varname> default to <literal>false</>,
very few statistics are collected in the default
configuration. Enabling one or more of these configuration
variables will significantly enhance the amount of useful data
produced by the statistics collector, at the expense of
additional run-time overhead.
</para>
- </important>
+ </note>
</sect2>
<para>
Another important point is that when a server process is asked to display
any of these statistics, it first fetches the most recent totals emitted by
- the collector process. It then continues to use this snapshot for all
+ the collector process and then continues to use this snapshot for all
statistical views and functions until the end of its current transaction.
So the statistics will appear not to change as long as you continue the
current transaction.
<entry>One row per server process, showing process
<acronym>ID</>, database, user, current query, and the time at
which the current query began execution. The columns that report
- data on the current query are only available if the
- <varname>STATS_COMMAND_STRING</varname> configuration option has
- been enabled. Furthermore, these columns can only be accessed by
+ data on the current query are only available if the parameter
+ <varname>stats_command_string</varname> has been turned on.
+ Furthermore, these columns can only be accessed by
superusers; or when the user examining the view is the same as the user
in the row; for others it reads as null. (Note that because of the
collector's reporting delay, current query will only be up-to-date for
<row>
<entry><structname>pg_stat_database</></entry>
- <entry>One row per database, showing number of active backends,
+ <entry>One row per database, showing the number of active backend server processes,
total transactions committed and total rolled back in that database,
total disk blocks read, and total number of buffer hits (i.e., block
read requests avoided by finding the block already in buffer cache).
<entry>For each table in the current database, total numbers of
sequential and index scans, total numbers of tuples returned by
each type of scan, and totals of tuple insertions, updates,
- and deletes.</entry>
+ and deletions.</entry>
</row>
<row>
queries that use the same underlying statistics access functions as
these standard views do. These functions are listed in <xref
linkend="monitoring-stats-funcs-table">. The per-database access
- functions accept a database OID to identify which database to
- report on. The per-table and per-index functions accept a table or
- index OID (note that only tables and indexes in the current
- database can be seen with these functions). The per-backend access
- functions accept a backend ID number, which ranges from one to the
- number of currently active backends.
+ functions take a database OID as argument to identify which database to
+ report on. The per-table and per-index functions take a table or
+ index OID. (Note that only tables and indexes in the current
+ database can be seen with these functions.) The per-backend access
+ functions take a backend ID number, which ranges from one to the
+ number of currently active backend processes.
</para>
<table id="monitoring-stats-funcs-table">
<tbody>
<row>
- <entry><function>pg_stat_get_db_numbackends</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_numbackends</function>(<type>oid</type>)</literal></entry>
<entry><type>integer</type></entry>
<entry>
- Number of active backends in database
+ Number of active backend processes for database
</entry>
</row>
<row>
- <entry><function>pg_stat_get_db_xact_commit</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_xact_commit</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Transactions committed in database
</row>
<row>
- <entry><function>pg_stat_get_db_xact_rollback</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_xact_rollback</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Transactions rolled back in database
</row>
<row>
- <entry><function>pg_stat_get_db_blocks_fetched</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_blocks_fetched</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block fetch requests for database
</row>
<row>
- <entry><function>pg_stat_get_db_blocks_hit</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_db_blocks_hit</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block fetch requests found in cache for database
</row>
<row>
- <entry><function>pg_stat_get_numscans</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_numscans</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of sequential scans done when argument is a table,
</row>
<row>
- <entry><function>pg_stat_get_tuples_returned</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_returned</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples read by sequential scans when argument is a table,
</row>
<row>
- <entry><function>pg_stat_get_tuples_fetched</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_fetched</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of valid (unexpired) table tuples fetched by sequential scans
</row>
<row>
- <entry><function>pg_stat_get_tuples_inserted</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_inserted</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples inserted into table
</row>
<row>
- <entry><function>pg_stat_get_tuples_updated</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_updated</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples updated in table
</row>
<row>
- <entry><function>pg_stat_get_tuples_deleted</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_tuples_deleted</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of tuples deleted from table
</row>
<row>
- <entry><function>pg_stat_get_blocks_fetched</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_blocks_fetched</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block fetch requests for table or index
</row>
<row>
- <entry><function>pg_stat_get_blocks_hit</function>(<type>oid</type>)</entry>
+ <entry><literal><function>pg_stat_get_blocks_hit</function>(<type>oid</type>)</literal></entry>
<entry><type>bigint</type></entry>
<entry>
Number of disk block requests found in cache for table or index
</row>
<row>
- <entry><function>pg_stat_get_backend_idset</function>()</entry>
+ <entry><literal><function>pg_stat_get_backend_idset</function>()</literal></entry>
<entry><type>set of integer</type></entry>
<entry>
- Set of currently active backend IDs (from 1 to N where N is the
- number of active backends). See usage example below
+ Set of currently active backend process IDs (from 1 to the
+ number of active backend processes). See usage example in the text.
</entry>
</row>
<row>
- <entry><function>pg_backend_pid</function>()</entry>
+ <entry><literal><function>pg_backend_pid</function>()</literal></entry>
<entry><type>integer</type></entry>
<entry>
- Process ID of the attached backend
+ Process ID of the backend process attached to the current session
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_pid</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_pid</function>(<type>integer</type>)</literal></entry>
<entry><type>integer</type></entry>
<entry>
- Process ID of all backend processes
+ Process ID of the given backend process
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_dbid</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_dbid</function>(<type>integer</type>)</literal></entry>
<entry><type>oid</type></entry>
<entry>
- Database ID of backend process
+ Database ID of the given backend process
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_userid</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_userid</function>(<type>integer</type>)</literal></entry>
<entry><type>oid</type></entry>
<entry>
- User ID of backend process
+ User ID of the given backend process
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_activity</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_activity</function>(<type>integer</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>
- Current query of backend process (NULL if caller is not
- superuser, or is the same user as that of the backend being queried,
- or <varname>STATS_COMMAND_STRING</varname> is not enabled)
+ Active command of the given backend process (null if the
+ current user is not a superuser nor the same user as that of
+ the session being queried, or
+ <varname>stats_command_string</varname> is not on)
</entry>
</row>
<row>
- <entry><function>pg_stat_get_backend_activity_start</function>(<type>integer</type>)</entry>
+ <entry><literal><function>pg_stat_get_backend_activity_start</function>(<type>integer</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>
- The time at which the specified backend's currently executing query was
- initiated (NULL if caller is not superuser, or
- <varname>STATS_COMMAND_STRING</varname> is not enabled)
+ The time at which the specified backend process' currently
+ executing query was started (null if the current user is not a
+ superuser, or <varname>stats_command_string</varname> is not
+ on)
</entry>
</row>
<row>
- <entry><function>pg_stat_reset</function>()</entry>
+ <entry><literal><function>pg_stat_reset</function>()</literal></entry>
<entry><type>boolean</type></entry>
<entry>
Reset all currently collected statistics
<note>
<para>
- <literal>blocks_fetched</literal> minus
- <literal>blocks_hit</literal> gives the number of kernel
+ <function>pg_stat_get_db_blocks_fetched</function> minus
+ <function>pg_stat_get_db_blocks_hit</function> gives the number of kernel
<function>read()</> calls issued for the table, index, or
database; but the actual number of physical reads is usually
lower due to kernel-level buffering.
<para>
The function <function>pg_stat_get_backend_idset</function> provides
- a convenient way to generate one row for each active backend. For
- example, to show the <acronym>PID</>s and current queries of all backends:
+ a convenient way to generate one row for each active backend process. For
+ example, to show the <acronym>PID</>s and current queries of all backend processes:
<programlisting>
-SELECT pg_stat_get_backend_pid(S.backendid) AS procpid,
- pg_stat_get_backend_activity(S.backendid) AS current_query
-FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS S;
+SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
+ pg_stat_get_backend_activity(s.backendid) AS current_query
+ FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;
</programlisting>
</para>
<para>
Another useful tool for monitoring database activity is the
- <literal>pg_locks</literal> system catalog. This allows the
+ <literal>pg_locks</literal> system table. It allows the
database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be used
to:
<listitem>
<para>
- View the relation in the current database with the most
+ Determine the relation in the current database with the most
ungranted locks (which might be a source of contention among
database clients).
</para>
view produces a consistent set of results, while not blocking
normal lock manager operations longer than necessary. Nonetheless
there could be some impact on database performance if this view is
- examined often.
+ read often.
</para>
</note>
<literal>pg_locks</literal> view contains one row per lockable
object and requested lock mode. Thus, the same lockable object may
appear many times, if multiple transactions are holding or waiting
- for locks on it. A lockable object is either a relation or a
+ for locks on it. A lockable object is either a relation (e.g., a table) or a
transaction ID. (Note that this view includes only table-level
locks, not row-level ones. If a transaction is waiting for a
row-level lock, it will appear in the view as waiting for the
</para>
<table id="monitoring-locks-table">
- <title>Lock Status System View</title>
+ <title><literal>pg_locks</literal> Columns</title>
<tgroup cols="3">
<thead>
<row>
<entry>Column Name</entry>
- <entry>Type</entry>
+ <entry>Data Type</entry>
<entry>Description</entry>
</row>
</thead>
<entry><type>oid</type></entry>
<entry>
The OID of the locked relation, or null if the lockable object
- is a transaction ID. This column can be joined with the
+ is a transaction ID. This column can be joined with the column <literal>oid</> of the
<literal>pg_class</literal> system catalog to get more
information on the locked relation. Note however that this
will only work for relations in the current database (those for
The OID of the database in which the locked relation exists, or
null if the lockable object is a transaction ID. If the lock
is on a globally-shared table, this field will be zero. This
- column can be joined with the <literal>pg_database</literal>
+ column can be joined with the column <literal>oid</> of the <literal>pg_database</literal>
system catalog to get more information on the locked object's
database.
</entry>
<entry><type>integer</type></entry>
<entry>
The process ID of the <productname>PostgreSQL</productname>
- backend belonging to the session that has acquired or is
+ server process belonging to the session that has acquired or is
attempting to acquire the lock. If you have enabled the
- statistics collector, this column can be joined with the
+ statistics collector, this column can be joined with the column
<literal>pg_stat_activity</literal> view to get more
- information on the backend holding or waiting to hold the
+ information on the session holding or waiting to hold the
lock.
</entry>
</row>
False indicates that this session is currently waiting to
acquire this lock, which implies that some other session is
holding a conflicting lock mode on the same lockable object.
- This backend will sleep until the other lock is released (or a
- deadlock situation is detected). A single backend can be
+ The waiting session will sleep until the other lock is released (or a
+ deadlock situation is detected). A single session can be
waiting to acquire at most one lock at a time.
</entry>
</row>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>clusterdb</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg>--table | -t <replaceable>table</replaceable> </arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
<command>clusterdb</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group><arg>--all</arg><arg>-a</arg></group>
</cmdsynopsis>
</refsynopsisdiv>
<term><option>--table <replaceable class="parameter">table</replaceable></></term>
<listitem>
<para>
- Clusters <replaceable class="parameter">table</replaceable> only.
+ Cluster <replaceable class="parameter">table</replaceable> only.
</para>
</listitem>
</varlistentry>
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>createdb</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<arg><replaceable>description</replaceable></arg>
</cmdsynopsis>
endterm="SQL-CREATEDATABASE-title">. Thus, there is nothing
special about creating databases via this or other methods. This
means that a database server must be running at the targeted
- port. Also, any default settings and environment variables used by
+ host. Also, any default settings and environment variables used by
the <application>libpq</application> front-end library will apply.
</para>
</refsect1>
<listitem>
<para>
Specifies the name of the database to be created. The name must be
- unique among all <productname>PostgreSQL</productname> databases in this installation.
+ unique among all <productname>PostgreSQL</productname> databases in this cluster.
The default is to create a database with the same name as the
current system user.
</para>
<term><option>--echo</></term>
<listitem>
<para>
- Echo the
queries that <application>createdb</application> generates
+ Echo the
commands that <application>createdb</application> generates
and sends to the server.
</para>
</listitem>
<listitem>
<para>
Specifies the host name of the machine on which the
- server is running. If host begins with a slash, it is used
+ server is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or the local Unix domain socket file
+ Specifies the TCP port or the local Unix domain socket file
extension on which the server is listening for connections.
</para>
</listitem>
To create the database <literal>demo</literal> using the
server on host <literal>eden</>, port 5000, using the
<literal>LATIN1</literal> encoding scheme with a look at the
- underlying query:
+ underlying command:
<screen>
<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
<computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>createlang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg choice="plain"><replaceable>langname</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
<command>createlang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group choice="plain"><arg>--list</arg><arg>-l</arg></group>
<arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
<term><option>--echo</></term>
<listitem>
<para>
- Displays SQL commands as they are executed.
+ Display SQL commands as they are executed.
</para>
</listitem>
</varlistentry>
<term><option>--list</></term>
<listitem>
<para>
- Shows a list of already installed languages in the target database
- (which must be specified).
+ Show a list of already installed languages in the target database.
</para>
</listitem>
</varlistentry>
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
<title>Examples</title>
<para>
- To install <literal>pltcl</literal> into the database
+ To install the language <literal>pltcl</literal> into the database
<literal>template1</literal>:
<screen>
<prompt>$ </prompt><userinput>createlang pltcl template1</userinput>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>createuser</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>username</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<listitem>
<para>
The new user is allowed to create other users.
- (Note: Actually, this makes the new user a <firstterm>superuser</>.
+ (Note: Actually, this makes the new user a <emphasis>superuser</>.
The option is poorly named.)
</para>
</listitem>
<term><option>--echo</></term>
<listitem>
<para>
- Echo the
queries that <application>createuser</application> generates
+ Echo the
commands that <application>createuser</application> generates
and sends to the server.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-i <replaceable class="parameter">uid</replaceable></></term>
- <term><option>--sysid <replaceable class="parameter">uid</replaceable></></term>
+ <term><option>-i <replaceable class="parameter">number</replaceable></></term>
+ <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
<listitem>
<para>
Allows you to pick a non-default user ID for the new user. This is not
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
<para>
To create the same user <literal>joe</literal> using the
server on host <literal>eden</>, port 5000, avoiding the prompts and
- taking a look at the underlying query:
+ taking a look at the underlying command:
<screen>
<prompt>$ </prompt><userinput>createuser -p 5000 -h eden -D -A -e joe</userinput>
<computeroutput>CREATE USER "joe" NOCREATEDB NOCREATEUSER</computeroutput>
+++ /dev/null
-<!--
-$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:
--->
+++ /dev/null
-<!--
-$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:
--->
+++ /dev/null
-<!--
-$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:
--->
+++ /dev/null
-<!--
-$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:
--->
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>dropdb</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<term><replaceable class="parameter">dbname</replaceable></term>
<listitem>
<para>
- Specifies the name of the database to be removed. The database
- must be one of the existing <productname>PostgreSQL</productname> databases
- in this installation.
+ Specifies the name of the database to be removed.
</para>
</listitem>
</varlistentry>
<term><option>--echo</></term>
<listitem>
<para>
- Echo the
queries that <application>dropdb</application> generates
+ Echo the
commands that <application>dropdb</application> generates
and sends to the server.
</para>
</listitem>
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
<para>
To destroy the database <literal>demo</literal> using the
server on host <literal>eden</literal>, port 5000, with verification and a peek
- at the underlying query:
+ at the underlying command:
<screen>
<prompt>$ </prompt><userinput>dropdb -p 5000 -h eden -i -e demo</userinput>
<computeroutput>Database "demo" will be permanently deleted.
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>droplang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<arg choice="plain"><replaceable>langname</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
<sbr>
<command>droplang</command>
- <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
+ <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
<group choice="plain"><arg>--list</arg><arg>-l</arg></group>
<arg choice="plain"><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
<term><option>--echo</></term>
<listitem>
<para>
- Displays SQL commands as they are executed.
+ Display SQL commands as they are executed.
</para>
</listitem>
</varlistentry>
<term><option>--list</></term>
<listitem>
<para>
- Shows a list of already installed languages in the target database
- (which must be specified).
+ Show a list of already installed languages in the target database.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
<title>Examples</title>
<para>
- To remove <literal>pltcl</literal>:
+ To remove the language <literal>pltcl</literal>:
<screen>
<prompt>$ </prompt><userinput>droplang pltcl dbname</userinput>
</screen>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>dropuser</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>username</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<application>dropuser</application> removes an existing
<productname>PostgreSQL</productname> user
<emphasis>and</emphasis> the databases which that user owned.
- Only users with <literal>usesuper</literal> set in
- the <literal>pg_shadow</literal> table can destroy
+ Only superusers (users with <literal>usesuper</literal> set in
+ the <literal>pg_shadow</literal> table) can destroy
<productname>PostgreSQL</productname> users.
</para>
<listitem>
<para>
Specifies the name of the <productname>PostgreSQL</productname> user to be removed.
- This name must exist in the <productname>PostgreSQL</productname> installation.
You will be prompted for a name if none is specified on the command line.
</para>
</listitem>
<term><option>--echo</></term>
<listitem>
<para>
- Echo the
queries that <application>dropuser</application> generates
+ Echo the
commands that <application>dropuser</application> generates
and sends to the server.
</para>
</listitem>
<para>
Specifies the host name of the machine on which the
server
- is running. If host begins with a slash, it is used
+ is running. If the value begins with a slash, it is used
as the directory for the Unix domain socket.
</para>
</listitem>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
+ Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</para>
</para>
<para>
- To remove user <literal>joe</literal> using the postmaster on host
+ To remove user <literal>joe</literal> using the server on host
<literal>eden</literal>, port 5000, with verification and a peek at the underlying
- query:
+ command:
<screen>
<prompt>$ </prompt><userinput>dropuser -p 5000 -h eden -i -e joe</userinput>
<computeroutput>User "joe" and any owned databases will be permanently deleted.
<!--
-$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
-->
<term><option>-c</option></term>
<listitem>
<para>
- Automatically generate C code from SQL code. Currently, this
+ Automatically generate certain C code from SQL code. Currently, this
works for <literal>EXEC SQL TYPE</literal>.
</para>
</listitem>
<term><option>-o <replaceable>filename</replaceable></option></term>
<listitem>
<para>
- Specifies that <application>ecpg</application> should write all
+ Specifies that <command>ecpg</command> should write all
its output to the given <replaceable>filename</replaceable>.
</para>
</listitem>
<term><option>-t</option></term>
<listitem>
<para>
- Turn on autocommit of transactions. In this mode, each query is
+ Turn on autocommit of transactions. In this mode, each SQL command is
automatically committed unless it is inside an explicit
- transaction block. In the default mode, queries are committed
+ transaction block. In the default mode, commands are committed
only when <command>EXEC SQL COMMIT</command> is issued.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>---help</option></term>
+ <term><option>--help</option></term>
<listitem>
<para>
Show a brief summary of the command usage, then exit.
<para>
Programs using C code with embedded SQL have to be linked against
the <filename>libecpg</filename> library, for example using the
- flags <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
+ linker options <literal>-L/usr/local/pgsql/lib -lecpg</literal>.
</para>
<para>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>initdb</command>
- <arg rep="repeat">options</arg>
+ <arg rep="repeat"><replaceable>option</></arg>
<group choice="plain">
<arg>--pgdata </arg>
<arg>-D </arg>
</title>
<para>
<command>initdb</command> creates a new
- <productname>PostgreSQL</productname> database cluster (or database
- system). A database cluster is a collection of databases that are
- managed by a single server instance.
+ <productname>PostgreSQL</productname> database cluster. A database
+ cluster is a collection of databases that are managed by a single
+ server instance.
</para>
<para>
- Creating a database system consists of creating the directories in which
+ Creating a database cluster consists of creating the directories in which
the database data will live, generating the shared catalog tables
(tables that belong to the whole cluster rather than to any particular
database), and creating the <literal>template1</literal>
- database. When you create a new database, everything in the
+ database. When you later create a new database, everything in the
<literal>template1</literal> database is copied.
It contains catalog tables filled in for things like the
built-in types.
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
<listitem>
<para>
- This option specifies the directory where the database system
+ This option specifies the directory where the database cluster
should be stored. This is the only information required by
<command>initdb</command>, but you can avoid writing it by
setting the <envar>PGDATA</envar> environment variable, which
<para>
Selects the encoding of the template database. This will also
be the default encoding of any database you create later, unless you
- override it there. To use the encoding feature, you must
- have enabled it at build time, at which time you also select the default
- for this option.
+ override it there. The default is <literal>SQL_ASCII</literal>.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Specifies where <command>initdb</command> should find
- its input files to initialize the database system. This is
+ its input files to initialize the database cluster. This is
normally not necessary. You will be told if you need to
specify their location explicitly.
</para>
<para>
By default, when <command>initdb</command>
determines that an error prevented it from completely creating the database
- system, it removes any files it may have created before discovering
+ cluster, it removes any files it may have created before discovering
that it can't finish the job. This option inhibits tidying-up and is
thus useful for debugging.
</para>
<listitem>
<para>
- Specifies the directory where the database system is to be
+ Specifies the directory where the database cluster is to be
stored; may be overridden using the <option>-D</option> option.
</para>
</listitem>
<!--
-$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
-->
<screen>
<prompt>$ </prompt><userinput>export PGDATA2=/opt/postgres/data</userinput>
</screen>
- Stop and start postmaster so it sees the <envar>PGDATA2</envar>
+ Stop and start <command>postmaster</> so it sees the <envar>PGDATA2</envar>
environment variable. The system must be configured so the
- postmaster sees <envar>PGDATA2</envar> every time it starts. Finally:
+ <command>postmaster</> sees <envar>PGDATA2</envar> every time it starts. Finally:
<screen>
<prompt>$</prompt> <userinput>initlocation PGDATA2</userinput>
<prompt>$</prompt> <userinput>createdb -D PGDATA2 testdb</userinput>
<!--
-$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
-->
<para>
Only the database administrator should execute this program as it
can cause bizarre behavior (i.e., crashes) if run during multiuser
- execution. If this command is executed while a
- <application>postmaster</application> is running, the shared memory
- and semaphores allocated by the
- <application>postmaster</application> will be deleted. This will
- result in a general failure of the backend servers started by that
- <application>postmaster</application>.
+ execution. If this command is executed while a server is running,
+ the shared memory and semaphores allocated by that server will be
+ deleted, which would have rather severe consequences for that
+ server.
</para>
</refsect1>
<para>
This script is a hack, but in the many years since it was written,
no one has come up with an equally effective and portable solution.
- Since the <application>postmaster</application> can now clean up by
+ Since the <command>postmaster</command> can now clean up by
itself, it is unlikely that <command>ipcclean</command> will be
improved upon in the future.
</para>
<para>
The script makes assumption about the format of output of the
- <application>ipcs</application>
+ <command>ipcs</command>
utility which may not be true across different operating systems.
Therefore, it may not work on your particular OS.
</para>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.13 2003/01/19 00:13:29 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.14 2003/03/24 14:32:51 petere Exp $ -->
<refentry id="app-pgconfig">
<refmeta>
<listitem>
<para>
Print the location of user executables. Use this, for example, to find
- the <application>psql</> program. This is normally also the location
+ the <command>psql</> program. This is normally also the location
where the <filename>pg_config</> program resides.
</para>
</listitem>
<title>Notes</title>
<para>
- The option <option>--includedir-server</option> is new in
+ The option <option>--includedir-server</option> was new in
<productname>PostgreSQL</> 7.2. In prior releases, the server include files were
installed in the same location as the client headers, which could
- be queried with the <option>--includedir</option>. To make your
+ be queried with the option <option>--includedir</option>. To make your
package handle both cases, try the newer option first and test the
exit status to see whether it succeeded.
</para>
<!--
-$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
-->
<refnamediv>
<refname>pg_controldata</refname>
- <refpurpose>display server-wide control information</refpurpose>
+ <refpurpose>display control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsect1 id="R1-APP-PGCONTROLDATA-1">
<title>Description</title>
<para>
- <command>pg_controldata</command> returns information initialized during
- <application>initdb</>, such as the catalog version and server locale.
+ <command>pg_controldata</command> prints information initialized during
+ <command>initdb</>, such as the catalog version and server locale.
It also shows information about write-ahead logging and checkpoint
- processing. This information is server-wide, and not specific to any one
+ processing. This information is cluster-wide, and not specific to any one
database.
</para>
<para>
- This utility may only be run by the user who installed the server because
- it requires read access to the <literal>datadir</>.
+ This utility may only be run by the user who initialized the cluster because
+ it requires read access to the data directory.
You can specify the data directory on the command line, or use
the environment variable <envar>PGDATA</>.
</para>
<!--
-$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
-->
<title>Description</title>
<para>
<application>pg_ctl</application> is a utility for starting,
- stopping, or restarting <xref linkend="app-postmaster">, the
- <productname>PostgreSQL</productname> backend server, or displaying
- the status of a running postmaster. Although the postmaster can be
- started manually, <application>pg_ctl</application> encapsulates
- tasks such as redirecting log output and properly detaching from the
- terminal and process group. It also provides convenient options for
+ stopping, or restarting the <productname>PostgreSQL</productname>
+ backend server (<xref linkend="app-postmaster">), or displaying the
+ status of a running server. Although the server can be started
+ manually, <application>pg_ctl</application> encapsulates tasks such
+ as redirecting log output and properly detaching from the terminal
+ and process group. It also provides convenient options for
controlled shutdown.
</para>
<para>
- In <option>start</option> mode, a new postmaster is launched. The
+ In <option>start</option> mode, a new server is launched. The
server is started in the background, and standard input is attached to
<filename>/dev/null</filename>. The standard output and standard
error are either appended to a log file (if the <option>-l</option>
standard output (not standard error). If no log file is chosen, the
standard output of <application>pg_ctl</application> should be redirected
to a file or piped to another process, for example a log rotating program,
- otherwise the postmaster will write its output to the controlling
+ otherwise <command>postmaster</command> will write its output to the controlling
terminal (from the background) and will not leave the shell's
process group.
</para>
<para>
- In <option>stop</option> mode, the postmaster that is running in
+ In <option>stop</option> mode, the server that is running in
the specified data directory is shut down. Three different
shutdown methods can be selected with the <option>-m</option>
option: <quote>Smart</quote> mode waits for all the clients to
disconnect. This is the default. <quote>Fast</quote> mode does
not wait for clients to disconnect. All active transactions are
rolled back and clients are forcibly disconnected, then the
- database is shut down. <quote>Immediate</quote> mode will abort
+ server is shut down. <quote>Immediate</quote> mode will abort
all server processes without a clean shutdown. This will lead to
a recovery run on restart.
</para>
<para>
<option>restart</option> mode effectively executes a stop followed
- by a start. This allows the changing of postmaster command line
- options.
+ by a start. This allows changing the <command>postmaster</command>
+ command-line options.
</para>
<para>
- <option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
- causing it to reread its configuration files
- (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
- etc.). This allows changing of configuration-file options that do not
- require a complete restart to take effect.
+ <option>reload</option> mode simply sends the
+ <command>postmaster</command> process a <systemitem>SIGHUP</>
+ signal, causing it to reread its configuration files
+ (<filename>postgresql.conf</filename>,
+ <filename>pg_hba.conf</filename>, etc.). This allows changing of
+ configuration-file options that do not require a complete restart
+ to take effect.
</para>
<para>
- <option>status</option> mode checks whether a postmaster is running.
- If it is, the <acronym>PID</acronym> and the command line
- options that were used to invoke it are displayed.
+ <option>status</option> mode checks whether a server is running in
+ the specified data directory. If it is, the <acronym>PID</acronym>
+ and the command line options that were used to invoke it are
+ displayed.
</para>
</refsect1>
<variablelist>
<varlistentry>
- <term>-D <replaceable class="parameter">datadir</replaceable></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
Specifies the file system location of the database files. If
</varlistentry>
<varlistentry>
- <term>-l <replaceable class="parameter">filename</replaceable></term>
+ <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
Append the server log output to
</varlistentry>
<varlistentry>
- <term>-m <replaceable class="parameter">mode</replaceable></term>
+ <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
<listitem>
<para>
Specifies the shutdown mode. <replaceable>mode</replaceable>
</varlistentry>
<varlistentry>
- <term>-o <replaceable class="parameter">options</replaceable></term>
+ <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
<listitem>
<para>
- Specifies options to be passed directly to
- <application>postmaster</application>.
+ Specifies options to be passed directly to the
+ <command>postmaster</command> command.
</para>
<para>
- The parameters are usually surrounded by single or double
+ The options are usually surrounded by single or double
quotes to ensure that they are passed through as a group.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-p <replaceable class="parameter">path</replaceable></term>
+ <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
<listitem>
<para>
Specifies the location of the <filename>postmaster</filename>
- executable. By default the postmaster is taken from the same
+ executable. By default the <filename>postmaster</filename> executable is taken from the same
directory as <command>pg_ctl</command>, or failing that, the hard-wired
installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors
- that the postmaster was not found.
+ that the <filename>postmaster</filename> executable was not found.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-s</term>
+ <term><option>-s</option></term>
<listitem>
<para>
Only print errors, no informational messages.
</varlistentry>
<varlistentry>
- <term>-w</term>
+ <term><option>-w</option></term>
<listitem>
<para>
Wait for the start or shutdown to complete. Times out after
</varlistentry>
<varlistentry>
- <term>-W</term>
+ <term><option>-W</option></term>
<listitem>
<para>
Do not wait for start or shutdown to complete. This is the
<term><filename>postmaster.pid</filename></term>
<listitem>
- <para>The existence of this file in the data directory is used to help
- <application>pg_ctl</application> determine if the server is
- currently running or not.
+ <para>
+ The existence of this file in the data directory is used to help
+ <application>pg_ctl</application> determine if the server is
+ currently running or not.
</para>
</listitem>
</varlistentry>
<term><filename>postmaster.opts.default</filename></term>
<listitem>
- <para>If this file exists in the data directory,
- <application>pg_ctl</application> (in <option>start</option> mode)
- will pass the contents of the file as options to the
- <application>postmaster</application>, unless overridden
- by the <option>-o</option> option.
+ <para>
+ If this file exists in the data directory,
+ <application>pg_ctl</application> (in <option>start</option>
+ mode) will pass the contents of the file as options to the
+ <command>postmaster</command> command, unless overridden by the
+ <option>-o</option> option.
</para>
</listitem>
</varlistentry>
<term><filename>postgresql.conf</filename></term>
<listitem>
- <para>This file, located in the data directory, is parsed to
- find the proper port to send to the
- <application>psql</application> when the <option>-w</option>
- is given in <option>start</option> mode.
+ <para>
+ This file, located in the data directory, is parsed to find the
+ proper port to use with <application>psql</application> when the
+ <option>-w</option> is given in <option>start</option> mode.
</para>
</listitem>
</varlistentry>
<para>
Waiting for complete start is not a well-defined operation and may
fail if access control is set up so that a local client cannot
- connect without manual interaction (e.g. password authentication).
+ connect without manual interaction (e.g., password authentication).
</para>
</refsect1>
<title>Examples</title>
<refsect2 id="R2-APP-PGCTL-3">
- <title>Starting the postmaster</title>
+ <title>Starting the Server</title>
<para>
- To start up a <application>postmaster</application>:
+ To start up a server:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
</para>
<para>
- An example of starting the <application>postmaster</application>,
- blocking until the postmaster comes up is:
+ An example of starting the server, blocking until the server has
+ come up is:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
</para>
<para>
- For a <application>postmaster</application> using port 5433, and
+ For a server using port 5433, and
running without <function>fsync</function>, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
</refsect2>
<refsect2 id="R2-APP-PGCTL-4">
- <title>Stopping the postmaster</title>
+ <title>Stopping the Server</title>
<para>
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
- stops the postmaster. Using the <option>-m</option> switch allows one
+ stops the server. Using the <option>-m</option> switch allows one
to control <emphasis>how</emphasis> the backend shuts down.
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-5">
- <title>Restarting the postmaster</title>
+ <title>Restarting the Server</title>
<para>
- This is almost equivalent to stopping the
- <application>postmaster</application> and starting it again
+ Restarting the server is almost equivalent to stopping the
+ server and starting it again
except that <command>pg_ctl</command> saves and reuses the command line options that
were passed to the previously running instance. To restart
- the <application>postmaster</application> in the simplest form:
+ the server in the simplest form, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
</para>
<para>
- To restart <application>postmaster</application>,
+ To restart server,
waiting for it to shut down and to come up:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
</refsect2>
<refsect2 id="R2-APP-PGCTL-6">
- <title>Showing postmaster status</title>
+ <title>Showing the Server Status</title>
<para>
Here is a sample status output from
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_dump</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg><replaceable>dbname</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
architectures.
</para>
- <para>
- <application>pg_dump</application> will save the information necessary to
- re-generate all user-defined types, functions, tables, indexes,
- aggregates, and operators. In addition, all the data is copied out
- in text format so that it can be readily copied in again, as well
- as imported into tools for editing.
- </para>
-
<para>
When used with one of the archive file formats and combined with
<application>pg_restore</application>, <application>pg_dump</application> provides a
The most flexible output file format is the <quote>custom</quote>
format (<option>-Fc</option>). It allows for selection and
reordering of all archived items, and is compressed by default. The
- <filename>tar</filename> format (<option>-Ft</option>) is not
+ <application>tar</application> format (<option>-Ft</option>) is not
compressed and it is not possible to reorder data when loading, but
it is otherwise quite flexible; moreover, it can be manipulated with
- other tools such as <filename>tar</filename>.
+ other tools such as <command>tar</command>.
</para>
<para>
- While running <command>pg_dump</command>, one should examine the
+ While running <application>pg_dump</application>, one should examine the
output for any warnings (printed on standard error), especially in
light of the limitations listed below.
</para>
<replaceable>table</replaceable>
(<replaceable>column</replaceable>, ...) VALUES
...</literal>). This will make restoration very slow,
- but it is necessary if you desire to rearrange column ordering.
+ but it is necessary if you desire to rearrange the column ordering.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
- <term>p</term>
+ <term><literal>p</></term>
<listitem>
<para>
Output a plain-text <acronym>SQL</acronym> script file (default)
</varlistentry>
<varlistentry>
- <term>t</term>
+ <term><literal>t</></term>
<listitem>
<para>
- Output a <filename>tar</filename> archive suitable for input into
+ Output a <command>tar</command> archive suitable for input into
<application>pg_restore</application>. Using this archive format
allows reordering and/or exclusion of schema elements
at the time the database is restored. It is also possible to limit
</varlistentry>
<varlistentry>
- <term>c</term>
+ <term><literal>c</></term>
<listitem>
<para>
Output a custom archive suitable for input into
<term><option>--compress=<replaceable class="parameter">0..9</replaceable></option></term>
<listitem>
<para>
- Specify the compression level to use in archive formats that support
- compression (currently only the custom archive format supports compression).
+ Specify the compression level to use in archive formats that
+ support compression. (Currently only the custom archive
+ format supports compression.)
</para>
</listitem>
</varlistentry>
<term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
<listitem>
<para>
- Specifies the host name of the machine on which the server is
- running. If the host name begins with a slash, it is used as the
- directory for the Unix domain socket.
+ Specifies the host name of the machine on which the server is
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <envar>PGHOST</envar> environment variable, if set,
+ else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket file
- extension on which the server
- is listening for connections. The port number defaults to 5432,
- or the value of the <envar>PGPORT</envar>
- environment variable (if set).
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
<refsect1 id="app-pgdump-diagnostics">
<title>Diagnostics</title>
- <msgset>
- <msgentry>
- <msg>
- <msgmain>
- <msgtext>
-<screen>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
- Is the postmaster running locally
- and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-</screen>
- </msgtext>
- </msgmain>
- </msg>
-
- <msgexplan>
- <para>
- <application>pg_dump</application> could not connect to the
- PostgreSQL server on the specified host and port. If you see this
- message, ensure that the server is running on the proper host and
- that you have specified the proper port.
- </para>
- </msgexplan>
- </msgentry>
-
- </msgset>
-
- <note>
- <para>
- <application>pg_dump</application> internally executes
- <command>SELECT</command> statements. If you have problems running
- <application>pg_dump</application>,
- make sure you are able to select information from the database using, for
- example, <xref linkend="app-psql">.
- </para>
- </note>
+ <para>
+ <application>pg_dump</application> internally executes
+ <command>SELECT</command> statements. If you have problems running
+ <application>pg_dump</application>, make sure you are able to
+ select information from the database using, for example, <xref
+ linkend="app-psql">.
+ </para>
</refsect1>
<title>Notes</title>
<para>
- If your installation has any local additions to the template1 database,
+ If your database cluster has any local additions to the <literal>template1</> database,
be careful to restore the output of <application>pg_dump</application> into a
truly empty database; otherwise you are likely to get errors due to
duplicate definitions of the added objects. To make an empty database
- without any local additions, copy from template0 not template1,
+ without any local additions, copy from <literal>template0</> not <literal>template1</>,
for example:
<programlisting>
CREATE DATABASE foo WITH TEMPLATE template0;
<listitem>
<para>
When dumping a single table or as plain text, <application>pg_dump</application>
- does not handle large objects. Large objects must be dumped in their
- entirety using one of the binary archive formats.
+ does not handle large objects. Large objects must be dumped with the
+ entire database using one of the non-text archive formats.
</para>
</listitem>
<listitem>
<para>
- When doing a data-only dump, <application>pg_dump</application> emits queries
- to disable triggers on user tables before inserting the data and queries to
- re-enable them after the data has been inserted. If the restore is stopped
- in the middle, the system catalogs may be left in the wrong state.
+ When a data-only dump is chosen and the option
+ <option>--disable-triggers</> is used,
+ <application>pg_dump</application> emits commands to disable
+ triggers on user tables before inserting the data and commands
+ to re-enable them after the data has been inserted. If the
+ restore is stopped in the middle, the system catalogs may be
+ left in the wrong state.
</para>
</listitem>
<para>
The <application>pg_dump</application> utility first appeared in
- <application>Postgres95</application> release <literal>0.02</literal>. The
+ <application>Postgres95</application> release 0.02. The
non-plain-text output formats were introduced in
- <application>PostgreSQL</application> release <literal>7.1</literal>.
+ <application>PostgreSQL</application> release 7.1.
</para>
</refsect1>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_dumpall</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
</para>
<para>
- <application>pg_dumpall</application> might need to connect several
- times to the <productname>PostgreSQL</productname> server, asking for
+ <application>pg_dumpall</application> needs to connect several
+ times to the <productname>PostgreSQL</productname> server and might be asking for
a password each time. It is convenient to have a
<filename>$HOME/.pgpass</> file in such cases.
</para>
<para>
Dump data as <command>INSERT</command> commands (rather
than <command>COPY</command>). This will make restoration very
- slow, but it makes the output more portable to other RDBMS
+ slow, but it makes the output more portable to other SQL database
packages.
</para>
</listitem>
<listitem>
<para>
Specifies the host name of the machine on which the database
- server is running. If host begins with a slash, it is used as
- the directory for the Unix domain socket. The default is
- taken from the <envar>PGHOST</envar> environment variable, if
- set, else a Unix domain socket connection is attempted.
+ server is running. If the value begins with a slash, it is
+ used as the directory for the Unix domain socket. The default
+ is taken from the <envar>PGHOST</envar> environment variable,
+ if set, else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
<term>-p <replaceable>port</replaceable></term>
<listitem>
<para>
- The port number on which the server is listening. Defaults to
- the <envar>PGPORT</envar> environment variable, if set, or a
- compiled-in default.
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
messages will refer to <application>pg_dump</application>.
</para>
- <para>
- <application>pg_dumpall</application> will need to connect several
- times to the <productname>PostgreSQL</productname> server. If password
- authentication is configured, it will ask for a password each time. In
- that case it would be convenient to set up a <filename>.pgpass</>
- password file.
- </para>
-
<para>
Once restored, it is wise to run <command>ANALYZE</> on each
database so the optimizer has useful statistics. You
- can also run <command>vacuumdb -a -z</> to <command>ANALYZE</> all
+ can also run <command>vacuumdb -a -z</> to analyze all
databases.
</para>
<!--
-$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
-->
<refnamediv>
<refname>pg_resetxlog</refname>
- <refpurpose>reset write-ahead log and pg_control contents</refpurpose>
+ <refpurpose>reset the write-ahead log and other control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsect1 id="R1-APP-PGRESETXLOG-1">
<title>Description</title>
<para>
- <command>pg_resetxlog</command> clears the write-ahead log and
- optionally resets some fields in the <filename>pg_control</> file. This
- function is sometimes
- needed if these files have become corrupted.
- It should be used only as a last resort,
- when the server will not start due to such corruption.
+ <command>pg_resetxlog</command> clears the write-ahead log (WAL) and
+ optionally resets some other control information (stored in the
+ <filename>pg_control</> file). This function is sometimes needed
+ if these files have become corrupted. It should be used only as a
+ last resort, when the server will not start due to such corruption.
</para>
<para>
After running this command, it should be possible to start the server,
but bear in mind that the database may contain inconsistent data due to
partially-committed transactions. You should immediately dump your data,
- run <application>initdb</>, and reload. After reload, check for
+ run <command>initdb</>, and reload. After reload, check for
inconsistencies and repair as needed.
</para>
<para>
This utility can only be run by the user who installed the server, because
- it requires read/write access to the <literal>datadir</>.
+ it requires read/write access to the data directory.
For safety reasons, you must specify the data directory on the command line.
<command>pg_resetxlog</command> does not use the environment variable
<envar>PGDATA</>.
The first three of these can be set using the switches discussed below.
<command>pg_resetxlog</command>'s own environment is the source for its
guess at the locale fields; take care that <envar>LANG</> and so forth
- match the environment that <application>initdb</> was run in.
+ match the environment that <command>initdb</> was run in.
If you are not able to determine correct values for all these fields,
<literal>-f</> can still be used, but
the recovered database must be treated with even more suspicion than
- usual --- an immediate dump and reload is imperative. <emphasis>Do not</>
- execute any data-modifying operations in the database before you dump,
+ usual: an immediate dump and reload is imperative. <emphasis>Do not</>
+ execute any data-modifying operations in the database before you dump;
as any such action is likely to make the corruption worse.
</para>
be set manually. These are only needed when
<command>pg_resetxlog</command> is unable to determine appropriate values
by reading <filename>pg_control</>. A safe value for the
- next transaction ID may be determined by looking for the largest
- file name in <envar>$PGDATA</><filename>/pg_clog</>, adding one,
+ next transaction ID may be determined by looking for the numerically largest
+ file name in the directory <filename>pg_clog</> under the data directory, adding one,
and then multiplying by 1048576. Note that the file names are in
hexadecimal. It is usually easiest to specify the switch value in
hexadecimal too. For example, if <filename>0011</> is the largest entry
zeroes provide the proper multiplier).
The WAL starting address should be
larger than any file number currently existing in
- <envar>$PGDATA</><filename>/pg_xlog</>. These also are in hex, and
+ the directory <filename>pg_xlog</> under the data directory. The addresses are also in hexadecimal and
have two parts. For example, if <filename>000000FF0000003A</> is the
largest entry in <filename>pg_xlog</>, <literal>-l 0xFF,0x3B</> will work.
There is no comparably easy way to determine a next OID that's beyond
<title>Notes</title>
<para>
- This command must not be used when the <application>postmaster</> is
+ This command must not be used when the server is
running. <command>pg_resetxlog</command> will refuse to start up if
- it finds a postmaster lock file in the <literal>datadir</>. If the
- <application>postmaster</> crashed then a lock file may have been left
+ it finds a server lock file in the data directory. If the
+ server crashed then a lock file may have been left
behind; in that case you can remove the lock file to allow
<command>pg_resetxlog</command> to run. But before you do
so, make doubly certain that there
- is no postmaster nor any backend server process still alive.
+ is no <command>postmaster</command> nor any backend server process still alive.
</para>
</refsect1>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.36 2003/03/18 00:02:11 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_restore.sgml,v 1.37 2003/03/24 14:32:51 petere Exp $ -->
<refentry id="APP-PGRESTORE">
- <docinfo>
- <date>2001-03-06</date>
- </docinfo>
-
<refmeta>
<refentrytitle>pg_restore</refentrytitle>
<manvolnum>1</manvolnum>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_restore</command>
- <arg rep="repeat"><replaceable>options</replaceable></arg>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
+ <arg><replaceable>filename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<application>pg_restore</application> is a utility for restoring a
<productname>PostgreSQL</productname> database from an archive
created by <xref linkend="app-pgdump"> in one of the non-plain-text
- formats. It
- will issue the commands necessary to re-generate all user-defined
- types, functions, tables, indexes, aggregates, and operators, as
- well as the data in the tables.
- </para>
-
- <para>
- The archive files contain information for
- <application>pg_restore</application> to rebuild the database, but also
- allow <application>pg_restore</application> to be selective about what is
- restored, or even to reorder the items prior to being restored. The
- archive files are designed to be portable across architectures.
+ formats. It will issue the commands necessary to reconstruct the
+ database to the state it was in at the time it was saved. The
+ archive files also allow <application>pg_restore</application> to
+ be selective about what is restored, or even to reorder the items
+ prior to being restored. The archive files are designed to be
+ portable across architectures.
</para>
<para>
- <application>pg_restore</application> can operate in two modes: If a
- database name is specified, the archive is restored directly into
- the database. Otherwise, a script containing the SQL commands
- necessary to rebuild the database is created (and written to a file
- or standard output), similar to the ones created by the
- <application>pg_dump</application> plain text format. Some of the options
- controlling the script output are therefore analogous to
+ <application>pg_restore</application> can operate in two modes: If
+ a database name is specified, the archive is restored directly into
+ the database. Large objects can only be restored by using a direct
+ database connection. Otherwise, a script containing the SQL
+ commands necessary to rebuild the database is created (and written
+ to a file or standard output), similar to the ones created by the
+ <application>pg_dump</application> plain text format. Some of the
+ options controlling the script output are therefore analogous to
<application>pg_dump</application> options.
</para>
<para>
Obviously, <application>pg_restore</application> cannot restore information
- that is not present in the archive file; for instance, if the
+ that is not present in the archive file. For instance, if the
archive was made using the <quote>dump data as
- <command>INSERT</command>s</quote> option,
+ <command>INSERT</command> commands</quote> option,
<application>pg_restore</application> will not be able to load the data
using <command>COPY</command> statements.
</para>
<title>Options</title>
<para>
- <command>pg_restore</command> accepts the following command
+ <application>pg_restore</application> accepts the following command
line arguments.
<variablelist>
<varlistentry>
- <term><replaceable class="parameter">archive-name</replaceable></term>
+ <term><replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Specifies the location of the archive file to be restored.
<term><option>--data-only</option></term>
<listitem>
<para>
- Restore only the data, no schema (definitions).
+ Restore only the data, not the schema (data definitions).
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Create the database before restoring into it. (When this
- switch appears, the database named with <option>-d</option> is
+ option is used, the database named with <option>-d</option> is
used only to issue the initial <literal>CREATE DATABASE</>
command. All data is restored into the database name that
appears in the archive.)
<para>
Connect to database <replaceable
class="parameter">dbname</replaceable> and restore directly
- into the database. Large objects can only be restored by using
- a direct database connection.
+ into the database.
</para>
</listitem>
</varlistentry>
the format, since <application>pg_restore</application> will
determine the format automatically. If specified, it can be
one of the following:
- </para>
<variablelist>
<varlistentry>
- <term>t</term>
+ <term><literal>t</></term>
<listitem>
<para>
- Archive is a <filename>tar</filename> archive. Using this
+ The archive is a <command>tar</command> archive. Using this
archive format allows reordering and/or exclusion of schema
elements at the time the database is restored. It is also
possible to limit which data is reloaded at restore time.
</varlistentry>
<varlistentry>
- <term>c</term>
+ <term><literal>c</></term>
<listitem>
<para>
- Archive is in the custom format of
+ The archive is in the custom format of
<application>pg_dump</application>. This is the most
flexible format in that it allows reordering of data load
as well as schema elements. This format is also compressed
</listitem>
</varlistentry>
</variablelist>
+ </para>
</listitem>
</varlistentry>
<term><option>--index=<replaceable class="parameter">index</replaceable></option></term>
<listitem>
<para>
- Restore definition for named <replaceable
- class="parameter">index</replaceable> only.
+ Restore definition of named index only.
</para>
</listitem>
</varlistentry>
<term><option>--list</option></term>
<listitem>
<para>
- List the contents of the archive. The output of this command
+ List the contents of the archive. The output of this operation
can be used with the <option>-L</option> option to restrict
and reorder the items that are restored.
</para>
CLASS="PARAMETER">list-file</REPLACEABLE> only, and in the
order they appear in the file. Lines can be moved and may also
be commented out by placing a <literal>;</literal> at the
- start of the line.
+ start of the line. (See below for examples.)
</para>
</listitem>
</varlistentry>
<para>
Prevent any attempt to restore original object
ownership. Objects will be owned by the user name used to
- attach to the database.
+ attach to the database. See also under <option>-R</option> and
+ <option>-X use-set-session-authorization</option>.
</para>
</listitem>
</varlistentry>
<term><option>--function=<replaceable class="parameter">function-name(argtype [, ...])</replaceable></option></term>
<listitem>
<para>
- Specify a procedure or function to be restored.
+ Restore the named function only.
</para>
</listitem>
</varlistentry>
<term><option>--schema-only</option></term>
<listitem>
<para>
- Restore the schema (definitions), no data. Sequence values will be reset.
+ Restore only the schema (data defintions), not the data.
+ Sequence values will be reset.
</para>
</listitem>
</varlistentry>
<term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
<listitem>
<para>
- Restore schema/data for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> only.
+ Restore definition and/or data of named table only.
</para>
</listitem>
</varlistentry>
<term><option>--trigger=<replaceable class="parameter">trigger</replaceable></option></term>
<listitem>
<para>
- Restore definition of <REPLACEABLE CLASS="PARAMETER">trigger</REPLACEABLE> only.
+ Restore named trigger only.
</para>
</listitem>
</varlistentry>
</para>
<para>
- <command>pg_restore</command> also accepts
+ <application>pg_restore</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<listitem>
<para>
Specifies the host name of the machine on which the server is
- running. If host begins with a slash, it is used as the
- directory for the Unix domain socket.
+ running. If the value begins with a slash, it is used as the
+ directory for the Unix domain socket. The default is taken
+ from the <envar>PGHOST</envar> environment variable, if set,
+ else a Unix domain socket connection is attempted.
</para>
</listitem>
</varlistentry>
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
- Specifies the Internet TCP/IP port or local Unix domain socket
- file extension on which the server is listening for
- connections. The port number defaults to 5432, or the value
- of the <envar>PGPORT</envar> environment variable (if set).
- </para>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <envar>PGPORT</envar> environment variable, if
+ set, or a compiled-in default.
+ </para>
</listitem>
</varlistentry>
<listitem>
<para>
- Default connection parameters.
+ Default connection parameters
</para>
</listitem>
</varlistentry>
<refsect1 id="app-pgrestore-diagnostics">
<title>Diagnostics</title>
- <msgset>
- <msgentry>
- <msg>
- <msgmain>
- <msgtext>
-<screen>
-Connection to database 'template1' failed.
-connectDBStart() -- connect() failed: No such file or directory
- Is the postmaster running locally
- and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
-</screen>
- </msgtext>
- </msgmain>
- </msg>
-
- <msgexplan>
- <para>
- <application>pg_restore</application> could not attach to the
- <productname>PostgreSQL</> server process on the specified
- host and port. If you see this message, ensure that the
- server is running on the proper host and that you have
- specified the proper port. If your site uses an
- authentication system, ensure that you have obtained the
- required authentication credentials.
- </para>
- </msgexplan>
- </msgentry>
- </msgset>
-
- <note>
- <para>
- When a direct database connection is specified using the -d
- option, <application>pg_restore</application> internally executes
- <acronym>SQL</acronym> statements. If you have problems running
- <application>pg_restore</application>, make sure you are able to select
- information from the database using, for example,
- <application>psql</application>.
- </para>
- </note>
+ <para>
+ When a direct database connection is specified using the
+ <option>-d</option> option, <application>pg_restore</application>
+ internally executes <acronym>SQL</acronym> statements. If you have
+ problems running <application>pg_restore</application>, make sure
+ you are able to select information from the database using, for
+ example, <application>psql</application>.
+ </para>
</refsect1>
<application>pg_restore</application> into a truly empty database;
otherwise you are likely to get errors due to duplicate definitions
of the added objects. To make an empty database without any local
- additions, copy from template0 not template1, for example:
+ additions, copy from <literal>template0</> not <literal>template1</>, for example:
<programlisting>
-CREATE DATABASE foo WITH TEMPLATE = template0;
+CREATE DATABASE foo WITH TEMPLATE template0;
</programlisting>
</para>
<itemizedlist>
<listitem>
<para>
- When restoring data to a pre-existing table, <application>pg_restore</application> emits queries
- to disable triggers on user tables before inserting the data then emits queries to
+ When restoring data to a pre-existing table and the option
+ <option>--disable-triggers</> is used,
+ <application>pg_restore</application> emits commands
+ to disable triggers on user tables before inserting the data then emits commands to
re-enable them after the data has been inserted. If the restore is stopped in the
middle, the system catalogs may be left in the wrong state.
</para>
<refsect1 id="app-pgrestore-examples">
<title>Examples</title>
- <para>
- To dump a database:
-<screen>
-<prompt>$</prompt> <userinput>pg_dump mydb > db.out</userinput>
-</screen>
- </para>
-
- <para>
- To reload this database:
-<screen>
-<prompt>$</prompt> <userinput>psql -d database -f db.out</userinput>
-</screen>
- </para>
-
<para>
To dump a database called <literal>mydb</> that contains
large objects to a <filename>tar</filename> file:
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
</programlisting>
- Semi-colons are comment delimiters, and the numbers at the start of lines refer to the
+ Semicolons start a comment, and the numbers at the start of lines refer to the
internal archive ID assigned to each item.
</para>
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
</programlisting>
- could be used as input to <command>pg_restore</command> and would only restore
- items 10 and 6, in that order.
+ could be used as input to <application>pg_restore</application> and would only restore
+ items 10 and 6, in that order:
<screen>
<prompt>$</prompt> <userinput>pg_restore -L archive.list archive.file</userinput>
</screen>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>pgtclsh</command>
- <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>arguments</replaceable></arg></arg>
+ <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>pgtksh</command>
- <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>arguments</replaceable></arg></arg>
+ <arg><replaceable>filename</replaceable> <arg rep="repeat"><replaceable>argument</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
<!--
-$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
-->
<arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
</group>
<arg>-S <replaceable>sort-mem</replaceable></arg>
- <arg>-v <replaceable>protocol-version</replaceable></arg>
+ <arg>-v <replaceable>protocol</replaceable></arg>
<arg>-W <replaceable>seconds</replaceable></arg>
<arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
</cmdsynopsis>
<title>Description</title>
<para>
- The <filename>postgres</filename> executable is the actual
+ The <command>postgres</command> executable is the actual
<productname>PostgreSQL</productname> server process that processes
queries. It is normally not called directly; instead a <xref
linkend="app-postmaster"> multiuser server is started.
<para>
The second form above is how
- <application>postgres</application> is invoked by the <xref
+ <command>postgres</command> is invoked by the <xref
linkend="app-postmaster"> (only
conceptually, since both <filename>postmaster</filename> and
<filename>postgres</filename> are in fact the same program); it
When invoked in interactive mode from the shell, the user can enter
queries and the results will be printed to the screen, but in a
form that is more useful for developers than end users. But note
- that running a single-user backend is not truly suitable for
+ that running a single-user server is not truly suitable for
debugging the server since no realistic interprocess communication
and locking will happen.
</para>
<para>
- When running a stand-alone backend, the session user will be set to
+ When running a stand-alone server, the session user will be set to
the user with ID 1. This user does not actually have to exist, so
- a stand-alone backend can be used to manually recover from certain
+ a stand-alone server can be used to manually recover from certain
kinds of accidental damage to the system catalogs. Implicit
superuser powers are granted to the user with ID 1 in stand-alone
mode.
<title>Options</title>
<para>
- When <application>postgres</application> is started by a <xref
+ When <command>postgres</command> is started by a <xref
linkend="app-postmaster"> then it
inherits all options set by the latter. Additionally,
- <application>postgres</application>-specific options can be passed
- from the <application>postmaster</application> with the
+ <command>postgres</command>-specific options can be passed
+ from the <command>postmaster</command> with the
<option>-o</option> switch.
</para>
variable <envar>PGOPTIONS</envar> is set, then
<application>libpq</>-based clients will pass that string to the
server, which will interpret it as
- <application>postgres</application> command-line options.
+ <command>postgres</command> command-line options.
</para>
<refsect2>
<para>
The options <option>-A</option>, <option>-B</option>,
<option>-c</option>, <option>-d</option>, <option>-D</option>,
- <option>-F</option>, and <option>--name</> have the same meanings
+ <option>-F</option>, and <option>--<replaceable>name</></option> have the same meanings
as the <xref linkend="app-postmaster"> except that
- <option>-d</option> <literal>0</> prevents the debugging level of
- the postmaster from being propagated to the backend.
+ <literal>-d 0</> prevents the server log level of
+ the <command>postmaster</> from being propagated to <command>postgres</>.
</para>
<variablelist>
<term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
- Sends all debugging and error output to
+ Send all server log output to
<replaceable class="parameter">filename</replaceable>.
- If the backend is running under the
- <application>postmaster</application>, this option is ignored,
+ If <command>postgres</command> is running under the
+ <command>postmaster</command>, this option is ignored,
and the <systemitem>stderr</> inherited from the
- <application>postmaster</application> is used.
+ <command>postmaster</command> is used.
</para>
</listitem>
</varlistentry>
<term><option>-P</option></term>
<listitem>
<para>
- Ignore system indexes while scanning/updating system tuples. The
+ Ignore system indexes while scanning/updating system tables. The
<command>REINDEX</command> command for system tables/indexes
requires this option to be used.
</para>
<term><option>-s</option></term>
<listitem>
<para>
- Print time information and other statistics at the end of each query.
+ Print time information and other statistics at the end of each command.
This is useful for benchmarking or for use in tuning the number of
buffers.
</para>
<para>
Specifies the amount of memory to be used by internal sorts and hashes
before resorting to temporary disk files. The value is specified in
- kilobytes, and defaults to 512 kilobytes. Note that for a complex query,
+ kilobytes, and defaults to 1024. Note that for a complex query,
several sorts and/or hashes might be running in parallel, and each one
will be allowed to use as much as
<replaceable class="parameter">sort-mem</replaceable> kilobytes
<term><option>-E</option></term>
<listitem>
<para>
- Echo all queries.
+ Echo all commands.
</para>
</listitem>
</varlistentry>
<term><option>-N</option></term>
<listitem>
<para>
- Disables use of newline as a query delimiter.
+ Disables use of newline as a statement delimiter.
</para>
</listitem>
</varlistentry>
disable sequential and index scans respectively, while
<literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
disable nested-loop, merge and hash joins respectively.
+ </para>
<note>
<para>
plan types if it has any other alternative.
</para>
</note>
- </para>
</listitem>
</varlistentry>
<listitem>
<para>
Allows the structure of system tables to be modified. This is
- used by <application>initdb</application>.
+ used by <command>initdb</command>.
</para>
</listitem>
</varlistentry>
<term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
<listitem>
<para>
- Indicates that this server has been started by a
- <application>postmaster</application> and makes different
- assumptions about buffer pool management, file descriptors,
+ Indicates that this process has been started by a
+ <command>postmaster</command> and specifies the database to use.
etc.
</para>
</listitem>
<para>
As soon as this option is encountered, the process sleeps for
the specified amount of seconds. This gives developers time
- to attach a debugger to the backend process.
+ to attach a debugger to the server process.
</para>
</listitem>
</varlistentry>
<para>
To stop a running query use the <literal>SIGINT</literal> signal. To
- tell <application>postgres</application> to reread the config file,
+ tell <command>postgres</command> to reread the configuration file,
use a <literal>SIGHUP</literal> signal. The
- <application>postmaster</application> uses <literal>SIGTERM</literal>
- to tell a postgres process to quit normally and
+ <command>postmaster</command> uses <literal>SIGTERM</literal>
+ to tell a <command>postgres</command> process to quit normally and
<literal>SIGQUIT</literal> to terminate without the normal cleanup.
These <emphasis>should not</emphasis> be used by users.
</para>
<title>Usage</title>
<para>
- Start a stand-alone backend with a command like
+ Start a stand-alone server with a command like
<screen>
-<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
+<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
</screen>
- Provide the correct path to the database area with <option>-D</>, or
+ Provide the correct path to the database directory with <option>-D</>, or
make sure that the environment variable <envar>PGDATA</> is set.
Also specify the name of the particular database you want to work in.
</para>
<para>
- Normally, the stand-alone backend treats newline as the command
+ Normally, the stand-alone server treats newline as the command
entry terminator; there is no intelligence about semicolons,
as there is in <application>psql</>. To continue a command
across multiple lines, you must type backslash just before each
<para>
But if you use the <option>-N</> command line switch, then newline does
- not terminate command entry. The backend will read the standard input
+ not terminate command entry. In this case, the server will read the standard input
until the end-of-file (<acronym>EOF</>) marker, then
- process the input as a single query string. Backslash-newline is not
+ process the input as a single command string. Backslash-newline is not
treated specially in this case.
</para>
</para>
<para>
- Note that the stand-alone backend does not provide sophisticated
+ Note that the stand-alone server does not provide sophisticated
line-editing features (no command history, for example).
</para>
<!--
-$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
-->
<title>Description</title>
<para>
- <application>postmaster</application> is the
+ <command>postmaster</command> is the
<productname>PostgreSQL</productname> multiuser database server.
In order for a client application to access a database it connects
(over a network or locally) to a running
- <application>postmaster</application>. The
- <application>postmaster</application> then starts a separate server
+ <command>postmaster</command>. The
+ <command>postmaster</command> then starts a separate server
process (<quote><xref linkend="app-postgres"></quote>) to handle
- the connection. The <application>postmaster</application> also
+ the connection. The <command>postmaster</command> also
manages the communication among server processes.
</para>
<para>
- By default the <application>postmaster</application> starts in the
- foreground and prints log messages to the standard output. In
- practical applications the <application>postmaster</application>
+ By default the <command>postmaster</command> starts in the
+ foreground and prints log messages to the standard error stream. In
+ practical applications the <command>postmaster</command>
should be started as a background process, perhaps at boot time.
</para>
<para>
- One <application>postmaster</application> always manages the data
+ One <command>postmaster</command> always manages the data
from exactly one database cluster. A database cluster is a
collection of databases that is stored at a common file system
- location. When the postmaster starts it needs to know the location
+ location. When the <command>postmaster</command> starts it needs to know the location
of the database cluster files (<quote>data area</quote>). This is
done with the <option>-D</option> invocation option or the
<envar>PGDATA</envar> environment variable; there is no default.
- More than one postmaster process can run on a system at one time,
+ More than one <command>postmaster</command> process can run on a system at one time,
as long as they use different data areas and different
communication ports (see below). A data area is created with <xref
linkend="app-initdb">.
<title>Options</title>
<para>
- <application>postmaster</application> accepts the following
+ <command>postmaster</command> accepts the following
command line arguments. For a detailed discussion of the options
consult the &cite-admin;. You can also save typing most of these
options by setting up a configuration file.
<variablelist>
<varlistentry>
- <term>-A 0|1</term>
+ <term><option>-A 0|1</option></term>
<listitem>
<para>
- Enables run-time assert checks, which is a debugging aid to
+ Enables run-time assertion checks, which is a debugging aid to
detect programming mistakes. This is only available if it was
enabled during compilation. If so, the default is on.
</para>
</varlistentry>
<varlistentry>
- <term>-B <replaceable class="parameter">nbuffers</replaceable></term>
+ <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
<listitem>
<para>
Sets the number of shared buffers for use by the server
</varlistentry>
<varlistentry>
- <term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+ <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem>
<para>
Sets a named run-time parameter. Consult the &cite-admin; for
</varlistentry>
<varlistentry>
- <term>-d <replaceable>debug-level</replaceable></term>
+ <term><option>-d <replaceable>debug-level</replaceable></option></term>
<listitem>
<para>
Sets the debug level. The higher this value is set, the more
</varlistentry>
<varlistentry>
- <term>-D <replaceable class="parameter">datadir</replaceable></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
Specifies the file system location of the data directory. See
</varlistentry>
<varlistentry>
- <term>-F</term>
+ <term><option>-F</option></term>
<listitem>
<para>
Disables <function>fsync</function> calls for performance
improvement, at the risk of data corruption in event of a
- system crash. This parameter corresponds to setting
+ system crash. This option corresponds to setting
<literal>fsync=false</> in <filename>postgresql.conf</>. Read the detailed
documentation before using this!
</para>
</varlistentry>
<varlistentry>
- <term>-h <replaceable class="parameter">hostname</replaceable></term>
+ <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
<listitem>
<para>
- Specifies the TCP/IP host name or address on which the
- <application>postmaster</application> is to listen for
+ Specifies the IP host name or address on which the
+ <command>postmaster</command> is to listen for
connections from client applications. Defaults to
listening on all configured addresses (including
<systemitem class="systemname">localhost</systemitem>).
</varlistentry>
<varlistentry>
- <term>-i</term>
+ <term><option>-i</option></term>
<listitem>
<para>
Allows clients to connect via TCP/IP (Internet domain)
to setting <literal>tcpip_socket=true</> in <filename>postgresql.conf</>.
</para>
<para>
- <option>--tcpip_socket=false</option> has the opposite
+ <option>--tcpip-socket=false</option> has the opposite
effect of this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>-k <replaceable class="parameter">directory</replaceable></term>
+ <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
<listitem>
<para>
Specifies the directory of the Unix-domain socket on which the
- <application>postmaster</application> is to listen for
+ <command>postmaster</command> is to listen for
connections from client applications. The default is normally
<filename>/tmp</filename>, but can be changed at build time.
</para>
</varlistentry>
<varlistentry>
- <term>-l</term>
+ <term><option>-l</option></term>
<listitem>
<para>
Enables secure connections using SSL. The <option>-i</option>
</varlistentry>
<varlistentry>
- <term>-N <replaceable class="parameter">max-connections</replaceable></term>
+ <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
<listitem>
<para>
Sets the maximum number of client connections that this
- <application>postmaster</application> will accept. By
+ <command>postmaster</command> will accept. By
default, this value is 32, but it can be set as high as your
system will support. (Note that
<option>-B</option> is required to be at least twice
</varlistentry>
<varlistentry>
- <term>-o <replaceable class="parameter">extra-options</replaceable></term>
+ <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
<listitem>
<para>
The command line-style options specified in <replaceable
class="parameter">extra-options</replaceable> are passed to
- all backend server processes started by this
- <application>postmaster</application>. See <xref
+ all server processes started by this
+ <command>postmaster</command>. See <xref
linkend="app-postgres"> for possibilities. If the option
string contains any spaces, the entire string must be quoted.
</para>
</varlistentry>
<varlistentry>
- <term>-p <replaceable class="parameter">port</replaceable></term>
+ <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
<listitem>
<para>
Specifies the TCP/IP port or local Unix domain socket file
- extension on which the <application>postmaster</application>
+ extension on which the <command>postmaster</command>
is to listen for connections from client applications.
Defaults to the value of the <envar>PGPORT</envar> environment
variable, or if <envar>PGPORT</envar> is not set, then
</varlistentry>
<varlistentry>
- <term>-S</term>
+ <term><option>-S</option></term>
<listitem>
<para>
- Specifies that the <application>postmaster</application>
+ Specifies that the <command>postmaster</command>
process should start up in silent mode. That is, it will
disassociate from the user's (controlling) terminal, start its
own process group, and redirect its standard output and
Using this switch discards all logging output, which is
probably not what you want, since it makes it very difficult
to troubleshoot problems. See below for a better way to start
- the <application>postmaster</application> in the background.
+ the <command>postmaster</command> in the background.
</para>
<para>
- <option>--silent_mode=false</option> has the opposite effect
+ <option>--silent-mode=false</option> has the opposite effect
of this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+ <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
<listitem>
<para>
Sets a named run-time parameter; a shorter form of
<para>
Two additional command line options are available for debugging
- problems that cause a backend to die abnormally. These options
- control the behavior of the <application>postmaster</application>
- in this situation, and <emphasis>neither option is intended for
- use in ordinary operation</emphasis>.
+ problems that cause a server process to die abnormally. The
+ ordinary strategy in this situation is to notify all other server
+ processes that they must terminate and then reinitialize the
+ shared memory and semaphores. This is because an errant server
+ process could have corrupted some shared state before terminating.
+ These options select alternative behaviors of the
+ <command>postmaster</command> in this situation.
+ <emphasis>Neither option is intended for use in ordinary
+ operation.</emphasis>
</para>
<para>
- The ordinary strategy for this situation is to notify all other
- backends that they must terminate and then reinitialize the shared
- memory and semaphores. This is because an errant backend could
- have corrupted some shared state before terminating.
</para>
<para>
<variablelist>
<varlistentry>
- <term>-n</term>
+ <term><option>-n</option></term>
<listitem>
<para>
- <application>postmaster</application>
+ <command>postmaster</command>
will not reinitialize shared data structures. A knowledgeable system
programmer can then use a debugger
to examine shared memory and semaphore state.
</varlistentry>
<varlistentry>
- <term>-s</term>
+ <term><option>-s</option></term>
<listitem>
<para>
- <application>postmaster</application>
- will stop all other backend processes by sending the signal
+ <command>postmaster</command>
+ will stop all other server processes by sending the signal
<literal>SIGSTOP</literal>,
but will not cause them to terminate. This permits system programmers
- to collect core dumps from all backend processes by hand.
+ to collect core dumps from all server processes by hand.
</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term><envar>PGDATASTYLE</envar></term>
+ <term><envar>PGDATESTYLE</envar></term>
<listitem>
<para>
<variablelist>
<varlistentry>
- <term><computeroutput>
-semget: No space left on device
- </computeroutput></term>
+ <term><computeroutput>semget: No space left on device</computeroutput></term>
<listitem>
<para>
- If you see this message, you should run the
- <application>ipcclean</application>
- command. After doing so, try starting
- <application>postmaster</application>
- again. If this still doesn't work, you probably need to configure
- your kernel for shared memory and semaphores as described in the
- installation notes. If you run multiple instances of
- <application>postmaster</application>
+ If you see this message, you probably need to configure
+ your kernel for shared memory and semaphores as described in the &cite-admin;.
+ If you run multiple instances of
+ <command>postmaster</command>
on a single host, or have a kernel with particularly small shared memory
and/or semaphore limits, you may have to reconfigure your kernel to increase
its shared memory or semaphore parameters.
+ </para>
<tip>
<para>
consumption.
</para>
</tip>
- </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><computeroutput>
-StreamServerPort: cannot bind to port
- </computeroutput></term>
+ <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term>
<listitem>
<para>
If you see this message, you should make certain that there is no
- other <application>postmaster</application>
+ other <command>postmaster</command>
process already running on the same port number. The easiest way to
determine this is by using the command
<screen>
<para>
If you
are sure that no other
- <application>postmaster</application>
+ <command>postmaster</command>
processes are running and you still get this error, try specifying a
different port using the
<literal>-p</literal>
option. You may also get this error if you terminate the
- <application>postmaster</application>
+ <command>postmaster</command>
and immediately restart it using the same port; in this case, you must
simply wait a few seconds until the operating system closes the port
before trying again. Finally, you may get this error if you specify
a port number that your operating system considers to be reserved.
For example, many versions of Unix consider port numbers under 1024 to
- be <firstterm>trusted</firstterm>
+ be <quote>trusted</quote>
and only permit the Unix superuser to access them.
</para>
</listitem>
<para>
If at all possible, <emphasis>do not</emphasis> use
<literal>SIGKILL</literal> to kill the
- <application>postmaster</application>. This will prevent
- <application>postmaster</application> from freeing the system
+ <command>postmaster</command>. This will prevent
+ <command>postmaster</command> from freeing the system
resources (e.g., shared memory and semaphores) that it holds before
terminating.
</para>
<para>
- To terminate the <application>postmaster</application> normally,
+ To terminate the <command>postmaster</command> normally,
the signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>,
or <literal>SIGQUIT</literal> can be used. The first will wait for
all clients to terminate before quitting, the second will
<para>
The utility command <xref linkend="app-pg-ctl"> can be used to
- start and shut down the <application>postmaster</application>
+ start and shut down the <command>postmaster</command>
safely and comfortably.
</para>
<refsect1 id="app-postmaster-examples">
<title>Examples</title>
<para>
- To start <application>postmaster</application> in the background
+ To start <command>postmaster</command> in the background
using default values, type:
<screen>
</para>
<para>
- To start <application>postmaster</application> with a specific
+ To start <command>postmaster</command> with a specific
port:
<screen>
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
</screen>
- This command will start up <application>postmaster</application>
+ This command will start up <command>postmaster</command>
communicating through the port 1234. In order to connect to this
- <
application>postmaster</application> using <application>psql</>, you would need to
+ <
command>postmaster</command> using <application>psql</>, you would need to
run it as
<screen>
<prompt>$</prompt> <userinput>psql -p 1234</userinput>
<!--
-$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
-->
<refsynopsisdiv>
<cmdsynopsis>
<command>psql</command>
- <arg><replaceable class="parameter">options</replaceable></arg>
+ <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
<arg><replaceable class="parameter">dbname</replaceable>
- <arg><replaceable class="parameter">user</replaceable></arg></arg>
+ <arg><replaceable class="parameter">username</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
</varlistentry>
<varlistentry>
- <term><option>-c <replaceable class="parameter">query</replaceable></></term>
- <term><option>--command <replaceable class="parameter">query</replaceable></></term>
+ <term><option>-c <replaceable class="parameter">command</replaceable></></term>
+ <term><option>--command <replaceable class="parameter">command</replaceable></></term>
<listitem>
<para>
Specifies that <application>psql</application> is to execute one
- query string, <replaceable class="parameter">query</replaceable>,
+ command string, <replaceable class="parameter">command</replaceable>,
and then exit. This is useful in shell scripts.
</para>
<para>
- <replaceable class="parameter">query</replaceable> must be either
- a query string that is completely parsable by the backend (i.e.,
+ <replaceable class="parameter">command</replaceable> must be either
+ a command string that is completely parsable by the server (i.e.,
it contains no <application>psql</application> specific features),
or it is a single backslash command. Thus you cannot mix
<acronym>SQL</acronym> and <application>psql</application>
<term><option>--echo-queries</></term>
<listitem>
<para>
- Show all queries that are sent to the backend. This is equivalent
+ Show all commands that are sent to the server. This is equivalent
to setting the variable <varname>ECHO</varname> to
<literal>queries</literal>.
</para>
<term><option>--echo-hidden</></term>
<listitem>
<para>
- Echoes the actual queries generated by \d and other backslash
+ Echo the actual queries generated by <command>\d</command> and other backslash
commands. You can use this if you wish to include similar
functionality into your own programs. This is equivalent to
setting the variable <varname>ECHO_HIDDEN</varname> from within
<listitem>
<para>
Use the file <replaceable class="parameter">filename</replaceable>
- as the source of queries instead of reading queries interactively.
+ as the source of commands instead of reading commands interactively.
After the file is processed, <application>psql</application>
terminates. This is in many ways equivalent to the internal
command <command>\i</command>.
<listitem>
<para>
Specifies the host name of the machine on which the
- <application>postmaster</application> is running. If host begins
+ server is running. If the value begins
with a slash, it is used as the directory for the Unix-domain
socket.
</para>
<term><option>--html</></term>
<listitem>
<para>
- Turn
s on <acronym>HTML</acronym> tabular output. This is
+ Turn on <acronym>HTML</acronym> tabular output. This is
equivalent to <literal>\pset format html</literal> or the
<command>\H</command> command.
</para>
<term><option>--list</></term>
<listitem>
<para>
- Lists all available databases, then exits. Other non-connection
+ List all available databases, then exits. Other non-connection
options are ignored. This is similar to the internal command
<command>\list</command>.
</para>
<term><option>--port <replaceable class="parameter">port</replaceable></></term>
<listitem>
<para>
- Specifies the TCP/IP port or, by omission, the local Unix domain
- socket file extension on which the
- <application>postmaster</application> is listening for
+ Specifies the TCP port or the local Unix domain
+ socket file extension on which the server is listening for
connections. Defaults to the value of the <envar>PGPORT</envar>
environment variable or, if not set, to the port specified at
compile time, usually 5432.
<listitem>
<para>
Run in single-step mode. That means the user is prompted before
- each query is sent to the backend, with the option to cancel
+ each command is sent to the server, with the option to cancel
execution as well. Use this to debug scripts.
</para>
</listitem>
<term><option>--single-line</></term>
<listitem>
<para>
- Runs in single-line mode where a newline terminates a query, as a
+ Runs in single-line mode where a newline terminates an SQL command, as a
semicolon does.
</para>
<para>
This option is deprecated, as it is conceptually flawed.
(Prompting for a non-default user name and prompting for a
- password because the backend requires it are really two different
+ password because the server requires it are really two different
things.) You are encouraged to look at the <option>-U</option> and
<option>-W</option> options instead.
</para>
<term><option>--username <replaceable class="parameter">username</replaceable></></term>
<listitem>
<para>
- Connects to the database as the user <replaceable
+ Connect to the database as the user <replaceable
class="parameter">username</replaceable> instead of the default.
(You must have permission to do so, of course.)
</para>
<term><option>--variable <replaceable class="parameter">assignment</replaceable></></term>
<listitem>
<para>
- Performs a variable assignment, like the <command>\set</command>
+ Perform a variable assignment, like the <command>\set</command>
internal command. Note that you must separate name and value, if
any, by an equal sign on the command line. To unset a variable,
leave off the equal sign. To just set a variable without a value,
<term><option>--version</></term>
<listitem>
<para>
- Show
s the <application>psql</application> version.
+ Show the <application>psql</application> version.
</para>
</listitem>
</varlistentry>
<para>
In the current version, <application>psql</application>
- automatically issues a password prompt whenever the backend
+ automatically issues a password prompt whenever the server
requests password authentication. Because this is currently based
on a hack, the automatic recognition might mysteriously fail,
hence this option to force a prompt. If no password prompt is
- issued and the backend requires password authentication the
+ issued and the server requires password authentication the
connection attempt will fail.
</para>
</listitem>
<term><option>--expanded</></term>
<listitem>
<para>
- Turns on extended row format mode. This is equivalent to the
+ Turn on the extended table formatting mode. This is equivalent to the
command <command>\x</command>.
</para>
</listitem>
<term><option>--help</></term>
<listitem>
<para>
- Show
s help about <application>psql</application> command line
+ Show help about <application>psql</application> command line
arguments.
</para>
</listitem>
<para>
<application>psql</application> returns 0 to the shell if it
finished normally, 1 if a fatal error of its own (out of memory,
- file not found) occurs, 2 if the connection to the backend went bad
- and the session is not interactive, and 3 if an error occurred in a
+ file not found) occurs, 2 if the connection to the server went bad
+ and the session was not interactive, and 3 if an error occurred in a
script and the variable <varname>ON_ERROR_STOP</varname> was set.
</para>
</refsect1>
<para>
If the connection could not be made for any reason (e.g., insufficient
- privileges, postmaster is not running on the server, etc.),
+ privileges, server is not running on the targeted host, etc.),
<application>psql</application> will return an error and terminate.
</para>
</refsect2>
<refsect2 id="R2-APP-PSQL-4">
- <title>Entering Queries</title>
+ <title>Entering SQL Commands</title>
<para>
In normal operation, <application>psql</application> provides a
</para>
<para>
- At the prompt, the user may type in <acronym>SQL</acronym> queries.
- Ordinarily, input lines are sent to the backend when a
- query-terminating semicolon is reached. An end of line does not
- terminate a query! Thus queries can be spread over several lines for
- clarity. If the query was sent and without error, the query results
+ At the prompt, the user may type in <acronym>SQL</acronym> commands.
+ Ordinarily, input lines are sent to the server when a
+ command-terminating semicolon is reached. An end of line does not
+ terminate a command. Thus commands can be spread over several lines for
+ clarity. If the command was sent and without error, the results of the command
are displayed on the screen.
</para>
<para>
- Whenever a
query is executed, <application>psql</application> also polls
+ Whenever a
command is executed, <application>psql</application> also polls
for asynchronous notification events generated by
<xref linkend="SQL-LISTEN" endterm="SQL-LISTEN-title"> and
<xref linkend="SQL-NOTIFY" endterm="SQL-NOTIFY-title">.
</para>
<para>
- Some commands take an <acronym>SQL</acronym> identifier
- (such as a table name) as argument. These arguments follow the
- syntax rules of <acronym>SQL</acronym> regarding double quotes: an
- identifier without double quotes is coerced to lower-case, while
- whitespace within double quotes is included in the argument.
+ Some commands take an <acronym>SQL</acronym> identifier (such as a
+ table name) as argument. These arguments follow the syntax rules
+ of <acronym>SQL</acronym>: Unquoted letters are forced to
+ lowercase, while double quotes (<literal>"</>) protect letters
+ from case conversion and allow incorporation of whitespace into
+ the identifier. Within double quotes, paired double quotes reduce
+ to a single double quote in the resulting name. For example,
+ <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>,
+ and <literal>"A weird"" name"</> becomes <literal>A weird"
+ name</>.
</para>
<para>
Parsing for arguments stops when another unquoted backslash occurs.
This is taken as the beginning of a new meta-command. The special
sequence <literal>\\</literal> (two backslashes) marks the end of
- arguments and continues parsing <acronym>SQL</acronym> queries, if
+ arguments and continues parsing <acronym>SQL</acronym> commands, if
any. That way <acronym>SQL</acronym> and
<application>psql</application> commands can be freely mixed on a
line. But in any case, the arguments of a meta-command cannot
<term><literal>\a</literal></term>
<listitem>
<para>
- If the current table output format is unaligned, switch to aligned.
- If it is not unaligned, set it to unaligned. This command is
+ If the current table output format is unaligned, it is switched to aligned.
+ If it is not unaligned, it is set to unaligned. This command is
kept for backwards compatibility. See <command>\pset</command> for a
general solution.
</para>
<term><literal>\cd</literal> <optional><replaceable>directory</replaceable></optional></term>
<listitem>
<para>
- Change the current working directory to
- <replaceable>directory</replaceable>. Without argument, change
+ Changes the current working directory to
+ <replaceable>directory</replaceable>. Without argument, changes
to the current user's home directory.
</para>
<term><literal>\C</literal> [ <replaceable class="parameter">title</replaceable> ]</term>
<listitem>
<para>
- Set the title of any tables being printed as the result of a
+ Sets the title of any tables being printed as the result of a
query or unset any such title. This command is equivalent to
<literal>\pset title <replaceable
class="parameter">title</replaceable></literal>. (The name of
<para>
Performs a frontend (client) copy. This is an operation that
runs an <acronym>SQL</acronym> <xref linkend="SQL-COPY"
- endterm="SQL-COPY-title"> command, but instead of the backend's
+ endterm="SQL-COPY-title"> command, but instead of the server
reading or writing the specified file,
<application>psql</application> reads or writes the file and
- routes the data between the backend and the local file system.
+ routes the data between the server and the local file system.
This means that file accessibility and privileges are those
of the local user, not the server, and no SQL superuser
privileges are required.
<para>
The syntax of the command is similar to that of the
- <acronym>SQL</acronym> <command>COPY</command> command (see its
- description for the details). Note that, because of this,
+ <acronym>SQL</acronym> <command>COPY</command> command. (See its
+ description for the details.) Note that, because of this,
special parsing rules apply to the <command>\copy</command>
command. In particular, the variable substitution rules and
backslash escapes do not apply.
<para>
This operation is not as efficient as the <acronym>SQL</acronym>
<command>COPY</command> command because all data must pass
- through the client/server IP or socket connection. For large
+ through the client/server connection. For large
amounts of data the other technique may be preferable.
</para>
</tip>
<para>
Note the difference in interpretation of
<literal>stdin</literal> and <literal>stdout</literal> between
- frontend and backend copies: in a frontend copy these always
+ client and server copies: in a client copy these always
refer to <application>psql</application>'s input and output
- stream. On a backend copy <literal>stdin</literal> comes from
+ stream. On a server copy <literal>stdin</literal> comes from
wherever the <command>COPY</command> itself came from (for
example, a script run with the <option>-f</option> option), and
<literal>stdout</literal> refers to the query output stream (see
<para>
Lists all available aggregate functions, together with the data
type they operate on. If <replaceable
- class="parameter">pattern</replaceable> (a regular expression)
+ class="parameter">pattern</replaceable>
is specified, only matching aggregates are shown.
</para>
</listitem>
<para>
Descriptions for objects can be created with the
- <command>COMMENT
ON</command> <acronym>SQL</acronym> command.
+ <command>COMMENT</command> <acronym>SQL</acronym> command.
</para>
-
- <note>
- <para>
- <productname>PostgreSQL</productname> stores the object
- descriptions in the <structname>pg_description</> system table.
- </para>
- </note>
-
</listitem>
</varlistentry>
<term><literal>\dD</literal> [ <replaceable class="parameter">pattern</replaceable> ]</term>
<listitem>
<para>
- Lists all available domains (derived types). If <replaceable
+ Lists all available domains. If <replaceable
class="parameter">pattern</replaceable>
is specified, only matching domains are shown.
</para>
order, to obtain a listing of all the matching objects. The letter
S restricts the listing to system objects; without S, only non-system
objects are shown.
- If <quote>+</quote> is appended to the command name, each object is
+ If <literal>+</literal> is appended to the command name, each object is
listed with its associated description, if any.
</para>
<para>
- If a <replaceable class="parameter">pattern</replaceable> is
+ If <replaceable class="parameter">pattern</replaceable> is
specified, only objects whose name matches the pattern are listed.
</para>
</listitem>
<listitem>
<para>
Lists available operators with their operand and return types.
- If a <replaceable class="parameter">pattern</replaceable> is
+ If <replaceable class="parameter">pattern</replaceable> is
specified, only operators whose name matches the pattern are listed.
</para>
</listitem>
<listitem>
<para>
Produces a list of all available tables with their
- associated access permissions.
- If a <replaceable class="parameter">pattern</replaceable> is
+ associated access privileges.
+ If <replaceable class="parameter">pattern</replaceable> is
specified, only tables whose name matches the pattern are listed.
</para>
<para>
The commands <xref linkend="SQL-GRANT"> and
<xref linkend="SQL-REVOKE">
- are used to set access permissions. See <xref linkend="SQL-GRANT">
+ are used to set access privileges. See <xref linkend="SQL-GRANT">
for more information.
</para>
</listitem>
<term><literal>\du [ <replaceable class="parameter">pattern</replaceable> ]</literal></term>
<listitem>
<para>
- Lists all database users, or only those that match <replaceable
+ Lists all database users or only those that match <replaceable
class="parameter">pattern</replaceable>.
</para>
</listitem>
<listitem>
<para>
- Sets the client encoding. Without an argument, this command
+ Sets the client character set encoding. Without an argument, this command
shows the current encoding.
</para>
<note>
<para>
This command will not notice changes made directly by <command>SET
- CLIENT_ENCODING</>. If you use <literal>\encoding</literal>,
+ client_encoding</>. If you use <command>\encoding</command>,
be sure to use it to set as well as examine the encoding.
</para>
</note>
<listitem>
<para>
Sets the field separator for unaligned query output. The default
- is pipe (<literal>|</literal>). See also
+ is the vertical bar (<literal>|</literal>). See also
<command>\pset</command> for a generic way of setting output
options.
</para>
<listitem>
<para>
- Sends the current query input buffer to the backend and
+ Sends the current query input buffer to the server and
optionally saves the output in <replaceable
class="parameter">filename</replaceable> or pipes the output
into a separate Unix shell to execute <replaceable
<term><literal>\help</literal> (or <literal>\h</literal>) [ <replaceable class="parameter">command</replaceable> ]</term>
<listitem>
<para>
- Give syntax help on the specified <acronym>SQL</acronym>
+ Give
s syntax help on the specified <acronym>SQL</acronym>
command. If <replaceable class="parameter">command</replaceable>
is not specified, then <application>psql</application> will list
all the commands for which syntax help is available. If
<replaceable class="parameter">command</replaceable> is an
- asterisk (<quote>*</quote>), then syntax help on all
+ asterisk (<literal>*</literal>), then syntax help on all
<acronym>SQL</acronym> commands is shown.
</para>
<term><literal>\l</literal> (or <literal>\list</literal>)</term>
<listitem>
<para>
- List the names, owners, and encodings of all the databases in
- the server. Append a <quote>+</quote> to the command name to
+ List the names, owners, and character set encodings of all the databases in
+ the server. Append a <literal>+</literal> to the command name to
see any descriptions for the databases as well.
</para>
</listitem>
<listitem>
<para>
Stores the file into a <productname>PostgreSQL</productname>
- <quote>large object</quote>. Optionally, it associates the given
+ large object. Optionally, it associates the given
comment with the object. Example:
<programlisting>
foo=> <userinput>\lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'</userinput>
lo_import 152801
</programlisting>
- The response indicates that the large object received object id
+ The response indicates that the large object received object ID
152801 which one ought to remember if one wants to access the
object ever again. For that reason it is recommended to always
associate a human-readable comment with every object. Those can
<listitem>
<para>
Shows a list of all <productname>PostgreSQL</productname>
- <quote>large objects</quote> currently stored in the database,
+ large objects currently stored in the database,
along with any comments provided for them.
</para>
</listitem>
projects / users / hanada / postgres.git / commitdiff