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