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

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.46 2006/01/05 10:07:44 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>
   <command>postgres</command>
   <arg rep="repeat"><replaceable>option</></arg>
   <arg choice="plain"><replaceable>database</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   The <command>postgres</command> executable is the actual
   <productname>PostgreSQL</productname> server process that processes
   SQL statements.  It is normally not called directly; instead a
   <xref linkend="app-postmaster"> multiuser server is started.
   Conceptually, the <command>postmaster</command> starts a new
   <command>postgres</command> process for each connection.
   (<filename>postmaster</filename> and <filename>postgres</filename>
   are in fact the same program, and on most platforms the connection
   process is forked).
  </para>

  <para>
   If the <command>postgres</command> command is called directly, it
   invokes the server 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.
   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.  In single-user mode, <command>postgres</command> accepts
    all the options that <command>postmaster</command> would accept.
   </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>-e</option>, <option>-F</option>, <option>-s</option>,
     <option>-S</option>, and <option>--<replaceable>name</></option>
     have the same meanings as with 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</>.  Other <command>postmaster</command>
     options are also accepted but will have no noticeable effect
     because they only apply to the multiuser server mode, namely
     <option>-h</option>, <option>-i</option>, <option>-k</option>,
     <option>-l</option>, and <option>-n</option>.
    </para>
   </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>-j</option></term>
      <listitem>
       <para>
	Disables use of newline as a statement delimiter.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-r</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>
    </variablelist>
   </refsect2>

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

    <para>
     The options <option>-f</option>, <option>-O</option>,
     <option>-P</option>, <option>-t</option>, and <option>-W</option>
     have the same meanings as with the <xref
     linkend="app-postmaster"> and are reserved for debugging and
     disaster recovery.  Further options for internal use are:

    <variablelist>
     <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>-y</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>--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>
    </para>
   </refsect2>
 </refsect1>

 <refsect1>
  <title>Environment</title>

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

    <listitem>
     <para>
      Default data directory location
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </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 &mdash; 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>-j</> 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>-j</>, 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:
-->