path: root/doc/src/sgml/ref/pg_ctl-ref.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.4 2000/11/25 17:17:30 petere Exp $
Postgres documentation
-->

<refentry id="app-pg-ctl">
 <docinfo>
  <date>2000-11-25</date>
 </docinfo>

 <refmeta>
  <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_ctl</refname>
  <refpurpose>Starts, stops, or restarts postmaster</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_ctl</command>
   <arg choice="plain">start</arg>
   <arg>-w</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-p <replaceable>path</replaceable></arg>
   <arg>-o <replaceable>options</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">stop</arg>
   <arg>-w</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-m
     <group choice="plain">
       <arg>s[mart]</arg>
       <arg>f[ast]</arg>
       <arg>i[mmediate]</arg>
     </group>
   </arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">restart</arg>
   <arg>-w</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-m
     <group choice="plain">
       <arg>s[mart]</arg>
       <arg>f[ast]</arg>
       <arg>i[mmediate]</arg>
     </group>
   </arg>
   <arg>-o <replaceable>options</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">status</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="app-pg-ctl-description">
  <title>Description</title>
  <para>
   <application>pg_ctl</application> is a utility for starting,
   stopping, or restarting the <xref linkend="app-postmaster"
   endterm="app-postmaster-title">, or displaying the status of a
   running postmaster.
  </para>

  <refsect2 id="app-pg-ctl-options">
   <title>Options</title>
   <para>

    <variablelist>
     <varlistentry>
      <term>-w</term>
      <listitem>
       <para>
	Wait for the database server to come up, by watching for
	creation of the pid file
	(<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).
	Times out after 60 seconds.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-D <replaceable class="parameter">datadir</replaceable></term>
      <listitem>
       <para>
	Specifies the file system location of the database files.  If
	this is omitted, the environment variable
	<envar>PGDATA</envar> is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-p <replaceable class="parameter">path</replaceable></term>
      <listitem>
       <para>
	Specifies the location of the <filename>postmaster</filename>
	executable.  By default the postmaster is taken from the same
	directory as pg_ctl, or failing that, the hard-wired
	installation directory.  It is not necessary to use this
	option unless you are doing something unusual and get errors
	that the postmaster was not found.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-o <replaceable class="parameter">options</replaceable></term>
      <listitem>
       <para>
        Specifies options to be passed directly to
	<application>postmaster</application>.
       </para>
       <para>
	The parameters are usually surrounded by single or double
	quotes to ensure that they are passed through as a group.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-m <replaceable class="parameter">mode</replaceable></term>
      <listitem>
       <para>
	Specifies the shutdown mode.

	<variablelist>
	 <varlistentry>
	  <term>smart</term>
	  <term>s</term>
	  <listitem>
	   <para>
	    Smart mode waits for all the clients to disconnect. This
	    is the default.
	   </para>
	  </listitem>
	 </varlistentry>

	 <varlistentry>
	  <term>fast</term>
	  <term>f</term>
	  <listitem>
	   <para>
	    Fast mode does not wait for clients to disconnect.  All
	    active transactions will be rolled back.
	   </para>
	  </listitem>
	 </varlistentry>

	 <varlistentry>
	  <term>immediate</term>
	  <term>i</term>
	  <listitem>
	   <para>
	    Immediate mode will abort without complete shutdown.  This
	    will lead to a recovery run on restart.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>start</term>
      <listitem>
       <para>
	Start up <application>postmaster</application>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>stop</term>
      <listitem>
       <para>
	Shut down <application>postmaster</application>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>restart</term>
      <listitem>
       <para>
	Stop the <application>postmaster</application>, if one is running,
	and then start it again.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>status</term>
      <listitem>
       <para>
	Show the current state of <application>postmaster</application>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2>
   <title>Files</title>

   <para>
    If the file <filename>postmaster.opts.default</filename> exists in
    the data directory, the contents of the file will be passed as
    options to the <application>postmaster</application>, unless
    overridden by the <option>-o</option> option.
   </para>
  </refsect2>

 </refsect1>


 <refsect1 id="R1-APP-PGCTL-2">
  <title>Usage</title>

  <refsect2 id="R2-APP-PGCTL-3">
   <title>Starting the postmaster</title>

   <para>
    To start up <application>postmaster</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
   </para>

   <para>
    An example of starting the <application>postmaster</application>,
    blocking until postmaster comes up is:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
   </para>

   <para>
    For a <application>postmaster</application> using port 5433, and
    running without <function>fsync</function>, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
</screen>
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-4">
   <title>Stopping the postmaster</title>
   <para>
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
    stops postmaster. Using the <option>-m</option> switch allows one
    to control <emphasis>how</emphasis> the backend shuts down.
    <option>-w</option> waits for postmaster to shut down.
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-5">
   <title>Restarting the postmaster</title>

   <para>
    This is almost equivalent to stopping the
    <application>postmaster</application> then starting it again
    except that pg_ctl saves and reuses the command line options that
    were passed to the previously running instance.  To restart
    <application>postmaster</application> in the simplest form:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
   </para>

   <para>
    To restart <application>postmaster</application>,
    waiting for it to shut down and to come up:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
</screen>
   </para>

   <para>
    To restart using port 5433 and disabling fsync after restarting:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
</screen>
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-6">
   <title>Showing postmaster status</title>

   <para>
    Here is a sample status output from
    <application>pg_ctl</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
<computeroutput>
pg_ctl: postmaster is running (pid: 13718)
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
</computeroutput>
</screen>
    This is the command line that would be invoked in restart mode.
   </para>
  </refsect2>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->