<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.9 2001/09/21 21:10:56 tgl Exp $
Postgres documentation
-->
<refentry id="app-pg-ctl">
<docinfo>
<date>2001-02-08</date>
</docinfo>
<refmeta>
<refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_ctl</refname>
<refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_ctl</command>
<arg choice="plain">start</arg>
<arg>-w</arg>
<arg>-s</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-l <replaceable>filename</replaceable></arg>
<arg>-o <replaceable>options</replaceable></arg>
<arg>-p <replaceable>path</replaceable></arg>
<sbr>
<command>pg_ctl</command>
<arg choice="plain">stop</arg>
<arg>-W</arg>
<arg>-s</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-m
<group choice="plain">
<arg>s[mart]</arg>
<arg>f[ast]</arg>
<arg>i[mmediate]</arg>
</group>
</arg>
<sbr>
<command>pg_ctl</command>
<arg choice="plain">restart</arg>
<arg>-w</arg>
<arg>-s</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-m
<group choice="plain">
<arg>s[mart]</arg>
<arg>f[ast]</arg>
<arg>i[mmediate]</arg>
</group>
</arg>
<arg>-o <replaceable>options</replaceable></arg>
<sbr>
<command>pg_ctl</command>
<arg choice="plain">reload</arg>
<arg>-s</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<sbr>
<command>pg_ctl</command>
<arg choice="plain">status</arg>
<arg>-D <replaceable>datadir</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="app-pg-ctl-description">
<title>Description</title>
<para>
<application>pg_ctl</application> is a utility for starting,
stopping, or restarting <xref linkend="app-postmaster">, the
<productname>PostgreSQL</productname> backend server, or displaying
the status of a running postmaster. Although the postmaster can be
started manually, <application>pg_ctl</application> encapulates
tasks such as redirecting log output, properly detaching from the
terminal and process group, and it provides convenient options for
controlled shut down.
</para>
<para>
In <option>start</option> mode, a new postmaster is launched. The
server is started in the background, the standard input attached to
<filename>/dev/null</filename>. The standard output and standard
error are either appended to a log file, if the <option>-l</option>
option is used, or are redirected to
<application>pg_ctl</application>'s standard output (not standard
error). If no log file is chosen, the standard output of
<application>pg_ctl</application> 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.
</para>
<para>
In <option>stop</option> mode, the postmaster that is running in
the specified data directory is shut down. Three different
shutdown methods can be selected with the <option>-m</option>
option: <quote>Smart</quote> mode waits for all the clients to
disconnect. This is the default. <quote>Fast</quote> mode does
not wait for clients to disconnect. All active transactions will
be rolled back. <quote>Immediate</quote> mode will abort without
complete shutdown. This will lead to a recovery run on restart.
</para>
<para>
<option>restart</option> mode effectively executes a stop followed
by a start. This allows the changing of postmaster command line
options.
</para>
<para>
<option>reload</option> mode simply sends the postmaster a SIGHUP signal,
causing it to reread its configuration files
(<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
etc). This allows changing of configuration-file options that do not
require a complete restart to take effect.
</para>
<para>
<option>status</option> mode checks whether a postmaster is running
and if so displays the <acronym>PID</acronym> and the command line
options that were used to invoke it.
</para>
<refsect2 id="app-pg-ctl-options">
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term>-D <replaceable class="parameter">datadir</replaceable></term>
<listitem>
<para>
Specifies the file system location of the database files. If
this is omitted, the environment variable
<envar>PGDATA</envar> is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Append the server log output to
<replaceable>filename</replaceable>. If the file does not
exist, it is created. The umask is set to 077, so access to
the log file from other users is disallowed by default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-m <replaceable class="parameter">mode</replaceable></term>
<listitem>
<para>
Specifies the shutdown mode. <replaceable>mode</replaceable>
may be <literal>smart</literal>, <literal>fast</literal>, or
<literal>immediate</literal>, or the first letter of one of
these three.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o <replaceable class="parameter">options</replaceable></term>
<listitem>
<para>
Specifies options to be passed directly to
<application>postmaster</application>.
</para>
<para>
The parameters are usually surrounded by single or double
quotes to ensure that they are passed through as a group.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">path</replaceable></term>
<listitem>
<para>
Specifies the location of the <filename>postmaster</filename>
executable. By default the postmaster is taken from the same
directory as pg_ctl, or failing that, the hard-wired
installation directory. It is not necessary to use this
option unless you are doing something unusual and get errors
that the postmaster was not found.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-w</term>
<listitem>
<para>
Wait for the start or shutdown to complete. Times out after
60 seconds. This is the default for shutdowns.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-W</term>
<listitem>
<para>
Do not wait for start or shutdown to complete. This is the
default for starts and restarts.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-s</term>
<listitem>
<para>
Only print errors, no informational messages.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<refsect2>
<title>Files</title>
<para>
If the file <filename>postmaster.opts.default</filename> exists in
the data directory, the contents of the file will be passed as
options to the <application>postmaster</application>, unless
overridden by the <option>-o</option> option.
</para>
</refsect2>
</refsect1>
<refsect1 id="R1-APP-PGCTL-2">
<title>Examples</title>
<refsect2 id="R2-APP-PGCTL-3">
<title>Starting the postmaster</title>
<para>
To start up <application>postmaster</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
</para>
<para>
An example of starting the <application>postmaster</application>,
blocking until postmaster comes up is:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
</para>
<para>
For a <application>postmaster</application> using port 5433, and
running without <function>fsync</function>, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
</screen>
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-4">
<title>Stopping the postmaster</title>
<para>
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
stops postmaster. Using the <option>-m</option> switch allows one
to control <emphasis>how</emphasis> the backend shuts down.
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-5">
<title>Restarting the postmaster</title>
<para>
This is almost equivalent to stopping the
<application>postmaster</application> then starting it again
except that pg_ctl saves and reuses the command line options that
were passed to the previously running instance. To restart
<application>postmaster</application> in the simplest form:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
</para>
<para>
To restart <application>postmaster</application>,
waiting for it to shut down and to come up:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
</screen>
</para>
<para>
To restart using port 5433 and disabling fsync after restarting:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
</screen>
</para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-6">
<title>Showing postmaster status</title>
<para>
Here is a sample status output from
<application>pg_ctl</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
<computeroutput>
pg_ctl: postmaster is running (pid: 13718)
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
</computeroutput>
</screen>
This is the command line that would be invoked in restart mode.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Bugs</title>
<para>
Waiting for complete start is not a well-defined operation and may
fail if access control is set up in way that a local client cannot
connect without manual interaction. It should be avoided.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
</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:
-->