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

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