Description

postmaster is the PostgreSQL multiuser database server. In
order for a client application to access a database it connects
(over a network or locally) to a running postmaster. The postmaster then starts a separate server process
("postgres") to handle the
connection. The postmaster also manages
the communication among server processes.

By default the postmaster starts in
the foreground and prints log messages to the standard error
stream. In practical applications the postmaster should be started as a background
process, perhaps at boot time.

One postmaster 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 "data area"). More than
one postmaster process can run on a
system at one time, so long as they use different data areas and
different communication ports (see below). A data area is created
with initdb.

When the postmaster starts it needs
to know the location of the data area. The location must be
specified by the -D option or the
PGDATA environment variable; there is no
default. Typically, -D or PGDATA points directly to the data area directory
created by initdb. Other
possible file layouts are discussed in Section 17.2.

Options

postmaster accepts the following
command line arguments. For a detailed discussion of the options
consult Chapter 17. You can
also save typing most of these options by setting up a
configuration file.

-A 0|1

Enables run-time assertion checks, which is a debugging
aid to detect programming mistakes. This option is only
available if assertions were enabled when PostgreSQL was compiled. If so, the
default is on.

-B nbuffers

Sets the number of shared buffers for use by the server
processes. The default value of this parameter is chosen
automatically by initdb;
refer to
Section 17.4.1 for more information.

-c name=value

Sets a named run-time parameter. The configuration
parameters supported by PostgreSQL are described in Chapter 17. Most of the other
command line options are in fact short forms of such a
parameter assignment. -c can appear
multiple times to set multiple parameters.

-d debug-level

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.

-D datadir

Specifies the file system location of the data directory
or configuration file(s). See Section 17.2 for
details.

-F

Disables fsync 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 fsync configuration
parameter. Read the detailed documentation before using
this!

--fsync=true has the opposite
effect of this option.

-h hostname

Specifies the IP host name or address on which the
postmaster is to listen for TCP/IP
connections from client applications. The value can also be
a comma-separated list of addresses, or * 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 postmaster.
Defaults to listening only on localhost. Specifying this option is
equivalent to setting the listen_addresses
configuration parameter.

-i

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 listen_addresses to
* in postgresql.conf or via -h.

This option is deprecated since it does not allow access
to the full functionality of listen_addresses.
It's usually better to set listen_addresses directly.

-k directory

Specifies the directory of the Unix-domain socket on
which the postmaster is to listen
for connections from client applications. The default is
normally /tmp, but can be changed
at build time.

-l

Enables secure connections using SSL. PostgreSQL must have been compiled
with support for SSL for
this option to be available. For more information on using
SSL, refer to Section 16.7.

-N max-connections

Sets the maximum number of client connections that this
postmaster will accept. By
default, this value is 32, but it can be set as high as
your system will support. (Note that -B is required to be at least twice
-N. See Section 16.4 for a discussion
of system resource requirements for large numbers of client
connections.) Specifying this option is equivalent to
setting the max_connections
configuration parameter.

-o extra-options

The command line-style options specified in extra-options are passed to all
server processes started by this postmaster. See postgres for possibilities. If the
option string contains any spaces, the entire string must
be quoted.

-p port

Specifies the TCP/IP port or local Unix domain socket
file extension on which the postmaster is to listen for connections from
client applications. Defaults to the value of the
PGPORT environment variable, or if
PGPORT 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 PGPORT.

-S

Specifies that the postmaster
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 /dev/null.

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 postmaster in the
background.

--silent-mode=false has the
opposite effect of this option.

--name=value

Sets a named run-time parameter; a shorter form of
-c.

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
postmaster in this situation.
Neither option is intended for
use in ordinary operation.

These special-case options are:

-n

postmaster will not
reinitialize shared data structures. A knowledgeable system
programmer can then use a debugger to examine shared memory
and semaphore state.

-s

postmaster will stop all other
server processes by sending the signal SIGSTOP, but will not cause them to
terminate. This permits system programmers to collect core
dumps from all server processes by hand.

Environment

PGCLIENTENCODING

Default character encoding used by clients. (The clients
may override this individually.) This value can also be set
in the configuration file.

PGDATA

Default data directory location

PGDATESTYLE

Default value of the DateStyle
run-time parameter. (The use of this environment variable
is deprecated.)

PGPORT

Default port (preferably set in the configuration
file)

TZ

Server time zone

Diagnostics

A failure message mentioning semget
or shmget probably indicates you need to
configure your kernel to provide adequate shared memory and
semaphores. For more discussion see Section 16.4.

Tip: You may be able to postpone reconfiguring your
kernel by decreasing shared_buffers
to reduce the shared memory consumption of PostgreSQL, and/or by reducing max_connections
to reduce the semaphore consumption.

A failure message suggesting that another postmaster is
already running should be checked carefully, for example by using
the command

$ps ax | grep postmaster

or

$ps -ef | grep postmaster

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.

A failure message indicating inability to bind to a port may
indicate that that port is already in use by some
non-PostgreSQL process. You may
also get this error if you terminate the postmaster 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
"trusted" and only permit the Unix
superuser to access them.

Notes

If at all possible, do
not use SIGKILL to kill the
postmaster. Doing so will prevent
postmaster from freeing the system
resources (e.g., shared memory and semaphores) that it holds
before terminating. This may cause problems for starting a fresh
postmaster run.

To terminate the postmaster normally,
the signals SIGTERM, SIGINT, or SIGQUIT 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 SIGHUP signal will reload the server configuration
files.

The utility command pg_ctl can be used to start and shut
down the postmaster safely and
comfortably.

The -- options will not work on
FreeBSD or OpenBSD. Use -c
instead. This is a bug in the affected operating systems; a
future release of PostgreSQL
will provide a workaround if this is not fixed.

Examples

To start postmaster in the background
using default values, type:

$nohup postmaster >logfile 2>&1 </dev/null &

To start postmaster with a specific
port:

$postmaster -p 1234

This command will start up postmaster
communicating through the port 1234. In order to connect to this
postmaster using psql, you would need to run it as

$psql -p 1234

or set the environment variable PGPORT:

$export PGPORT=1234$psql

Named run-time parameters can be set in either of these
styles:

$postmaster -c work_mem=1234$postmaster --work-mem=1234

Either form overrides whatever setting might exist for
work_mem in postgresql.conf. Notice that underscores in
parameter names can be written as either underscore or dash on
the command line.

Tip: Except for short-term experiments, it's
probably better practice to edit the setting in postgresql.conf than to rely on a
command-line switch to set a parameter.