postgres-ref.sgml

PostgreSQL7.4.6 for Linux

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.41 2003/11/02 12:58:11 petere 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>sort-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>sort-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">sort-mem</replaceable></term>
      <listitem>
       <para>
	Specifies the amount of memory to be used by internal sorts and hashes
	before resorting to temporary disk files.  The value is specified in
	kilobytes, and defaults to 1024.  Note that for a complex query,
	several sorts and/or hashes might be running in parallel, and each one
	will be allowed to use as much as
	<replaceable class="parameter">sort-mem</replaceable> kilobytes
	before it starts to put data into temporary files.
       </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>