<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.43 2004/02/03 17:34:02 tgl Exp $
PostgreSQL documentation
-->

<refentry id="APP-POSTGRES">
 <refmeta>
  <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>postgres</refname>
  <refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose>
 </refnamediv>

 <indexterm zone="app-postgres">
  <primary>postgres (the program)</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <!-- standalone call -->
   <command>postgres</command>
   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
   <arg>-B <replaceable>nbuffers</replaceable></arg>
   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   <arg>-d <replaceable>debug-level</replaceable></arg>
   <arg>--describe-config</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-e</arg>
   <arg>-E</arg>
   <arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
   <arg>-F</arg>
   <arg>-N</arg>
   <arg>-o <replaceable>filename</replaceable></arg>
   <arg>-O</arg>
   <arg>-P</arg>
   <group>
    <arg>-s</arg>
    <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
   </group>
   <arg>-S <replaceable>work-mem</replaceable></arg>
   <arg>-W <replaceable>seconds</replaceable></arg>
   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   <arg choice="plain"><replaceable>database</replaceable></arg>
   <sbr>
   <!-- postmaster fork -->
   <command>postgres</command>
   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
   <arg>-B <replaceable>nbuffers</replaceable></arg>
   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
   <arg>-d <replaceable>debug-level</replaceable></arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-e</arg>
   <arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
   <arg>-F</arg>
   <arg>-o <replaceable>filename</replaceable></arg>
   <arg>-O</arg>
   <arg>-p <replaceable>database</replaceable></arg>
   <arg>-P</arg>
   <group>
    <arg>-s</arg>
    <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
   </group>
   <arg>-S <replaceable>work-mem</replaceable></arg>
   <arg>-v <replaceable>protocol</replaceable></arg>
   <arg>-W <replaceable>seconds</replaceable></arg>
   <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   The <command>postgres</command> executable is the actual
   <productname>PostgreSQL</productname> server process that processes
   queries.  It is normally not called directly; instead a <xref
   linkend="app-postmaster"> multiuser server is started.
  </para>

  <para>
   The second form above is how
   <command>postgres</command> is invoked by the <xref
   linkend="app-postmaster"> (only
   conceptually, since both <filename>postmaster</filename> and
   <filename>postgres</filename> are in fact the same program); it
   should not be invoked directly this way.  The first form invokes
   the server directly in interactive single-user mode.  The primary use
   for this mode is during bootstrapping by <xref linkend="app-initdb">.
   Sometimes it is used for debugging or disaster recovery.
  </para>

  <para>
   When invoked in interactive mode from the shell, the user can enter
   queries and the results will be printed to the screen, but in a
   form that is more useful for developers than end users.  But note
   that running a single-user server is not truly suitable for
   debugging the server since no realistic interprocess communication
   and locking will happen.
  </para>

  <para>
   When running a stand-alone server, the session user will be set to
   the user with ID 1.  This user does not actually have to exist, so
   a stand-alone server can be used to manually recover from certain
   kinds of accidental damage to the system catalogs.  Implicit
   superuser powers are granted to the user with ID 1 in stand-alone
   mode.
  </para>
 </refsect1>

 <refsect1>
  <title>Options</title>

   <para>
    When <command>postgres</command> is started by a <xref
    linkend="app-postmaster"> then it
    inherits all options set by the latter.  Additionally,
    <command>postgres</command>-specific options can be passed
    from the <command>postmaster</command> with the
    <option>-o</option> switch.
   </para>

   <para>
    You can avoid having to type these options by setting up a
    configuration file.  See <xref linkend="runtime-config"> for details.  Some
    (safe) options can also be set from the connecting client in an
    application-dependent way.  For example, if the environment
    variable <envar>PGOPTIONS</envar> is set, then
    <application>libpq</>-based clients will pass that string to the
    server, which will interpret it as
    <command>postgres</command> command-line options.
   </para>

   <refsect2>
    <title>General Purpose</title>

    <para>
     The options <option>-A</option>, <option>-B</option>,
     <option>-c</option>, <option>-d</option>, <option>-D</option>,
     <option>-F</option>, and <option>--<replaceable>name</></option> have the same meanings
     as the <xref linkend="app-postmaster"> except that
     <literal>-d 0</> prevents the server log level of
     the <command>postmaster</> from being propagated to <command>postgres</>.
    </para>

    <variablelist>
     <varlistentry>
      <term><option>-e</option></term>
      <listitem>
       <para>
        Sets the default date style to <quote>European</quote>, that is
	<literal>DMY</> ordering of input date fields.  This also causes
	the day to be printed before the month in certain date output formats.
	See <xref linkend="datatype-datetime"> for more information.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-o</option> <replaceable class="parameter">filename</replaceable></term>
      <listitem>
       <para>
	Send all server log output to 
	<replaceable class="parameter">filename</replaceable>.
	If <command>postgres</command> is running under the
	<command>postmaster</command>, this option is ignored,
	and the <systemitem>stderr</> inherited from the
	<command>postmaster</command> is used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-P</option></term>
      <listitem>
       <para>
	Ignore system indexes when reading system tables (but still update
	the indexes when modifying the tables).  This is useful when
	recovering from damaged system indexes.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-s</option></term>
      <listitem>
       <para>
	Print time information and other statistics at the end of each command.
	This is useful for benchmarking or for use in tuning the number of
	buffers.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-S</option> <replaceable class="parameter">work-mem</replaceable></term>
      <listitem>
       <para>
	Specifies the amount of memory to be used by internal sorts and hashes
	before resorting to temporary disk files.  See the description of the
	<varname>work_mem</> configuration parameter in <xref
	linkend="runtime-config-resource-memory">.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </refsect2>

   <refsect2>
    <title>Options for stand-alone mode</title>

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">database</replaceable></term>
      <listitem>
       <para>
	Specifies the name of the database to be accessed.  If it is
	omitted it defaults to the user name.	
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-E</option></term>
      <listitem>
       <para>
	Echo all commands.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-N</option></term>
      <listitem>
       <para>
	Disables use of newline as a statement delimiter.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect2>

   <refsect2>
    <title>Semi-internal Options</title>

    <para>
     There are several other options that may be specified, used
     mainly for debugging purposes.  These are listed here only for
     the use by <productname>PostgreSQL</productname> system
     developers.  <emphasis>Use of any of these options is highly
     discouraged.</emphasis>  Furthermore, any of these options may
     disappear or change in a future release without notice.
   </para>
    <variablelist>

     <varlistentry>
      <term><option>-f</option> <literal>{ s | i | m | n | h }</literal></term>
      <listitem>
       <para>
	Forbids the use of particular scan and join methods:
	<literal>s</literal> and <literal>i</literal>
	disable sequential and index scans respectively, while
	<literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
	disable nested-loop, merge and hash joins respectively.
       </para>
	
	<note>
	 <para>
	  Neither sequential scans nor nested-loop joins can be disabled completely;
	  the <literal>-fs</literal> and <literal>-fn</literal>
	  options simply discourage the optimizer from using those
	  plan types if it has any other alternative.
	 </para>
	</note>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-O</option></term>
      <listitem>
       <para>
	Allows the structure of system tables to be modified.  This is
	used by <command>initdb</command>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p</option> <replaceable class="parameter">database</replaceable></term>
      <listitem>
       <para>
	Indicates that this process has been started by a
	<command>postmaster</command> and specifies the database to use.
	etc.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term>
      <listitem>
       <para>
	Print timing statistics for each query relating to each of the
	major system modules.  This option cannot be used together
	with the <option>-s</option> option.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term>
      <listitem>
       <para>
	Specifies the version number of the frontend/backend protocol
	to be used for this particular session.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
      <listitem>
       <para>
	As soon as this option is encountered, the process sleeps for
	the specified amount of seconds.  This gives developers time
	to attach a debugger to the server process.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--describe-config</option></term>
      <listitem>
       <para>
        This option dumps out the server's internal configuration variables, 
        descriptions, and defaults in tab-delimited <command>COPY</> format.
        It is designed primarily for use by administration tools.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </refsect2>
 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
      Default data direction location
     </para>
    </listitem>
   </varlistentry>

  </variablelist>

  <para>
   For others, which have little influence during single-user mode,
   see <xref linkend="app-postmaster">.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   To cancel a running query, send the <literal>SIGINT</literal> signal
   to the <command>postgres</command> process running that command.
  </para>

  <para>
   To tell <command>postgres</command> to reload the configuration files,
   send a <literal>SIGHUP</literal> signal.  Normally it's best to
   <literal>SIGHUP</literal> the <command>postmaster</command> instead;
   the <command>postmaster</command> will in turn <literal>SIGHUP</literal>
   each of its children.  But in some cases it might be desirable to have only
   one <command>postgres</command> process reload the configuration files.
  </para>

  <para>
   The <command>postmaster</command> uses <literal>SIGTERM</literal>
   to tell a <command>postgres</command> process to quit normally and
   <literal>SIGQUIT</literal> to terminate without the normal cleanup.
   These signals <emphasis>should not</emphasis> be used by users.  It is also
   unwise to send <literal>SIGKILL</literal> to a <command>postgres</command>
   process --- the <command>postmaster</command> will interpret this as
   a crash in <command>postgres</command>, and will force all the sibling
   <command>postgres</command> processes to quit as part of its standard
   crash-recovery procedure.
  </para>

 </refsect1>

 <refsect1>
  <title>Usage</title>

   <para>
    Start a stand-alone server with a command like
<screen>
<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
</screen>
    Provide the correct path to the database directory with <option>-D</>, or
    make sure that the environment variable <envar>PGDATA</> is set.
    Also specify the name of the particular database you want to work in.
   </para>

   <para>
    Normally, the stand-alone server treats newline as the command
    entry terminator; there is no intelligence about semicolons,
    as there is in <application>psql</>.  To continue a command
    across multiple lines, you must type backslash just before each
    newline except the last one.
   </para>

   <para>
    But if you use the <option>-N</> command line switch, then newline does
    not terminate command entry.  In this case, the server will read the standard input
    until the end-of-file (<acronym>EOF</>) marker, then
    process the input as a single command string.  Backslash-newline is not
    treated specially in this case.
   </para>

   <para>
    To quit the session, type <acronym>EOF</acronym>
    (<keycombo action="simul"><keycap>Control</><keycap>D</></>, usually).
    If you've
    used <option>-N</>, two consecutive <acronym>EOF</>s are needed to exit.
   </para>

   <para>
    Note that the stand-alone server does not provide sophisticated
    line-editing features (no command history, for example).
   </para>

 </refsect1>

 <refsect1>
  <title>See Also</title>

  <para>
   <xref linkend="app-initdb">,
   <xref linkend="app-ipcclean">,
   <xref linkend="app-postmaster">
  </para>
 </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:
-->
