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.5 2000/12/25 23:15:26 petere Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="app-pg-ctl">
   7  <docinfo>
   8   <date>2000-11-25</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>-p <replaceable>path</replaceable></arg>
  29    <arg>-o <replaceable>options</replaceable></arg>
  30    <sbr>
  31    <command>pg_ctl</command>
  32    <arg choice="plain">stop</arg>
  33    <arg>-w</arg>
  34    <arg>-D <replaceable>datadir</replaceable></arg>
  35    <arg>-m
  36      <group choice="plain">
  37        <arg>s[mart]</arg>
  38        <arg>f[ast]</arg>
  39        <arg>i[mmediate]</arg>
  40      </group>
  41    </arg>
  42    <sbr>
  43    <command>pg_ctl</command>
  44    <arg choice="plain">restart</arg>
  45    <arg>-w</arg>
  46    <arg>-D <replaceable>datadir</replaceable></arg>
  47    <arg>-m
  48      <group choice="plain">
  49        <arg>s[mart]</arg>
  50        <arg>f[ast]</arg>
  51        <arg>i[mmediate]</arg>
  52      </group>
  53    </arg>
  54    <arg>-o <replaceable>options</replaceable></arg>
  55    <sbr>
  56    <command>pg_ctl</command>
  57    <arg choice="plain">status</arg>
  58    <arg>-D <replaceable>datadir</replaceable></arg>
  59   </cmdsynopsis>
  60  </refsynopsisdiv>
  61
  62
  63  <refsect1 id="app-pg-ctl-description">
  64   <title>Description</title>
  65   <para>
  66    <application>pg_ctl</application> is a utility for starting,
  67    stopping, or restarting the <xref linkend="app-postmaster">, or
  68    displaying the status of a running postmaster.
  69   </para>
  70
  71   <refsect2 id="app-pg-ctl-options">
  72    <title>Options</title>
  73    <para>
  74
  75     <variablelist>
  76      <varlistentry>
  77       <term>-w</term>
  78       <listitem>
  79        <para>
  80         Wait for the database server to come up, by watching for
  81         creation of the pid file
  82         (<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).
  83         Times out after 60 seconds.
  84        </para>
  85       </listitem>
  86      </varlistentry>
  87
  88      <varlistentry>
  89       <term>-D <replaceable class="parameter">datadir</replaceable></term>
  90       <listitem>
  91        <para>
  92         Specifies the file system location of the database files.  If
  93         this is omitted, the environment variable
  94         <envar>PGDATA</envar> is used.
  95        </para>
  96       </listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term>-p <replaceable class="parameter">path</replaceable></term>
 101       <listitem>
 102        <para>
 103         Specifies the location of the <filename>postmaster</filename>
 104         executable.  By default the postmaster is taken from the same
 105         directory as pg_ctl, or failing that, the hard-wired
 106         installation directory.  It is not necessary to use this
 107         option unless you are doing something unusual and get errors
 108         that the postmaster was not found.
 109        </para>
 110       </listitem>
 111      </varlistentry>
 112
 113      <varlistentry>
 114       <term>-o <replaceable class="parameter">options</replaceable></term>
 115       <listitem>
 116        <para>
 117         Specifies options to be passed directly to
 118         <application>postmaster</application>.
 119        </para>
 120        <para>
 121         The parameters are usually surrounded by single or double
 122         quotes to ensure that they are passed through as a group.
 123        </para>
 124       </listitem>
 125      </varlistentry>
 126
 127      <varlistentry>
 128       <term>-m <replaceable class="parameter">mode</replaceable></term>
 129       <listitem>
 130        <para>
 131         Specifies the shutdown mode.
 132
 133         <variablelist>
 134          <varlistentry>
 135           <term>smart</term>
 136           <term>s</term>
 137           <listitem>
 138            <para>
 139             Smart mode waits for all the clients to disconnect. This
 140             is the default.
 141            </para>
 142           </listitem>
 143          </varlistentry>
 144
 145          <varlistentry>
 146           <term>fast</term>
 147           <term>f</term>
 148           <listitem>
 149            <para>
 150             Fast mode does not wait for clients to disconnect.  All
 151             active transactions will be rolled back.
 152            </para>
 153           </listitem>
 154          </varlistentry>
 155
 156          <varlistentry>
 157           <term>immediate</term>
 158           <term>i</term>
 159           <listitem>
 160            <para>
 161             Immediate mode will abort without complete shutdown.  This
 162             will lead to a recovery run on restart.
 163            </para>
 164           </listitem>
 165          </varlistentry>
 166         </variablelist>
 167        </para>
 168       </listitem>
 169      </varlistentry>
 170
 171      <varlistentry>
 172       <term>start</term>
 173       <listitem>
 174        <para>
 175         Start up <application>postmaster</application>.
 176        </para>
 177       </listitem>
 178      </varlistentry>
 179
 180      <varlistentry>
 181       <term>stop</term>
 182       <listitem>
 183        <para>
 184         Shut down <application>postmaster</application>.
 185        </para>
 186       </listitem>
 187      </varlistentry>
 188
 189      <varlistentry>
 190       <term>restart</term>
 191       <listitem>
 192        <para>
 193         Stop the <application>postmaster</application>, if one is running,
 194         and then start it again.
 195        </para>
 196       </listitem>
 197      </varlistentry>
 198
 199      <varlistentry>
 200       <term>status</term>
 201       <listitem>
 202        <para>
 203         Show the current state of <application>postmaster</application>.
 204        </para>
 205       </listitem>
 206      </varlistentry>
 207     </variablelist>
 208    </para>
 209   </refsect2>
 210
 211   <refsect2>
 212    <title>Files</title>
 213
 214    <para>
 215     If the file <filename>postmaster.opts.default</filename> exists in
 216     the data directory, the contents of the file will be passed as
 217     options to the <application>postmaster</application>, unless
 218     overridden by the <option>-o</option> option.
 219    </para>
 220   </refsect2>
 221
 222  </refsect1>
 223
 224
 225  <refsect1 id="R1-APP-PGCTL-2">
 226   <title>Usage</title>
 227
 228   <refsect2 id="R2-APP-PGCTL-3">
 229    <title>Starting the postmaster</title>
 230
 231    <para>
 232     To start up <application>postmaster</application>:
 233 <screen>
 234 <prompt>$</prompt> <userinput>pg_ctl start</userinput>
 235 </screen>
 236    </para>
 237
 238    <para>
 239     An example of starting the <application>postmaster</application>,
 240     blocking until postmaster comes up is:
 241 <screen>
 242 <prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
 243 </screen>
 244    </para>
 245
 246    <para>
 247     For a <application>postmaster</application> using port 5433, and
 248     running without <function>fsync</function>, use:
 249 <screen>
 250 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
 251 </screen>
 252    </para>
 253   </refsect2>
 254
 255   <refsect2 id="R2-APP-PGCTL-4">
 256    <title>Stopping the postmaster</title>
 257    <para>
 258 <screen>
 259 <prompt>$</prompt> <userinput>pg_ctl stop</userinput>
 260 </screen>
 261     stops postmaster. Using the <option>-m</option> switch allows one
 262     to control <emphasis>how</emphasis> the backend shuts down.
 263     <option>-w</option> waits for postmaster to shut down.
 264    </para>
 265   </refsect2>
 266
 267   <refsect2 id="R2-APP-PGCTL-5">
 268    <title>Restarting the postmaster</title>
 269
 270    <para>
 271     This is almost equivalent to stopping the
 272     <application>postmaster</application> then starting it again
 273     except that pg_ctl saves and reuses the command line options that
 274     were passed to the previously running instance.  To restart
 275     <application>postmaster</application> in the simplest form:
 276 <screen>
 277 <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
 278 </screen>
 279    </para>
 280
 281    <para>
 282     To restart <application>postmaster</application>,
 283     waiting for it to shut down and to come up:
 284 <screen>
 285 <prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
 286 </screen>
 287    </para>
 288
 289    <para>
 290     To restart using port 5433 and disabling fsync after restarting:
 291 <screen>
 292 <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
 293 </screen>
 294    </para>
 295   </refsect2>
 296
 297   <refsect2 id="R2-APP-PGCTL-6">
 298    <title>Showing postmaster status</title>
 299
 300    <para>
 301     Here is a sample status output from
 302     <application>pg_ctl</application>:
 303 <screen>
 304 <prompt>$</prompt> <userinput>pg_ctl status</userinput>
 305 <computeroutput>
 306 pg_ctl: postmaster is running (pid: 13718)
 307 Command line was:
 308 /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
 309 </computeroutput>
 310 </screen>
 311     This is the command line that would be invoked in restart mode.
 312    </para>
 313   </refsect2>
 314  </refsect1>
 315 </refentry>
 316
 317 <!-- Keep this comment at the end of the file
 318 Local variables:
 319 mode:sgml
 320 sgml-omittag:nil
 321 sgml-shorttag:t
 322 sgml-minimize-attributes:nil
 323 sgml-always-quote-attributes:t
 324 sgml-indent-step:1
 325 sgml-indent-data:t
 326 sgml-parent-document:nil
 327 sgml-default-dtd-file:"../reference.ced"
 328 sgml-exposed-tags:nil
 329 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 330 sgml-local-ecat-files:nil
 331 End:
 332 -->