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