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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.6 2001/02/08 19:39:24 petere Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="app-pg-ctl">
   7  <docinfo>
   8   <date>2001-02-08</date>
   9  </docinfo>
  10
  11  <refmeta>
  12   <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>pg_ctl</refname>
  19   <refpurpose>Starts, stops, or restarts postmaster</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>pg_ctl</command>
  25    <arg choice="plain">start</arg>
  26    <arg>-w</arg>
  27    <arg>-D <replaceable>datadir</replaceable></arg>
  28    <arg>-l <replaceable>filename</replaceable></arg>
  29    <arg>-o <replaceable>options</replaceable></arg>
  30    <arg>-p <replaceable>path</replaceable></arg>
  31    <sbr>
  32    <command>pg_ctl</command>
  33    <arg choice="plain">stop</arg>
  34    <arg>-W</arg>
  35    <arg>-D <replaceable>datadir</replaceable></arg>
  36    <arg>-m
  37      <group choice="plain">
  38        <arg>s[mart]</arg>
  39        <arg>f[ast]</arg>
  40        <arg>i[mmediate]</arg>
  41      </group>
  42    </arg>
  43    <sbr>
  44    <command>pg_ctl</command>
  45    <arg choice="plain">restart</arg>
  46    <arg>-w</arg>
  47    <arg>-D <replaceable>datadir</replaceable></arg>
  48    <arg>-m
  49      <group choice="plain">
  50        <arg>s[mart]</arg>
  51        <arg>f[ast]</arg>
  52        <arg>i[mmediate]</arg>
  53      </group>
  54    </arg>
  55    <arg>-o <replaceable>options</replaceable></arg>
  56    <sbr>
  57    <command>pg_ctl</command>
  58    <arg choice="plain">status</arg>
  59    <arg>-D <replaceable>datadir</replaceable></arg>
  60   </cmdsynopsis>
  61  </refsynopsisdiv>
  62
  63
  64  <refsect1 id="app-pg-ctl-description">
  65   <title>Description</title>
  66   <para>
  67    <application>pg_ctl</application> is a utility for starting,
  68    stopping, or restarting <xref linkend="app-postmaster">, the
  69    <productname>PostgreSQL</productname> backend server, or displaying
  70    the status of a running postmaster.  Although the postmaster can be
  71    started manually, <application>pg_ctl</application> encapulates
  72    tasks such as redirecting log output, properly detaching from the
  73    terminal and process group, and additionally provides an option for
  74    controlled shut down.
  75   </para>
  76
  77   <para>
  78    In <option>start</option> mode, a new postmaster is launched.  The
  79    server is started in the background, the standard input attached to
  80    <filename>/dev/null</filename>.  The standard output and standard
  81    error are either appended to a log file, if the <option>-l</option>
  82    option is used, or are redirected to
  83    <application>pg_ctl</application>'s standard output (not standard
  84    error).  If no log file is chosen, the standard output of
  85    <application>pg_ctl</application> should be redirected to a file or
  86    piped to another process, for example a log rotating program,
  87    otherwise the postmaster will write its output the the controlling
  88    terminal (from the background) and will not leave the shell's
  89    process group.
  90   </para>
  91
  92   <para>
  93    In <option>stop</option> mode, the postmaster that is running on
  94    the specified data directory is shut down.  Three different
  95    shutdown methods can be selected with the <option>-m</option>
  96    option: <quote>Smart</quote> mode waits for all the clients to
  97    disconnect.  This is the default.  <quote>Fast</quote> mode does
  98    not wait for clients to disconnect.  All active transactions will
  99    be rolled back.  <quote>Immediate</quote> mode will abort without
 100    complete shutdown.  This will lead to a recovery run on restart.
 101    By the default, stop mode waits for the shutdown to complete.
 102   </para>
 103
 104   <para>
 105    <option>restart</option> mode effectively executes a stop followed
 106    by a start.  This allows the changing of postmaster command line
 107    options.
 108   </para>
 109
 110   <para>
 111    <option>status</option> mode checks whether a postmaster is running
 112    and if so displays the <acronym>PID</acronym> and the command line
 113    options that were used to invoke it.
 114   </para>
 115
 116   <refsect2 id="app-pg-ctl-options">
 117    <title>Options</title>
 118    <para>
 119
 120     <variablelist>
 121      <varlistentry>
 122       <term>-D <replaceable class="parameter">datadir</replaceable></term>
 123       <listitem>
 124        <para>
 125         Specifies the file system location of the database files.  If
 126         this is omitted, the environment variable
 127         <envar>PGDATA</envar> is used.
 128        </para>
 129       </listitem>
 130      </varlistentry>
 131
 132      <varlistentry>
 133       <term>-l <replaceable class="parameter">filename</replaceable></term>
 134       <listitem>
 135        <para>
 136         Append the server log output to
 137         <replaceable>filename</replaceable>.  If the file does not
 138         exist, it is created.  The umask is set to 077, so access to
 139         the log file from other users is disallowed by default.
 140        </para>
 141       </listitem>
 142      </varlistentry>
 143
 144      <varlistentry>
 145       <term>-m <replaceable class="parameter">mode</replaceable></term>
 146       <listitem>
 147        <para>
 148         Specifies the shutdown mode.  <replaceable>mode</replaceable>
 149         may be <literal>smart</literal>, <literal>fast</literal>, or
 150         <literal>immediate</literal>, or the first letter of one of
 151         these three.
 152        </para>
 153       </listitem>
 154      </varlistentry>
 155
 156      <varlistentry>
 157       <term>-o <replaceable class="parameter">options</replaceable></term>
 158       <listitem>
 159        <para>
 160         Specifies options to be passed directly to
 161         <application>postmaster</application>.
 162        </para>
 163        <para>
 164         The parameters are usually surrounded by single or double
 165         quotes to ensure that they are passed through as a group.
 166        </para>
 167       </listitem>
 168      </varlistentry>
 169
 170      <varlistentry>
 171       <term>-p <replaceable class="parameter">path</replaceable></term>
 172       <listitem>
 173        <para>
 174         Specifies the location of the <filename>postmaster</filename>
 175         executable.  By default the postmaster is taken from the same
 176         directory as pg_ctl, or failing that, the hard-wired
 177         installation directory.  It is not necessary to use this
 178         option unless you are doing something unusual and get errors
 179         that the postmaster was not found.
 180        </para>
 181       </listitem>
 182      </varlistentry>
 183
 184      <varlistentry>
 185       <term>-w</term>
 186       <listitem>
 187        <para>
 188         Wait for the start or stutdown to complete.  Times out after
 189         60 seconds.  This is the default for shutdowns.
 190        </para>
 191       </listitem>
 192      </varlistentry>
 193
 194      <varlistentry>
 195       <term>-W</term>
 196       <listitem>
 197        <para>
 198         Do not wait for start or shutdown to complete.  This is the
 199         default for starts and restarts.
 200        </para>
 201       </listitem>
 202      </varlistentry>
 203     </variablelist>
 204    </para>
 205   </refsect2>
 206
 207   <refsect2>
 208    <title>Files</title>
 209
 210    <para>
 211     If the file <filename>postmaster.opts.default</filename> exists in
 212     the data directory, the contents of the file will be passed as
 213     options to the <application>postmaster</application>, unless
 214     overridden by the <option>-o</option> option.
 215    </para>
 216   </refsect2>
 217
 218  </refsect1>
 219
 220
 221  <refsect1 id="R1-APP-PGCTL-2">
 222   <title>Examples</title>
 223
 224   <refsect2 id="R2-APP-PGCTL-3">
 225    <title>Starting the postmaster</title>
 226
 227    <para>
 228     To start up <application>postmaster</application>:
 229 <screen>
 230 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 231 </screen>
 232    </para>
 233
 234    <para>
 235     An example of starting the <application>postmaster</application>,
 236     blocking until postmaster comes up is:
 237 <screen>
 238 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 239 </screen>
 240    </para>
 241
 242    <para>
 243     For a <application>postmaster</application> using port 5433, and
 244     running without <function>fsync</function>, use:
 245 <screen>
 246 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 247 </screen>
 248    </para>
 249   </refsect2>
 250
 251   <refsect2 id="R2-APP-PGCTL-4">
 252    <title>Stopping the postmaster</title>
 253    <para>
 254 <screen>
 255 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 256 </screen>
 257     stops postmaster. Using the <option>-m</option> switch allows one
 258     to control <emphasis>how</emphasis> the backend shuts down.
 259    </para>
 260   </refsect2>
 261
 262   <refsect2 id="R2-APP-PGCTL-5">
 263    <title>Restarting the postmaster</title>
 264
 265    <para>
 266     This is almost equivalent to stopping the
 267     <application>postmaster</application> then starting it again
 268     except that pg_ctl saves and reuses the command line options that
 269     were passed to the previously running instance.  To restart
 270     <application>postmaster</application> in the simplest form:
 271 <screen>
 272 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 273 </screen>
 274    </para>
 275
 276    <para>
 277     To restart <application>postmaster</application>,
 278     waiting for it to shut down and to come up:
 279 <screen>
 280 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 281 </screen>
 282    </para>
 283
 284    <para>
 285     To restart using port 5433 and disabling fsync after restarting:
 286 <screen>
 287 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 288 </screen>
 289    </para>
 290   </refsect2>
 291
 292   <refsect2 id="R2-APP-PGCTL-6">
 293    <title>Showing postmaster status</title>
 294
 295    <para>
 296     Here is a sample status output from
 297     <application>pg_ctl</application>:
 298 <screen>
 299 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 300 <computeroutput>
 301 pg_ctl: postmaster is running (pid: 13718)
 302 Command line was:
 303 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 304 </computeroutput>
 305 </screen>
 306     This is the command line that would be invoked in restart mode.
 307    </para>
 308   </refsect2>
 309  </refsect1>
 310
 311  <refsect1>
 312   <title>Bugs</title>
 313
 314   <para>
 315    Waiting for complete start is not a well-defined operation and may
 316    fail if access control is set up in way that a local client cannot
 317    connect without manual interaction.  It should be avoided.
 318   </para>
 319  </refsect1>
 320
 321  <refsect1>
 322   <title>See Also</title>
 323
 324   <para>
 325    <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
 326   </para>
 327  </refsect1>
 328
 329 </refentry>
 330
 331 <!-- Keep this comment at the end of the file
 332 Local variables:
 333 mode:sgml
 334 sgml-omittag:nil
 335 sgml-shorttag:t
 336 sgml-minimize-attributes:nil
 337 sgml-always-quote-attributes:t
 338 sgml-indent-step:1
 339 sgml-indent-data:t
 340 sgml-parent-document:nil
 341 sgml-default-dtd-file:"../reference.ced"
 342 sgml-exposed-tags:nil
 343 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 344 sgml-local-ecat-files:nil
 345 End:
 346 -->