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