mirror of
https://github.com/postgres/postgres.git
synced 2025-12-21 05:21:08 +03:00
605 lines
20 KiB
Plaintext
605 lines
20 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.52 2004/09/20 00:04:19 neilc Exp $
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-postmaster">
|
|
<refmeta>
|
|
<refentrytitle id="APP-POSTMASTER-TITLE"><application>postmaster</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname id="postmaster-ref">postmaster</refname>
|
|
<refpurpose><productname>PostgreSQL</productname> multiuser database server</refpurpose>
|
|
</refnamediv>
|
|
|
|
<indexterm zone="app-postmaster">
|
|
<primary>postmaster</primary>
|
|
</indexterm>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>postmaster</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>-F</arg>
|
|
<arg>-h <replaceable>hostname</replaceable></arg>
|
|
<arg>-i</arg>
|
|
<arg>-k <replaceable>directory</replaceable></arg>
|
|
<arg>-l</arg>
|
|
<arg>-N <replaceable>max-connections</replaceable></arg>
|
|
<arg>-o <replaceable>extra-options</replaceable></arg>
|
|
<arg>-p <replaceable>port</replaceable></arg>
|
|
<arg>-S</arg>
|
|
<arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
|
|
<group><arg>-n</arg><arg>-s</arg></group>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<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
|
|
<command>postmaster</command>. The
|
|
<command>postmaster</command> then starts a separate server
|
|
process (<quote><xref linkend="app-postgres"></quote>) to handle
|
|
the connection. The <command>postmaster</command> also
|
|
manages the communication among server processes.
|
|
</para>
|
|
|
|
<para>
|
|
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 <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 <command>postmaster</command> starts it needs
|
|
to know the location of the database cluster files (<quote>data
|
|
area</quote>).
|
|
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">.
|
|
</para>
|
|
|
|
<para>
|
|
The <quote>data area</> is specified by the <option>-D</option> option
|
|
or the <envar>PGDATA</envar> environment variable; there is no default.
|
|
Typically, it points to a directory created by <application>
|
|
initdb</>. However, for administrative flexibility, you can
|
|
point to a directory containing only configuration files:
|
|
<filename>postgresql.conf</>, <filename>pg_hba.conf</>, and
|
|
<filename>pg_ident.conf</>. You can then set
|
|
<filename>postgresql.conf</>'s <varname>pgdata</> variable to point to the
|
|
data directory. You can also point just to the server configuration file
|
|
like <filename>postgresql.conf</> and set its variables to point to the
|
|
other configuration files and the data directory.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="app-postmaster-options">
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
<command>postmaster</command> accepts the following
|
|
command line arguments. For a detailed discussion of the options
|
|
consult <xref linkend="runtime-config">. You can also save typing most of these
|
|
options by setting up a configuration file.
|
|
|
|
<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>
|
|
|
|
<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.
|
|
</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. See
|
|
discussion above.
|
|
</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 the
|
|
<command>postmaster</command> is to listen for TCP/IP
|
|
connections from client applications. The value can also be a
|
|
space-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>postmaster</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 the
|
|
<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>
|
|
</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>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
|
|
<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>postmaster</command>. See <xref
|
|
linkend="app-postgres"> for possibilities. If the option
|
|
string contains any spaces, the entire string must be quoted.
|
|
</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 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
|
|
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>
|
|
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
|
|
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
|
|
the <command>postmaster</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>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Two additional command line options are available 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.
|
|
These options select alternative behaviors of the
|
|
<command>postmaster</command> in this situation.
|
|
<emphasis>Neither option is intended for use in ordinary
|
|
operation.</emphasis>
|
|
</para>
|
|
|
|
<para>
|
|
</para>
|
|
|
|
<para>
|
|
These special-case options are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<listitem>
|
|
<para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-s</option></term>
|
|
<listitem>
|
|
<para>
|
|
<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 server processes by hand.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
</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>
|
|
|
|
<listitem>
|
|
<para>
|
|
Default data direction location
|
|
</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">.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
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>
|
|
</tip>
|
|
|
|
<para>
|
|
A failure message suggesting that another postmaster is already running
|
|
should be checked carefully, for example by using the command
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
|
|
</screen>
|
|
or
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput>
|
|
</screen>
|
|
depending on your system. If you are certain that no conflicting
|
|
postmaster 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 the <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 <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
|
|
<command>postmaster</command>. Doing so will prevent
|
|
<command>postmaster</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>postmaster</command> run.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The utility command <xref linkend="app-pg-ctl"> can be used to
|
|
start and shut down the <command>postmaster</command>
|
|
safely and comfortably.
|
|
</para>
|
|
|
|
<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 id="app-postmaster-examples">
|
|
<title>Examples</title>
|
|
<para>
|
|
To start <command>postmaster</command> in the background
|
|
using default values, type:
|
|
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>nohup postmaster >logfile 2>&1 </dev/null &</userinput>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
To start <command>postmaster</command> with a specific
|
|
port:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
|
|
</screen>
|
|
This command will start up <command>postmaster</command>
|
|
communicating through the port 1234. In order to connect to this
|
|
<command>postmaster</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>postmaster -c work_mem=1234</userinput>
|
|
<prompt>$</prompt> <userinput>postmaster --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.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
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>
|
|
</tip>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="app-initdb">,
|
|
<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:
|
|
-->
|