mirror of
https://github.com/postgres/postgres.git
synced 2025-10-28 11:55:03 +03:00
Merge postmaster and postgres command into just postgres. postmaster
symlink is kept for now for compatibility. To call single-user mode, use postgres --single.
This commit is contained in:
Peter Eisentraut
@@ -1,29 +1,28 @@
|
||||
<!--
|
||||
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.46 2006/01/05 10:07:44 petere Exp $
|
||||
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.47 2006/06/18 15:38:36 petere Exp $
|
||||
PostgreSQL documentation
|
||||
-->
|
||||
|
||||
<refentry id="APP-POSTGRES">
|
||||
<refentry id="app-postgres">
|
||||
<refmeta>
|
||||
<refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
|
||||
<refentrytitle><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>
|
||||
<refpurpose><productname>PostgreSQL</productname> database server</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<indexterm zone="app-postgres">
|
||||
<primary>postgres (the program)</primary>
|
||||
<primary>postgres</primary>
|
||||
</indexterm>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>postgres</command>
|
||||
<arg rep="repeat"><replaceable>option</></arg>
|
||||
<arg choice="plain"><replaceable>database</replaceable></arg>
|
||||
</cmdsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
@@ -31,85 +30,500 @@ PostgreSQL documentation
|
||||
<title>Description</title>
|
||||
|
||||
<para>
|
||||
The <command>postgres</command> executable is the actual
|
||||
<productname>PostgreSQL</productname> server process that processes
|
||||
SQL statements. It is normally not called directly; instead a
|
||||
<xref linkend="app-postmaster"> multiuser server is started.
|
||||
Conceptually, the <command>postmaster</command> starts a new
|
||||
<command>postgres</command> process for each connection.
|
||||
(<filename>postmaster</filename> and <filename>postgres</filename>
|
||||
are in fact the same program, and on most platforms the connection
|
||||
process is forked).
|
||||
<command>postgres</command> is the
|
||||
<productname>PostgreSQL</productname> database server. In order
|
||||
for a client application to access a database it connects (over a
|
||||
network or locally) to a running <command>postgres</command> process.
|
||||
The <command>postgres</command> instance then starts a separate server
|
||||
process to handle the connection.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the <command>postgres</command> command is called directly, it
|
||||
invokes the server 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.
|
||||
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 server is not truly suitable for
|
||||
debugging the server since no realistic interprocess communication
|
||||
and locking will happen.
|
||||
One <command>postgres</command> instance 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 (the
|
||||
<quote>data area</quote>). More than one
|
||||
<command>postgres</command> process can run on a system at one
|
||||
time, so long as they use different data areas and different
|
||||
communication ports (see below). When
|
||||
<command>postgres</command> starts it needs to know the location
|
||||
of the data area. The location must be specified by the
|
||||
<option>-D</option> option or the <envar>PGDATA</envar> environment
|
||||
variable; there is no default. Typically, <option>-D</option> or
|
||||
<envar>PGDATA</envar> points directly to the data area directory
|
||||
created by <application>initdb</>. Other possible file layouts are
|
||||
discussed in <xref linkend="runtime-config-file-locations">. A
|
||||
data area is created with <xref linkend="app-initdb">.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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 server can be used to manually recover from certain
|
||||
By default <command>postgres</command> starts in the
|
||||
foreground and prints log messages to the standard error stream. In
|
||||
practical applications the <command>postgres</command>
|
||||
should be started as a background process, perhaps at boot time.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <command>postgres</command> command can also be called in
|
||||
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. 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
|
||||
server is not truly suitable for debugging the server since no
|
||||
realistic interprocess communication and locking will happen. 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 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
|
||||
superuser powers are granted to the user with ID 1 in single-user
|
||||
mode.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<refsect1 id="app-postgres-options">
|
||||
<title>Options</title>
|
||||
|
||||
<para>
|
||||
When <command>postgres</command> is started by a <xref
|
||||
linkend="app-postmaster"> then it inherits all options set by the
|
||||
latter. In single-user mode, <command>postgres</command> accepts
|
||||
all the options that <command>postmaster</command> would accept.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can avoid having to type these options by setting up a
|
||||
configuration file. See <xref linkend="runtime-config"> 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
|
||||
<command>postgres</command> accepts the following command-line
|
||||
arguments. For a detailed discussion of the options consult <xref
|
||||
linkend="runtime-config">. You can save typing most of these
|
||||
options by setting up a configuration file. Some (safe) options
|
||||
can also be set from the connecting client in an
|
||||
application-dependent way to apply only for that session. 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
|
||||
<command>postgres</command> command-line options.
|
||||
</para>
|
||||
|
||||
<refsect2>
|
||||
<title>General Purpose</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>-A 0|1</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Enables run-time assertion checks, which is a debugging aid to
|
||||
detect programming mistakes. This option is only available if
|
||||
assertions were enabled when <productname>PostgreSQL</> was
|
||||
compiled. If so, the default is on.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<para>
|
||||
The options <option>-A</option>, <option>-B</option>,
|
||||
<option>-c</option>, <option>-d</option>, <option>-D</option>,
|
||||
<option>-e</option>, <option>-F</option>, <option>-s</option>,
|
||||
<option>-S</option>, and <option>--<replaceable>name</></option>
|
||||
have the same meanings as with the <xref linkend="app-postmaster">
|
||||
except that <literal>-d 0</> prevents the server log level of the
|
||||
<command>postmaster</> from being propagated to
|
||||
<command>postgres</>. Other <command>postmaster</command>
|
||||
options are also accepted but will have no noticeable effect
|
||||
because they only apply to the multiuser server mode, namely
|
||||
<option>-h</option>, <option>-i</option>, <option>-k</option>,
|
||||
<option>-l</option>, and <option>-n</option>.
|
||||
</para>
|
||||
<varlistentry>
|
||||
<term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the number of shared buffers for use by the server
|
||||
processes. The default value of this parameter is chosen
|
||||
automatically by <application>initdb</application>; refer to <xref
|
||||
linkend="runtime-config-resource-memory"> for more information.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets a named run-time parameter. The configuration parameters
|
||||
supported by <productname>PostgreSQL</productname> are
|
||||
described in <xref linkend="runtime-config">. Most of the
|
||||
other command line options are in fact short forms of such a
|
||||
parameter assignment. <option>-c</> can appear multiple times
|
||||
to set multiple parameters.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-d <replaceable>debug-level</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the debug level. The higher this value is set, the more
|
||||
debugging output is written to the server log. Values are
|
||||
from 1 to 5. It is also possible to pass <literal>-d
|
||||
0</literal> for a specific session, which will prevent the
|
||||
server log level of the <command>postgres</> from being
|
||||
propagated to this session.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the file system location of the data directory or
|
||||
configuration file(s). See
|
||||
<xref linkend="runtime-config-file-locations"> for details.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-e</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the default date style to <quote>European</quote>, that is
|
||||
<literal>DMY</> ordering of input date fields. This also causes
|
||||
the day to be printed before the month in certain date output formats.
|
||||
See <xref linkend="datatype-datetime"> for more information.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-F</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Disables <function>fsync</function> calls for improved
|
||||
performance, at the risk of data corruption in the event of a
|
||||
system crash. Specifying this option is equivalent to
|
||||
disabling the <xref linkend="guc-fsync"> configuration
|
||||
parameter. Read the detailed documentation before using this!
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<option>--fsync=true</option> has the opposite effect
|
||||
of this option.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the IP host name or address on which
|
||||
<command>postgres</command> is to listen for TCP/IP
|
||||
connections from client applications. The value can also be a
|
||||
comma-separated list of addresses, or <literal>*</> to specify
|
||||
listening on all available interfaces. An empty value
|
||||
specifies not listening on any IP addresses, in which case
|
||||
only Unix-domain sockets can be used to connect to the
|
||||
<command>postgres</command>. Defaults to listening only on
|
||||
<systemitem class="systemname">localhost</systemitem>.
|
||||
Specifying this option is equivalent to setting the <xref
|
||||
linkend="guc-listen-addresses"> configuration parameter.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-i</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows remote clients to connect via TCP/IP (Internet domain)
|
||||
connections. Without this option, only local connections are
|
||||
accepted. This option is equivalent to setting
|
||||
<varname>listen_addresses</> to <literal>*</> in
|
||||
<filename>postgresql.conf</> or via <option>-h</>.
|
||||
</para>
|
||||
<para>
|
||||
This option is deprecated since it does not allow access to the
|
||||
full functionality of <xref linkend="guc-listen-addresses">.
|
||||
It's usually better to set <varname>listen_addresses</> directly.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the directory of the Unix-domain socket on which
|
||||
<command>postgres</command> is to listen for
|
||||
connections from client applications. The default is normally
|
||||
<filename>/tmp</filename>, but can be changed at build time.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-l</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Enables secure connections using <acronym>SSL</acronym>.
|
||||
<productname>PostgreSQL</productname> must have been compiled with
|
||||
support for <acronym>SSL</acronym> for this option to be
|
||||
available. For more information on using <acronym>SSL</acronym>,
|
||||
refer to <xref linkend="ssl-tcp">.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the maximum number of client connections that this
|
||||
<command>postgres</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
|
||||
<option>-N</option>. See <xref linkend="kernel-resources"> for a discussion of
|
||||
system resource requirements for large numbers of client
|
||||
connections.) Specifying this option is equivalent to setting the
|
||||
<xref linkend="guc-max-connections"> configuration parameter.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<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 server processes started by this
|
||||
<command>postgres</command>. If the option string contains
|
||||
any spaces, the entire string must be quoted.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The use of this option is obsolete; all command-line options
|
||||
for server processes can be specified directly on the
|
||||
<command>postgres</command> command line
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<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 <command>postgres</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
|
||||
defaults to the value established during compilation (normally
|
||||
5432). If you specify a port other than the default port,
|
||||
then all client applications must specify the same port using
|
||||
either command-line options or <envar>PGPORT</envar>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-s</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-S</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies that the <command>postgres</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
|
||||
standard error to <filename>/dev/null</filename>.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
<command>postgres</command> in the background.
|
||||
</para>
|
||||
<para>
|
||||
<option>--silent-mode=false</option> has the opposite effect
|
||||
of this option.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets a named run-time parameter; a shorter form of
|
||||
<option>-c</>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--describe-config</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This option dumps out the server's internal configuration variables,
|
||||
descriptions, and defaults in tab-delimited <command>COPY</> format.
|
||||
It is designed primarily for use by administration tools.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Options for stand-alone mode</title>
|
||||
<title>Semi-internal Options</title>
|
||||
|
||||
<para>
|
||||
There are several other options that may be specified, used
|
||||
mainly for debugging purposes and in some cases to assist with
|
||||
recovery of severely damaged databases. There should be no reason
|
||||
to use them in a production database setup. These are listed
|
||||
here only for the use by <productname>PostgreSQL</productname>
|
||||
system developers. 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.
|
||||
</para>
|
||||
|
||||
<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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-n</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This option is for debugging 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. This
|
||||
option specifies that <command>postgres</command> will
|
||||
not reinitialize shared data structures. A knowledgeable
|
||||
system programmer can then use a debugger to examine shared
|
||||
memory and semaphore state.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-O</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows the structure of system tables to be modified. This is
|
||||
used by <command>initdb</command>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-P</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Ignore system indexes when reading system tables (but still update
|
||||
the indexes when modifying the tables). This is useful when
|
||||
recovering from damaged system indexes.
|
||||
</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>-T</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This option is for debugging 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. This
|
||||
option specifies that <command>postgres</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 server processes by hand.
|
||||
</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 a particular session. This option is for
|
||||
internal use only.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A delay of this many seconds occurs when a new server process
|
||||
is started, after it conducts the authentication procedure.
|
||||
This is intended to give an opportunity to attach to the
|
||||
server process with a debugger.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-y</option> <replaceable class="parameter">database</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Indicates that this is a subprocess started by
|
||||
<command>postgres</command> and specifies the database to
|
||||
use. This option is for internal use only.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Options for single-user mode</title>
|
||||
|
||||
<para>
|
||||
The following options only apply to the single-user mode.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><option>--single</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Selects the single-user mode. This must be the first argument
|
||||
on the command line.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><replaceable class="parameter">database</replaceable></term>
|
||||
<listitem>
|
||||
@@ -142,69 +556,33 @@ PostgreSQL documentation
|
||||
<term><option>-r</option> <replaceable class="parameter">filename</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Send all server log output to
|
||||
<replaceable class="parameter">filename</replaceable>.
|
||||
If <command>postgres</command> is running under the
|
||||
<command>postmaster</command>, this option is ignored,
|
||||
and the <systemitem>stderr</> inherited from the
|
||||
<command>postmaster</command> is used.
|
||||
Send all server log output to <replaceable
|
||||
class="parameter">filename</replaceable>. In normal multiuser
|
||||
mode, this option is ignored, and <systemitem>stderr</> is
|
||||
used by all processes.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Semi-internal Options</title>
|
||||
|
||||
<para>
|
||||
The options <option>-f</option>, <option>-O</option>,
|
||||
<option>-P</option>, <option>-t</option>, and <option>-W</option>
|
||||
have the same meanings as with the <xref
|
||||
linkend="app-postmaster"> and are reserved for debugging and
|
||||
disaster recovery. Further options for internal use are:
|
||||
|
||||
<variablelist>
|
||||
<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>-y</option> <replaceable class="parameter">database</replaceable></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Indicates that this process has been started by a
|
||||
<command>postmaster</command> and specifies the database to use.
|
||||
etc.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--describe-config</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This option dumps out the server's internal configuration variables,
|
||||
descriptions, and defaults in tab-delimited <command>COPY</> format.
|
||||
It is designed primarily for use by administration tools.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Environment</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><envar>PGCLIENTENCODING</envar></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Default character encoding used by clients. (The clients may
|
||||
override this individually.) This value can also be set in the
|
||||
configuration file.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><envar>PGDATA</envar></term>
|
||||
|
||||
@@ -214,47 +592,154 @@ PostgreSQL documentation
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><envar>PGDATESTYLE</envar></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Default value of the <xref linkend="guc-datestyle"> run-time
|
||||
parameter. (The use of this environment variable is deprecated.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><envar>PGPORT</envar></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Default port (preferably set in the configuration file)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><envar>TZ</envar></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Server time zone
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Diagnostics</title>
|
||||
|
||||
<para>
|
||||
A failure message mentioning <literal>semget</> or
|
||||
<literal>shmget</> probably indicates you need to configure your
|
||||
kernel to provide adequate shared memory and semaphores. For more
|
||||
discussion see <xref linkend="kernel-resources">. You may be able
|
||||
to postpone reconfiguring your kernel by decreasing <xref
|
||||
linkend="guc-shared-buffers"> to reduce the shared memory
|
||||
consumption of <productname>PostgreSQL</>, and/or by reducing
|
||||
<xref linkend="guc-max-connections"> to reduce the semaphore
|
||||
consumption.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A failure message suggesting that another server is already running
|
||||
should be checked carefully, for example by using the command
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>ps ax | grep postgres</userinput>
|
||||
</screen>
|
||||
or
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>ps -ef | grep postgres</userinput>
|
||||
</screen>
|
||||
depending on your system. If you are certain that no conflicting
|
||||
server is running, you may remove the lock file mentioned in the
|
||||
message and try again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A failure message indicating inability to bind to a port may
|
||||
indicate that that port is already in use by some
|
||||
non-<productname>PostgreSQL</productname> process. You may also
|
||||
get this error if you terminate <command>postgres</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 <quote>trusted</quote> and only permit
|
||||
the Unix superuser to access them.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>
|
||||
If at all possible, <emphasis>do not</emphasis> use
|
||||
<literal>SIGKILL</literal> to kill the main
|
||||
<command>postgres</command> server. Doing so will prevent
|
||||
<command>postgres</command> from freeing the system
|
||||
resources (e.g., shared memory and semaphores) that it holds before
|
||||
terminating. This may cause problems for starting a fresh
|
||||
<command>postgres</command> run.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To terminate the <command>postgres</command> server 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
|
||||
forcefully disconnect all clients, and the third will quit
|
||||
immediately without proper shutdown, resulting in a recovery run
|
||||
during restart. The <literal>SIGHUP</literal> signal will reload
|
||||
the server configuration files. It is also possible to send
|
||||
<literal>SIGHUP</literal> to an individual server process, but that
|
||||
is usually not sensible.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The utility command <xref linkend="app-pg-ctl"> can be used to
|
||||
start and shut down the <command>postgres</command> server
|
||||
safely and comfortably.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To cancel a running query, send the <literal>SIGINT</literal> signal
|
||||
to the <command>postgres</command> process running that command.
|
||||
to the process running that command.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To tell <command>postgres</command> to reload the configuration files,
|
||||
send a <literal>SIGHUP</literal> signal. Normally it's best to
|
||||
<literal>SIGHUP</literal> the <command>postmaster</command> instead;
|
||||
the <command>postmaster</command> will in turn <literal>SIGHUP</literal>
|
||||
each of its children. But in some cases it might be desirable to have only
|
||||
one <command>postgres</command> process reload the configuration files.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <command>postmaster</command> uses <literal>SIGTERM</literal>
|
||||
to tell a <command>postgres</command> process to quit normally and
|
||||
The <command>postgres</command> server uses <literal>SIGTERM</literal>
|
||||
to tell subordinate server processes to quit normally and
|
||||
<literal>SIGQUIT</literal> to terminate without the normal cleanup.
|
||||
These signals <emphasis>should not</emphasis> be used by users. It is also
|
||||
unwise to send <literal>SIGKILL</literal> to a <command>postgres</command>
|
||||
process — the <command>postmaster</command> will interpret this as
|
||||
a crash in <command>postgres</command>, and will force all the sibling
|
||||
<command>postgres</command> processes to quit as part of its standard
|
||||
crash-recovery procedure.
|
||||
These signals <emphasis>should not</emphasis> be used by users. It
|
||||
is also unwise to send <literal>SIGKILL</literal> to a server
|
||||
process — the main <command>postgres</command> process will
|
||||
interpret this as a crash and will force all the sibling processes
|
||||
to quit as part of its standard crash-recovery procedure.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="app-postgres-bugs">
|
||||
<title>Bugs</title>
|
||||
<para>
|
||||
The <option>--</> options will not work on <systemitem
|
||||
class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>.
|
||||
Use <option>-c</> instead. This is a bug in the affected operating
|
||||
systems; a future release of <productname>PostgreSQL</productname>
|
||||
will provide a workaround if this is not fixed.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Usage</title>
|
||||
|
||||
<para>
|
||||
Start a stand-alone server with a command like
|
||||
To start a single-user mode server, use a command like
|
||||
<screen>
|
||||
<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
|
||||
<userinput>postgres --single -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
|
||||
</screen>
|
||||
Provide the correct path to the database directory with <option>-D</>, or
|
||||
make sure that the environment variable <envar>PGDATA</> is set.
|
||||
@@ -262,7 +747,7 @@ PostgreSQL documentation
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Normally, the stand-alone server treats newline as the command
|
||||
Normally, the single-user mode 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
|
||||
@@ -285,10 +770,57 @@ PostgreSQL documentation
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that the stand-alone server does not provide sophisticated
|
||||
Note that the single-user mode server does not provide sophisticated
|
||||
line-editing features (no command history, for example).
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="app-postgres-examples">
|
||||
<title>Examples</title>
|
||||
|
||||
<para>
|
||||
To start <command>postgres</command> in the background
|
||||
using default values, type:
|
||||
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>nohup postgres >logfile 2>&1 </dev/null &</userinput>
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To start <command>postgres</command> with a specific
|
||||
port:
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>postgres -p 1234</userinput>
|
||||
</screen>
|
||||
This command will start up <command>postgres</command>
|
||||
communicating through the port 1234. In order to connect to this
|
||||
<command>postgres</command> using <application>psql</>, you would need to
|
||||
run it as
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>psql -p 1234</userinput>
|
||||
</screen>
|
||||
or set the environment variable <envar>PGPORT</envar>:
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
|
||||
<prompt>$</prompt> <userinput>psql</userinput>
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Named run-time parameters can be set in either of these styles:
|
||||
<screen>
|
||||
<prompt>$</prompt> <userinput>postgres -c work_mem=1234</userinput>
|
||||
<prompt>$</prompt> <userinput>postgres --work-mem=1234</userinput>
|
||||
</screen>
|
||||
Either form overrides whatever setting might exist for
|
||||
<varname>work_mem</> in <filename>postgresql.conf</>. Notice that
|
||||
underscores in parameter names can be written as either underscore
|
||||
or dash on the command line. Except for short-term experiments,
|
||||
it's probably better practice to edit the setting in
|
||||
<filename>postgresql.conf</> than to rely on a command-line switch
|
||||
to set a parameter.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
@@ -296,26 +828,7 @@ PostgreSQL documentation
|
||||
|
||||
<para>
|
||||
<xref linkend="app-initdb">,
|
||||
<xref linkend="app-ipcclean">,
|
||||
<xref linkend="app-postmaster">
|
||||
<xref linkend="app-pg-ctl">
|
||||
</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:nil
|
||||
sgml-default-dtd-file:"../reference.ced"
|
||||
sgml-exposed-tags:nil
|
||||
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
||||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
-->
|
||||
|
||||
Reference in New Issue
Block a user