| |
man : postmaster(1)
POSTMASTER(1) PostgreSQL Server Applications POSTMASTER(1)
NAME
postmaster - PostgreSQL multiuser database server
SYNOPSIS
postmaster [ -A [ 0 ] [ 1 ] ] [ -B nbuffers ] [ -c
name=value ] [ -d debug-level ] [ -D datadir ] [ -F ]
[ -h hostname ] [ -i ] [ -k directory ] [ -l ] [ -N
max-connections ] [ -o extra-options ] [ -p port ] [ -S
] [ --name=value ] [ [ -n ] [ -s ] ]
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 postmas-
ter. The postmaster then starts a separate server process
(``postgres(1)'') 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 prac-
tical 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(1).
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 the documentation.
OPTIONS
postmaster accepts the following command line arguments.
For a detailed discussion of the options consult the docu-
mentation. 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
Application 2005-11-05 1
POSTMASTER(1) PostgreSQL Server Applications POSTMASTER(1)
parameter is chosen automatically by initdb; refer
to the documentation for more information.
-c name=value
Sets a named run-time parameter. The configuration
parameters supported by PostgreSQL are described in
the documentation. 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 the docu-
mentation for details.
-F Disables fsync calls for improved performance, at
the risk of data corruption in the event of a sys-
tem 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 space-
separated list of addresses, or * to specify lis-
tening 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 configu-
ration parameter.
-i Allows remote clients to connect via TCP/IP (Inter-
net 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 lis-
ten_addresses. It's usually better to set lis-
ten_addresses directly.
Application 2005-11-05 2
POSTMASTER(1) PostgreSQL Server Applications POSTMASTER(1)
-k directory
Specifies the directory of the Unix-domain socket
on which the postmaster is to listen for connec-
tions from client applications. The default is nor-
mally /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 the documentation.
-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 the documentation for a discus-
sion of system resource requirements for large num-
bers of client connections.) Specifying this option
is equivalent to setting the max_connections con-
figuration 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(1) for possibili-
ties. 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
Application 2005-11-05 3
POSTMASTER(1) PostgreSQL Server Applications POSTMASTER(1)
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 cor-
rupted 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 struc-
tures. 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 depre-
cated.)
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
Application 2005-11-05 4
POSTMASTER(1) PostgreSQL Server Applications POSTMASTER(1)
adequate shared memory and semaphores. For more discussion
see the documentation.
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 con-
flicting 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 spec-
ify 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 post-
master. 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 recov-
ery run during restart. The SIGHUP signal will reload the
server configuration files.
The utility command pg_ctl(1) can be used to start and
shut down the postmaster safely and comfortably.
Application 2005-11-05 5
POSTMASTER(1) PostgreSQL Server Applications POSTMASTER(1)
The -- options will not work on FreeBSD or OpenBSD. Use
-c instead. This is a bug in the affected operating sys-
tems; a future release of PostgreSQL will provide a
workaround if this is not fixed.
EXAMPLES
To start postmaster in the background using default val-
ues, 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 post-
master 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 proba-
bly better practice to edit the setting in post-
gresql.conf than to rely on a command-line switch
to set a parameter.
SEE ALSO
initdb(1), pg_ctl(1)
Application 2005-11-05 6
|
