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