Description
pg_ctl is a utility for starting,
stopping, or restarting postmaster, the
PostgreSQL backend server, or displaying
the status of a running postmaster. Although the postmaster can be
started manually, pg_ctl encapsulates
tasks such as redirecting log output, properly detaching from the
terminal and process group, and it provides convenient options for
controlled shutdown.
In start mode, a new postmaster is launched. The
server is started in the background, the standard input attached to
/dev/null. The standard output and standard
error are either appended to a log file, if the -l
option is used, or are redirected to
pg_ctl's standard output (not standard
error). If no log file is chosen, the standard output of
pg_ctl should be redirected to a file or
piped to another process, for example a log rotating program,
otherwise the postmaster will write its output the the controlling
terminal (from the background) and will not leave the shell's
process group.
In stop mode, the postmaster that is running in
the specified data directory is shut down. Three different
shutdown methods can be selected with the -m
option: "Smart" mode waits for all the clients to
disconnect. This is the default. "Fast" mode does
not wait for clients to disconnect. All active transactions are
rolled back and clients are forcibly disconnected, then the
database is shut down. "Immediate" mode will abort
all server processes without clean shutdown. This will lead to a recovery
run on restart.
restart mode effectively executes a stop followed
by a start. This allows the changing of postmaster command line
options.
reload mode simply sends the postmaster a SIGHUP signal,
causing it to reread its configuration files
(postgresql.conf, pg_hba.conf,
etc.). This allows changing of configuration-file options that do not
require a complete restart to take effect.
status mode checks whether a postmaster is running
and if so displays the PID and the command line
options that were used to invoke it.
Files
If the file postmaster.opts.default exists in
the data directory, the contents of the file will be passed as
options to the postmaster, unless
overridden by the -o option.
Examples
Starting the postmaster
To start up a postmaster:
$ pg_ctl start
An example of starting the postmaster,
blocking until the postmaster comes up is:
$ pg_ctl -w start
For a postmaster using port 5433, and
running without fsync, use:
$ pg_ctl -o "-F -p 5433" start
Stopping the postmaster
$ pg_ctl stop
stops the postmaster. Using the -m switch allows one
to control how the backend shuts down.
Restarting the postmaster
This is almost equivalent to stopping the
postmaster and starting it again
except that pg_ctl saves and reuses the command line options that
were passed to the previously running instance. To restart
the postmaster in the simplest form:
$ pg_ctl restart
To restart postmaster,
waiting for it to shut down and to come up:
$ pg_ctl -w restart
To restart using port 5433 and disabling fsync after restarting:
$ pg_ctl -o "-F -p 5433" restart
Showing postmaster status
Here is a sample status output from
pg_ctl:
$ pg_ctl status
pg_ctl: postmaster is running (pid: 13718)
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
This is the command line that would be invoked in restart mode.
