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.35 2006/12/02 00:34:52 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     <variablelist>
 176      <varlistentry>
 177       <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
 178       <listitem>
 179        <para>
 180         Specifies the file system location of the database files.  If
 181         this is omitted, the environment variable
 182         <envar>PGDATA</envar> is used.
 183        </para>
 184       </listitem>
 185      </varlistentry>
 186
 187      <varlistentry>
 188       <term><option>-l <replaceable class="parameter">filename</replaceable></option></term>
 189       <listitem>
 190        <para>
 191         Append the server log output to
 192         <replaceable>filename</replaceable>.  If the file does not
 193         exist, it is created.  The <systemitem>umask</> is set to 077, so access to
 194         the log file from other users is disallowed by default.
 195        </para>
 196       </listitem>
 197      </varlistentry>
 198
 199      <varlistentry>
 200       <term><option>-m <replaceable class="parameter">mode</replaceable></option></term>
 201       <listitem>
 202        <para>
 203         Specifies the shutdown mode.  <replaceable>mode</replaceable>
 204         may be <literal>smart</literal>, <literal>fast</literal>, or
 205         <literal>immediate</literal>, or the first letter of one of
 206         these three.
 207        </para>
 208       </listitem>
 209      </varlistentry>
 210
 211      <varlistentry>
 212       <term><option>-o <replaceable class="parameter">options</replaceable></option></term>
 213       <listitem>
 214        <para>
 215         Specifies options to be passed directly to the
 216         <command>postgres</command> command.
 217        </para>
 218        <para>
 219         The options are usually surrounded by single or double
 220         quotes to ensure that they are passed through as a group.
 221        </para>
 222       </listitem>
 223      </varlistentry>
 224
 225      <varlistentry>
 226       <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
 227       <listitem>
 228        <para>
 229         Specifies the location of the <filename>postgres</filename>
 230         executable.  By default the <filename>postgres</filename> executable is taken from the same
 231         directory as <command>pg_ctl</command>, or failing that, the hard-wired
 232         installation directory.  It is not necessary to use this
 233         option unless you are doing something unusual and get errors
 234         that the <filename>postgres</filename> executable was not found.
 235        </para>
 236       </listitem>
 237      </varlistentry>
 238
 239      <varlistentry>
 240       <term><option>-s</option></term>
 241       <listitem>
 242        <para>
 243         Only print errors, no informational messages.
 244        </para>
 245       </listitem>
 246      </varlistentry>
 247
 248      <varlistentry>
 249       <term><option>-w</option></term>
 250       <listitem>
 251        <para>
 252         Wait for the start or shutdown to complete.  Times out after
 253         60 seconds.  This is the default for shutdowns. A successful
 254         shutdown is indicated by removal of the <acronym>PID</acronym>
 255         file. For starting up, a successful <command>psql -l</command>
 256         indicates success. <command>pg_ctl</command> will attempt to
 257         use the proper port for <application>psql</>. If the environment variable
 258         <envar>PGPORT</envar> exists, that is used. Otherwise, it will see if a port
 259         has been set in the <filename>postgresql.conf</filename> file.
 260         If neither of those is used, it will use the default port that
 261         <productname>PostgreSQL</productname> was compiled with
 262         (5432 by default). When waiting, <command>pg_ctl</command> will
 263         return an accurate exit code based on the success of the startup
 264         or shutdown.
 265        </para>
 266       </listitem>
 267      </varlistentry>
 268
 269      <varlistentry>
 270       <term><option>-W</option></term>
 271       <listitem>
 272        <para>
 273         Do not wait for start or shutdown to complete.  This is the
 274         default for starts and restarts.
 275        </para>
 276       </listitem>
 277      </varlistentry>
 278    </variablelist>
 279
 280   <refsect2 id="app-pg-ctl-windows-options">
 281    <title>Options for Windows</title>
 282
 283    <variablelist>
 284     <varlistentry>
 285      <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
 286      <listitem>
 287       <para>
 288        Name of the system service to register. The name will be used
 289        as both the service name and the display name.
 290       </para>
 291      </listitem>
 292     </varlistentry>
 293
 294     <varlistentry>
 295      <term><option>-P <replaceable class="parameter">password</replaceable></option></term>
 296      <listitem>
 297       <para>
 298        Password for the user to start the service.
 299       </para>
 300      </listitem>
 301     </varlistentry>
 302
 303     <varlistentry>
 304      <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
 305      <listitem>
 306       <para>
 307        User name for the user to start the service. For domain users, use the
 308        format <literal>DOMAIN\username</literal>.
 309       </para>
 310      </listitem>
 311     </varlistentry>
 312    </variablelist>
 313   </refsect2>
 314
 315  </refsect1>
 316
 317
 318  <refsect1>
 319   <title>Environment</title>
 320
 321   <variablelist>
 322    <varlistentry>
 323     <term><envar>PGDATA</envar></term>
 324
 325     <listitem>
 326      <para>
 327       Default data directory location.
 328      </para>
 329     </listitem>
 330    </varlistentry>
 331
 332    <varlistentry>
 333     <term><envar>PGPORT</envar></term>
 334
 335     <listitem>
 336      <para>
 337       Default port for <xref linkend="app-psql"> (used by the -w option).
 338      </para>
 339     </listitem>
 340    </varlistentry>
 341   </variablelist>
 342
 343   <para>
 344    For others, see <xref linkend="app-postgres">.
 345   </para>
 346  </refsect1>
 347
 348
 349  <refsect1>
 350   <title>Files</title>
 351
 352   <variablelist>
 353    <varlistentry>
 354     <term><filename>postmaster.pid</filename></term>
 355
 356     <listitem>
 357      <para>
 358       The existence of this file in the data directory is used to help
 359       <application>pg_ctl</application> determine if the server is
 360       currently running or not.
 361      </para>
 362     </listitem>
 363    </varlistentry>
 364
 365    <varlistentry>
 366     <term><filename>postmaster.opts.default</filename></term>
 367
 368     <listitem>
 369      <para>
 370       If this file exists in the data directory,
 371       <application>pg_ctl</application> (in <option>start</option>
 372       mode) will pass the contents of the file as options to the
 373       <command>postgres</command> command, unless overridden by the
 374       <option>-o</option> option.
 375      </para>
 376     </listitem>
 377    </varlistentry>
 378
 379    <varlistentry>
 380     <term><filename>postmaster.opts</filename></term>
 381
 382     <listitem>
 383      <para>If this file exists in the data directory,
 384       <application>pg_ctl</application> (in <option>restart</option> mode)
 385       will pass the contents of the file as options to
 386       <application>postgres</application>, unless overridden
 387       by the <option>-o</option> option. The contents of this file
 388       are also displayed in <option>status</option> mode.
 389      </para>
 390     </listitem>
 391    </varlistentry>
 392
 393    <varlistentry>
 394     <term><filename>postgresql.conf</filename></term>
 395
 396     <listitem>
 397      <para>
 398       This file, located in the data directory, is parsed to find the
 399       proper port to use with <application>psql</application> when the
 400       <option>-w</option> is given in <option>start</option> mode.
 401      </para>
 402     </listitem>
 403    </varlistentry>
 404
 405   </variablelist>
 406  </refsect1>
 407
 408
 409  <refsect1>
 410   <title>Notes</title>
 411
 412   <para>
 413    Waiting for complete start is not a well-defined operation and may
 414    fail if access control is set up so that a local client cannot
 415    connect without manual interaction (e.g., password authentication).
 416   </para>
 417  </refsect1>
 418
 419
 420  <refsect1 id="R1-APP-PGCTL-2">
 421   <title>Examples</title>
 422
 423   <refsect2 id="R2-APP-PGCTL-3">
 424    <title>Starting the Server</title>
 425
 426    <para>
 427     To start up a server:
 428 <screen>
 429 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 430 </screen>
 431    </para>
 432
 433    <para>
 434     An example of starting the server, blocking until the server has
 435     come up is:
 436 <screen>
 437 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 438 </screen>
 439    </para>
 440
 441    <para>
 442     For a server using port 5433, and
 443     running without <function>fsync</function>, use:
 444 <screen>
 445 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 446 </screen>
 447    </para>
 448   </refsect2>
 449
 450   <refsect2 id="R2-APP-PGCTL-4">
 451    <title>Stopping the Server</title>
 452    <para>
 453 <screen>
 454 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 455 </screen>
 456     stops the server. Using the <option>-m</option> switch allows one
 457     to control <emphasis>how</emphasis> the backend shuts down.
 458    </para>
 459   </refsect2>
 460
 461   <refsect2 id="R2-APP-PGCTL-5">
 462    <title>Restarting the Server</title>
 463
 464    <para>
 465     Restarting the server is almost equivalent to stopping the
 466     server and starting it again
 467     except that <command>pg_ctl</command> saves and reuses the command line options that
 468     were passed to the previously running instance.  To restart
 469     the server in the simplest form, use:
 470 <screen>
 471 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 472 </screen>
 473    </para>
 474
 475    <para>
 476     To restart server,
 477     waiting for it to shut down and to come up:
 478 <screen>
 479 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 480 </screen>
 481    </para>
 482
 483    <para>
 484     To restart using port 5433 and disabling <function>fsync</> after restarting:
 485 <screen>
 486 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 487 </screen>
 488    </para>
 489   </refsect2>
 490
 491   <refsect2 id="R2-APP-PGCTL-6">
 492    <title>Showing the Server Status</title>
 493
 494    <para>
 495     Here is a sample status output from
 496     <application>pg_ctl</application>:
 497 <screen>
 498 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 499 <computeroutput>
 500 pg_ctl: server is running (pid: 13718)
 501 Command line was:
 502 /usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 503 </computeroutput>
 504 </screen>
 505     This is the command line that would be invoked in restart mode.
 506    </para>
 507   </refsect2>
 508  </refsect1>
 509
 510
 511  <refsect1>
 512   <title>See Also</title>
 513
 514   <para>
 515    <xref linkend="app-postgres">
 516   </para>
 517  </refsect1>
 518
 519 </refentry>