head	1.52;
access;
symbols
	REL9_0_0:1.52
	REL9_1_ALPHA1:1.52
	REL9_0_RC1:1.52
	REL9_0_BETA4:1.52
	REL9_0_STABLE:1.52.0.4
	REL9_0_BETA3:1.52
	REL9_0_BETA2:1.52
	REL7_4_29:1.41
	REL8_0_25:1.45
	REL8_1_21:1.45
	REL8_2_17:1.47.2.1
	REL8_3_11:1.51
	REL8_4_4:1.51
	REL9_0_BETA1:1.52
	REL9_0_ALPHA5_BRANCH:1.52.0.2
	REL9_0_ALPHA5:1.52
	REL7_4_28:1.41
	REL8_0_24:1.45
	REL8_1_20:1.45
	REL8_2_16:1.47.2.1
	REL8_3_10:1.51
	REL8_4_3:1.51
	REL9_0_ALPHA4:1.51
	REL9_0_ALPHA4_BRANCH:1.51.0.12
	REL8_5_ALPHA3:1.51
	REL8_5_ALPHA3_BRANCH:1.51.0.10
	REL7_4_27:1.41
	REL8_0_23:1.45
	REL8_1_19:1.45
	REL8_2_15:1.47.2.1
	REL8_3_9:1.51
	REL8_4_2:1.51
	REL8_5_ALPHA2:1.51
	REL8_5_ALPHA2_BRANCH:1.51.0.8
	REL7_4_26:1.41
	REL8_0_22:1.45
	REL8_1_18:1.45
	REL8_2_14:1.47.2.1
	REL8_3_8:1.51
	REL8_4_1:1.51
	REL8_5_ALPHA1:1.51
	REL8_5_ALPHA1_BRANCH:1.51.0.6
	REL8_4_STABLE:1.51.0.4
	REL8_4_0:1.51
	REL8_4_RC2:1.51
	REL8_4_RC1:1.51
	REL8_4_BETA2:1.51
	REL8_4_BETA1:1.51
	REL7_4_25:1.41
	REL8_0_21:1.45
	REL8_1_17:1.45
	REL8_2_13:1.47.2.1
	REL8_3_7:1.51
	REL7_4_24:1.41
	REL8_0_20:1.45
	REL8_1_16:1.45
	REL8_2_12:1.47.2.1
	REL8_3_6:1.51
	REL7_4_23:1.41
	REL8_0_19:1.45
	REL8_1_15:1.45
	REL8_2_11:1.47.2.1
	REL8_3_5:1.51
	REL7_4_22:1.41
	REL8_0_18:1.45
	REL8_1_14:1.45
	REL8_2_10:1.47.2.1
	REL8_3_4:1.51
	REL7_4_21:1.41
	REL8_0_17:1.45
	REL8_1_13:1.45
	REL8_2_9:1.47.2.1
	REL8_3_3:1.51
	REL7_4_20:1.41
	REL8_0_16:1.45
	REL8_1_12:1.45
	REL8_2_8:1.47.2.1
	REL8_3_2:1.51
	REL8_2_7:1.47.2.1
	REL8_3_1:1.51
	REL8_3_STABLE:1.51.0.2
	REL8_3_0:1.51
	REL8_3_RC2:1.51
	REL7_3_21:1.29
	REL7_4_19:1.41
	REL8_0_15:1.45
	REL8_1_11:1.45
	REL8_2_6:1.47.2.1
	REL8_3_RC1:1.51
	REL8_3_BETA4:1.51
	REL8_3_BETA3:1.51
	REL8_3_BETA2:1.51
	REL8_3_BETA1:1.51
	REL7_3_20:1.29
	REL7_4_18:1.41
	REL8_0_14:1.45
	REL8_1_10:1.45
	REL8_2_5:1.47.2.1
	REL7_3_19:1.29
	REL7_4_17:1.41
	REL8_0_13:1.45
	REL8_1_9:1.45
	REL8_2_4:1.47.2.1
	REL8_0_12:1.45
	REL8_1_8:1.45
	REL8_2_3:1.47.2.1
	REL7_3_18:1.29
	REL7_4_16:1.41
	REL8_0_11:1.45
	REL8_1_7:1.45
	REL8_2_2:1.47.2.1
	REL8_0_10:1.45
	REL8_1_6:1.45
	REL8_2_1:1.47.2.1
	REL7_4_15:1.41
	REL7_3_17:1.29
	REL8_2_STABLE:1.47.0.2
	REL8_2_0:1.47
	REL8_2_RC1:1.47
	REL8_2_BETA3:1.47
	REL8_2_BETA2:1.47
	REL8_1_5:1.45
	REL8_0_9:1.45
	REL7_4_14:1.41
	REL7_3_16:1.29
	REL8_2_BETA1:1.47
	REL7_3_15:1.29
	REL7_4_13:1.41
	REL8_0_8:1.45
	REL8_1_4:1.45
	REL7_3_14:1.29
	REL7_4_12:1.41
	REL8_0_7:1.45
	REL8_1_3:1.45
	REL7_3_13:1.29
	REL7_4_11:1.41
	REL8_0_6:1.45
	REL8_1_2:1.45
	REL7_3_12:1.29
	REL7_4_10:1.41
	REL8_0_5:1.45
	REL8_1_1:1.45
	REL8_1_STABLE:1.45.0.6
	REL8_1_0:1.45
	REL8_1_0RC1:1.45
	REL8_1_0BETA4:1.45
	REL8_1_0BETA3:1.45
	REL7_3_11:1.29
	REL7_4_9:1.41
	REL8_0_4:1.45
	REL8_1_0BETA2:1.45
	REL8_1_0BETA1:1.45
	REL7_2_8:1.23
	REL7_3_10:1.29
	REL7_4_8:1.41
	REL8_0_3:1.45
	REL8_0_2:1.45
	REL7_2_7:1.23
	REL7_3_9:1.29
	REL7_4_7:1.41
	REL8_0_1:1.45
	REL8_0_STABLE:1.45.0.4
	REL8_0_0:1.45.0.2
	REL8_0_0RC5:1.45
	REL8_0_0RC4:1.45
	REL8_0_0RC3:1.45
	REL8_0_0RC2:1.45
	REL8_0_0RC1:1.45
	REL8_0_0BETA5:1.45
	REL8_0_0BETA4:1.44
	REL7_4_6:1.41
	REL7_3_8:1.29
	REL7_2_6:1.23
	REL8_0_0BETA3:1.43
	REL8_0_0BETA2:1.43
	REL7_2_5:1.23
	REL7_4_5:1.41
	REL7_3_7:1.29
	REL7_4_4:1.41
	REL8_0_0BETA1:1.43
	REL7_4_3:1.41
	REL7_4_2:1.41
	REL7_3_6:1.29
	REL7_4_1:1.41
	REL7_3_5:1.29
	REL7_4:1.41
	REL7_4_RC2:1.41
	REL7_4_STABLE:1.41.0.2
	REL7_4_RC1:1.41
	REL7_4_BETA5:1.38
	REL7_4_BETA4:1.37
	REL7_4_BETA3:1.35
	REL7_4_BETA2:1.34
	WIN32_DEV:1.34.0.2
	REL7_4_BETA1:1.34
	REL7_3_4:1.29
	REL7_3_2:1.29
	REL7_2_4:1.23
	REL7_3_STABLE:1.29.0.2
	REL7_2_3:1.23
	REL7_2_STABLE:1.23.0.2
	REL7_2:1.23
	REL7_2_RC2:1.23
	REL7_2_RC1:1.23
	REL7_2_BETA5:1.23
	REL7_2_BETA4:1.23
	REL7_2_BETA3:1.20
	REL7_2_BETA2:1.20
	REL7_2_BETA1:1.20
	REL7_1_2:1.17
	REL7_1_STABLE:1.17.0.2
	REL7_1_BETA:1.15
	REL7_1_BETA3:1.16
	REL7_1_BETA2:1.16
	REL7_1:1.17
	REL7_0_PATCHES:1.9.0.2
	REL7_0:1.9
	REL6_5_PATCHES:1.4.0.2
	REL6_5:1.4;
locks; strict;
comment	@# @;


1.52
date	2010.02.22.22.30.10;	author momjian;	state Exp;
branches;
next	1.51;

1.51
date	2007.07.09.01.08.09;	author tgl;	state Exp;
branches;
next	1.50;

1.50
date	2007.02.16.02.10.07;	author alvherre;	state Exp;
branches;
next	1.49;

1.49
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches;
next	1.48;

1.48
date	2007.01.04.00.57.51;	author tgl;	state Exp;
branches;
next	1.47;

1.47
date	2006.06.18.15.38.36;	author petere;	state Exp;
branches
	1.47.2.1;
next	1.46;

1.46
date	2006.01.05.10.07.44;	author petere;	state Exp;
branches;
next	1.45;

1.45
date	2004.11.15.06.32.15;	author neilc;	state Exp;
branches;
next	1.44;

1.44
date	2004.10.08.01.36.32;	author tgl;	state Exp;
branches;
next	1.43;

1.43
date	2004.02.03.17.34.02;	author tgl;	state Exp;
branches;
next	1.42;

1.42
date	2003.11.29.19.51.39;	author pgsql;	state Exp;
branches;
next	1.41;

1.41
date	2003.11.02.12.58.11;	author petere;	state Exp;
branches;
next	1.40;

1.40
date	2003.10.28.19.39.18;	author momjian;	state Exp;
branches;
next	1.39;

1.39
date	2003.10.28.15.01.27;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	2003.10.16.17.38.01;	author momjian;	state Exp;
branches;
next	1.37;

1.37
date	2003.09.24.18.54.01;	author tgl;	state Exp;
branches;
next	1.36;

1.36
date	2003.09.18.20.30.15;	author tgl;	state Exp;
branches;
next	1.35;

1.35
date	2003.08.31.17.32.24;	author petere;	state Exp;
branches;
next	1.34;

1.34
date	2003.07.29.00.03.17;	author tgl;	state Exp;
branches
	1.34.2.1;
next	1.33;

1.33
date	2003.05.02.20.54.33;	author tgl;	state Exp;
branches;
next	1.32;

1.32
date	2003.03.25.16.15.43;	author petere;	state Exp;
branches;
next	1.31;

1.31
date	2003.03.24.14.32.51;	author petere;	state Exp;
branches;
next	1.30;

1.30
date	2003.01.19.00.13.31;	author momjian;	state Exp;
branches;
next	1.29;

1.29
date	2002.10.23.23.33.08;	author momjian;	state Exp;
branches;
next	1.28;

1.28
date	2002.10.11.23.03.48;	author petere;	state Exp;
branches;
next	1.27;

1.27
date	2002.07.28.15.22.21;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2002.04.21.19.02.39;	author thomas;	state Exp;
branches;
next	1.25;

1.25
date	2002.03.22.19.20.43;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2002.03.02.21.39.16;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2001.12.08.03.24.38;	author thomas;	state Exp;
branches;
next	1.22;

1.22
date	2001.11.28.20.49.10;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2001.11.25.01.11.36;	author tgl;	state Exp;
branches;
next	1.20;

1.20
date	2001.09.27.16.29.12;	author tgl;	state Exp;
branches;
next	1.19;

1.19
date	2001.09.08.15.24.00;	author petere;	state Exp;
branches;
next	1.18;

1.18
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2001.03.17.16.27.31;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.15;

1.15
date	2000.11.14.18.11.31;	author petere;	state Exp;
branches;
next	1.14;

1.14
date	2000.10.05.19.48.18;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2000.07.22.04.45.09;	author momjian;	state Exp;
branches;
next	1.12;

1.12
date	2000.07.21.17.58.49;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2000.07.21.03.14.33;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	2000.07.21.03.13.32;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	2000.05.08.16.19.56;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	2000.05.03.07.33.44;	author inoue;	state Exp;
branches;
next	1.7;

1.7
date	2000.03.27.17.14.43;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	99.08.06.13.50.31;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	99.07.22.15.09.14;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	99.07.06.17.16.41;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	99.06.14.07.37.04;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	99.05.27.15.49.15;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	99.05.26.17.25.38;	author thomas;	state Exp;
branches;
next	;

1.34.2.1
date	2003.09.07.04.36.46;	author momjian;	state Exp;
branches;
next	;

1.47.2.1
date	2007.01.04.00.58.01;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.52
log
@Document that pg_ctl cares about the PGHOST environment variable.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.51 2007/07/09 01:08:09 tgl Exp $
PostgreSQL documentation
-->

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

 <refnamediv>
  <refname>postgres</refname>
  <refpurpose><productname>PostgreSQL</productname> database server</refpurpose>
 </refnamediv>

 <indexterm zone="app-postgres">
  <primary>postgres</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>postgres</command>
   <arg rep="repeat"><replaceable>option</></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>postgres</command> is the
   <productname>PostgreSQL</productname> database server.  In order
   for a client application to access a database it connects (over a
   network or locally) to a running <command>postgres</command> instance.
   The <command>postgres</command> instance then starts a separate server
   process to handle the connection.
  </para>

  <para>
   One <command>postgres</command> instance always manages the data of
   exactly one database cluster.  A database cluster is a collection
   of databases that is stored at a common file system location (the
   <quote>data area</quote>).  More than one
   <command>postgres</command> instance can run on a system at one
   time, so long as they use different data areas and different
   communication ports (see below).  When
   <command>postgres</command> starts it needs to know the location
   of the data area.  The location must be specified by the
   <option>-D</option> option or the <envar>PGDATA</envar> environment
   variable; there is no default.  Typically, <option>-D</option> or
   <envar>PGDATA</envar> points directly to the data area directory
   created by <xref linkend="app-initdb">.  Other possible file layouts are
   discussed in <xref linkend="runtime-config-file-locations">.
  </para>

  <para>
   By default <command>postgres</command> starts in the
   foreground and prints log messages to the standard error stream.  In
   practical applications <command>postgres</command>
   should be started as a background process, perhaps at boot time.
  </para>

  <para>
   The <command>postgres</command> command can also be called in
   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 (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).
   When invoked in single-user
   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.  In the single-user mode,
   the session user will be set to the user with ID 1, and implicit
   superuser powers are granted to this user.
   This user does not actually have to exist, so the single-user mode
   can be used to manually recover from certain
   kinds of accidental damage to the system catalogs.
  </para>
 </refsect1>

 <refsect1 id="app-postgres-options">
  <title>Options</title>

   <para>
    <command>postgres</command> accepts the following command-line
    arguments.  For a detailed discussion of the options consult <xref
    linkend="runtime-config">.  You can save typing most of these
    options by setting up a configuration file.  Some (safe) options
    can also be set from the connecting client in an
    application-dependent way to apply only for that session.  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>
    
    <variablelist>
     <varlistentry>
      <term><option>-A 0|1</option></term>
      <listitem>
       <para>
        Enables run-time assertion checks, which is a debugging aid to
        detect programming mistakes.  This option is only available if
        assertions were enabled when <productname>PostgreSQL</> was
        compiled. If so, the default is on.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
      <listitem>
       <para>
        Sets the number of shared buffers for use by the server
        processes.  The default value of this parameter is chosen
        automatically by <application>initdb</application>.
        Specifying this option is equivalent to setting the
        <xref linkend="guc-shared-buffers"> configuration parameter.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
      <listitem>
       <para>
        Sets a named run-time parameter. The configuration parameters
        supported by <productname>PostgreSQL</productname> are
        described in <xref linkend="runtime-config">. Most of the
        other command line options are in fact short forms of such a
        parameter assignment.  <option>-c</> can appear multiple times
        to set multiple parameters.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-d <replaceable>debug-level</replaceable></option></term>
      <listitem>
       <para>
        Sets the debug level.  The higher this value is set, the more
        debugging output is written to the server log.  Values are
        from 1 to 5.  It is also possible to pass <literal>-d
        0</literal> for a specific session, which will prevent the
        server log level of the parent <command>postgres</> process from being
        propagated to this session.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
      <listitem>
       <para>
        Specifies the file system location of the data directory or
        configuration file(s).  See
        <xref linkend="runtime-config-file-locations"> for details.
       </para>
      </listitem>
     </varlistentry>

     <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>-F</option></term>
      <listitem>
       <para>
        Disables <function>fsync</function> calls for improved
        performance, at the risk of data corruption in the event of a
        system crash.  Specifying this option is equivalent to
        disabling the <xref linkend="guc-fsync"> configuration
        parameter. Read the detailed documentation before using this!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
      <listitem>
       <para>
        Specifies the IP host name or address on which
        <command>postgres</command> is to listen for TCP/IP
        connections from client applications.  The value can also be a
        comma-separated list of addresses, or <literal>*</> to specify
        listening on all available interfaces.  An empty value
        specifies not listening on any IP addresses, in which case
        only Unix-domain sockets can be used to connect to the
        server.  Defaults to listening only on
        <systemitem class="systemname">localhost</systemitem>.
        Specifying this option is equivalent to setting the <xref
        linkend="guc-listen-addresses"> configuration parameter.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i</option></term>
      <listitem>
       <para>
        Allows remote clients to connect via TCP/IP (Internet domain)
        connections.  Without this option, only local connections are
        accepted.  This option is equivalent to setting
        <varname>listen_addresses</> to <literal>*</> in
        <filename>postgresql.conf</> or via <option>-h</>.
       </para>
       <para>
        This option is deprecated since it does not allow access to the
        full functionality of <xref linkend="guc-listen-addresses">.
        It's usually better to set <varname>listen_addresses</> directly.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
      <listitem>
       <para>
        Specifies the directory of the Unix-domain socket on which
        <command>postgres</command> is to listen for
        connections from client applications.  The default is normally
        <filename>/tmp</filename>, but can be changed at build time.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-l</option></term>
      <listitem>
       <para>
        Enables secure connections using <acronym>SSL</acronym>.
        <productname>PostgreSQL</productname> must have been compiled with
        support for <acronym>SSL</acronym> for this option to be
        available. For more information on using <acronym>SSL</acronym>,
        refer to <xref linkend="ssl-tcp">.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
      <listitem>
       <para>
        Sets the maximum number of client connections that this
        server will accept.  The default value of this parameter is chosen
        automatically by <application>initdb</application>.
        Specifying this option is equivalent to setting the
        <xref linkend="guc-max-connections"> configuration parameter.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
      <listitem>
       <para>
        The command-line-style options specified in <replaceable
        class="parameter">extra-options</replaceable> are passed to
        all server processes started by this
        <command>postgres</command> process.  If the option string contains
        any spaces, the entire string must be quoted.
       </para>

       <para>
        The use of this option is obsolete; all command-line options
        for server processes can be specified directly on the
        <command>postgres</command> command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
      <listitem>
       <para>
        Specifies the TCP/IP port or local Unix domain socket file
        extension on which <command>postgres</command>
        is to listen for connections from client applications.
        Defaults to the value of the <envar>PGPORT</envar> environment
        variable, or if <envar>PGPORT</envar> is not set, then
        defaults to the value established during compilation (normally
        5432).  If you specify a port other than the default port,
        then all client applications must specify the same port using
        either command-line options or <envar>PGPORT</envar>.
       </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>

     <varlistentry>
      <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
      <listitem>
       <para>
        Sets a named run-time parameter; a shorter form of
        <option>-c</>.
       </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>

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

    <para>
     The options described here are used
     mainly for debugging purposes, and in some cases to assist with
     recovery of severely damaged databases. There should be no reason
     to use them in a production database setup.  They are listed
     here only for use by <productname>PostgreSQL</productname>
     system developers.  Furthermore, these options might
     change or be removed 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>
        
       <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>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-n</option></term>
      <listitem>
       <para>
        This option is for debugging problems that cause a server
        process to die abnormally.  The ordinary strategy in this
        situation is to notify all other server processes that they
        must terminate and then reinitialize the shared memory and
        semaphores.  This is because an errant server process could
        have corrupted some shared state before terminating.  This
        option specifies that <command>postgres</command> will
        not reinitialize shared data structures.  A knowledgeable
        system programmer can then use a debugger to examine shared
        memory and semaphore state.
       </para>
     </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></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>-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>-T</option></term>
      <listitem>
       <para>
        This option is for debugging problems that cause a server
        process to die abnormally.  The ordinary strategy in this
        situation is to notify all other server processes that they
        must terminate and then reinitialize the shared memory and
        semaphores.  This is because an errant server process could
        have corrupted some shared state before terminating.  This
        option specifies that <command>postgres</command> will
        stop all other server processes by sending the signal
        <literal>SIGSTOP</literal>, but will not cause them to
        terminate.  This permits system programmers to collect core
        dumps from all server processes by hand.
       </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 a particular session.  This option is for
        internal use only.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
      <listitem>
       <para>
        A delay of this many seconds occurs when a new server process
        is started, after it conducts the authentication procedure.
        This is intended to give an opportunity to attach to the
        server process with a debugger.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect2>

   <refsect2>
    <title>Options for single-user mode</title>

    <para>
     The following options only apply to the single-user mode.
    </para>

    <variablelist>
     <varlistentry>
      <term><option>--single</option></term>
      <listitem>
       <para>
        Selects the single-user mode.  This must be the first argument
        on the command line.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">database</replaceable></term>
      <listitem>
       <para>
        Specifies the name of the database to be accessed.  This must be
        the last argument on the command line.  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>.  In normal multiuser
        mode, this option is ignored, and <systemitem>stderr</> is
        used by all processes.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect2>
 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGCLIENTENCODING</envar></term>

    <listitem>
     <para>
      Default character encoding used by clients.  (The clients can
      override this individually.)  This value can also be set in the
      configuration file.
     </para>
    </listitem>
   </varlistentry>

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

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

   <varlistentry>
    <term><envar>PGDATESTYLE</envar></term>

    <listitem>
     <para>
      Default value of the <xref linkend="guc-datestyle"> run-time
      parameter.  (The use of this environment variable is deprecated.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGPORT</envar></term>

    <listitem>
     <para>
      Default port number (preferably set in the configuration file)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>TZ</envar></term>

    <listitem>
     <para>
      Server time zone
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>

 <refsect1>
   <title>Diagnostics</title>

   <para>
    A failure message mentioning <literal>semget</> or
    <literal>shmget</> probably indicates you need to configure your
    kernel to provide adequate shared memory and semaphores.  For more
    discussion see <xref linkend="kernel-resources">.  You might be able
    to postpone reconfiguring your kernel by decreasing <xref
    linkend="guc-shared-buffers"> to reduce the shared memory
    consumption of <productname>PostgreSQL</>, and/or by reducing
    <xref linkend="guc-max-connections"> to reduce the semaphore
    consumption.
   </para>

   <para>
    A failure message suggesting that another server is already running
    should be checked carefully, for example by using the command
<screen>
<prompt>$</prompt> <userinput>ps ax | grep postgres</userinput>
</screen>
        or
<screen>
<prompt>$</prompt> <userinput>ps -ef | grep postgres</userinput>
</screen>
    depending on your system.  If you are certain that no conflicting
    server is running, you can remove the lock file mentioned in the
    message and try again.
   </para>

   <para>
    A failure message indicating inability to bind to a port might
    indicate that that port is already in use by some
    non-<productname>PostgreSQL</productname> process.  You might also
    get this error if you terminate <command>postgres</command>
    and immediately restart it using the same port; in this case, you
    must simply wait a few seconds until the operating system closes
    the port before trying again.  Finally, you might get this error if
    you specify a port number that your operating system considers to
    be reserved.  For example, many versions of Unix consider port
    numbers under 1024 to be <quote>trusted</quote> and only permit
    the Unix superuser to access them.
   </para>

 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   The utility command <xref linkend="app-pg-ctl"> can be used to
   start and shut down the <command>postgres</command> server
   safely and comfortably.
  </para>
  
  <para>
   If at all possible, <emphasis>do not</emphasis> use
   <literal>SIGKILL</literal> to kill the main
   <command>postgres</command> server.  Doing so will prevent
   <command>postgres</command> from freeing the system
   resources (e.g., shared memory and semaphores) that it holds before
   terminating.  This might cause problems for starting a fresh
   <command>postgres</command> run.
  </para>

  <para>
   To terminate the <command>postgres</command> server normally, the
   signals <literal>SIGTERM</literal>, <literal>SIGINT</literal>, or
   <literal>SIGQUIT</literal> can be used.  The first will wait for
   all clients to terminate before quitting, the second will
   forcefully disconnect all clients, and the third will quit
   immediately without proper shutdown, resulting in a recovery run
   during restart.
  </para>

  <para>
   The <literal>SIGHUP</literal> signal will reload
   the server configuration files.  It is also possible to send
   <literal>SIGHUP</literal> to an individual server process, but that
   is usually not sensible.
  </para>

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

  <para>
   The <command>postgres</command> server uses <literal>SIGTERM</literal>
   to tell subordinate server processes 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 server
   process &mdash; the main <command>postgres</command> process will
   interpret this as a crash and will force all the sibling processes
   to quit as part of its standard crash-recovery procedure.
  </para>
 </refsect1>

 <refsect1 id="app-postgres-bugs">
  <title>Bugs</title>
  <para>
   The <option>--</> options will not work on <systemitem
   class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>.
   Use <option>-c</> instead. This is a bug in the affected operating
   systems; a future release of <productname>PostgreSQL</productname>
   will provide a workaround if this is not fixed.
  </para>
 </refsect1>

 <refsect1>
  <title>Usage</title>

   <para>
    To start a single-user mode server, use a command like
<screen>
<userinput>postgres --single -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 single-user mode 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 single-user mode server does not provide sophisticated
    line-editing features (no command history, for example).
   </para>
 </refsect1>

 <refsect1 id="app-postgres-examples">
  <title>Examples</title>

  <para>
   To start <command>postgres</command> in the background
   using default values, type:

<screen>
<prompt>$</prompt> <userinput>nohup postgres &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
</screen>
  </para>

  <para>
   To start <command>postgres</command> with a specific
   port:
<screen>
<prompt>$</prompt> <userinput>postgres -p 1234</userinput>
</screen>
   This command will start up <command>postgres</command>
   communicating through the port 1234. In order to connect to this
   server using <application>psql</>, you would need to run it as
<screen>
<prompt>$</prompt> <userinput>psql -p 1234</userinput>
</screen>
   or set the environment variable <envar>PGPORT</envar>:
<screen>
<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
<prompt>$</prompt> <userinput>psql</userinput>
</screen>
  </para>

  <para>
   Named run-time parameters can be set in either of these styles:
<screen>
<prompt>$</prompt> <userinput>postgres -c work_mem=1234</userinput>
<prompt>$</prompt> <userinput>postgres --work-mem=1234</userinput>
</screen>
   Either form overrides whatever setting might exist for
   <varname>work_mem</> in <filename>postgresql.conf</>.  Notice that
   underscores in parameter names can be written as either underscore
   or dash on the command line.  Except for short-term experiments,
   it's probably better practice to edit the setting in
   <filename>postgresql.conf</> than to rely on a command-line switch
   to set a parameter.
  </para>
 </refsect1>

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

  <para>
   <xref linkend="app-initdb">,
   <xref linkend="app-pg-ctl">
  </para>
 </refsect1>
</refentry>
@


1.51
log
@Minor copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.50 2007/02/16 02:10:07 alvherre Exp $
d582 1
a582 1
      Default port (preferably set in the configuration file)
@


1.50
log
@Remove useless database name from bootstrap argument processing (including
startup and bgwriter processes), and the -y flag.  It's not used anywhere.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.49 2007/01/31 23:26:04 momjian Exp $
d36 1
a36 1
   network or locally) to a running <command>postgres</command> process.
d42 1
a42 1
   One <command>postgres</command> instance always manages the data from
d46 1
a46 1
   <command>postgres</command> process can run on a system at one
d122 3
a124 2
        automatically by <application>initdb</application>; refer to <xref
        linkend="runtime-config-resource-memory"> for more information.
d260 3
a262 7
        server will accept.  By
        default, this value is 32, but it can be set as high as your
        system will support.  (Note that
        <option>-B</option> is required to be at least twice
        <option>-N</option>.  See <xref linkend="kernel-resources"> for a discussion of
        system resource requirements for large numbers of client
        connections.) Specifying this option is equivalent to setting the
d272 1
a272 1
        The command line-style options specified in <replaceable
d354 2
a355 2
     There are several other options that can be specified, used
     mainly for debugging purposes and in some cases to assist with
d357 2
a358 2
     to use them in a production database setup.  These are listed
     here only for the use by <productname>PostgreSQL</productname>
d500 3
a502 2
        Specifies the name of the database to be accessed.  If it is
        omitted it defaults to the user name.   
d648 6
d672 5
a676 1
   during restart.  The <literal>SIGHUP</literal> signal will reload
a682 6
   The utility command <xref linkend="app-pg-ctl"> can be used to
   start and shut down the <command>postgres</command> server
   safely and comfortably.
  </para>

  <para>
@


1.49
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.48 2007/01/04 00:57:51 tgl Exp $
a477 11

     <varlistentry>
      <term><option>-y</option> <replaceable class="parameter">database</replaceable></term>
      <listitem>
       <para>
        Indicates that this is a subprocess started by a parent
        <command>postgres</command> process, and specifies the database to
        use.  This option is for internal use only.
       </para>
      </listitem>
     </varlistentry>
@


1.48
log
@Fix erroneous implementation of -s in postmaster.c (the switch doesn't take
an optarg).  Add some comments noting that code in three different files has
to be kept in sync.  Fix erroneous description of -S switch (it sets work_mem
not silent_mode), and do some light copy-editing elsewhere in postgres-ref.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.47 2006/06/18 15:38:36 petere Exp $
d357 1
a357 1
     There are several other options that may be specified, used
d362 2
a363 2
     system developers.  Furthermore, any of these options may
     disappear or change in a future release without notice.
d562 1
a562 1
      Default character encoding used by clients.  (The clients may
d620 1
a620 1
    discussion see <xref linkend="kernel-resources">.  You may be able
d639 1
a639 1
    server is running, you may remove the lock file mentioned in the
d644 1
a644 1
    A failure message indicating inability to bind to a port may
d646 1
a646 1
    non-<productname>PostgreSQL</productname> process.  You may also
d650 1
a650 1
    the port before trying again.  Finally, you may get this error if
d668 1
a668 1
   terminating.  This may cause problems for starting a fresh
@


1.47
log
@Merge postmaster and postgres command into just postgres.  postmaster
symlink is kept for now for compatibility.  To call single-user mode, use
postgres --single.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.56 2006/01/06 01:35:09 tgl Exp $
d54 2
a55 3
   created by <application>initdb</>.  Other possible file layouts are
   discussed in <xref linkend="runtime-config-file-locations">.  A
   data area is created with <xref linkend="app-initdb">.
d61 1
a61 1
   practical applications the <command>postgres</command>
d69 4
a72 1
   for debugging or disaster recovery.  When invoked in interactive
d75 6
a80 9
   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.  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 single-user
   mode.
d120 4
a123 4
	Sets the number of shared buffers for use by the server
	processes.  The default value of this parameter is chosen
	automatically by <application>initdb</application>; refer to <xref
	linkend="runtime-config-resource-memory"> for more information.
d150 1
a150 1
        server log level of the <command>postgres</> from being
d172 3
a174 3
	<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.
a188 5

       <para>
        <option>--fsync=true</option> has the opposite effect
        of this option.
       </para>
d203 1
a203 1
        <command>postgres</command>.  Defaults to listening only on
d233 4
a236 4
	Specifies the directory of the Unix-domain socket on which
	<command>postgres</command> is to listen for
	connections from client applications.  The default is normally
	<filename>/tmp</filename>, but can be changed at build time.
d245 5
a249 5
	Enables secure connections using <acronym>SSL</acronym>.
	<productname>PostgreSQL</productname> must have been compiled with
	support for <acronym>SSL</acronym> for this option to be
	available. For more information on using <acronym>SSL</acronym>,
	refer to <xref linkend="ssl-tcp">.
d258 9
a266 9
	Sets the maximum number of client connections that this
	<command>postgres</command> will accept.  By
	default, this value is 32, but it can be set as high as your
	system will support.  (Note that
	<option>-B</option> is required to be at least twice
	<option>-N</option>.  See <xref linkend="kernel-resources"> for a discussion of
	system resource requirements for large numbers of client
	connections.) Specifying this option is equivalent to setting the
	<xref linkend="guc-max-connections"> configuration parameter.
d275 5
a279 5
	The command line-style options specified in <replaceable
	class="parameter">extra-options</replaceable> are passed to
	all server processes started by this
	<command>postgres</command>.  If the option string contains
	any spaces, the entire string must be quoted.
d285 1
a285 1
        <command>postgres</command> command line
d294 9
a302 9
	Specifies the TCP/IP port or local Unix domain socket file
	extension on which <command>postgres</command>
	is to listen for connections from client applications.
	Defaults to the value of the <envar>PGPORT</envar> environment
	variable, or if <envar>PGPORT</envar> is not set, then
	defaults to the value established during compilation (normally
	5432).  If you specify a port other than the default port,
	then all client applications must specify the same port using
	either command-line options or <envar>PGPORT</envar>.
d311 3
a313 3
	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.
d319 1
a319 1
      <term><option>-S</option></term>
d322 4
a325 15
	Specifies that the <command>postgres</command>
	process should start up in silent mode.  That is, it will
	disassociate from the user's (controlling) terminal, start its
	own process group, and redirect its standard output and
	standard error to <filename>/dev/null</filename>.
       </para>
       <para>
        Using this switch discards all logging output, which is
	probably not what you want, since it makes it very difficult
	to troubleshoot problems.  See below for a better way to start
	<command>postgres</command> in the background.
       </para>
       <para>
        <option>--silent-mode=false</option> has the opposite effect
        of this option.
d371 5
a375 5
	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.
d377 1
a377 1
	
d409 2
a410 2
	Allows the structure of system tables to be modified.  This is
	used by <command>initdb</command>.
d419 3
a421 3
	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.
d430 3
a432 3
	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.
d460 3
a462 3
	Specifies the version number of the frontend/backend protocol
	to be used for a particular session.  This option is for
	internal use only.
d483 3
a485 3
	Indicates that this is a subprocess started by
	<command>postgres</command> and specifies the database to
	use.  This option is for internal use only.
d504 2
a505 2
	Selects the single-user mode.  This must be the first argument
	on the command line.
d514 2
a515 2
	Specifies the name of the database to be accessed.  If it is
	omitted it defaults to the user name.	
d524 1
a524 1
	Echo all commands.
d533 1
a533 1
	Disables use of newline as a statement delimiter.
d542 4
a545 4
	Send all server log output to <replaceable
	class="parameter">filename</replaceable>.  In normal multiuser
	mode, this option is ignored, and <systemitem>stderr</> is
	used by all processes.
d781 1
a781 2
   <command>postgres</command> using <application>psql</>, you would need to
   run it as
@


1.47.2.1
log
@Fix erroneous implementation of -s in postmaster.c (the switch doesn't take
an optarg).  Add some comments noting that code in three different files has
to be kept in sync.  Fix erroneous description of -S switch (it sets work_mem
not silent_mode), and do some light copy-editing elsewhere in postgres-ref.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.47 2006/06/18 15:38:36 petere Exp $
d54 3
a56 2
   created by <xref linkend="app-initdb">.  Other possible file layouts are
   discussed in <xref linkend="runtime-config-file-locations">.
d62 1
a62 1
   practical applications <command>postgres</command>
d70 1
a70 4
   for debugging or disaster recovery (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).
   When invoked in single-user
d73 9
a81 6
   for developers than end users.  In the single-user mode,
   the session user will be set to the user with ID 1, and implicit
   superuser powers are granted to this user.
   This user does not actually have to exist, so the single-user mode
   can be used to manually recover from certain
   kinds of accidental damage to the system catalogs.
d121 4
a124 4
        Sets the number of shared buffers for use by the server
        processes.  The default value of this parameter is chosen
        automatically by <application>initdb</application>; refer to <xref
        linkend="runtime-config-resource-memory"> for more information.
d151 1
a151 1
        server log level of the parent <command>postgres</> process from being
d173 3
a175 3
        <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.
d190 5
d209 1
a209 1
        server.  Defaults to listening only on
d239 4
a242 4
        Specifies the directory of the Unix-domain socket on which
        <command>postgres</command> is to listen for
        connections from client applications.  The default is normally
        <filename>/tmp</filename>, but can be changed at build time.
d251 5
a255 5
        Enables secure connections using <acronym>SSL</acronym>.
        <productname>PostgreSQL</productname> must have been compiled with
        support for <acronym>SSL</acronym> for this option to be
        available. For more information on using <acronym>SSL</acronym>,
        refer to <xref linkend="ssl-tcp">.
d264 9
a272 9
        Sets the maximum number of client connections that this
        server will accept.  By
        default, this value is 32, but it can be set as high as your
        system will support.  (Note that
        <option>-B</option> is required to be at least twice
        <option>-N</option>.  See <xref linkend="kernel-resources"> for a discussion of
        system resource requirements for large numbers of client
        connections.) Specifying this option is equivalent to setting the
        <xref linkend="guc-max-connections"> configuration parameter.
d281 5
a285 5
        The command line-style options specified in <replaceable
        class="parameter">extra-options</replaceable> are passed to
        all server processes started by this
        <command>postgres</command> process.  If the option string contains
        any spaces, the entire string must be quoted.
d291 1
a291 1
        <command>postgres</command> command line.
d300 9
a308 9
        Specifies the TCP/IP port or local Unix domain socket file
        extension on which <command>postgres</command>
        is to listen for connections from client applications.
        Defaults to the value of the <envar>PGPORT</envar> environment
        variable, or if <envar>PGPORT</envar> is not set, then
        defaults to the value established during compilation (normally
        5432).  If you specify a port other than the default port,
        then all client applications must specify the same port using
        either command-line options or <envar>PGPORT</envar>.
d317 3
a319 3
        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.
d325 1
a325 1
      <term><option>-S</option> <replaceable class="parameter">work-mem</replaceable></term>
d328 15
a342 4
        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">.
d388 5
a392 5
        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.
d394 1
a394 1
        
d426 2
a427 2
        Allows the structure of system tables to be modified.  This is
        used by <command>initdb</command>.
d436 3
a438 3
        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.
d447 3
a449 3
        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.
d477 3
a479 3
        Specifies the version number of the frontend/backend protocol
        to be used for a particular session.  This option is for
        internal use only.
d500 3
a502 3
        Indicates that this is a subprocess started by a parent
        <command>postgres</command> process, and specifies the database to
        use.  This option is for internal use only.
d521 2
a522 2
        Selects the single-user mode.  This must be the first argument
        on the command line.
d531 2
a532 2
        Specifies the name of the database to be accessed.  If it is
        omitted it defaults to the user name.   
d541 1
a541 1
        Echo all commands.
d550 1
a550 1
        Disables use of newline as a statement delimiter.
d559 4
a562 4
        Send all server log output to <replaceable
        class="parameter">filename</replaceable>.  In normal multiuser
        mode, this option is ignored, and <systemitem>stderr</> is
        used by all processes.
d798 2
a799 1
   server using <application>psql</>, you would need to run it as
@


1.46
log
@Make all command-line options of postmaster and postgres the same.  See
http://archives.postgresql.org/pgsql-hackers/2006-01/msg00151.php for the
complete plan.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.45 2004/11/15 06:32:15 neilc Exp $
d6 1
a6 1
<refentry id="APP-POSTGRES">
d8 1
a8 1
  <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
d15 1
a15 1
  <refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose>
d19 1
a19 1
  <primary>postgres (the program)</primary>
a25 1
   <arg choice="plain"><replaceable>database</replaceable></arg>
d33 6
a38 9
   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).
d42 15
a56 11
   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.
d60 19
a78 3
   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
d80 1
a80 1
   superuser powers are granted to the user with ID 1 in stand-alone
d85 1
a85 1
 <refsect1>
d89 9
a97 14
    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
d103 184
d288 7
a294 15
    <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>
d296 16
a311 2
   <refsect2>
    <title>Options for stand-alone mode</title>
a312 1
    <variablelist>
d314 1
a314 1
      <term><replaceable class="parameter">database</replaceable></term>
d317 3
a319 2
	Specifies the name of the database to be accessed.  If it is
	omitted it defaults to the user name.	
d325 1
a325 1
      <term><option>-E</option></term>
d328 15
a342 1
	Echo all commands.
d348 1
a348 1
      <term><option>-j</option></term>
d351 2
a352 1
	Disables use of newline as a statement delimiter.
d358 1
a358 1
      <term><option>-r</option> <replaceable class="parameter">filename</replaceable></term>
d361 3
a363 6
	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.
d374 8
a381 5
     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:
d385 89
d478 14
a491 1
	to be used for this particular session.
d500 23
a522 3
	Indicates that this process has been started by a
	<command>postmaster</command> and specifies the database to use.
	etc.
d528 29
a556 1
      <term><option>--describe-config</option></term>
d559 4
a562 3
        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.
a566 1
    </para>
d575 12
d595 32
d631 46
d678 23
d703 3
a705 2
   To cancel a running query, send the <literal>SIGINT</literal> signal
   to the <command>postgres</command> process running that command.
d709 2
a710 6
   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.
d714 2
a715 2
   The <command>postmaster</command> uses <literal>SIGTERM</literal>
   to tell a <command>postgres</command> process to quit normally and
d717 5
a721 6
   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.
d723 1
d725 9
d740 1
a740 1
    Start a stand-alone server with a command like
d742 1
a742 1
<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
d750 1
a750 1
    Normally, the stand-alone server treats newline as the command
d773 1
a773 1
    Note that the stand-alone server does not provide sophisticated
d776 4
d781 43
d831 1
a831 2
   <xref linkend="app-ipcclean">,
   <xref linkend="app-postmaster">
a833 1

a834 17

<!-- 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:
-->
@


1.45
log
@Replace "--" and "---" with "&mdash;" as appropriate, for better-looking
output.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.44 2004/10/08 01:36:32 tgl Exp $
a23 1
   <!-- standalone call -->
d25 1
a25 21
   <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>
a26 23
   <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>
d36 7
a42 14
   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.
d46 5
d74 3
a76 5
    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.
d96 10
a105 4
     <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</>.
a106 63

    <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>
d133 1
a133 1
      <term><option>-N</option></term>
a139 37
    </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>
d142 1
a142 1
      <term><option>-O</option></term>
d145 6
a150 2
	Allows the structure of system tables to be modified.  This is
	used by <command>initdb</command>.
d154 2
d157 2
a158 10
     <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>
d160 6
a165 10
     <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>
d167 1
d179 1
a179 1
      <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
d182 3
a184 3
	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.
a198 1

d200 1
a216 1

a217 5

  <para>
   For others, which have little influence during single-user mode,
   see <xref linkend="app-postmaster">.
  </para>
d273 1
a273 1
    But if you use the <option>-N</> command line switch, then newline does
d284 1
a284 1
    used <option>-N</>, two consecutive <acronym>EOF</>s are needed to exit.
@


1.44
log
@Whack some sense into the configuration-file-location patch.
Refactor code into something reasonably understandable, cause
use of the feature to not fail in standalone backends or in
EXEC_BACKEND case, fix sloppy guc.c table entries, make the
documentation minimally usable.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.43 2004/02/03 17:34:02 tgl Exp $
d396 1
a396 1
   process --- the <command>postmaster</command> will interpret this as
@


1.43
log
@Rename SortMem and VacuumMem to work_mem and maintenance_work_mem.
Make btree index creation and initial validation of foreign-key constraints
use maintenance_work_mem rather than work_mem as their memory limit.
Add some code to guc.c to allow these variables to be referenced by their
old names in SHOW and SET commands, for backwards compatibility.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.42 2003/11/29 19:51:39 pgsql Exp $
d360 1
a360 1
      Default data direction location
@


1.42
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.41 2003/11/02 12:58:11 petere Exp $
d44 1
a44 1
   <arg>-S <replaceable>sort-mem</replaceable></arg>
d67 1
a67 1
   <arg>-S <replaceable>sort-mem</replaceable></arg>
d200 1
a200 1
      <term><option>-S</option> <replaceable class="parameter">sort-mem</replaceable></term>
d204 3
a206 6
	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.
@


1.41
log
@Put --describe-config in the right place.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.40 2003/10/28 19:39:18 momjian Exp $
@


1.40
log
@Add --describe-config to top of postgres manual page.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.39 2003/10/28 15:01:27 momjian Exp $
d30 1
a69 1
   <arg>--describe-config</arg>
@


1.39
log
@Document --describe-config.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.38 2003/10/16 17:38:01 momjian Exp $
d69 1
@


1.38
log
@Add mention of SIGHUP on the postmaster manual page.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.37 2003/09/24 18:54:01 tgl Exp $
d334 11
@


1.37
log
@Repair some REINDEX problems per recent discussions.  The relcache is
now able to cope with assigning new relfilenode values to nailed-in-cache
indexes, so they can be reindexed using the fully crash-safe method.  This
leaves only shared system indexes as special cases.  Remove the 'index
deactivation' code, since it provides no useful protection in the shared-
index case.  Require reindexing of shared indexes to be done in standalone
mode, but remove other restrictions on REINDEX.  -P (IgnoreSystemIndexes)
now prevents using indexes for lookups, but does not disable index updates.
It is therefore safe to allow from PGOPTIONS.  Upshot: reindexing system catalogs
can be done without a standalone backend for all cases except
shared catalogs.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.36 2003/09/18 20:30:15 tgl Exp $
d373 1
a373 1
   To tell <command>postgres</command> to reread the configuration file,
d378 1
a378 1
   one <command>postgres</command> process reread the configuration file.
@


1.36
log
@Put a tad more detail in the discussion of postmaster and postgres
signal handling.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.35 2003/08/31 17:32:24 petere Exp $
d180 3
a182 3
	Ignore system indexes while scanning/updating system tables. The
	<command>REINDEX</command> command for system tables/indexes
	requires this option to be used.
@


1.35
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.34 2003/07/29 00:03:17 tgl Exp $
d368 15
a382 4
   To stop a running query use the <literal>SIGINT</literal> signal. To
   tell <command>postgres</command> to reread the configuration file,
   use a <literal>SIGHUP</literal> signal. The
   <command>postmaster</command> uses <literal>SIGTERM</literal>
d385 6
a390 1
   These <emphasis>should not</emphasis> be used by users.
@


1.34
log
@Apply (a somewhat revised version of) Greg Mullane's patch to eliminate
heuristic determination of day vs month in date/time input.  Add the
ability to specify that input is interpreted as yy-mm-dd order (which
formerly worked, but only for yy greater than 31).  DateStyle's input
component now has the preferred spellings DMY, MDY, or YMD; the older
keywords European and US are now aliases for the first two of these.
Per recent discussions on pgsql-general.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.33 2003/05/02 20:54:33 tgl Exp $
d17 4
@


1.34.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.35 2003/08/31 17:32:24 petere Exp $
a16 4

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


1.33
log
@Portal and memory management infrastructure for extended query protocol.
Both plannable queries and utility commands are now always executed
within Portals, which have been revamped so that they can handle the
load (they used to be good only for single SELECT queries).  Restructure
code to push command-completion-tag selection logic out of postgres.c,
so that it won't have to be duplicated between simple and extended queries.
initdb forced due to addition of a field to Query nodes.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.32 2003/03/25 16:15:43 petere Exp $
d150 4
a153 5
        Sets the default date style to <quote>European</quote>, which
	means that the <quote>day before month</quote> (rather than
	month before day) rule is used to interpret ambiguous date
	input, and that the day is printed before the month in certain
	date output formats.  See <xref linkend="datatype-datetime"> for more information.
@


1.32
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.31 2003/03/24 14:32:51 petere Exp $
a30 1
   <arg>-i</arg>
a53 1
   <arg>-i</arg>
a278 9
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-i</option></term>
      <listitem>
       <para>
	Prevents query execution, but shows the plan tree.
       </para>
@


1.31
log
@Another big editing pass for consistent content and presentation.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.30 2003/01/19 00:13:31 momjian Exp $
d126 1
a126 1
    configuration file.  See the &cite-admin; for details.  Some
d156 1
a156 1
	date output formats.  See the &cite-user; for more information.
@


1.30
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.29 2002/10/23 23:33:08 momjian Exp $
d65 1
a65 1
   <arg>-v <replaceable>protocol-version</replaceable></arg>
d75 1
a75 1
   The <filename>postgres</filename> executable is the actual
d83 1
a83 1
   <application>postgres</application> is invoked by the <xref
d97 1
a97 1
   that running a single-user backend is not truly suitable for
d103 1
a103 1
   When running a stand-alone backend, the session user will be set to
d105 1
a105 1
   a stand-alone backend can be used to manually recover from certain
d116 1
a116 1
    When <application>postgres</application> is started by a <xref
d119 2
a120 2
    <application>postgres</application>-specific options can be passed
    from the <application>postmaster</application> with the
d132 1
a132 1
    <application>postgres</application> command-line options.
d141 1
a141 1
     <option>-F</option>, and <option>--name</> have the same meanings
d143 2
a144 2
     <option>-d</option> <literal>0</> prevents the debugging level of
     the postmaster from being propagated to the backend.
d165 1
a165 1
	Sends all debugging and error output to 
d167 2
a168 2
	If the backend is running under the
	<application>postmaster</application>, this option is ignored,
d170 1
a170 1
	<application>postmaster</application> is used.
d179 1
a179 1
	Ignore system indexes while scanning/updating system tuples. The
d190 1
a190 1
	Print time information and other statistics at the end of each query.
d203 1
a203 1
	kilobytes, and defaults to 512 kilobytes.  Note that for a complex query,
d233 1
a233 1
	Echo all queries.
d242 1
a242 1
	Disables use of newline as a query delimiter.
d271 1
a280 1
       </para>
d298 1
a298 1
	used by <application>initdb</application>.
d307 2
a308 3
	Indicates that this server has been started by a
	<application>postmaster</application> and makes different
	assumptions about buffer pool management, file descriptors,
d341 1
a341 1
	to attach a debugger to the backend process.
d377 1
a377 1
   tell <application>postgres</application> to reread the config file,
d379 2
a380 2
   <application>postmaster</application> uses <literal>SIGTERM</literal>
   to tell a postgres process to quit normally and
d391 1
a391 1
    Start a stand-alone backend with a command like
d393 1
a393 1
<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
d395 1
a395 1
    Provide the correct path to the database area with <option>-D</>, or
d401 1
a401 1
    Normally, the stand-alone backend treats newline as the command
d410 1
a410 1
    not terminate command entry.  The backend will read the standard input
d412 1
a412 1
    process the input as a single query string.  Backslash-newline is not
d424 1
a424 1
    Note that the stand-alone backend does not provide sophisticated
@


1.29
log
@Add mention of postgres signals to reference page

Joseph Shraibman
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.28 2002/10/11 23:03:48 petere Exp $
d126 5
a130 5
    configuration file.  See the <citetitle>Administrator's
    Guide</citetitle> 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
d156 1
a156 2
	date output formats.  See the <citetitle>PostgreSQL User's
	Guide</citetitle> for more information.
@


1.28
log
@Assorted reference page updates
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/postgres-ref.sgml,v 1.27 2002/07/28 15:22:21 petere Exp $
d372 15
@


1.27
log
@Structure reference pages consistently.  Document that structure.
Add information about environment variables.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.26 2002/04/21 19:02:39 thomas Exp $
d104 1
a104 1
   the user with id 1.  This user does not actually have to exist, so
d107 1
a107 1
   superuser powers are granted to the user with id 1 in stand-alone
d110 1
d112 2
a113 2
  <refsect2>
   <title>Options</title>
d135 1
a135 1
   <refsect3>
d214 1
a214 1
   </refsect3>
d216 1
a216 1
   <refsect3>
d248 1
a248 1
   </refsect3>
d250 1
a250 1
   <refsect3>
d349 1
a349 2
   </refsect3>
  </refsect2>
@


1.26
log
@Augment the date/time examples in the User's Guide to reflect the newer
 capabilities of specifying time zones as intervals per SQL9x.
Put refentrytitle contents on the same line as the tag.
 Otherwise, leading whitespace is propagated into the product, which
 (at least) messes up the ToC layout.
Remove (some) docinfo tags containing dates. Best to omit if the dates
 are not accurate; maybe use CVS dates instead or leave them out.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.25 2002/03/22 19:20:43 petere Exp $
d350 22
@


1.25
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.24 2002/03/02 21:39:16 momjian Exp $
a6 4
 <docinfo>
  <date>2000-11-12</date>
 </docinfo>

@


1.24
log
@Commit to match discussed elog() changes.  Only update is that LOG is
now just below FATAL in server_min_messages.  Added more text to
highlight ordering difference between it and client_min_messages.

---------------------------------------------------------------------------

REALLYFATAL => PANIC
STOP => PANIC
New INFO level the prints to client by default
New LOG level the prints to server log by default
Cause VACUUM information to print only to the client
NOTICE => INFO where purely information messages are sent
DEBUG => LOG for purely server status messages
DEBUG removed, kept as backward compatible
DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1 added
DebugLvl removed in favor of new DEBUG[1-5] symbols
New server_min_messages GUC parameter with values:
        DEBUG[5-1], INFO, NOTICE, ERROR, LOG, FATAL, PANIC
New client_min_messages GUC parameter with values:
        DEBUG[5-1], LOG, INFO, NOTICE, ERROR, FATAL, PANIC
Server startup now logged with LOG instead of DEBUG
Remove debug_level GUC parameter
elog() numbers now start at 10
Add test to print error message if older elog() values are passed to elog()
Bootstrap mode now has a -d that requires an argument, like postmaster
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.23 2001/12/08 03:24:38 thomas Exp $
d82 1
a82 1
   linkend="app-postmaster"> multi-user server is started.
d133 1
a133 1
    is set, then libpq-based clients will pass that string to the
d147 1
a147 1
     the postmaster from being propogated to the backend.
d152 1
a152 1
      <term>-e</term>
d166 1
a166 1
      <term>-o <replaceable class="parameter">filename</replaceable></term>
d173 1
a173 1
	and the stderr inherited from the
d180 1
a180 1
      <term>-P</term>
d191 1
a191 1
      <term>-s</term>
d202 1
a202 1
      <term>-S <replaceable class="parameter">sort-mem</replaceable></term>
d234 1
a234 1
      <term>-E</term>
d243 1
a243 1
      <term>-N</term>
d267 1
a267 1
      <term>-f { s | i | m | n | h }</term>
d289 1
a289 1
      <term>-i</term>
d298 1
a298 1
      <term>-O</term>
d308 1
a308 1
      <term>-p <replaceable class="parameter">database</replaceable></term>
d320 1
a320 1
      <term>-t pa[rser] | pl[anner] | e[xecutor]</term>
d331 1
a331 1
      <term>-v <replaceable class="parameter">protocol</replaceable></term>
d341 1
a341 1
      <term>-W <replaceable class="parameter">seconds</replaceable></term>
d380 1
a380 1
    until the end-of-file (EOF) marker, then
d386 1
a386 1
    To quit the session, type EOF
d389 1
a389 1
    used <option>-N</>, two consecutive EOFs are needed to exit.
@


1.23
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.22 2001/11/28 20:49:10 petere Exp $
d144 4
a147 2
     <option>-F</option>, and <option>--name</> have the same meanings as
     for the <xref linkend="app-postmaster">.
@


1.22
log
@proof-reading
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.21 2001/11/25 01:11:36 tgl Exp $
Postgres documentation
@


1.21
log
@Further work on postmaster and postgres reference pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.20 2001/09/27 16:29:12 tgl Exp $
d102 1
a102 1
   debugging the server since no realistic inter-process communication
d358 1
a358 1
    Start a standalone backend with a command like
d368 1
a368 1
    Normally, the standalone backend treats newline as the command
d377 2
a378 1
    not terminate command entry.  The backend will read stdin until EOF, then
d384 4
a387 2
    The standalone backend does not have readline input processing
    (no command history, for example).
d391 2
a392 2
    To quit the backend, type EOF (control-D, usually).  If you've
    used <option>-N</>, two consecutive EOFs are needed to exit.
@


1.20
log
@Remove useless LockDisable() function and associated overhead, per my
proposal of 26-Aug.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.19 2001/09/08 15:24:00 petere Exp $
d46 1
d71 1
d92 3
a94 2
   the server directly in interactive mode.  The primary use for this
   mode is for bootstrapping by <xref linkend="app-initdb">.
d144 2
a145 2
     and <option>-F</option> have the same meaning as with the <xref
     linkend="app-postmaster">.
d169 4
a172 6
	If the backend is running under the <application>postmaster</application>,
	error messages are still sent to the frontend process as well as to
	<replaceable class="parameter">filename</replaceable>,
	but debugging output is sent to the controlling tty of the
	<application>postmaster</application>
	(since only one file descriptor can be sent to an actual file).
d181 1
a181 1
	Ignore system indexes to scan/update system tuples. The
d352 40
@


1.19
log
@Make the world somewhat safe for (not from) DELETE FROM pg_shadow;

Assign the fixed user id 1 to the user created by initdb.
A stand-alone backend will always set the user id to 1.
(Consequently, the name of that user is no longer important.)

In stand-alone mode, the user id 1 will have implicit superuser
status, to allow repairs even if there are no users defined.

Print a warning message when starting in stand-alone mode when no
users are defined.

Disallow dropping the current user and session user.

Granting/revoking superuser status also grants/revokes usecatupd.
(Previously, it would never grant it back.  This could lead to "deadlocks".)

CREATE USER and CREATE GROUP will start allocating user ids at 100
(unless explicitly specified), to prevent accidental creation of a
superuser (plus some room for future extensions).
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.18 2001/09/03 12:57:50 petere Exp $
a35 1
   <arg>-L</arg>
a58 1
   <arg>-L</arg>
a289 9
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-L</term>
      <listitem>
       <para>
	Turns off the locking system.
@


1.18
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.17 2001/03/17 16:27:31 petere Exp $
d38 1
a38 1
   <arg>-o <replaceable>file-name</replaceable></arg>
d61 1
a61 1
   <arg>-o <replaceable>file-name</replaceable></arg>
d106 6
a111 3
   When running a stand-alone backend the session user name will
   automatically be set to the current effective Unix user name.  If
   that user does not exist the server will not start.
d163 1
a163 1
      <term>-o <replaceable class="parameter">file-name</replaceable></term>
d167 1
a167 1
	<replaceable class="parameter">OutputFile</replaceable>.
d170 1
a170 1
	<replaceable class="parameter">OutputFile</replaceable>,
d365 1
a365 1
  <title>See also</title>
@


1.17
log
@Tuning for docbook2man.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.16 2000/12/25 23:15:26 petere Exp $
d19 1
a19 1
  <refpurpose>Run a <productname>PostgreSQL</productname> single-user backend</refpurpose>
@


1.16
log
@Refine some things to create better looking man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.15 2000/11/14 18:11:31 petere Exp $
d81 6
a86 1
   queries.  The second form above is how
d263 1
a263 1
      <term>-f [ s | i | m | n | h ]</term>
@


1.15
log
@Update and polish postmaster and postgres help output and man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.14 2000/10/05 19:48:18 momjian Exp $
d83 1
a83 1
   linkend="app-postmaster" endterm="app-postmaster-title"> (only
d88 1
a88 2
   mode is for bootstrapping by <xref linkend="app-initdb"
   endterm="app-initdb-title">.
d111 1
a111 1
    linkend="app-postmaster" endterm="app-postmaster-title"> then it
d136 1
a136 1
     linkend="app-postmaster" endterm="app-postmaster-title">.
d360 3
a362 3
   <xref linkend="app-initdb" endterm="app-initdb-title">,
   <xref linkend="app-ipcclean" endterm="app-ipcclean-title">,
   <xref linkend="app-postmaster" endterm="app-postmaster-title">
@


1.14
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.13 2000/07/22 04:45:09 momjian Exp $
d7 4
d12 2
a13 3
  <refentrytitle id="APP-POSTGRES-TITLE">
   <application>postgres</application>
  </refentrytitle>
d16 1
d18 2
a19 6
  <refname>
   <application>postgres</application>
  </refname>
  <refpurpose>
   Run a <productname>Postgres</productname> single-user backend
  </refpurpose>
d21 1
d23 51
a73 35
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
postgres [ <replaceable class="parameter">dbname</replaceable> ]
postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -E ] [ -F ]
   [ -O ] [ -P ] [ -Q ] [ -S <replaceable class="parameter">SortSize</replaceable> ] [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] ] [ -e ]
   [ -o ] [ <replaceable class="parameter">OutputFile</replaceable> ] [ -s ] [ -v <replaceable class="parameter">protocol</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> ]
  </synopsis>

  <refsect2 id="R2-APP-POSTGRES-1">
   <refsect2info>
    <date>1999-05-19</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
    <application>postgres</application> accepts the following command line arguments:
    
    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">dbname</replaceable></term>
      <listitem>
       <para>
	The optional argument
	<replaceable class="parameter">dbname</replaceable>
	specifies the name of the database to be accessed.
	<replaceable class="parameter">dbname</replaceable>
	defaults to the value of the
	<envar>USER</envar>
	environment variable.
       </para>
      </listitem>
     </varlistentry>
d75 2
a76 16
     <varlistentry>
      <term>-B <replaceable class="parameter">nBuffers</replaceable></term>
      <listitem>
       <para>
	If the backend is running under the 
	<application>postmaster</application>,
	<replaceable class="parameter">nBuffers</replaceable>
	is the number of shared-memory buffers that the
	<application>postmaster</application>
	has allocated for the backend server processes that it starts.  If the
	backend is running stand-alone, this specifies the number of buffers to
	allocate.  This value defaults to 64 buffers, where each buffer is 8k bytes
	(or whatever BLCKSZ is set to in config.h).
       </para>
      </listitem>
     </varlistentry>
d78 13
a90 8
     <varlistentry>
      <term>-C</term>
      <listitem>
       <para>
	Do not show the server version number.
       </para>
      </listitem>
     </varlistentry>
d92 8
a99 16
     <varlistentry>
      <term>-D <replaceable class="parameter">DataDir</replaceable></term>
      <listitem>
       <para>
	Specifies the directory to use as the root of the tree of database
	directories.  If -D is not given, the default data directory name is
	the value of the environment variable 
	<envar>PGDATA</envar>.
	If <envar>PGDATA</envar> is not set, then the directory used is
	<filename>$POSTGRESHOME/data</filename>.
	If neither environment variable is set and this command-line
	option is not specified, the default directory that was
	set at compile-time is used.
       </para>
      </listitem>
     </varlistentry>
d101 5
a105 8
     <varlistentry>
      <term>-E</term>
      <listitem>
       <para>
	Echo all queries.
       </para>
      </listitem>
     </varlistentry>
d107 2
a108 12
     <varlistentry>
      <term>-F</term>
      <listitem>
       <para>
	Disable an automatic <function>fsync()</function> call after each transaction.
	This option improves performance, but an operating system crash
	while a transaction is in progress may  cause the loss of
	the most recently entered data. Without the <function>fsync()</function> call
	the data is buffered by the operating system, and written to disk sometime later.
       </para>
      </listitem>
     </varlistentry>
d110 8
a117 10
     <varlistentry>
      <term>-O</term>
      <listitem>
       <para>
	Override restrictions, so system table structures can be modified.
	These tables are typically those with a leading
	<literal>pg_</literal> in the table name.
       </para>
      </listitem>
     </varlistentry>
d119 10
a128 12
     <varlistentry>
      <term>-P</term>
      <listitem>
       <para>
	Ignore system indexes to scan/update system
	tuples. The <command>REINDEX</command> for system tables/indexes
	requires this option. System tables are
	typically those with a leading <literal>pg_</literal> in the
	table name.
       </para>
      </listitem>
     </varlistentry>
d130 2
a131 23
     <varlistentry>
      <term>-Q</term>
      <listitem>
       <para>
	Specifies "quiet" mode.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-S <replaceable class="parameter">SortSize</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 512 kilobytes.  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">SortSize</replaceable> kilobytes
	before it starts to put data into temporary files.
       </para>
      </listitem>
     </varlistentry>
d133 6
a138 20
     <varlistentry>
      <term>-d [ <replaceable class="parameter">DebugLevel</replaceable> ]</term>
      <listitem>
       <para>
	The optional argument <replaceable class="parameter">DebugLevel</replaceable>
	determines the amount of debugging output the backend servers will
	produce.
	If <replaceable class="parameter">DebugLevel</replaceable>
	is one, the postmaster will trace all connection traffic,
	and nothing else.
	For levels two and higher,
	debugging is turned on in the backend process and the postmaster
	displays more information,
	including the backend environment and process traffic.
	Note that if no file is specified for backend servers to
	send their debugging output then this output will appear on the
	controlling tty of their parent <application>postmaster</application>.
       </para>
      </listitem>
     </varlistentry>
d140 1
d145 6
a150 13
	This option controls how dates are interpreted upon
	input to and output from the database.
	If the <option>-e</option>
	option is supplied, then dates passed to and from the frontend
	processes will be assumed to be in "European"
	format (<literal>DD-MM-YYYY</literal>),
	otherwise dates are assumed to be in
	"American" format (<literal>MM-DD-YYYY</literal>).
	Dates are accepted by the backend in a wide variety of formats,
	and for input dates this switch mostly affects the interpretation
	for ambiguous cases.
	See the <citetitle>PostgreSQL User's Guide</citetitle>
	for more information.
d156 1
a156 1
      <term>-o <replaceable class="parameter">OutputFile</replaceable></term>
d172 11
d194 1
a194 1
      <term>-v <replaceable class="parameter">protocol</replaceable></term>
d197 7
a203 2
	Specifies the number of the frontend/backend protocol to be used for this
	particular session.
d207 1
d209 1
a209 1
   </para>
d211 2
a212 10
   <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>Postgres</productname> system developers.
    <emphasis>Use of any of these options is highly discouraged.</emphasis>
    Furthermore, any of these options may disappear or change at any time.
   </para>

   <para>
    These special-case options are:
d216 1
a216 1
      <term>-A [ n | r | b | Q | X ]</term>
d219 2
a220 1
	This option generates a tremendous amount of output.
d222 2
a223 2
     </listitem>
    </varlistentry>
d226 1
a226 1
      <term>-L</term>
d229 1
a229 1
	Turns off the locking system.
d242 15
d290 1
a290 1
      <term>-p <replaceable class="parameter">dbname</replaceable></term>
d293 23
a315 5
	Indicates to the backend server that it has been started by a 
	<application>postmaster</application>
	and makes different assumptions about buffer pool management, file
	descriptors, etc.  Switches following -p are restricted to those
	considered "secure".
d324 3
a326 2
	Print timing statistics for each query relating to each of the major
	system modules.  This option cannot be used with <option>-s</option>.
a329 3
    </variablelist>
   </para>
  </refsect2>
d331 9
a339 10
  <refsect2 id="R2-APP-POSTGRES-2">
   <refsect2info>
    <date>1999-05-19</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
    Of the nigh-infinite number of error messages you may see when you
    execute the backend server directly, the most common will probably be:
a340 1
    <variablelist>
d342 1
a342 3
      <term><computeroutput>
semget: No space left on device
       </computeroutput></term>
d345 3
a347 18
	If you see this message, you should run the
	<application>ipcclean</application>
	command.  After doing this, try starting
	<application>postmaster</application>
	again.  If this still doesn't work, you probably need to configure
	your kernel for shared memory and semaphores as described in the
	installation notes.  If you have a kernel with particularly small shared memory
	and/or semaphore limits, you may have to reconfigure your kernel to increase
	its shared memory or semaphore parameters.

	<tip>
	 <para>
	  You may be able to postpone
	  reconfiguring your kernel by decreasing -B to reduce
	  <productname>Postgres</productname>' shared memory
	  consumption.
	 </para>
	</tip>
d351 1
d353 1
a353 1
   </para>
d355 1
a355 17
 </refsynopsisdiv>

 <refsect1 id="R1-APP-POSTGRES-1">
  <refsect1info>
   <date>1999-05-19</date>
  </refsect1info>
  <title>
   Description
  </title>

  <para>
   The Postgres backend server can be executed directly from the user shell.
   This should be done only while debugging by the DBA, and should not be
   done while other Postgres backends are being managed by a
   <application>postmaster</application>
   on this set of databases.
  </para>
d357 2
a358 6
  <para>
   Some of the switches explained here can be passed to the backend
   through the "database options" field of a connection request, and thus can be
   set for a particular backend without going to the trouble of restarting the
   postmaster.  This is particularly handy for debugging-related switches.
  </para>
d361 3
a363 5
   The optional argument <replaceable class="parameter">dbname</replaceable>
   specifies the name of the database to be accessed.
   <replaceable class="parameter">dbname</replaceable>
   defaults to the value of the
   <envar>USER</envar> environment variable.
a366 16
 <refsect1 id="R1-APP-POSTGRES-2">
  <refsect1info>
   <date>1998-10-04</date>
  </refsect1info>
  <title>
   Notes
  </title>
  
  <para>
   Useful utilities for dealing with shared memory problems include
   <application>ipcs(1)</application>,
   <application>ipcrm(1</application>), and
   <application>ipcclean(1)</application>.
   See also <xref linkend="app-postmaster" endterm="app-postmaster-title">.
  </para>
 </refsect1>
@


1.13
log
@spell cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.12 2000/07/21 17:58:49 momjian Exp $
d328 1
a328 1
	and make different assumptions about buffer pool management, file
@


1.12
log
@More doc cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.11 2000/07/21 03:14:33 momjian Exp $
d68 1
a68 1
	backend is running standalone, this specifies the number of buffers to
@


1.11
log
@Clean up flags
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.10 2000/07/21 03:13:32 momjian Exp $
d129 1
a129 1
	"<literal>pg_</literal>" in the table name.
d139 1
a139 1
	tuples. <command>REINDEX</command> for system tables/indexes
d141 1
a141 1
	typically those with a leading "<literal>pg_</literal>" in the
@


1.10
log
@Fix postgres -A options flags
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.9 2000/05/08 16:19:56 thomas Exp $
d265 1
a265 1
      <term>-A n|r|b|Q|X</term>
@


1.9
log
@Minor fixups for markup and wording.
@
text
@d2 1
a2 1
$Header: /home/lockhart/cvs/repository/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.8 2000/05/03 07:33:44 inoue Exp $
d265 1
a265 1
      <term>-A n|r|b|Q\fIn\fP|X\fIn\fP</term>
@


1.8
log
@Oops,I've forgotten to add an documentation about -P option of
postgres.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.7 2000/03/27 17:14:43 thomas Exp $
d128 2
a129 1
	These tables are typically those with a leading "pg_" in the table name.
d138 5
a142 3
	Ignore system indexes to scan/update system tuples. Reindex command
	for system table/indexes requires this option. System tables are
	typically those with a leading "pg_" in the table name.
@


1.7
log
@Start updating for the v7.0 release.
Use "generic functions" for math and other routines.
Use SQL92 "type 'literal'" syntax rather than Postgres "'literal'::type".
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.6 1999/08/06 13:50:31 thomas Exp $
d28 1
a28 1
   [ -O ] [ -Q ] [ -S <replaceable class="parameter">SortSize</replaceable> ] [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] ] [ -e ]
d129 11
@


1.6
log
@Fix markup to allow clean man pages.
Add new pages for programming languages and tcl shells.
@
text
@d2 1
a2 1
$Header: /opt/postgres/cvs/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.5 1999/07/22 15:09:14 thomas Exp $
d193 1
a193 1
	See <citetitle>The PostgreSQL User's Guide</citetitle>
@


1.5
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d14 1
a14 1
  <refname id="postgres-ref">
d193 1
a193 1
	See <xref linkend="datatype-title" endterm="datatype-title">
d423 1
a423 1
   See also <xref linkend="postmaster-ref" endterm="postmaster-ref">.
@


1.4
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 5
d8 1
a8 1
  <refentrytitle>
d23 1
a23 1
   <date>1999-05-19</date>
@


1.3
log
@Minor updates for release.
Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml
 (the emacs parser) to handle parsing.
@
text
@d39 1
a39 3
      <term>
       <replaceable class="parameter">dbname</replaceable>
      </term>
d54 1
a54 3
      <term>
       -B <replaceable class="parameter">nBuffers</replaceable>
      </term>
d71 1
a71 3
      <term>
       -C
      </term>
d80 1
a80 3
      <term>
       -D <replaceable class="parameter">DataDir</replaceable>
      </term>
d97 1
a97 3
      <term>
       -E
      </term>
d106 1
a106 3
      <term>
       -F
      </term>
d119 1
a119 3
      <term>
       -O
      </term>
d129 1
a129 3
      <term>
       -Q
      </term>
d138 1
a138 3
      <term>
       -S <replaceable class="parameter">SortSize</replaceable>
      </term>
d153 1
a153 3
      <term>
       -d [ <replaceable class="parameter">DebugLevel</replaceable> ]
      </term>
d174 1
a174 3
      <term>
       -e
      </term>
d195 1
a195 3
      <term>
       -o <replaceable class="parameter">OutputFile</replaceable>
      </term>
d211 1
a211 3
      <term>
       -s
      </term>
d222 1
a222 3
      <term>
       -v <replaceable class="parameter">protocol</replaceable>
      </term>
d246 1
a246 3
      <term>
       -A n|r|b|Q\fIn\fP|X\fIn\fP
      </term>
d255 1
a255 3
      <term>
       -L
      </term>
d264 1
a264 3
      <term>
       -N
      </term>
d273 1
a273 3
      <term>
       -f [ s | i | m | n | h ]
      </term>
d295 1
a295 3
      <term>
       -i
      </term>
d304 1
a304 3
      <term>
       -p <replaceable class="parameter">dbname</replaceable>
      </term>
d317 1
a317 3
      <term>
       -t pa[rser] | pl[anner] | e[xecutor]
      </term>
d342 3
a344 3
      <term>
       semget: No space left on device
      </term>
@


1.2
log
@Markup fixes.
@
text
@d209 2
a210 1
	for ambiguous cases. See <xref linkend="datatype" endterm="datatype">
@


1.1
log
@First copy from the man pages.
postgres-ref.sgml is not yet marked up.
@
text
@d1 479
a479 220
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /opt/postgres/cvs/pgsql/src/man/postgres.1,v 1.16 1999/05/22 17:47:47 tgl Exp $
.TH POSTGRESQL UNIX 05/19/99 PostgreSQL PostgreSQL
.SH NAME
postgres - the Postgres backend server
.SH SYNOPSIS
.BR "postgres"
[\c
.BR "-B"
n_buffers]
[\c
.BR "-C"
]
[\c
.BR "-D"
data_directory]
[\c
.BR "-E"
]
[\c
.BR "-F"
]
[\c
.BR "-O"
]
[\c
.BR "-Q"
]
[\c
.BR "-S kbytes"
]
[\c
.BR "-d"
debug_level]
[\c
.BR "-e"
]
[\c
.BR "-o"
output_file]
[\c
.BR "-s"
]
[\c
.BR "-v protocol"
]
[dbname]
.in -5n
.SH DESCRIPTION
The Postgres backend server can be executed directly from the user shell.
This should be done only while debugging by the DBA, and should not be
done while other Postgres backends are being managed by a
.IR postmaster
on this set of databases.
.PP
Some of the switches explained in this man page can be passed to the backend
through the "database options" field of a connection request, and thus can be
set for a particular backend without going to the trouble of restarting the
postmaster.  This is particularly handy for debugging-related switches.
.PP
The optional argument
.IR dbname
specifies the name of the database to be accessed.
.IR Dbname
defaults to the value of the
.SM USER
environment variable.
.PP
The 
.IR postgres
server understands the following command-line options:
.TP
.BR "-B" " n_buffers"
If the backend is running under the 
.IR postmaster ,
.IR "n_buffers"
is the number of shared-memory buffers that the
.IR "postmaster"
has allocated for the backend server processes that it starts.  If the
backend is running standalone, this specifies the number of buffers to
allocate.  This value defaults to 64 buffers, where each buffer is 8k bytes
(or whatever BLCKSZ is set to in config.h).
.TP
.BR "-C"
Do not show server version number.
.TP
.BR "-D" " data_directory"
This option specifies the pathname of the directory that contains the
database system data (the tables, the catalogs, etc.).  If you don't 
specify this option, Postgres uses the value of the PGDATA environment
variable.  You must either specify a -D option or set PGDATA.
 
The data directory pathname for a database system is normally determined when
the database system is created with
.IR initdb ,
with a --pgdata option to
.IR initdb .
.TP
.BR "-E"
Echo all queries.
.TP
.BR "-F"
Disable automatic fsync() call after each transaction.
This option improves performance, but an operating system crash
while a transaction is in progress will probably cause data loss.
.TP
.BR "-O"
Override restrictions, so system table structures can be modified(pg_*).
.TP
.BR "-Q"
Specifies \*(lqquiet\*(rq mode.
.TP
.BR "-S" " kbytes"
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 512 kilobytes.  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 -S kilobytes before it starts to put
data into temporary files.
.TP
.BR "-e"
The
.IR "-e"
option controls how dates are input to and output from the database.
.IP
If the
.IR "-e"
option is supplied, then all dates passed to and from the frontend
processes will be assumed to be in
.IR "European"
format ie.
.IR "DD-MM-YYYY"
otherwise dates are input and output in
.IR "American"
format ie.
.IR "MM-DD-YYYY"
.TP
.BR "-d" " debug_level"
Turns on debugging at the numeric level
.IR "debug_level" .
Turning on debugging will cause query, parse trees, and query plans to
be displayed.
.TP
.BR "-o" " output_file"
Sends all debugging and error output to 
.IR output_file .
If the backend is running under the 
.IR postmaster ,
error messages are still sent to the frontend process as well as to
.IR output_file ,
but debugging output is sent to the controlling tty of the
.IR postmaster
(since only one file descriptor can be sent to an actual file).
.TP
.BR "-s"
Print time information and other statistics at the end of each query.
This is useful for benchmarking or for use in tuning the number of
buffers.
.TP
.BR "-v" " protocol"
Specifies the number of the frontend/backend protocol to be used for this
particular session.
.SH "DEVELOPER COMMAND OPTIONS"
There are several other options that may be specified, used mainly
for debugging purposes.  These are listed here only for the use by
Postgres system developers.
.BR "Use of any of these options is highly discouraged" .
Furthermore, any of these options may disappear or change at any time.
.TP
.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
.IP
This option generates a tremendous amount of output.
.TP
.BR "-L"
Turns off the locking system.
.TP
.BR "-N"
Disables use of newline as a query delimiter.
.TP
.BR "-f"
Forbids the use of particular scan and join methods:
.IR s " and " i
disable sequential and index scans respectively, while
.IR n ", " m " and " h
disable nested-loop, merge and hash joins respectively.
(Neither sequential scans nor nested-loop joins can be disabled completely;
the -fs and -fn options simply discourage the optimizer from using those
plan types if it has any other alternative.)
.TP
.BR "-i"
Prevents query execution, but shows the plan tree.
.TP
.BR "-p" " databasename"
Indicates to the backend server that it has been started by a 
.IR postmaster
and make different assumptions about buffer pool management, file
descriptors, etc.  Switches following -p are restricted to those
considered "secure".
.TP
.BR "-t" "pa[rser]|pl[anner]|e[xecutor]"
Print timing statistics for each query relating to each of the major
system modules.  This option cannot be used with
.BR "-s" .
.SH "SEE ALSO"
ipcclean(1),
psql(1), 
postmaster(1).
.SH "DIAGNOSTICS"
Of the nigh-infinite number of error messages you may see when you
execute the backend server directly, the most common will probably be:
.TP
.BR "semget: No space left on device"
If you see this message, you should run the
.IR ipcclean
command.  After doing this, try starting
.IR postgres
again.  If this still doesn't work, you probably need to configure
your kernel for shared memory and semaphores as described in the
installation notes.
@
