encapsulates tasks such
as redirecting log output and properly detaching from the terminal
and process group. It also provides convenient options for
controlled shutdown.
</para>
<para>
The <option>init</option> or <option>initdb</option> mode creates a new
<productname>PostgreSQL</productname> database cluster, that is,
a collection of databases that will be managed by a single
server instance. This mode invokes the <command>initdb</command>
command. See <xref linkend="app-initdb"/> for details.
</para>
<para>
<option>start</option> mode launches a new server. The
server is started in the background, and its standard input is attached
to <filename>/dev/null</filename> (or <literal>nul</literal> on Windows).
On Unix-like systems, by default, the server's standard output and
standard error are sent to <application>pg_ctl</application>'s
standard output (not standard error). The standard output of
<application>pg_ctl</application> should then be redirected to a
file or piped to another process such as a log rotating program
like <application>rotatelogs</application>; otherwise <command>postgres</command>
will write its output to the controlling terminal (from the
background) and will not leave the shell's process group. On
Windows, by default the server's standard output and standard error
are sent to the terminal. These default behaviors can be changed
by using <option>-l</option> to append the server's output to a log file.
Use of either <option>-l</option> or output redirection is recommended.
</para>
<para>
<option>stop</option> mode shuts down the server that is running in
the specified data directory. Three different
shutdown methods can be selected with the <option>-m</option>
option. <quote>Smart</quote> mode disallows new connections, then waits
for all existing clients to disconnect.
If the server is in hot standby, recovery and streaming replication
will be terminated once all clients have disconnected.
<quote>Fast</quote> mode (the default) does not wait for clients to disconnect.
All active transactions are
rolled back and clients are forcibly disconnected, then the
server is shut down. <quote>Immediate</quote> mode will abort
all server processes immediately, without a clean shutdown. This choice
will lead to a crash-recovery cycle during the next server start.
</para>
<para>
<option>restart</option> mode effectively executes a stop followed
by a start. This allows changing the <command>postgres</command>
command-line options, or changing configuration-file options that
cannot be changed without restarting the server.
If relative paths were used on the command line during server
start, <option>restart</option> might fail unless
<application>pg_ctl</application> is executed in the same current
directory as it was during server start.
</para>
<para>
<option>reload</option> mode simply sends the
<command>postgres</command> server process a <systemitem>SIGHUP</systemitem>
signal, causing it to reread its configuration files
(<filename>postgresql.conf</filename>,
<filename>pg_hba.conf</filename>, etc.). This allows changing
configuration-file options that do not require a full server restart
to take effect.
</para>
<para>
<option>status</option> mode checks whether a server is running in
the specified data directory. If it is, the server's <acronym>PID</acronym>
and the command line options that were used to invoke it are displayed.
If the server is not running, <application>pg_ctl</application> returns
an exit status of 3. If an accessible data directory is not
specified, <application>pg_ctl</application> returns an exit status of 4.
</para>
<para>
<option>promote</option> mode commands the standby server that is
running in the specified data directory to end standby mode
and begin read-write operations.