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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.29 2004/11/27 21:56:05 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  <indexterm zone="app-pg-ctl">
  19   <primary>pg_ctl</primary>
  20  </indexterm>
  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    <sbr>
  69    <command>pg_ctl</command>
  70    <arg choice="plain">kill</arg>
  71    <arg><replaceable>signal_name</replaceable></arg>
  72    <arg><replaceable>process_id</replaceable></arg>
  73   </cmdsynopsis>
  74  </refsynopsisdiv>
  75
  76
  77  <refsect1 id="app-pg-ctl-description">
  78   <title>Description</title>
  79   <para>
  80    <application>pg_ctl</application> is a utility for starting,
  81    stopping, or restarting the <productname>PostgreSQL</productname>
  82    backend server (<xref linkend="app-postmaster">), or displaying the
  83    status of a running server.  Although the server can be started
  84    manually, <application>pg_ctl</application> encapsulates tasks such
  85    as redirecting log output and properly detaching from the terminal
  86    and process group. It also provides convenient options for
  87    controlled shutdown.
  88   </para>
  89
  90   <para>
  91    In <option>start</option> mode, a new server is launched.  The
  92    server is started in the background, and standard input is attached to
  93    <filename>/dev/null</filename>.  The standard output and standard
  94    error are either appended to a log file (if the <option>-l</option>
  95    option is used), or redirected to <application>pg_ctl</application>'s
  96    standard output (not standard error).  If no log file is chosen, the
  97    standard output of <application>pg_ctl</application> should be redirected
  98    to a file or piped to another process such as a log rotating program
  99    like <application>rotatelogs</>; otherwise the <command>postmaster</command>
 100    will write its output to the controlling terminal (from the background)
 101    and will not leave the shell's process group.
 102   </para>
 103
 104   <para>
 105    In <option>stop</option> mode, the server that is running in
 106    the specified data directory is shut down.  Three different
 107    shutdown methods can be selected with the <option>-m</option>
 108    option: <quote>Smart</quote> mode waits for all the clients to
 109    disconnect.  This is the default.  <quote>Fast</quote> mode does
 110    not wait for clients to disconnect.  All active transactions are
 111    rolled back and clients are forcibly disconnected, then the
 112    server is shut down.  <quote>Immediate</quote> mode will abort
 113    all server processes without a clean shutdown.  This will lead to
 114    a recovery run on restart.
 115   </para>
 116
 117   <para>
 118    <option>restart</option> mode effectively executes a stop followed
 119    by a start.  This allows changing the <command>postmaster</command>
 120    command-line options.
 121   </para>
 122
 123   <para>
 124    <option>reload</option> mode simply sends the
 125    <command>postmaster</command> process a <systemitem>SIGHUP</>
 126    signal, causing it to reread its configuration files
 127    (<filename>postgresql.conf</filename>,
 128    <filename>pg_hba.conf</filename>, etc.).  This allows changing of
 129    configuration-file options that do not require a complete restart
 130    to take effect.
 131   </para>
 132
 133   <para>
 134    <option>status</option> mode checks whether a server is running in
 135    the specified data directory. If it is, the <acronym>PID</acronym>
 136    and the command line options that were used to invoke it are
 137    displayed.
 138   </para>
 139
 140   <para>
 141    <option>kill</option> mode allows you to send a signal to a specified
 142     process.  This is particularly valuable for <productname>Microsoft Windows</>
 143     which does not have a <application>kill</> command.  Use
 144     <literal>--help</> to see a list of supported signal names.
 145   </para>
 146  </refsect1>
 147
 148  <refsect1 id="app-pg-ctl-options">
 149   <title>Options</title>
 150
 151   <para>
 152
 153     <variablelist>
 154      <varlistentry>
 155       <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
 156       <listitem>
 157        <para>
 158         Specifies the file system location of the database files.  If
 159         this is omitted, the environment variable
 160         <envar>PGDATA</envar> is used.
 161        </para>
 162       </listitem>
 163      </varlistentry>
 164
 165      <varlistentry>
 166       <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
 167       <listitem>
 168        <para>
 169         Append the server log output to
 170         <replaceable>filename</replaceable>.  If the file does not
 171         exist, it is created.  The <systemitem>umask</> is set to 077, so access to
 172         the log file from other users is disallowed by default.
 173        </para>
 174       </listitem>
 175      </varlistentry>
 176
 177      <varlistentry>
 178       <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
 179       <listitem>
 180        <para>
 181         Specifies the shutdown mode.  <replaceable>mode</replaceable>
 182         may be <literal>smart</literal>, <literal>fast</literal>, or
 183         <literal>immediate</literal>, or the first letter of one of
 184         these three.
 185        </para>
 186       </listitem>
 187      </varlistentry>
 188
 189      <varlistentry>
 190       <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
 191       <listitem>
 192        <para>
 193         Specifies options to be passed directly to the
 194         <command>postmaster</command> command.
 195        </para>
 196        <para>
 197         The options are usually surrounded by single or double
 198         quotes to ensure that they are passed through as a group.
 199        </para>
 200       </listitem>
 201      </varlistentry>
 202
 203      <varlistentry>
 204       <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
 205       <listitem>
 206        <para>
 207         Specifies the location of the <filename>postmaster</filename>
 208         executable.  By default the <filename>postmaster</filename> executable is taken from the same
 209         directory as <command>pg_ctl</command>, or failing that, the hard-wired
 210         installation directory.  It is not necessary to use this
 211         option unless you are doing something unusual and get errors
 212         that the <filename>postmaster</filename> executable was not found.
 213        </para>
 214       </listitem>
 215      </varlistentry>
 216
 217      <varlistentry>
 218       <term><option>-s</option></term>
 219       <listitem>
 220        <para>
 221         Only print errors, no informational messages.
 222        </para>
 223       </listitem>
 224      </varlistentry>
 225
 226      <varlistentry>
 227       <term><option>-w</option></term>
 228       <listitem>
 229        <para>
 230         Wait for the start or shutdown to complete.  Times out after
 231         60 seconds.  This is the default for shutdowns. A successful
 232         shutdown is indicated by removal of the <acronym>PID</acronym>
 233         file. For starting up, a successful <command>psql -l</command>
 234         indicates success. <command>pg_ctl</command> will attempt to
 235         use the proper port for <application>psql</>. If the environment variable
 236         <envar>PGPORT</envar> exists, that is used. Otherwise, it will see if a port
 237         has been set in the <filename>postgresql.conf</filename> file.
 238         If neither of those is used, it will use the default port that
 239         <productname>PostgreSQL</productname> was compiled with
 240         (5432 by default).
 241        </para>
 242       </listitem>
 243      </varlistentry>
 244
 245      <varlistentry>
 246       <term><option>-W</option></term>
 247       <listitem>
 248        <para>
 249         Do not wait for start or shutdown to complete.  This is the
 250         default for starts and restarts.
 251        </para>
 252       </listitem>
 253      </varlistentry>
 254     </variablelist>
 255    </para>
 256  </refsect1>
 257
 258
 259  <refsect1>
 260   <title>Environment</title>
 261
 262   <variablelist>
 263    <varlistentry>
 264     <term><envar>PGDATA</envar></term>
 265
 266     <listitem>
 267      <para>
 268       Default data directory location.
 269      </para>
 270     </listitem>
 271    </varlistentry>
 272
 273    <varlistentry>
 274     <term><envar>PGPORT</envar></term>
 275
 276     <listitem>
 277      <para>
 278       Default port for <xref linkend="app-psql"> (used by the -w option).
 279      </para>
 280     </listitem>
 281    </varlistentry>
 282   </variablelist>
 283
 284   <para>
 285    For others, see <xref linkend="app-postmaster">.
 286   </para>
 287  </refsect1>
 288
 289
 290  <refsect1>
 291   <title>Files</title>
 292
 293   <variablelist>
 294    <varlistentry>
 295     <term><filename>postmaster.pid</filename></term>
 296
 297     <listitem>
 298      <para>
 299       The existence of this file in the data directory is used to help
 300       <application>pg_ctl</application> determine if the server is
 301       currently running or not.
 302      </para>
 303     </listitem>
 304    </varlistentry>
 305
 306    <varlistentry>
 307     <term><filename>postmaster.opts.default</filename></term>
 308
 309     <listitem>
 310      <para>
 311       If this file exists in the data directory,
 312       <application>pg_ctl</application> (in <option>start</option>
 313       mode) will pass the contents of the file as options to the
 314       <command>postmaster</command> command, unless overridden by the
 315       <option>-o</option> option.
 316      </para>
 317     </listitem>
 318    </varlistentry>
 319
 320    <varlistentry>
 321     <term><filename>postmaster.opts</filename></term>
 322
 323     <listitem>
 324      <para>If this file exists in the data directory,
 325       <application>pg_ctl</application> (in <option>restart</option> mode)
 326       will pass the contents of the file as options to the
 327       <application>postmaster</application>, unless overridden
 328       by the <option>-o</option> option. The contents of this file
 329       are also displayed in <option>status</option> mode.
 330      </para>
 331     </listitem>
 332    </varlistentry>
 333
 334    <varlistentry>
 335     <term><filename>postgresql.conf</filename></term>
 336
 337     <listitem>
 338      <para>
 339       This file, located in the data directory, is parsed to find the
 340       proper port to use with <application>psql</application> when the
 341       <option>-w</option> is given in <option>start</option> mode.
 342      </para>
 343     </listitem>
 344    </varlistentry>
 345
 346   </variablelist>
 347  </refsect1>
 348
 349
 350  <refsect1>
 351   <title>Notes</title>
 352
 353   <para>
 354    Waiting for complete start is not a well-defined operation and may
 355    fail if access control is set up so that a local client cannot
 356    connect without manual interaction (e.g., password authentication).
 357   </para>
 358  </refsect1>
 359
 360
 361  <refsect1 id="R1-APP-PGCTL-2">
 362   <title>Examples</title>
 363
 364   <refsect2 id="R2-APP-PGCTL-3">
 365    <title>Starting the Server</title>
 366
 367    <para>
 368     To start up a server:
 369 <screen>
 370 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 371 </screen>
 372    </para>
 373
 374    <para>
 375     An example of starting the server, blocking until the server has
 376     come up is:
 377 <screen>
 378 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 379 </screen>
 380    </para>
 381
 382    <para>
 383     For a server using port 5433, and
 384     running without <function>fsync</function>, use:
 385 <screen>
 386 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 387 </screen>
 388    </para>
 389   </refsect2>
 390
 391   <refsect2 id="R2-APP-PGCTL-4">
 392    <title>Stopping the Server</title>
 393    <para>
 394 <screen>
 395 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 396 </screen>
 397     stops the server. Using the <option>-m</option> switch allows one
 398     to control <emphasis>how</emphasis> the backend shuts down.
 399    </para>
 400   </refsect2>
 401
 402   <refsect2 id="R2-APP-PGCTL-5">
 403    <title>Restarting the Server</title>
 404
 405    <para>
 406     Restarting the server is almost equivalent to stopping the
 407     server and starting it again
 408     except that <command>pg_ctl</command> saves and reuses the command line options that
 409     were passed to the previously running instance.  To restart
 410     the server in the simplest form, use:
 411 <screen>
 412 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 413 </screen>
 414    </para>
 415
 416    <para>
 417     To restart server,
 418     waiting for it to shut down and to come up:
 419 <screen>
 420 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 421 </screen>
 422    </para>
 423
 424    <para>
 425     To restart using port 5433 and disabling <function>fsync</> after restarting:
 426 <screen>
 427 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 428 </screen>
 429    </para>
 430   </refsect2>
 431
 432   <refsect2 id="R2-APP-PGCTL-6">
 433    <title>Showing the Server Status</title>
 434
 435    <para>
 436     Here is a sample status output from
 437     <application>pg_ctl</application>:
 438 <screen>
 439 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 440 <computeroutput>
 441 pg_ctl: postmaster is running (pid: 13718)
 442 Command line was:
 443 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 444 </computeroutput>
 445 </screen>
 446     This is the command line that would be invoked in restart mode.
 447    </para>
 448   </refsect2>
 449  </refsect1>
 450
 451
 452  <refsect1>
 453   <title>See Also</title>
 454
 455   <para>
 456    <xref linkend="app-postmaster">
 457   </para>
 458  </refsect1>
 459
 460 </refentry>
 461
 462 <!-- Keep this comment at the end of the file
 463 Local variables:
 464 mode:sgml
 465 sgml-omittag:nil
 466 sgml-shorttag:t
 467 sgml-minimize-attributes:nil
 468 sgml-always-quote-attributes:t
 469 sgml-indent-step:1
 470 sgml-indent-data:t
 471 sgml-parent-document:nil
 472 sgml-default-dtd-file:"../reference.ced"
 473 sgml-exposed-tags:nil
 474 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 475 sgml-local-ecat-files:nil
 476 End:
 477 -->