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.12 2001/12/08 03:24:37 thomas Exp $
   3 PostgreSQL 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 shutdown.
  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 are
 107    rolled back and clients are forcibly disconnected, then the
 108    database is shut down.  <quote>Immediate</quote> mode will abort
 109    all server processes without clean shutdown.  This will lead to a recovery
 110    run on restart.
 111   </para>
 112
 113   <para>
 114    <option>restart</option> mode effectively executes a stop followed
 115    by a start.  This allows the changing of postmaster command line
 116    options.
 117   </para>
 118
 119   <para>
 120    <option>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
 121    causing it to reread its configuration files
 122    (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
 123    etc.).  This allows changing of configuration-file options that do not
 124    require a complete restart to take effect.
 125   </para>
 126
 127   <para>
 128    <option>status</option> mode checks whether a postmaster is running
 129    and if so displays the <acronym>PID</acronym> and the command line
 130    options that were used to invoke it.
 131   </para>
 132
 133   <refsect2 id="app-pg-ctl-options">
 134    <title>Options</title>
 135    <para>
 136
 137     <variablelist>
 138      <varlistentry>
 139       <term>-D <replaceable class="parameter">datadir</replaceable></term>
 140       <listitem>
 141        <para>
 142         Specifies the file system location of the database files.  If
 143         this is omitted, the environment variable
 144         <envar>PGDATA</envar> is used.
 145        </para>
 146       </listitem>
 147      </varlistentry>
 148
 149      <varlistentry>
 150       <term>-l <replaceable class="parameter">filename</replaceable></term>
 151       <listitem>
 152        <para>
 153         Append the server log output to
 154         <replaceable>filename</replaceable>.  If the file does not
 155         exist, it is created.  The umask is set to 077, so access to
 156         the log file from other users is disallowed by default.
 157        </para>
 158       </listitem>
 159      </varlistentry>
 160
 161      <varlistentry>
 162       <term>-m <replaceable class="parameter">mode</replaceable></term>
 163       <listitem>
 164        <para>
 165         Specifies the shutdown mode.  <replaceable>mode</replaceable>
 166         may be <literal>smart</literal>, <literal>fast</literal>, or
 167         <literal>immediate</literal>, or the first letter of one of
 168         these three.
 169        </para>
 170       </listitem>
 171      </varlistentry>
 172
 173      <varlistentry>
 174       <term>-o <replaceable class="parameter">options</replaceable></term>
 175       <listitem>
 176        <para>
 177         Specifies options to be passed directly to
 178         <application>postmaster</application>.
 179        </para>
 180        <para>
 181         The parameters are usually surrounded by single or double
 182         quotes to ensure that they are passed through as a group.
 183        </para>
 184       </listitem>
 185      </varlistentry>
 186
 187      <varlistentry>
 188       <term>-p <replaceable class="parameter">path</replaceable></term>
 189       <listitem>
 190        <para>
 191         Specifies the location of the <filename>postmaster</filename>
 192         executable.  By default the postmaster is taken from the same
 193         directory as pg_ctl, or failing that, the hard-wired
 194         installation directory.  It is not necessary to use this
 195         option unless you are doing something unusual and get errors
 196         that the postmaster was not found.
 197        </para>
 198       </listitem>
 199      </varlistentry>
 200
 201      <varlistentry>
 202       <term>-s</term>
 203       <listitem>
 204        <para>
 205         Only print errors, no informational messages.
 206        </para>
 207       </listitem>
 208      </varlistentry>
 209
 210      <varlistentry>
 211       <term>-w</term>
 212       <listitem>
 213        <para>
 214         Wait for the start or shutdown to complete.  Times out after
 215         60 seconds.  This is the default for shutdowns.
 216        </para>
 217       </listitem>
 218      </varlistentry>
 219
 220      <varlistentry>
 221       <term>-W</term>
 222       <listitem>
 223        <para>
 224         Do not wait for start or shutdown to complete.  This is the
 225         default for starts and restarts.
 226        </para>
 227       </listitem>
 228      </varlistentry>
 229     </variablelist>
 230    </para>
 231   </refsect2>
 232
 233   <refsect2>
 234    <title>Files</title>
 235
 236    <para>
 237     If the file <filename>postmaster.opts.default</filename> exists in
 238     the data directory, the contents of the file will be passed as
 239     options to the <application>postmaster</application>, unless
 240     overridden by the <option>-o</option> option.
 241    </para>
 242   </refsect2>
 243
 244  </refsect1>
 245
 246
 247  <refsect1 id="R1-APP-PGCTL-2">
 248   <title>Examples</title>
 249
 250   <refsect2 id="R2-APP-PGCTL-3">
 251    <title>Starting the postmaster</title>
 252
 253    <para>
 254     To start up a <application>postmaster</application>:
 255 <screen>
 256 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 257 </screen>
 258    </para>
 259
 260    <para>
 261     An example of starting the <application>postmaster</application>,
 262     blocking until the postmaster comes up is:
 263 <screen>
 264 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 265 </screen>
 266    </para>
 267
 268    <para>
 269     For a <application>postmaster</application> using port 5433, and
 270     running without <function>fsync</function>, use:
 271 <screen>
 272 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 273 </screen>
 274    </para>
 275   </refsect2>
 276
 277   <refsect2 id="R2-APP-PGCTL-4">
 278    <title>Stopping the postmaster</title>
 279    <para>
 280 <screen>
 281 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 282 </screen>
 283     stops the postmaster. Using the <option>-m</option> switch allows one
 284     to control <emphasis>how</emphasis> the backend shuts down.
 285    </para>
 286   </refsect2>
 287
 288   <refsect2 id="R2-APP-PGCTL-5">
 289    <title>Restarting the postmaster</title>
 290
 291    <para>
 292     This is almost equivalent to stopping the
 293     <application>postmaster</application> and starting it again
 294     except that pg_ctl saves and reuses the command line options that
 295     were passed to the previously running instance.  To restart
 296     the <application>postmaster</application> in the simplest form:
 297 <screen>
 298 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 299 </screen>
 300    </para>
 301
 302    <para>
 303     To restart <application>postmaster</application>,
 304     waiting for it to shut down and to come up:
 305 <screen>
 306 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 307 </screen>
 308    </para>
 309
 310    <para>
 311     To restart using port 5433 and disabling fsync after restarting:
 312 <screen>
 313 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 314 </screen>
 315    </para>
 316   </refsect2>
 317
 318   <refsect2 id="R2-APP-PGCTL-6">
 319    <title>Showing postmaster status</title>
 320
 321    <para>
 322     Here is a sample status output from
 323     <application>pg_ctl</application>:
 324 <screen>
 325 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 326 <computeroutput>
 327 pg_ctl: postmaster is running (pid: 13718)
 328 Command line was:
 329 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 330 </computeroutput>
 331 </screen>
 332     This is the command line that would be invoked in restart mode.
 333    </para>
 334   </refsect2>
 335  </refsect1>
 336
 337  <refsect1>
 338   <title>Bugs</title>
 339
 340   <para>
 341    Waiting for complete start is not a well-defined operation and may
 342    fail if access control is set up so that a local client cannot
 343    connect without manual interaction.  It should be avoided.
 344   </para>
 345  </refsect1>
 346
 347  <refsect1>
 348   <title>See Also</title>
 349
 350   <para>
 351    <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
 352   </para>
 353  </refsect1>
 354
 355 </refentry>
 356
 357 <!-- Keep this comment at the end of the file
 358 Local variables:
 359 mode:sgml
 360 sgml-omittag:nil
 361 sgml-shorttag:t
 362 sgml-minimize-attributes:nil
 363 sgml-always-quote-attributes:t
 364 sgml-indent-step:1
 365 sgml-indent-data:t
 366 sgml-parent-document:nil
 367 sgml-default-dtd-file:"../reference.ced"
 368 sgml-exposed-tags:nil
 369 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 370 sgml-local-ecat-files:nil
 371 End:
 372 -->