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