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.  The default is 60 seconds.
 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 but can be overridden with the option <option>-t</option>.
 328         To wait is the default option for shutdowns. A successful
 329         shutdown is indicated by removal of the <acronym>PID</acronym>
 330         file. For starting up, a successful <command>psql -l</command>
 331         indicates success. <command>pg_ctl</command> will attempt to
 332         use the proper port for <application>psql</>. If the environment variable
 333         <envar>PGPORT</envar> exists, that is used. Otherwise, it will see if a port
 334         has been set in the <filename>postgresql.conf</filename> file.
 335         If neither of those is used, it will use the default port that
 336         <productname>PostgreSQL</productname> was compiled with
 337         (5432 by default). When waiting, <command>pg_ctl</command> will
 338         return an accurate exit code based on the success of the startup
 339         or shutdown.
 340        </para>
 341       </listitem>
 342      </varlistentry>
 343
 344      <varlistentry>
 345       <term><option>-W</option></term>
 346       <listitem>
 347        <para>
 348         Do not wait for start or shutdown to complete.  This is the
 349         default for starts and restarts.
 350        </para>
 351       </listitem>
 352      </varlistentry>
 353    </variablelist>
 354
 355   <refsect2 id="app-pg-ctl-windows-options">
 356    <title>Options for Windows</title>
 357
 358    <variablelist>
 359     <varlistentry>
 360      <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
 361      <listitem>
 362       <para>
 363        Name of the system service to register. The name will be used
 364        as both the service name and the display name.
 365       </para>
 366      </listitem>
 367     </varlistentry>
 368
 369     <varlistentry>
 370      <term><option>-P <replaceable class="parameter">password</replaceable></option></term>
 371      <listitem>
 372       <para>
 373        Password for the user to start the service.
 374       </para>
 375      </listitem>
 376     </varlistentry>
 377
 378     <varlistentry>
 379      <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
 380      <listitem>
 381       <para>
 382        User name for the user to start the service. For domain users, use the
 383        format <literal>DOMAIN\username</literal>.
 384       </para>
 385      </listitem>
 386     </varlistentry>
 387    </variablelist>
 388   </refsect2>
 389
 390  </refsect1>
 391
 392
 393  <refsect1>
 394   <title>Environment</title>
 395
 396   <variablelist>
 397    <varlistentry>
 398     <term><envar>PGDATA</envar></term>
 399
 400     <listitem>
 401      <para>
 402       Default data directory location.
 403      </para>
 404     </listitem>
 405    </varlistentry>
 406
 407    <varlistentry>
 408     <term><envar>PGHOST</envar></term>
 409
 410     <listitem>
 411      <para>
 412       Default host name or Unix-domain socket location for <xref
 413       linkend="app-psql"> (used by the <option>-w</option> option).
 414      </para>
 415     </listitem>
 416    </varlistentry>
 417
 418    <varlistentry>
 419     <term><envar>PGPORT</envar></term>
 420
 421     <listitem>
 422      <para>
 423       Default port number for <xref linkend="app-psql"> (used by the <option>-w</option> option).
 424      </para>
 425     </listitem>
 426    </varlistentry>
 427
 428   </variablelist>
 429
 430   <para>
 431    For additional server variables, see <xref linkend="app-postgres">.
 432    This utility, like most other <productname>PostgreSQL</> utilities,
 433    also uses the environment variables supported by <application>libpq</>
 434    (see <xref linkend="libpq-envars">).
 435   </para>
 436  </refsect1>
 437
 438
 439  <refsect1>
 440   <title>Files</title>
 441
 442   <variablelist>
 443    <varlistentry>
 444     <term><filename>postmaster.pid</filename></term>
 445
 446     <listitem>
 447      <para>
 448       The existence of this file in the data directory is used to help
 449       <application>pg_ctl</application> determine if the server is
 450       currently running or not.
 451      </para>
 452     </listitem>
 453    </varlistentry>
 454
 455    <varlistentry>
 456     <term><filename>postmaster.opts</filename></term>
 457
 458     <listitem>
 459      <para>If this file exists in the data directory,
 460       <application>pg_ctl</application> (in <option>restart</option> mode)
 461       will pass the contents of the file as options to
 462       <application>postgres</application>, unless overridden
 463       by the <option>-o</option> option. The contents of this file
 464       are also displayed in <option>status</option> mode.
 465      </para>
 466     </listitem>
 467    </varlistentry>
 468
 469    <varlistentry>
 470     <term><filename>postgresql.conf</filename></term>
 471
 472     <listitem>
 473      <para>
 474       This file, located in the data directory, is parsed to find the
 475       proper port to use with <application>psql</application> when the
 476       <option>-w</option> is given in <option>start</option> mode.
 477      </para>
 478     </listitem>
 479    </varlistentry>
 480
 481   </variablelist>
 482  </refsect1>
 483
 484
 485  <refsect1>
 486   <title>Notes</title>
 487
 488   <para>
 489    Waiting for complete start is not a well-defined operation and might
 490    fail if access control is set up so that a local client cannot
 491    connect without manual interaction (e.g., password authentication).  For
 492    additional connection variables, see <xref linkend="libpq-envars">,
 493    and for passwords, also see <xref linkend="libpq-pgpass">.
 494   </para>
 495  </refsect1>
 496
 497
 498  <refsect1 id="R1-APP-PGCTL-2">
 499   <title>Examples</title>
 500
 501   <refsect2 id="R2-APP-PGCTL-3">
 502    <title>Starting the Server</title>
 503
 504    <para>
 505     To start up a server:
 506 <screen>
 507 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 508 </screen>
 509    </para>
 510
 511    <para>
 512     An example of starting the server, blocking until the server has
 513     come up is:
 514 <screen>
 515 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 516 </screen>
 517    </para>
 518
 519    <para>
 520     For a server using port 5433, and
 521     running without <function>fsync</function>, use:
 522 <screen>
 523 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 524 </screen>
 525    </para>
 526   </refsect2>
 527
 528   <refsect2 id="R2-APP-PGCTL-4">
 529    <title>Stopping the Server</title>
 530    <para>
 531 <screen>
 532 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 533 </screen>
 534     stops the server. Using the <option>-m</option> switch allows one
 535     to control <emphasis>how</emphasis> the backend shuts down.
 536    </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 server,
 555     waiting for it to shut down and to come up:
 556 <screen>
 557 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 558 </screen>
 559    </para>
 560
 561    <para>
 562     To restart using port 5433 and disabling <function>fsync</> after restarting:
 563 <screen>
 564 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 565 </screen>
 566    </para>
 567   </refsect2>
 568
 569   <refsect2 id="R2-APP-PGCTL-6">
 570    <title>Showing the Server Status</title>
 571
 572    <para>
 573     Here is a sample status output from
 574     <application>pg_ctl</application>:
 575 <screen>
 576 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 577 <computeroutput>
 578 pg_ctl: server is running (pid: 13718)
 579 Command line was:
 580 /usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 581 </computeroutput>
 582 </screen>
 583     This is the command line that would be invoked in restart mode.
 584    </para>
 585   </refsect2>
 586  </refsect1>
 587
 588
 589  <refsect1>
 590   <title>See Also</title>
 591
 592   <simplelist type="inline">
 593    <member><xref linkend="app-initdb"></member>
 594    <member><xref linkend="app-postgres"></member>
 595   </simplelist>
 596  </refsect1>
 597
 598 </refentry>