-->
<refentry id="app-pg-ctl">
+ <indexterm zone="app-pg-ctl">
+ <primary>pg_ctl</primary>
+ </indexterm>
+
<refmeta>
<refentrytitle><application>pg_ctl</application></refentrytitle>
<manvolnum>1</manvolnum>
<refnamediv>
<refname>pg_ctl</refname>
- <refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
+ <refpurpose>initialize, start, stop, or control a <productname>PostgreSQL</productname> server</refpurpose>
</refnamediv>
- <indexterm zone="app-pg-ctl">
- <primary>pg_ctl</primary>
- </indexterm>
-
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">init[db]</arg>
- <arg>-s</arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
- <arg>-o <replaceable>initdb-options</replaceable></arg>
+ <arg choice="plain"><option>init[db]</option></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <arg choice="opt"><option>-o</option> <replaceable>initdb-options</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">start</arg>
- <arg>-w</arg>
- <arg>-t <replaceable>seconds</replaceable></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>
- <arg>-c</arg>
+ <arg choice="plain"><option>start</option></arg>
+ <arg choice="opt"><option>-w</option></arg>
+ <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <arg choice="opt"><option>-l</option> <replaceable>filename</replaceable></arg>
+ <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
+ <arg choice="opt"><option>-p</option> <replaceable>path</replaceable></arg>
+ <arg choice="opt"><option>-c</option></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">stop</arg>
- <arg>-W</arg>
- <arg>-t <replaceable>seconds</replaceable></arg>
- <arg>-s</arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
- <arg>-m
+ <arg choice="plain"><option>stop</option></arg>
+ <arg choice="opt"><option>-W</option></arg>
+ <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <arg choice="opt"><option>-m</option>
<group choice="plain">
- <arg>s[mart]</arg>
- <arg>f[ast]</arg>
- <arg>i[mmediate]</arg>
+ <arg choice="plain"><option>s[mart]</option></arg>
+ <arg choice="plain"><option>f[ast]</option></arg>
+ <arg choice="plain"><option>i[mmediate]</option></arg>
</group>
</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">restart</arg>
- <arg>-w</arg>
- <arg>-t <replaceable>seconds</replaceable></arg>
- <arg>-s</arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
- <arg>-c</arg>
- <arg>-m
+ <arg choice="plain"><option>restart</option></arg>
+ <arg choice="opt"><option>-w</option></arg>
+ <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <arg choice="opt"><option>-c</option></arg>
+ <arg choice="opt"><option>-m</option>
<group choice="plain">
- <arg>s[mart]</arg>
- <arg>f[ast]</arg>
- <arg>i[mmediate]</arg>
+ <arg choice="plain"><option>s[mart]</option></arg>
+ <arg choice="plain"><option>f[ast]</option></arg>
+ <arg choice="plain"><option>i[mmediate]</option></arg>
</group>
</arg>
- <arg>-o <replaceable>options</replaceable></arg>
+ <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>pg_ctl</command>
+ <arg choice="plain"><option>reload</option></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">reload</arg>
- <arg>-s</arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
+ <arg choice="plain"><option>status</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">status</arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
+ <arg choice="plain"><option>promote</option></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">kill</arg>
- <arg><replaceable>signal_name</replaceable></arg>
- <arg><replaceable>process_id</replaceable></arg>
+ <arg choice="plain"><option>kill</option></arg>
+ <arg choice="plain"><replaceable>signal_name</replaceable></arg>
+ <arg choice="plain"><replaceable>process_id</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">register</arg>
- <arg>-N <replaceable>servicename</replaceable></arg>
- <arg>-U <replaceable>username</replaceable></arg>
- <arg>-P <replaceable>password</replaceable></arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
- <arg>-S
+ <arg choice="plain"><option>register</option></arg>
+ <arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg>
+ <arg choice="opt"><option>-U</option> <replaceable>username</replaceable></arg>
+ <arg choice="opt"><option>-P</option> <replaceable>password</replaceable></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <arg choice="opt"><option>-S</option>
<group choice="plain">
- <arg>a[uto]</arg>
- <arg>d[emand]</arg>
+ <arg choice="plain"><option>a[uto]</option></arg>
+ <arg choice="plain"><option>d[emand]</option></arg>
</group>
</arg>
- <arg>-w</arg>
- <arg>-t <replaceable>seconds</replaceable></arg>
- <arg>-o <replaceable>options</replaceable></arg>
+ <arg choice="opt"><option>-w</option></arg>
+ <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
+ <arg choice="opt"><option>-s</option></arg>
+ <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>pg_ctl</command>
- <arg choice="plain">unregister</arg>
- <arg>-N <replaceable>servicename</replaceable></arg>
+ <arg choice="plain"><option>unregister</option></arg>
+ <arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<application>pg_ctl</application> is a utility for initializing a
<productname>PostgreSQL</productname> database cluster, starting,
stopping, or restarting the <productname>PostgreSQL</productname>
- backend server (<xref linkend="app-postgres">), or displaying the
+ database server (<xref linkend="app-postgres">), or displaying the
status of a running server. Although the server can be started
manually, <application>pg_ctl</application> encapsulates tasks such
as redirecting log output and properly detaching from the terminal
<para>
<option>restart</option> mode effectively executes a stop followed
by a start. This allows changing the <command>postgres</command>
- command-line options.
+ command-line options. <option>restart</option> might fail if
+ relative paths specified were specified on the command-line during
+ server start.
</para>
<para>
<option>status</option> mode checks whether a server is running in
the specified data directory. If it is, the <acronym>PID</acronym>
and the command line options that were used to invoke it are
- displayed.
+ displayed. If the server is not running, the process returns an
+ exit status of 3. If an accessible data directory is not specified,
+ the process returns an exit status of 4.
+ </para>
+
+ <para>
+ In <option>promote</option> mode, the standby server that is
+ running in the specified data directory is commanded to exit
+ recovery and begin read-write operations.
</para>
<para>
<varlistentry>
<term><option>-c</option></term>
+ <term><option>--core-file</option></term>
<listitem>
<para>
Attempt to allow server crashes to produce core files, on platforms
<varlistentry>
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata <replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
- Specifies the file system location of the database files. If
+ Specifies the file system location of the database configuration files. If
this is omitted, the environment variable
<envar>PGDATA</envar> is used.
</para>
<varlistentry>
<term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
+ <term><option>--log <replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
Append the server log output to
<varlistentry>
<term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
+ <term><option>--mode <replaceable class="parameter">mode</replaceable></option></term>
<listitem>
<para>
Specifies the shutdown mode. <replaceable>mode</replaceable>
<varlistentry>
<term><option>-s</option></term>
+ <term><option>--silent</option></term>
<listitem>
<para>
Print only errors, no informational messages.
<varlistentry>
<term><option>-t</option></term>
+ <term><option>--timeout</option></term>
<listitem>
<para>
The maximum number of seconds to wait when waiting for startup or
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-V</></term>
+ <term><option>--version</></term>
+ <listitem>
+ <para>
+ Print the <application>pg_ctl</application> version and exit.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-w</option></term>
<listitem>
attempts to connect to the server.
When waiting for shutdown, <command>pg_ctl</command> waits for
the server to remove its <acronym>PID</acronym> file.
+ This option allows the entry of an <acronym>SSL</> passphrase on startup.
<command>pg_ctl</command> returns an exit code based on the
success of the startup or shutdown.
</para>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>-?</></term>
+ <term><option>--help</></term>
+ <listitem>
+ <para>
+ Show help about <application>pg_ctl</application> command line
+ arguments, and exit.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
<refsect2 id="app-pg-ctl-windows-options">
<variablelist>
<varlistentry>
- <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
+ <term><option>-e <replaceable class="parameter">source</replaceable></option></term>
<listitem>
<para>
- Name of the system service to register. The name will be used
- as both the service name and the display name.
+ Name of the event source for <application>pg_ctl</application> to use
+ for logging to the event log when running as a Windows service. The
+ default is <literal>PostgreSQL</literal>. Note that this only controls
+ the logging from <application>pg_ctl</application> itself - once
+ started, the server will use the event source specified
+ by <xref linkend="guc-event-source">. Should the server fail during
+ early startup, it may also log using the default event
+ source <literal>PostgreSQL</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
+ <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
<listitem>
<para>
- User name for the user to start the service. For domain users, use the
- format <literal>DOMAIN\username</literal>.
+ Name of the system service to register. The name will be used
+ as both the service name and the display name.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
+ <listitem>
+ <para>
+ User name for the user to start the service. For domain users, use the
+ format <literal>DOMAIN\username</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect2>
<title>Starting the Server</title>
<para>
- To start up a server:
+ To start the server:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
</para>
<para>
- An example of starting the server, and waiting until the server is
- accepting connection:
+ To start the server, waiting until the server is
+ accepting connections:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
</para>
<para>
- For a server using port 5433, and
+ To start the server using port 5433, and
running without <function>fsync</function>, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
-</screen>
- </para>
+</screen></para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-4">
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
The <option>-m</option> option allows control over
- <emphasis>how</emphasis> the server shuts down.
- </para>
+ <emphasis>how</emphasis> the server shuts down:
+<screen>
+<prompt>$</prompt> <userinput>pg_ctl stop -m fast</userinput>
+</screen></para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-5">
</para>
<para>
- To restart using port 5433 and disable <function>fsync</> upon restart:
+ To restart using port 5433, disabling <function>fsync</> upon restart:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
-</screen>
- </para>
+</screen></para>
</refsect2>
<refsect2 id="R2-APP-PGCTL-6">