-
Peter Eisentraut authoredPeter Eisentraut authored
postgres-ref.sgml 13.68 KiB
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.25 2002/03/22 19:20:43 petere Exp $
PostgreSQL documentation
-->
<refentry id="APP-POSTGRES">
<docinfo>
<date>2000-11-12</date>
</docinfo>
<refmeta>
<refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>postgres</refname>
<refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<!-- standalone call -->
<command>postgres</command>
<arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
<arg>-B <replaceable>nbuffers</replaceable></arg>
<arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<arg>-d <replaceable>debug-level</replaceable></arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-e</arg>
<arg>-E</arg>
<arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
<arg>-F</arg>
<arg>-i</arg>
<arg>-N</arg>
<arg>-o <replaceable>filename</replaceable></arg>
<arg>-O</arg>
<arg>-P</arg>
<group>
<arg>-s</arg>
<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>-W <replaceable>seconds</replaceable></arg>
<arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<arg choice="plain"><replaceable>database</replaceable></arg>
<sbr>
<!-- postmaster fork -->
<command>postgres</command>
<arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
<arg>-B <replaceable>nbuffers</replaceable></arg>
<arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<arg>-d <replaceable>debug-level</replaceable></arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-e</arg>
<arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
<arg>-F</arg>
<arg>-i</arg>
<arg>-o <replaceable>filename</replaceable></arg>
<arg>-O</arg>
<arg>-p <replaceable>database</replaceable></arg>
<arg>-P</arg>
<group>
<arg>-s</arg>
<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>-W <replaceable>seconds</replaceable></arg> <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <filename>postgres</filename> 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>
<para>
The second form above is how
<application>postgres</application> 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
should not be invoked directly this way. The first form invokes
the server directly in interactive single-user mode. The primary use
for this mode is during bootstrapping by <xref linkend="app-initdb">.
Sometimes it is used for debugging or disaster recovery.
</para>
<para>
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
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
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
kinds of accidental damage to the system catalogs. Implicit
superuser powers are granted to the user with id 1 in stand-alone
mode.
</para>
<refsect2>
<title>Options</title>
<para>
When <application>postgres</application> 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
<option>-o</option> switch.
</para>
<para>
You can avoid having to type these options by setting up a
configuration file. See the <citetitle>Administrator's
Guide</citetitle> for details. Some (safe) options can also be
set from the connecting client in an application-dependent way.
For example, if the environment 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.
</para>
<refsect3>
<title>General Purpose</title>
<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
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.
</para>
<variablelist>
<varlistentry>
<term><option>-e</option></term>
<listitem>
<para>
Sets the default date style to <quote>European</quote>, which
means that the <quote>day before month</quote> (rather than
month before day) rule is used to interpret ambiguous date
input, and that the day is printed before the month in certain
date output formats. See the <citetitle>PostgreSQL User's
Guide</citetitle> for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Sends all debugging and error output to
<replaceable class="parameter">filename</replaceable>.
If the backend is running under the
<application>postmaster</application>, this option is ignored,
and the <systemitem>stderr</> inherited from the
<application>postmaster</application> is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option></term>
<listitem>
<para>
Ignore system indexes while scanning/updating system tuples. The
<command>REINDEX</command> command for system tables/indexes
requires this option to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option></term>
<listitem>
<para>
Print time information and other statistics at the end of each query.
This is useful for benchmarking or for use in tuning the number of
buffers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S</option> <replaceable class="parameter">sort-mem</replaceable></term>
<listitem>
<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,
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 before it starts to put data into temporary files.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3>
<title>Options for stand-alone mode</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">database</replaceable></term>
<listitem>
<para>
Specifies the name of the database to be accessed. If it is
omitted it defaults to the user name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-E</option></term>
<listitem>
<para>
Echo all queries.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-N</option></term>
<listitem>
<para>
Disables use of newline as a query delimiter.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3>
<title>Semi-internal Options</title>
<para>
There are several other options that may be specified, used
mainly for debugging purposes. These are listed here only for
the use by <productname>PostgreSQL</productname> system
developers. <emphasis>Use of any of these options is highly
discouraged.</emphasis> Furthermore, any of these options may
disappear or change in a future release without notice.
</para>
<variablelist>
<varlistentry>
<term><option>-f</option> <literal>{ s | i | m | n | h }</literal></term>
<listitem>
<para>
Forbids the use of particular scan and join methods:
<literal>s</literal> and <literal>i</literal>
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.
<note>
<para>
Neither sequential scans nor nested-loop joins can be disabled completely;
the <literal>-fs</literal> and <literal>-fn</literal>
options simply discourage the optimizer from using those plan types if it has any other alternative.
</para>
</note>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option></term>
<listitem>
<para>
Prevents query execution, but shows the plan tree.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-O</option></term>
<listitem>
<para>
Allows the structure of system tables to be modified. This is
used by <application>initdb</application>.
</para>
</listitem>
</varlistentry>
<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,
etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term>
<listitem>
<para>
Print timing statistics for each query relating to each of the
major system modules. This option cannot be used together
with the <option>-s</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term>
<listitem>
<para>
Specifies the version number of the frontend/backend protocol
to be used for this particular session.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
<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.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
</refsect2>
</refsect1>
<refsect1>
<title>Usage</title>
<para>
Start a stand-alone backend with a command like
<screen>
<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
</screen>
Provide the correct path to the database area 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
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
newline except the last one.
</para>
<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
until the end-of-file (<acronym>EOF</>) marker, then
process the input as a single query string. Backslash-newline is not
treated specially in this case.
</para>
<para>
To quit the session, type <acronym>EOF</acronym>
(<keycombo action="simul"><keycap>Control</><keycap>D</></>, usually).
If you've
used <option>-N</>, two consecutive <acronym>EOF</>s are needed to exit.
</para>
<para>
Note that the stand-alone backend does not provide sophisticated
line-editing features (no command history, for example).
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<xref linkend="app-initdb">,
<xref linkend="app-ipcclean">,
<xref linkend="app-postmaster">
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nilsgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->