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