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.2 2000/10/08 13:22:24 petere Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="app-pg-ctl">
   7  <refmeta>
   8   <refentrytitle id="app-pg-ctl-title">
   9    <application>pg_ctl</application>
  10   </refentrytitle>
  11   <refmiscinfo>Application</refmiscinfo>
  12  </refmeta>
  13
  14  <refnamediv>
  15   <refname>
  16    <application>pg_ctl</application>
  17   </refname>
  18   <refpurpose>
  19    Starts, stops, and restarts postmaster
  20   </refpurpose>
  21  </refnamediv>
  22
  23  <refsynopsisdiv>
  24   <refsynopsisdivinfo>
  25    <date>2000-04-05</date>
  26   </refsynopsisdivinfo>
  27
  28   <synopsis>
  29 pg_ctl [-w] [-D <replaceable class="parameter">datadir</replaceable>][-p <replaceable class="parameter">path</replaceable>] [-o "<replaceable class="parameter">options</replaceable>"] start
  30 pg_ctl [-w] [-D <replaceable class="parameter">datadir</replaceable>] [-m [s[mart]|f[ast]|i[mmediate]]] stop
  31 pg_ctl [-w] [-D <replaceable class="parameter">datadir</replaceable>] [-m [s[mart]|f[ast]|i[mmediate]]
  32     [-o "<replaceable class="parameter">options</replaceable>"] restart
  33 pg_ctl [-D <replaceable class="parameter">datadir</replaceable>] status
  34   </synopsis>
  35
  36   <refsect2 id="R2-APP-PGCTL-1">
  37    <title>
  38     Inputs
  39    </title>
  40    <para>
  41
  42     <variablelist>
  43      <varlistentry>
  44       <term>-w</term>
  45       <listitem>
  46        <para>
  47         Wait for the database server to come up, by
  48         watching for creation of the pid file (PGDATA/postmaster.pid).
  49         Times out after 60 seconds.
  50        </para>
  51       </listitem>
  52      </varlistentry>
  53
  54      <varlistentry>
  55       <term>-D <replaceable class="parameter">datadir</replaceable></term>
  56       <listitem>
  57        <para>
  58         Specifies the database location for this database installation.
  59        </para>
  60       </listitem>
  61      </varlistentry>
  62
  63      <varlistentry>
  64       <term>-p <replaceable class="parameter">path</replaceable></term>
  65       <listitem>
  66        <para>
  67         Specifies the path to the postmaster image.
  68        </para>
  69       </listitem>
  70      </varlistentry>
  71
  72      <varlistentry>
  73       <term>-o "<replaceable class="parameter">options</replaceable>"</term>
  74       <listitem>
  75        <para>
  76         Specifies options to be passed directly to
  77         <application>postmaster</application>.
  78        </para>
  79        <para>
  80         The parameters are usually surrounded by single or double
  81         quotes to ensure that they are passed through as a group.
  82        </para>
  83       </listitem>
  84      </varlistentry>
  85
  86      <varlistentry>
  87       <term>-m <replaceable class="parameter">mode</replaceable></term>
  88       <listitem>
  89        <para>
  90         Specifies the shutdown mode.
  91
  92         <variablelist>
  93          <varlistentry>
  94           <term>smart</term>
  95           <term>s</term>
  96           <listitem>
  97            <para>
  98             smart mode waits for all
  99             the clients to logout. This is the default.
 100            </para>
 101           </listitem>
 102          </varlistentry>
 103
 104          <varlistentry>
 105           <term>fast</term>
 106           <term>f</term>
 107           <listitem>
 108            <para>
 109             Fast mode sends SIGTERM to the backends; that means
 110             active transactions get rolled back.
 111            </para>
 112           </listitem>
 113          </varlistentry>
 114
 115          <varlistentry>
 116           <term>immediate</term>
 117           <term>i</term>
 118           <listitem>
 119            <para>
 120             Immediate mode sends SIGUSR1
 121             to the backends and lets them abort. In this case, database recovery
 122             will be necessary on the next start-up.
 123            </para>
 124           </listitem>
 125          </varlistentry>
 126         </variablelist>
 127        </para>
 128       </listitem>
 129      </varlistentry>
 130
 131      <varlistentry>
 132       <term>start</term>
 133       <listitem>
 134        <para>
 135         Start up <application>postmaster</application>.
 136        </para>
 137       </listitem>
 138      </varlistentry>
 139
 140      <varlistentry>
 141       <term>stop</term>
 142       <listitem>
 143        <para>
 144         Shut down <application>postmaster</application>.
 145        </para>
 146       </listitem>
 147      </varlistentry>
 148
 149      <varlistentry>
 150       <term>restart</term>
 151       <listitem>
 152        <para>
 153         Restart the <application>postmaster</application>, performing
 154         a stop/start sequence.
 155        </para>
 156       </listitem>
 157      </varlistentry>
 158
 159      <varlistentry>
 160       <term>status</term>
 161       <listitem>
 162        <para>
 163         Show the current state of <application>postmaster</application>.
 164        </para>
 165       </listitem>
 166      </varlistentry>
 167     </variablelist>
 168    </para>
 169   </refsect2>
 170
 171   <refsect2 id="R2-APP-PGCTL-2">
 172    <refsect2info>
 173     <date>1999-11-07</date>
 174    </refsect2info>
 175    <title>
 176     Outputs
 177    </title>
 178    <para>
 179     <variablelist>
 180      <varlistentry>
 181       <term><computeroutput>pg_ctl: postmaster is <replaceable>state</replaceable> (pid: <replaceable>#</replaceable>)</computeroutput></term>
 182       <listitem>
 183        <para>
 184         Postmaster status.
 185        </para>
 186       </listitem>
 187      </varlistentry>
 188     </variablelist>
 189
 190     If there is an error condition, the backend error message will be displayed.
 191    </para>
 192   </refsect2>
 193  </refsynopsisdiv>
 194
 195  <refsect1 id="R1-APP-PGCTL-1">
 196   <title>
 197    Description
 198   </title>
 199   <para>
 200    <application>pg_ctl</application> is a utility for starting,
 201    stopping or restarting <application>postmaster</application>.
 202   </para>
 203  </refsect1>
 204
 205  <refsect1 id="R1-APP-PGCTL-2">
 206   <title>
 207    Usage
 208   </title>
 209
 210   <refsect2 id="R2-APP-PGCTL-3">
 211    <title>
 212     Starting postmaster
 213    </title>
 214
 215    <para>
 216     To start up <application>postmaster</application>:
 217
 218     <programlisting>
 219 $ pg_ctl start
 220     </programlisting>
 221    </para>
 222
 223    <para>
 224     If -w is supplied, pg_ctl waits for the database server to come up, by
 225     watching for creation of the pid file (PGDATA/postmaster.pid), for up
 226     to 60 seconds.
 227    </para>
 228
 229    <para>
 230     Parameters to invoke <application>postmaster</application> are
 231     taken from the following sources:
 232
 233     <itemizedlist>
 234      <listitem>
 235       <para>
 236        Path to postmaster: found in the command search path.
 237       </para>
 238      </listitem>
 239
 240      <listitem>
 241       <para>
 242        Database directory: <envar>PGDATA</envar> environment variable.
 243       </para>
 244      </listitem>
 245
 246      <listitem>
 247       <para>
 248        Other parameters:
 249        <filename><envar>PGDATA</envar>/postmaster.opts.default</filename>.
 250       </para>
 251      </listitem>
 252     </itemizedlist>
 253    </para>
 254
 255    <para>
 256     <filename>postmaster.opts.default</filename> contains parameters
 257     for <application>postmaster</application>.
 258    </para>
 259
 260    <para>
 261     Note that <filename>postmaster.opts.default</filename> is
 262     installed by <application>initdb</application> from
 263     <filename>lib/postmaster.opts.default.sample</filename>
 264     under the <productname>Postgres</productname> installation
 265     directory (<filename>lib/postmaster.opts.default.sample</filename>
 266     is copied from
 267     <filename>src/bin/pg_ctl/postmaster.opts.default.sample</filename>
 268     while installing <productname>Postgres</productname>).
 269    </para>
 270
 271    <para>
 272     To override the default parameters you can use <option>-D</option>,
 273     <option>-p</option> and <option>-o</option> options.
 274    </para>
 275
 276    <para>
 277     An example of starting the
 278     <application>postmaster</application>, blocking until
 279     postmaster comes up is:
 280     <programlisting>
 281 $ pg_ctl -w start
 282     </programlisting>
 283    </para>
 284
 285    <para>
 286     To specify the <application>postmaster</application> binary path,
 287     try:
 288
 289     <programlisting>
 290 $ pg_ctl -p /usr/local/pgsq/bin/postmaster start
 291     </programlisting>
 292    </para>
 293
 294    <para>
 295     For a <application>postmaster</application> using port 5433, and
 296     running without <function>fsync</function>, use:
 297
 298     <programlisting>
 299 $ pg_ctl -o "-o -F -p 5433" start
 300     </programlisting>
 301    </para>
 302   </refsect2>
 303
 304   <refsect2 id="R2-APP-PGCTL-4">
 305    <title>
 306     Stopping postmaster
 307    </title>
 308    <para>
 309
 310     <programlisting>
 311 $ pg_ctl stop
 312     </programlisting>
 313
 314     stops postmaster. Using the <option>-m</option> switch allows one
 315     to control <emphasis>how</emphasis> the backend shuts down.
 316     <option>-w</option>
 317     waits for postmaster to shut down.
 318     <option>-m</option> specifies the shut down mode.
 319    </para>
 320   </refsect2>
 321
 322   <refsect2 id="R2-APP-PGCTL-5">
 323    <title>
 324     Restarting postmaster
 325    </title>
 326
 327    <para>
 328     This is almost equivalent to stopping the
 329     <application>postmaster</application> then starting it
 330     again except that the parameters used before stopping
 331     it would be used too. This is done by saving them in
 332     $<envar>PGDATA</envar>/postmaster.opts file.
 333     <option>-w</option>, <option>-D</option>, <option>-m</option>,
 334     <option>-fast</option>, <option>-immediate</option> and
 335     <option>-o</option>
 336     can also be used in the restarting mode and they have the same meanings as
 337     described above.
 338    </para>
 339
 340    <para>
 341     To restart <application>postmaster</application> in the simplest
 342     form:
 343
 344     <programlisting>
 345 $ pg_ctl restart
 346     </programlisting>
 347    </para>
 348
 349    <para>
 350     To restart <application>postmaster</application>,
 351     waiting for it to shut down and to come up:
 352
 353     <programlisting>
 354 $ pg_ctl -w restart
 355     </programlisting>
 356    </para>
 357
 358    <para>
 359     To restart using port 5433 and disabling fsync after restarting:
 360
 361     <programlisting>
 362 $ pg_ctl -o "-o -F -p 5433" restart
 363     </programlisting>
 364    </para>
 365   </refsect2>
 366
 367   <refsect2 id="R2-APP-PGCTL-6">
 368    <title>
 369     postmaster status
 370    </title>
 371
 372    <para>
 373     To get status information from postmaster:
 374
 375     <programlisting>
 376 $ pg_ctl status
 377     </programlisting>
 378    </para>
 379
 380    <para>
 381     Here is a sample output from <application>pg_ctl</application>:
 382
 383     <programlisting>
 384 pg_ctl: postmaster is running (pid: 13718)
 385 options are:
 386 /usr/local/src/pgsql/current/bin/postmaster
 387 -p 5433
 388 -D /usr/local/src/pgsql/current/data
 389 -B 64
 390 -b /usr/local/src/pgsql/current/bin/postgres
 391 -N 32
 392 -o '-F'
 393     </programlisting>
 394    </para>
 395   </refsect2>
 396  </refsect1>
 397 </refentry>
 398
 399 <!-- Keep this comment at the end of the file
 400 Local variables:
 401 mode:sgml
 402 sgml-omittag:nil
 403 sgml-shorttag:t
 404 sgml-minimize-attributes:nil
 405 sgml-always-quote-attributes:t
 406 sgml-indent-step:1
 407 sgml-indent-data:t
 408 sgml-parent-document:nil
 409 sgml-default-dtd-file:"../reference.ced"
 410 sgml-exposed-tags:nil
 411 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 412 sgml-local-ecat-files:nil
 413 End:
 414 -->