-->
<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">reload</arg>
- <arg>-s</arg>
- <arg>-D <replaceable>datadir</replaceable></arg>
+ <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">status</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">kill</arg>
- <arg><replaceable>signal_name</replaceable></arg>
- <arg><replaceable>process_id</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">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>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"><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>
<para>
Wait for the startup or shutdown to complete.
Waiting is the default option for shutdowns, but not startups.
+ When waiting for startup, <command>pg_ctl</command> repeatedly
+ 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.
- When waiting for startup, <command>pg_ctl</command> repeatedly
- attempts to connect to the server via <application>psql</>, and
- reports success when this is successful.
- <command>pg_ctl</command> will attempt to use the proper port for
- <application>psql</>. If the environment variable
- <envar>PGPORT</envar> exists, that is used. Otherwise,
- <command>pg_ctl</command> will see if a port has been set in the
- <filename>postgresql.conf</filename> file. If not, it will use the
- default port that <productname>PostgreSQL</productname> was compiled
- with (5432 by default).
- When waiting, <command>pg_ctl</command> will
- return an exit code based on the success of the startup
- or shutdown.
+ 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>
</listitem>
</varlistentry>
</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>
</listitem>
</varlistentry>
- <varlistentry>
- <term><envar>PGHOST</envar></term>
-
- <listitem>
- <para>
- Default host name or Unix-domain socket location for <xref
- linkend="app-psql"> (used when waiting for startup).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><envar>PGPORT</envar></term>
-
- <listitem>
- <para>
- Default port number for <xref linkend="app-psql">
- (used when waiting for startup).
- </para>
- </listitem>
- </varlistentry>
-
</variablelist>
<para>
<para>
The existence of this file in the data directory is used to help
<application>pg_ctl</application> determine if the server is
- currently running or not.
+ currently running.
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
- <varlistentry>
- <term><filename>postgresql.conf</filename></term>
-
- <listitem>
- <para>
- This file, located in the data directory, is parsed to find the
- proper port to use with <application>psql</application>
- when waiting for startup.
- </para>
- </listitem>
- </varlistentry>
-
</variablelist>
</refsect1>
- <refsect1>
- <title>Notes</title>
-
- <para>
- Waiting for complete startup is not a well-defined operation and might
- fail if access control is set up so that a local client cannot
- connect without manual interaction (e.g., password authentication). For
- additional connection variables, see <xref linkend="libpq-envars">,
- and for passwords, also see <xref linkend="libpq-pgpass">.
- </para>
- </refsect1>
-
-
<refsect1 id="R1-APP-PGCTL-2">
<title>Examples</title>
<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, blocking until the server has
- come up is:
+ 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">
<title>Stopping the Server</title>
<para>
+ To stop the server, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
- stops the server. Using the <option>-m</option> switch allows one
- to control <emphasis>how</emphasis> the backend shuts down.
- </para>
+ The <option>-m</option> option allows control over
+ <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>
Restarting the server is almost equivalent to stopping the
- server and starting it again
+ server and starting it again,
except that <command>pg_ctl</command> saves and reuses the command line options that
were passed to the previously running instance. To restart
the server in the simplest form, use:
<para>
To restart the server,
- waiting for it to shut down and come up again:
+ waiting for it to shut down and restart:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
</screen>
</para>
<para>
- To restart using port 5433 and disabling <function>fsync</> after restarting:
+ 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">
<title>Showing the Server Status</title>
<para>
- Here is a sample status output from
+ Here is sample status output from
<application>pg_ctl</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
<computeroutput>
-pg_ctl: server is running (pid: 13718)
-Command line was:
-/usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
+pg_ctl: server is running (PID: 13718)
+/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
</computeroutput>
</screen>
This is the command line that would be invoked in restart mode.
projects / postgresql / blobdiff