granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/pg_ctl-ref.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.9 2001/09/21 21:10:56 tgl Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="app-pg-ctl">
   7  <docinfo>
   8   <date>2001-02-08</date>
   9  </docinfo>
  10
  11  <refmeta>
  12   <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>pg_ctl</refname>
  19   <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>pg_ctl</command>
  25    <arg choice="plain">start</arg>
  26    <arg>-w</arg>
  27    <arg>-s</arg>
  28    <arg>-D <replaceable>datadir</replaceable></arg>
  29    <arg>-l <replaceable>filename</replaceable></arg>
  30    <arg>-o <replaceable>options</replaceable></arg>
  31    <arg>-p <replaceable>path</replaceable></arg>
  32    <sbr>
  33    <command>pg_ctl</command>
  34    <arg choice="plain">stop</arg>
  35    <arg>-W</arg>
  36    <arg>-s</arg>
  37    <arg>-D <replaceable>datadir</replaceable></arg>
  38    <arg>-m
  39      <group choice="plain">
  40        <arg>s[mart]</arg>
  41        <arg>f[ast]</arg>
  42        <arg>i[mmediate]</arg>
  43      </group>
  44    </arg>
  45    <sbr>
  46    <command>pg_ctl</command>
  47    <arg choice="plain">restart</arg>
  48    <arg>-w</arg>
  49    <arg>-s</arg>
  50    <arg>-D <replaceable>datadir</replaceable></arg>
  51    <arg>-m
  52      <group choice="plain">
  53        <arg>s[mart]</arg>
  54        <arg>f[ast]</arg>
  55        <arg>i[mmediate]</arg>
  56      </group>
  57    </arg>
  58    <arg>-o <replaceable>options</replaceable></arg>
  59    <sbr>
  60    <command>pg_ctl</command>
  61    <arg choice="plain">reload</arg>
  62    <arg>-s</arg>
  63    <arg>-D <replaceable>datadir</replaceable></arg>
  64    <sbr>
  65    <command>pg_ctl</command>
  66    <arg choice="plain">status</arg>
  67    <arg>-D <replaceable>datadir</replaceable></arg>
  68   </cmdsynopsis>
  69  </refsynopsisdiv>
  70
  71
  72  <refsect1 id="app-pg-ctl-description">
  73   <title>Description</title>
  74   <para>
  75    <application>pg_ctl</application> is a utility for starting,
  76    stopping, or restarting <xref linkend="app-postmaster">, the
  77    <productname>PostgreSQL</productname> backend server, or displaying
  78    the status of a running postmaster.  Although the postmaster can be
  79    started manually, <application>pg_ctl</application> encapulates
  80    tasks such as redirecting log output, properly detaching from the
  81    terminal and process group, and it provides convenient options for
  82    controlled shut down.
  83   </para>
  84
  85   <para>
  86    In <option>start</option> mode, a new postmaster is launched.  The
  87    server is started in the background, the standard input attached to
  88    <filename>/dev/null</filename>.  The standard output and standard
  89    error are either appended to a log file, if the <option>-l</option>
  90    option is used, or are redirected to
  91    <application>pg_ctl</application>'s standard output (not standard
  92    error).  If no log file is chosen, the standard output of
  93    <application>pg_ctl</application> should be redirected to a file or
  94    piped to another process, for example a log rotating program,
  95    otherwise the postmaster will write its output the the controlling
  96    terminal (from the background) and will not leave the shell's
  97    process group.
  98   </para>
  99
 100   <para>
 101    In <option>stop</option> mode, the postmaster that is running in
 102    the specified data directory is shut down.  Three different
 103    shutdown methods can be selected with the <option>-m</option>
 104    option: <quote>Smart</quote> mode waits for all the clients to
 105    disconnect.  This is the default.  <quote>Fast</quote> mode does
 106    not wait for clients to disconnect.  All active transactions will
 107    be rolled back.  <quote>Immediate</quote> mode will abort without
 108    complete shutdown.  This will lead to a recovery run on restart.
 109   </para>
 110
 111   <para>
 112    <option>restart</option> mode effectively executes a stop followed
 113    by a start.  This allows the changing of postmaster command line
 114    options.
 115   </para>
 116
 117   <para>
 118    <option>reload</option> mode simply sends the postmaster a SIGHUP signal,
 119    causing it to reread its configuration files
 120    (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
 121    etc).  This allows changing of configuration-file options that do not
 122    require a complete restart to take effect.
 123   </para>
 124
 125   <para>
 126    <option>status</option> mode checks whether a postmaster is running
 127    and if so displays the <acronym>PID</acronym> and the command line
 128    options that were used to invoke it.
 129   </para>
 130
 131   <refsect2 id="app-pg-ctl-options">
 132    <title>Options</title>
 133    <para>
 134
 135     <variablelist>
 136      <varlistentry>
 137       <term>-D <replaceable class="parameter">datadir</replaceable></term>
 138       <listitem>
 139        <para>
 140         Specifies the file system location of the database files.  If
 141         this is omitted, the environment variable
 142         <envar>PGDATA</envar> is used.
 143        </para>
 144       </listitem>
 145      </varlistentry>
 146
 147      <varlistentry>
 148       <term>-l <replaceable class="parameter">filename</replaceable></term>
 149       <listitem>
 150        <para>
 151         Append the server log output to
 152         <replaceable>filename</replaceable>.  If the file does not
 153         exist, it is created.  The umask is set to 077, so access to
 154         the log file from other users is disallowed by default.
 155        </para>
 156       </listitem>
 157      </varlistentry>
 158
 159      <varlistentry>
 160       <term>-m <replaceable class="parameter">mode</replaceable></term>
 161       <listitem>
 162        <para>
 163         Specifies the shutdown mode.  <replaceable>mode</replaceable>
 164         may be <literal>smart</literal>, <literal>fast</literal>, or
 165         <literal>immediate</literal>, or the first letter of one of
 166         these three.
 167        </para>
 168       </listitem>
 169      </varlistentry>
 170
 171      <varlistentry>
 172       <term>-o <replaceable class="parameter">options</replaceable></term>
 173       <listitem>
 174        <para>
 175         Specifies options to be passed directly to
 176         <application>postmaster</application>.
 177        </para>
 178        <para>
 179         The parameters are usually surrounded by single or double
 180         quotes to ensure that they are passed through as a group.
 181        </para>
 182       </listitem>
 183      </varlistentry>
 184
 185      <varlistentry>
 186       <term>-p <replaceable class="parameter">path</replaceable></term>
 187       <listitem>
 188        <para>
 189         Specifies the location of the <filename>postmaster</filename>
 190         executable.  By default the postmaster is taken from the same
 191         directory as pg_ctl, or failing that, the hard-wired
 192         installation directory.  It is not necessary to use this
 193         option unless you are doing something unusual and get errors
 194         that the postmaster was not found.
 195        </para>
 196       </listitem>
 197      </varlistentry>
 198
 199      <varlistentry>
 200       <term>-w</term>
 201       <listitem>
 202        <para>
 203         Wait for the start or shutdown to complete.  Times out after
 204         60 seconds.  This is the default for shutdowns.
 205        </para>
 206       </listitem>
 207      </varlistentry>
 208
 209      <varlistentry>
 210       <term>-W</term>
 211       <listitem>
 212        <para>
 213         Do not wait for start or shutdown to complete.  This is the
 214         default for starts and restarts.
 215        </para>
 216       </listitem>
 217      </varlistentry>
 218
 219      <varlistentry>
 220       <term>-s</term>
 221       <listitem>
 222        <para>
 223         Only print errors, no informational messages.
 224        </para>
 225       </listitem>
 226      </varlistentry>
 227     </variablelist>
 228    </para>
 229   </refsect2>
 230
 231   <refsect2>
 232    <title>Files</title>
 233
 234    <para>
 235     If the file <filename>postmaster.opts.default</filename> exists in
 236     the data directory, the contents of the file will be passed as
 237     options to the <application>postmaster</application>, unless
 238     overridden by the <option>-o</option> option.
 239    </para>
 240   </refsect2>
 241
 242  </refsect1>
 243
 244
 245  <refsect1 id="R1-APP-PGCTL-2">
 246   <title>Examples</title>
 247
 248   <refsect2 id="R2-APP-PGCTL-3">
 249    <title>Starting the postmaster</title>
 250
 251    <para>
 252     To start up <application>postmaster</application>:
 253 <screen>
 254 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 255 </screen>
 256    </para>
 257
 258    <para>
 259     An example of starting the <application>postmaster</application>,
 260     blocking until postmaster comes up is:
 261 <screen>
 262 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 263 </screen>
 264    </para>
 265
 266    <para>
 267     For a <application>postmaster</application> using port 5433, and
 268     running without <function>fsync</function>, use:
 269 <screen>
 270 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 271 </screen>
 272    </para>
 273   </refsect2>
 274
 275   <refsect2 id="R2-APP-PGCTL-4">
 276    <title>Stopping the postmaster</title>
 277    <para>
 278 <screen>
 279 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 280 </screen>
 281     stops postmaster. Using the <option>-m</option> switch allows one
 282     to control <emphasis>how</emphasis> the backend shuts down.
 283    </para>
 284   </refsect2>
 285
 286   <refsect2 id="R2-APP-PGCTL-5">
 287    <title>Restarting the postmaster</title>
 288
 289    <para>
 290     This is almost equivalent to stopping the
 291     <application>postmaster</application> then starting it again
 292     except that pg_ctl saves and reuses the command line options that
 293     were passed to the previously running instance.  To restart
 294     <application>postmaster</application> in the simplest form:
 295 <screen>
 296 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 297 </screen>
 298    </para>
 299
 300    <para>
 301     To restart <application>postmaster</application>,
 302     waiting for it to shut down and to come up:
 303 <screen>
 304 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 305 </screen>
 306    </para>
 307
 308    <para>
 309     To restart using port 5433 and disabling fsync after restarting:
 310 <screen>
 311 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 312 </screen>
 313    </para>
 314   </refsect2>
 315
 316   <refsect2 id="R2-APP-PGCTL-6">
 317    <title>Showing postmaster status</title>
 318
 319    <para>
 320     Here is a sample status output from
 321     <application>pg_ctl</application>:
 322 <screen>
 323 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 324 <computeroutput>
 325 pg_ctl: postmaster is running (pid: 13718)
 326 Command line was:
 327 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 328 </computeroutput>
 329 </screen>
 330     This is the command line that would be invoked in restart mode.
 331    </para>
 332   </refsect2>
 333  </refsect1>
 334
 335  <refsect1>
 336   <title>Bugs</title>
 337
 338   <para>
 339    Waiting for complete start is not a well-defined operation and may
 340    fail if access control is set up in way that a local client cannot
 341    connect without manual interaction.  It should be avoided.
 342   </para>
 343  </refsect1>
 344
 345  <refsect1>
 346   <title>See Also</title>
 347
 348   <para>
 349    <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
 350   </para>
 351  </refsect1>
 352
 353 </refentry>
 354
 355 <!-- Keep this comment at the end of the file
 356 Local variables:
 357 mode:sgml
 358 sgml-omittag:nil
 359 sgml-shorttag:t
 360 sgml-minimize-attributes:nil
 361 sgml-always-quote-attributes:t
 362 sgml-indent-step:1
 363 sgml-indent-data:t
 364 sgml-parent-document:nil
 365 sgml-default-dtd-file:"../reference.ced"
 366 sgml-exposed-tags:nil
 367 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 368 sgml-local-ecat-files:nil
 369 End:
 370 -->