open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update and polish postmaster and postgres help output and man pages.

Browse Source
REL7_1_STABLE
Peter Eisentraut 25 years ago
parent 3eaf3363d7
commit 8a9315ca92
5 changed files with 535 additions and 608 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 511
      doc/src/sgml/ref/postgres-ref.sgml
  2. 503
      doc/src/sgml/ref/postmaster.sgml
  3. 46
      doc/src/sgml/runtime.sgml
  4. 26
      src/backend/postmaster/postmaster.c
  5. 57
      src/backend/tcop/postgres.c

511
doc/src/sgml/ref/postgres-ref.sgml
Unescape View File

@ -1,217 +1,159 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.14 2000/10/05 19:48:18 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.15 2000/11/14 18:11:31 petere Exp $
Postgres documentation
-->
<refentry id="APP-POSTGRES">
<docinfo>
<date>2000-11-12</date>
</docinfo>
<refmeta>
<refentrytitle id="APP-POSTGRES-TITLE">
<application>postgres</application>
</refentrytitle>
<refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
<application>postgres</application>
</refname>
<refpurpose>
Run a <productname>Postgres</productname> single-user backend
</refpurpose>
<refname>postgres</refname>
<refpurpose>Run a <productname>PostgreSQL</productname> single-user backend</refpurpose>
</refnamediv>
<refsynopsisdiv>
<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>
<cmdsynopsis>
<!-- standalone call -->
<command>postgres</command>
<arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
<arg>-B <replaceable>nbuffers</replaceable></arg>
<arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<arg>-d <replaceable>debug-level</replaceable></arg>
<arg>-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>-i</arg>
<arg>-L</arg>
<arg>-N</arg>
<arg>-o <replaceable>file-name</replaceable></arg>
<arg>-O</arg>
<arg>-P</arg>
<group>
<arg>-s</arg>
<arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
</group>
<arg>-S <replaceable>sort-mem</replaceable></arg>
<arg>-W <replaceable>seconds</replaceable></arg>
<arg choice="plain"><replaceable>database</replaceable></arg>
<sbr>
<!-- postmaster fork -->
<command>postgres</command>
<arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
<arg>-B <replaceable>nbuffers</replaceable></arg>
<arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<arg>-d <replaceable>debug-level</replaceable></arg>
<arg>-D <replaceable>datadir</replaceable></arg>
<arg>-e</arg>
<arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
<arg>-F</arg>
<arg>-i</arg>
<arg>-L</arg>
<arg>-o <replaceable>file-name</replaceable></arg>
<arg>-O</arg>
<arg>-p <replaceable>database</replaceable></arg>
<arg>-P</arg>
<group>
<arg>-s</arg>
<arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
</group>
<arg>-S <replaceable>sort-mem</replaceable></arg>
<arg>-v <replaceable>protocol-version</replaceable></arg>
<arg>-W <replaceable>seconds</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<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>
<refsect1>
<title>Description</title>
<varlistentry>
<term>-C</term>
<listitem>
<para>
Do not show the server version number.
</para>
</listitem>
</varlistentry>
<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>
<para>
The <filename>postgres</filename> executable is the actual
<productname>PostgreSQL</productname> server process that processes
queries. The second form above is how
<application>postgres</application> is invoked by the <xref
linkend="app-postmaster" endterm="app-postmaster-title"> (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 mode. The primary use for this
mode is for bootstrapping by <xref linkend="app-initdb"
endterm="app-initdb-title">.
</para>
<varlistentry>
<term>-E</term>
<listitem>
<para>
Echo all queries.
</para>
</listitem>
</varlistentry>
<para>
When invoked in interactive mode from the shell, the user can enter
queries and the results will be printed to the screen, but in a
form that is more useful for developers than end users. But note
that running a single-user backend is not truly suitable for
debugging the server since no realistic inter-process communication
and locking will happen.
</para>
<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>
<para>
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.
</para>
<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>
<refsect2>
<title>Options</title>
<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>
<para>
When <application>postgres</application> is started by a <xref
linkend="app-postmaster" endterm="app-postmaster-title"> then it
inherits all options set by the latter. Additionally,
<application>postgres</application>-specific options can be passed
from the <application>postmaster</application> with the
<option>-o</option> switch.
</para>
<varlistentry>
<term>-Q</term>
<listitem>
<para>
Specifies "quiet" mode.
</para>
</listitem>
</varlistentry>
<para>
You can avoid having to type these options by setting up a
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 libpq-based clients will pass that string to the
server, which will interpret it as
<application>postgres</application> command-line options.
</para>
<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>
<refsect3>
<title>General Purpose</title>
<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>
<para>
The options <option>-A</option>, <option>-B</option>,
<option>-c</option>, <option>-d</option>, <option>-D</option>,
and <option>-F</option> have the same meaning as with the <xref
linkend="app-postmaster" endterm="app-postmaster-title">.
</para>
<variablelist>
<varlistentry>
<term>-e</term>
<listitem>
<para>
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.
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 the <citetitle>PostgreSQL User's
Guide</citetitle> for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o <replaceable class="parameter">OutputFile</replaceable></term>
<term>-o <replaceable class="parameter">file-name</replaceable></term>
<listitem>
<para>
Sends all debugging and error output to
@ -226,6 +168,17 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
</listitem>
</varlistentry>
<varlistentry>
<term>-P</term>
<listitem>
<para>
Ignore system indexes to scan/update system tuples. The
<command>REINDEX</command> command for system tables/indexes
requires this option to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-s</term>
<listitem>
@ -238,43 +191,42 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
</varlistentry>
<varlistentry>
<term>-v <replaceable class="parameter">protocol</replaceable></term>
<term>-S <replaceable class="parameter">sort-mem</replaceable></term>
<listitem>
<para>
Specifies the number of the frontend/backend protocol to be used for this
particular session.
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">sort-mem</replaceable> kilobytes
before it starts to put data into temporary files.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<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>
</variablelist>
</refsect3>
<para>
These special-case options are:
<refsect3>
<title>Options for stand-alone mode</title>
<variablelist>
<varlistentry>
<term>-A [ n | r | b | Q | X ]</term>
<term><replaceable class="parameter">database</replaceable></term>
<listitem>
<para>
This option generates a tremendous amount of output.
Specifies the name of the database to be accessed. If it is
omitted it defaults to the user name.
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
<varlistentry>
<term>-L</term>
<term>-E</term>
<listitem>
<para>
Turns off the locking system.
Echo all queries.
</para>
</listitem>
</varlistentry>
@ -287,6 +239,21 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
<refsect3>
<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>-f [ s | i | m | n | h ]</term>
@ -320,123 +287,83 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">dbname</replaceable></term>
<term>-L</term>
<listitem>
<para>
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".
Turns off the locking system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-t pa[rser] | pl[anner] | e[xecutor]</term>
<term>-O</term>
<listitem>
<para>
Print timing statistics for each query relating to each of the major
system modules. This option cannot be used with <option>-s</option>.
Allows the structure of system tables to be modified. This is
used by <application>initdb</application>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
<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:
<varlistentry>
<term>-p <replaceable class="parameter">database</replaceable></term>
<listitem>
<para>
Indicates that this server has been started by a
<application>postmaster</application> and makes different
assumptions about buffer pool management, file descriptors,
etc.
</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
<term><computeroutput>
semget: No space left on device
</computeroutput></term>
<term>-t pa[rser] | pl[anner] | e[xecutor]</term>
<listitem>
<para>
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.
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>
<tip>
<para>
You may be able to postpone
reconfiguring your kernel by decreasing -B to reduce
<productname>Postgres</productname>' shared memory
consumption.
</para>
</tip>
<varlistentry>
<term>-v <replaceable class="parameter">protocol</replaceable></term>
<listitem>
<para>
Specifies the version number of the frontend/backend protocol
to be used for this particular session.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-APP-POSTGRES-1">
<refsect1info>
<date>1999-05-19</date>
</refsect1info>
<title>
Description
</title>
<varlistentry>
<term>-W <replaceable class="parameter">seconds</replaceable></term>
<listitem>
<para>
As soon as this option is encountered, the process sleeps for
the specified amount of seconds. This gives developers time
to attach a debugger to the backend process.
</para>
</listitem>
</varlistentry>
<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>
</variablelist>
</refsect3>
</refsect2>
</refsect1>
<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>
<refsect1>
<title>See also</title>
<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.
<xref linkend="app-initdb" endterm="app-initdb-title">,
<xref linkend="app-ipcclean" endterm="app-ipcclean-title">,
<xref linkend="app-postmaster" endterm="app-postmaster-title">
</para>
</refsect1>
<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>
</refentry>
<!-- Keep this comment at the end of the file

503
doc/src/sgml/ref/postmaster.sgml
Unescape View File

@ -1,155 +1,174 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.14 2000/11/13 23:57:20 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.15 2000/11/14 18:11:31 petere Exp $
Postgres documentation
-->
<refentry id="APP-POSTMASTER">
<docinfo>
<date>2000-11-12</date>
</docinfo>
<refmeta>
<refentrytitle id="APP-POSTMASTER-TITLE">
<application>postmaster</application>
</refentrytitle>
<refentrytitle id="APP-POSTMASTER-TITLE"><application>postmaster</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname id="postmaster-ref">
<application>postmaster</application>
</refname>
<refpurpose>
Run the <productname>Postgres</productname> multi-user backend
</refpurpose>
<refname id="postmaster-ref">postmaster</refname>
<refpurpose><productname>PostgreSQL</productname> multi-user database server</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -N <replaceable class="parameter">maxBackends</replaceable> ] [ -S ]
[ -d <replaceable class="parameter">DebugLevel</replaceable> ]
[ -h <replaceable class="parameter">hostname</replaceable> ] [ -i ]
[ -k <replaceable class="parameter">path</replaceable> ] [ -l ]
[ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] [ -n | -s ]
</synopsis>
<refsect2 id="R2-APP-POSTMASTER-1">
<refsect2info>
<date>1999-05-19</date>
</refsect2info>
<title>
Inputs
</title>
<cmdsynopsis>
<command>postmaster</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>-F</arg>
<arg>-h <replaceable>hostname</replaceable></arg>
<arg>-i</arg>
<arg>-k <replaceable>filename</replaceable></arg>
<arg>-l</arg>
<arg>-N <replaceable>max-connections</replaceable></arg>
<arg>-o <replaceable>extra-options</replaceable></arg>
<arg>-p <replaceable>port</replaceable></arg>
<arg>-S</arg>
<group><arg>-n</arg><arg>-s</arg></group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>postmaster</application> is the
<productname>PostgreSQL</productname> multi-user database server.
In order for a client application to access a database it connects
(over a network or locally) to a running
<application>postmaster</application>. The
<application>postmaster</application> then starts a separate server
process (<quote><xref linkend="app-postgres"
endterm="app-postgres-title"></quote>) to handle the connection.
The postmaster also manages the communication among server
processes.
</para>
<para>
By default the postmaster starts in the foreground and prints log
messages to the standard output. In practical applications the
postmaster should be started as a background process, perhaps at
boot time.
</para>
<para>
One postmaster always manages the data from exactly one database
cluster. A database cluster is a collection of databases that is
stored at a common file system location. When the postmaster
starts it needs to know the location of the database cluster files
(<quote>data area</quote>). This is done with the
<option>-D</option> invocation option or the <envar>PGDATA</envar>
environment variable, there is no default. More than one
postmaster process can run on a system at one time, as long as they
use different data areas and different port numbers (see below). A
data area is created with <xref linkend="app-initdb"
endterm="app-initdb-title">.
</para>
<refsect2 id="app-postmaster-options">
<title>Options</title>
<para>
<application>postmaster</application> accepts the following command line arguments:
<application>postmaster</application> accepts the following
command line arguments. For a detailed discussion of the options
consult the <citetitle>Administrator's Guide</citetitle>. You can
also save typing most of these options by setting up a
configuration file.
<variablelist>
<varlistentry>
<term>-B <replaceable class="parameter">nBuffers</replaceable></term>
<term>-A 0|1</term>
<listitem>
<para>
Sets the number of shared-memory disk buffers for the
<application>postmaster</application>
to allocate for use by the backend server processes that it
starts. This value defaults to 64 buffers, where each buffer is 8k bytes
(or whatever BLCKSZ is set to in src/include/config.h).
Enables run-time assert checks, which is a debugging aid to
detect programming mistakes. This is only available if it was
enabled during compilation. If so, the default is on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-D <replaceable class="parameter">DataDir</replaceable></term>
<term>-B <replaceable class="parameter">nbuffers</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.
Sets the number of shared buffers for use by the server
processes. This value defaults to 64 buffers, where each
buffer is 8 kB.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-N <replaceable class="parameter">maxBackends</replaceable></term>
<term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
<listitem>
<para>
Sets the maximum number of backend server processes that this postmaster
is allowed to start. By default, this value is 32, but it can be set
as high as 1024 if your system will support that many processes.
(Note that -B is required to be at least twice -N, so you'll need to
increase -B if you increase -N.)
Both the default and upper limit values for -N can be altered
when building <productname>Postgres</productname>
(see src/include/config.h).
Sets a named run-time parameter. Consult the
<citetitle>Administrator's Guide</citetitle> for a list and
descriptions. Most of the other command line options are in
fact short forms of such a parameter assignment.
</para>
<para>
On some systems it is also possible to equivalently use
GNU-style long options in the form
<literal>--name=value</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-S</term>
<term>-d <replaceable>debug-level</replaceable></term>
<listitem>
<para>
Specifies that the <application>postmaster</application>
process should start up in silent mode. That is, it will disassociate
from the user's (controlling) tty, start its own process group, and
redirect its standard output and standard error to
<filename>/dev/null</filename>.
</para>
<para>
<emphasis>Note</emphasis> that using this switch makes it very
difficult to troubleshoot problems, since all tracing and logging
output that would normally be generated by this postmaster and its
child backends will be discarded.
Sets the debug level. The higher this value is set, the more
debugging output is written to the server log. The default is
0, which means no debugging. Values up to 4 make sense.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-d <replaceable class="parameter">DebugLevel</replaceable></term>
<term>-D <replaceable class="parameter">datadir</replaceable></term>
<listitem>
<para>
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.
Levels two and higher turn on increasing amounts of debug output
from the backend processes, and the postmaster
displays more information
including the backend environment and process traffic.
Note that unless the postmaster's standard output and standard error
are redirected into a log file, all this output will appear on the
controlling tty of the <application>postmaster</application>.
Specifies the file system location of the data directory. See
discussion above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h <replaceable class="parameter">hostName</replaceable></term>
<term>-F</term>
<listitem>
<para>
Specifies the TCP/IP hostname or address
on which the <application>postmaster</application>
is to listen for connections from frontend applications. Defaults to
the value of the <envar>PGHOST</envar>
environment variable, or if <envar>PGHOST</envar>
is not set, it defaults to listening on all configured addresses
(including localhost).
</para>
<para>
If you use a hostname do not try to run
multiple instances of <application>postmaster</application> on the
same IP address but different ports. Doing so will result in them
attempting (incorrectly) to use the same shared memory segments.
Also, if you use a hostname, all of the host's IP addresses
on which <application>postmaster</application> instances are
listening must be distinct in the two last octets.
Disables <function>fsync</function> calls for performance
improvement at the risk of data corruption. Read the detailed
documentation before using this!
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h <replaceable class="parameter">hostname</replaceable></term>
<listitem>
<para>
If you don't use this option, each instance must listen on a
different port (via -p or <envar>PGPORT</envar>). And, of course, do
not try to use both approaches on one host.
Specifies the TCP/IP hostname or address on which the
<application>postmaster</application> is to listen for
connections from client applications. Defaults to the value
of the <envar>PGHOST</envar> environment variable, or if
<envar>PGHOST</envar> is not set, it defaults to listening on
all configured addresses (including localhost).
</para>
</listitem>
</varlistentry>
@ -158,65 +177,63 @@ postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <re
<term>-i</term>
<listitem>
<para>
Allows clients to connect via TCP/IP (Internet domain) connections.
Without this option, only local Unix domain socket connections are
accepted.
Allows clients to connect via TCP/IP (Internet domain)
connections. Without this option, only local Unix domain
socket connections are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-k <replaceable class="parameter">path</replaceable></term>
<term>-k <replaceable class="parameter">filename</replaceable></term>
<listitem>
<para>
Specifies the local Unix domain socket path name
on which the <application>postmaster</application>
is to listen for connections from frontend applications. Defaults to
the value of the
<envar>PGUNIXSOCKET</envar>
environment variable, or if <envar>PGUNIXSOCKET</envar>
is not set, then defaults to a file in <filename>/tmp</filename>
constructed from the port number.
Specifies the Unix domain socket file name on which the
<application>postmaster</application> is to listen for
connections from client applications. Defaults to the value
of the <envar>PGUNIXSOCKET</envar> environment variable, or if
<envar>PGUNIXSOCKET</envar> is not set, then defaults to a
file in <filename>/tmp</filename> constructed from the port
number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l</term>
<listitem>
<para>
You can use this option to put the Unix-domain socket in a
directory that is private to one or more users using Unix
directory permissions. This is necessary for securely
creating databases automatically on shared machines.
In that situation, also disallow all TCP/IP connections
initially in <filename>pg_hba.conf</filename>.
If you specify a socket path other than the
default then all frontend applications (including
<application>psql</application>) must specify the same
socket path using either command-line options or
<envar>PGUNIXSOCKET</envar>.
Enables secure connections using SSL. The <option>-i</option>
option is also required. You must have compiled with SSL
enabled to use this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l</term>
<term>-N <replaceable class="parameter">max-connections</replaceable></term>
<listitem>
<para>
Enables secure connections using SSL. The <option>-i</option> option
is also required.
You must have compiled with SSL enabled to use this option.
Sets the maximum number of client connections that this
postmaster will accept. By default, this value is 32, but it
can be set as high as 1024 if your system will support that
many processes. (Note that <option>-B</option> is required to
be at least twice <option>-N</option>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o <replaceable class="parameter">BackendOptions</replaceable></term>
<term>-o <replaceable class="parameter">extra-options</replaceable></term>
<listitem>
<para>
The
<literal>postgres</literal>
option(s) specified in
<replaceable class="parameter">BackendOptions</replaceable>
are passed to all backend server processes started by this
<application>postmaster</application>.
If the option string contains any spaces, the entire string must be
quoted.
The command line-style options specified in <replaceable
class="parameter">EXTRA-OPTIONS</replaceable> are passed to
all backend server processes started by this
<application>postmaster</application>. See <xref
linkend="app-postgres" endterm="app-postgres-title"> for
possibilities. If the option string contains any spaces, the
entire string must be quoted.
</para>
</listitem>
</varlistentry>
@ -225,38 +242,54 @@ postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <re
<term>-p <replaceable class="parameter">port</replaceable></term>
<listitem>
<para>
Specifies the TCP/IP port or local Unix domain socket file extension
on which the <application>postmaster</application>
is to listen for connections from frontend 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 when Postgres was
compiled (normally 5432). If you specify a port other than the
default port, then all frontend applications (including
<application>psql</application>) must specify the same
port using either command-line options or
<envar>PGPORT</envar>.
Specifies the TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
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>-S</term>
<listitem>
<para>
Specifies that the <application>postmaster</application>
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
the postmaster in the background.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Two additional command line options are available for debugging problems
that cause a backend to die abnormally.
These options control the behavior of the
<application>postmaster</application> in this situation, and
<emphasis>neither option is intended for use in
ordinary operation</emphasis>.
Two additional command line options are available for debugging
problems that cause a backend to die abnormally. These options
control the behavior of the <application>postmaster</application>
in this situation, and <emphasis>neither option is intended for
use in ordinary operation</emphasis>.
</para>
<para>
The ordinary strategy for this situation is to notify all other
backends that they must terminate and then reinitialize the shared
memory and semaphores. This is because an errant backend could have
corrupted some shared state before terminating.
memory and semaphores. This is because an errant backend could
have corrupted some shared state before terminating.
</para>
<para>
@ -292,31 +325,12 @@ postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <re
</refsect2>
<refsect2 id="R2-APP-POSTMASTER-2">
<refsect2info>
<date>1999-05-19</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<!--
<varlistentry>
<term>
FindBackend: could not find a backend to execute...
</term>
<listitem>
<para>
If you see this message, you do not have the
<application>postgres</application>
executable in your path. Add the directory in which
<application>postgres</application> resides to
your path.
</para>
</listitem>
</varlistentry>
-->
<varlistentry>
<term><computeroutput>
semget: No space left on device
@ -416,124 +430,65 @@ IpcMemoryAttach: shmat() failed: Permission denied
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-APP-POSTMASTER-1">
<refsect1info>
<date>1999-05-19</date>
</refsect1info>
<title>
Description
</title>
<para>
<application>postmaster</application>
manages the communication between frontend and backend processes, as
well as allocating the shared buffer pool and SysV semaphores
(on machines without a test-and-set instruction).
<application>postmaster</application>
does not itself interact with the user and should be started as a
background process.
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<emphasis>Only one postmaster should be running at a time in a given
<productname>Postgres</productname> installation.</emphasis>
Here, an installation means a database directory and
<application>postmaster</application> port number.
You can run more than one postmaster on a machine only if each one has a
separate directory and port number.
If at all possible, <emphasis>do not</emphasis> use
<literal>SIGKILL</literal> to kill the
<application>postmaster</application>. This will prevent
<application>postmaster</application> from freeing the system
resources (e.g., shared memory and semaphores) that it holds before
terminating.
</para>
</refsect1>
<refsect1 id="R1-APP-POSTMASTER-2">
<refsect1info>
<date>1998-10-04</date>
</refsect1info>
<title>
Notes
</title>
<para>
If at all possible,
<emphasis>do not</emphasis>
use <literal>SIGKILL</literal>
when killing the <application>postmaster</application>.
<literal>SIGHUP</literal>,
<literal>SIGINT</literal>,
or
<literal>SIGTERM</literal>
(the default signal for
<application>kill</application>(1))"
should be used instead. Using
<programlisting>
$ kill -KILL
</programlisting>
or its alternative form
<programlisting>
$ kill -9
</programlisting>
will prevent <application>postmaster</application>
from freeing the system resources (e.g., shared memory and semaphores)
that it holds before dying. Use <literal>SIGTERM</literal> instead
to avoid having to clean up manually (as described earlier).
To terminate the postmaster 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 lengthy shutdown, resulting in a recovery run
during restart.
</para>
<para>
Useful utilities for dealing with shared memory problems include
<application>ipcs(1)</application>,
<application>ipcrm(1</application>), and
<application>ipcclean(1)</application>.
The utility command <xref linkend="app-pg-ctl"> can be used to
start and shut down the postmaster safely and comfortably.
</para>
</refsect1>
<refsect1 id="R1-APP-POSTMASTER-3">
<refsect1info>
<date>1998-10-04</date>
</refsect1info>
<title>
Usage
</title>
<para>
To start <application>postmaster</application> using default
values, type:
<programlisting>
$ nohup postmaster >logfile 2>&1 &
</programlisting>
<refsect1 id="app-postmaster-usage">
<title>Usage</title>
<para>
To start <application>postmaster</application> in the background
using default values, type:
This command will start up <application>postmaster</application>
on the default port (5432). This is the
simplest and most common way to start the
<application>postmaster</application>.
<screen>
<prompt>$</prompt> <userinput>nohup postmaster &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
</screen>
</para>
<para>
To start <application>postmaster</application> with a specific port:
<programlisting>
$ nohup postmaster -p 1234 &
</programlisting>
To start <application>postmaster</application> with a specific
port:
<screen>
<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
</screen>
This command will start up <application>postmaster</application>
communicating through the port 1234. In order to
connect to this <application>postmaster</application>
using psql, you would need to run it as
<programlisting>
$ psql -p 1234
</programlisting>
communicating through the port 1234. In order to connect to this
<application>postmaster</application> using 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>:
<programlisting>
$ export PGPORT 1234
$ psql
</programlisting>
<screen>
<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
<prompt>$</prompt> <userinput>psql</userinput>
</screen>
</para>
</refsect1>
</refentry>

46
doc/src/sgml/runtime.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.34 2000/11/13 21:35:02 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.35 2000/11/14 18:11:30 petere Exp $
-->
<Chapter Id="runtime">
@ -930,7 +930,34 @@ env PGOPTIONS='-c geqo=off' psql
</varlistentry>
<varlistentry>
<term>KRB_SERVER_KEYFILE</>
<term>HOSTNAME (<type>string</type>)</term>
<listitem>
<para>
Specifies the TCP/IP hostname or address on which the
<application>postmaster</application> is to listen for
connections from client applications. Defaults to the value
of the <envar>PGHOST</envar> environment variable, or if
<envar>PGHOST</envar> is not set, it defaults to listening on
all configured addresses (including localhost).
</para>
<para>
If you use a hostname do not try to run multiple instances of
<application>postmaster</application> on the same IP address
but different ports. Doing so will result in them attempting
(incorrectly) to use the same shared memory segments. Also,
if you use a hostname, all of the host's IP addresses on which
<application>postmaster</application> instances are listening
must be distinct in the two last octets.
</para>
<para>
If you do not use this option, then each instance must listen
on a different port.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>KRB_SERVER_KEYFILE (<type>string</type>)</term>
<listitem>
<para>
Sets the location of the Kerberos server key file. See
@ -1056,6 +1083,21 @@ env PGOPTIONS='-c geqo=off' psql
</listitem>
</varlistentry>
<varlistentry>
<term>UNIXSOCKET (<type>string</type>)</term>
<listitem>
<para>
Specifies the Unix domain socket file name on which the
<application>postmaster</application> is to listen for
connections from client applications. Defaults to the value
of the <envar>PGUNIXSOCKET</envar> environment variable, or if
<envar>PGUNIXSOCKET</envar> is not set, then defaults to a
file in <filename>/tmp</filename> constructed from the port
number.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>UNIX_SOCKET_GROUP (<type>string</type>)</term>
<listitem>

26
src/backend/postmaster/postmaster.c
Unescape View File

@ -11,7 +11,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/postmaster/postmaster.c,v 1.185 2000/11/14 01:15:01 momjian Exp $
* $Header: /cvsroot/pgsql/src/backend/postmaster/postmaster.c,v 1.186 2000/11/14 18:11:31 petere Exp $
*
* NOTES
*
@ -790,30 +790,30 @@ static void
usage(const char *progname)
{
printf("%s is the PostgreSQL server.\n\n", progname);
printf("Usage:\n %s [options]\n\n", progname);
printf("Usage:\n %s [options...]\n\n", progname);
printf("Options:\n");
#ifdef USE_ASSERT_CHECKING
printf(" -A 1|0 enable/disable runtime assert checking\n");
printf(" -A 1|0 enable/disable run-time assert checking\n");
#endif
printf(" -B <buffers> number of shared buffers\n");
printf(" -c <name>=<value> set run-time parameter\n");
printf(" -B NBUFFERS number of shared buffers (default %d)\n", DEF_NBUFFERS);
printf(" -c NAME=VALUE set run-time parameter\n");
printf(" -d 1-5 debugging level\n");
printf(" -D <directory> database directory\n");
printf(" -D DATADIR database directory\n");
printf(" -F turn fsync off\n");
printf(" -h hostname specify hostname or IP address\n");
printf(" -h HOSTNAME host name or IP address to listen to\n");
printf(" -i enable TCP/IP connections\n");
printf(" -k path specify Unix-domain socket name\n");
printf(" -k FILENAME Unix domain socket location\n");
#ifdef USE_SSL
printf(" -l enable SSL connections\n");
#endif
printf(" -N <number> maximum number of allowed connections (1..%d, default %d)\n",
printf(" -N MAX-CONNECT maximum number of allowed connections (1..%d, default %d)\n",
MAXBACKENDS, DEF_MAXBACKENDS);
printf(" -o <option> pass 'option' to each backend server\n");
printf(" -p <port> port number to listen on\n");
printf(" -S silent mode (dissociate from tty)\n");
printf(" -o OPTIONS pass 'OPTIONS' to each backend server\n");
printf(" -p PORT port number to listen on (default %d)\n", DEF_PGPORT);
printf(" -S silent mode (start in background without logging output)\n");
printf("\nDeveloper options:\n");
printf(" -n don't reinitialize shared memory after abnormal exit\n");
printf(" -n do not reinitialize shared memory after abnormal exit\n");
printf(" -s send SIGSTOP to all backend servers if one dies\n");
printf("\nPlease read the documentation for the complete list of run-time\n"

57
src/backend/tcop/postgres.c
Unescape View File

@ -8,7 +8,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/tcop/postgres.c,v 1.187 2000/11/08 17:57:46 petere Exp $
* $Header: /cvsroot/pgsql/src/backend/tcop/postgres.c,v 1.188 2000/11/14 18:11:32 petere Exp $
*
* NOTES
* this is the "main" module of the postgres backend and
@ -1001,38 +1001,41 @@ SigHupHandler(SIGNAL_ARGS)
}
static void
usage(char *progname)
{
fprintf(stderr,
"Usage: %s [options] [dbname]\n", progname);
printf("%s is the PostgreSQL stand-alone backend. It is not\nintended to be used by normal users.\n\n", progname);
printf("Usage:\n %s [options...] [dbname]\n\n", progname);
printf("Options:\n");
#ifdef USE_ASSERT_CHECKING
fprintf(stderr, "\t-A on\t\tenable/disable assert checking\n");
printf(" -A 1|0 enable/disable run-time assert checking\n");
#endif
fprintf(stderr, "\t-B buffers\tset number of buffers in buffer pool\n");
fprintf(stderr, "\t-c name=value\tset run-time parameter\n");
fprintf(stderr, "\t-C \t\tsuppress version info\n");
fprintf(stderr, "\t-D dir\t\tdata directory\n");
fprintf(stderr, "\t-E \t\techo query before execution\n");
fprintf(stderr, "\t-F \t\tturn fsync off\n");
fprintf(stderr, "\t-L \t\tturn off locking\n");
fprintf(stderr, "\t-N \t\tdon't use newline as interactive query delimiter\n");
fprintf(stderr, "\t-O \t\tallow system table structure changes\n");
fprintf(stderr, "\t-Q \t\tsuppress informational messages\n");
fprintf(stderr, "\t-S kbytes\tset amount of memory for sorts (in kbytes)\n");
fprintf(stderr, "\t-T options\tspecify pg_options\n");
fprintf(stderr, "\t-W sec\t\twait N seconds to allow attach from a debugger\n");
fprintf(stderr, "\t-d [1-5]\tset debug level\n");
fprintf(stderr, "\t-e \t\tturn on European date format\n");
fprintf(stderr, "\t-f [s|i|n|m|h]\tforbid use of some plan types\n");
fprintf(stderr, "\t-i \t\tdon't execute queries\n");
fprintf(stderr, "\t-o file\t\tsend stdout and stderr to given filename\n");
fprintf(stderr, "\t-p database\tbackend is started under a postmaster\n");
fprintf(stderr, "\t-s \t\tshow stats after each query\n");
fprintf(stderr, "\t-t [pa|pl|ex]\tshow timings after each query\n");
fprintf(stderr, "\t-v version\tset protocol version being used by frontend\n");
printf(" -B NBUFFERS number of shared buffers (default %d)\n", DEF_NBUFFERS);
printf(" -c NAME=VALUE set run-time parameter\n");
printf(" -d 1-5 debugging level\n");
printf(" -D DATADIR database directory\n");
printf(" -e use European date format\n");
printf(" -E echo query before execution\n");
printf(" -F turn fsync off\n");
printf(" -N do not use newline as interactive query delimiter\n");
printf(" -o FILENAME send stdout and stderr to given file\n");
printf(" -P disable system indexes\n");
printf(" -s show statistics after each query\n");
printf(" -S SORT-MEM set amount of memory for sorts (in kbytes)\n");
printf("Developer options:\n");
printf(" -f [s|i|n|m|h] forbid use of some plan types\n");
printf(" -i do not execute queries\n");
printf(" -L turn off locking\n");
printf(" -O allow system table structure changes\n");
printf(" -t [pa|pl|ex] show timings after each query\n");
printf(" -W NUM wait NUM seconds to allow attach from a debugger\n");
printf("\nReport bugs to <pgsql-bugs@postgresql.org>.\n");
}
/* ----------------------------------------------------------------
* PostgresMain
* postgres main loop -- all backends, interactive or otherwise start here
@ -1646,7 +1649,7 @@ PostgresMain(int argc, char *argv[], int real_argc, char *real_argv[], const cha
if (!IsUnderPostmaster)
{
puts("\nPOSTGRES backend interactive interface ");
puts("$Revision: 1.187 $ $Date: 2000/11/08 17:57:46 $\n");
puts("$Revision: 1.188 $ $Date: 2000/11/14 18:11:32 $\n");
}
/*

Write Preview
Loading…
Cancel
Save