mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-22 06:23:24 +02:00
633 lines
14 KiB
Plaintext
633 lines
14 KiB
Plaintext
<Chapter Id="runtime">
|
|
<Title>Runtime Environment</Title>
|
|
|
|
<Para>
|
|
This chapter outlines the interaction between <Productname>Postgres</Productname> and
|
|
the operating system.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>Using <Productname>Postgres</Productname> from Unix</title>
|
|
|
|
<para>
|
|
All <Productname>Postgres</Productname> commands that are executed
|
|
directly from a Unix shell are
|
|
found in the directory <quote>.../bin</quote>. Including this directory in
|
|
your search path will make executing the commands easier.
|
|
</para>
|
|
|
|
<para>
|
|
A collection of system catalogs exist at each site. These include a
|
|
class (<literal>pg_user</literal>) that contains an instance for each valid
|
|
<Productname>Postgres</Productname> user. The instance specifies a set of
|
|
<Productname>Postgres</Productname> privileges, such as
|
|
the ability to act as <Productname>Postgres</Productname> super-user,
|
|
the ability to create/destroy
|
|
databases, and the ability to update the system catalogs. A Unix
|
|
user cannot do anything with <Productname>Postgres</Productname>
|
|
until an appropriate instance is
|
|
installed in this class. Further information on the system catalogs
|
|
is available by running queries on the appropriate classes.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 Id="postmaster">
|
|
<Title>Starting <Application>postmaster</Application></Title>
|
|
|
|
<Para>
|
|
Nothing can happen to a database unless the
|
|
<Application>postmaster</Application>
|
|
process is running. As the site administrator, there
|
|
are a number of things you should remember before
|
|
starting the <Application>postmaster</Application>.
|
|
These are discussed in the installation and configuration sections
|
|
of this manual.
|
|
However, if <ProductName>Postgres</ProductName> has been installed by following
|
|
the installation instructions exactly as written, the
|
|
following simple command is all you should
|
|
need to start the <Application>postmaster</Application>:
|
|
|
|
<ProgramListing>
|
|
% postmaster
|
|
</ProgramListing>
|
|
</para>
|
|
|
|
<para>
|
|
The <Application>postmaster</Application> occasionally prints out
|
|
messages which
|
|
are often helpful during troubleshooting. If you wish
|
|
to view debugging messages from the <Application>postmaster</Application>,
|
|
you can
|
|
start it with the -d option and redirect the output to
|
|
the log file:
|
|
|
|
<ProgramListing>
|
|
% postmaster -d > pm.log 2>&1 &
|
|
</ProgramListing>
|
|
|
|
If you do not wish to see these messages, you can type
|
|
<ProgramListing>
|
|
% postmaster -S
|
|
</ProgramListing>
|
|
and the <Application>postmaster</Application> will be "S"ilent.
|
|
Notice that there
|
|
is no ampersand ("&") at the end of the last example so
|
|
postmaster will be running in the foreground.
|
|
</Para>
|
|
</sect1>
|
|
|
|
<sect1 Id="pg-options">
|
|
<Title id="pg-options-title">Using pg_options</Title>
|
|
|
|
<Para>
|
|
<Note>
|
|
<Para>
|
|
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
|
|
</Para>
|
|
</Note>
|
|
</para>
|
|
<Para>
|
|
The optional file <filename>data/pg_options</filename> contains runtime
|
|
options used by the backend to control trace messages and other backend
|
|
tunable parameters.
|
|
The file is re-read by a backend
|
|
when it receives a SIGHUP signal, making thus possible to change run-time
|
|
options on the fly without needing to restart
|
|
<productname>Postgres</productname>.
|
|
The options specified in this file may be debugging flags used by the trace
|
|
package (<filename>backend/utils/misc/trace.c</filename>) or numeric
|
|
parameters which can be used by the backend to control its behaviour.
|
|
</para>
|
|
|
|
<para>
|
|
All pg_options are initialized to zero at backend startup.
|
|
New or modified options will be read by all new backends when they are started.
|
|
To make effective any changes for all running backends we need to send a
|
|
SIGHUP to the postmaster. The signal will be automatically sent to all the
|
|
backends. We can also activate the changes only for a specific backend by
|
|
sending the SIGHUP directly to it.
|
|
</para>
|
|
<para>
|
|
pg_options can also be specified with the <option>-T</option> switch of
|
|
<productname>Postgres</productname>:
|
|
|
|
<programlisting>
|
|
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
|
|
</programlisting>
|
|
</para>
|
|
|
|
<Para>
|
|
The functions used for printing errors and debug messages can now make use
|
|
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
|
|
or stderr are prefixed by a timestamp containing also the backend pid:
|
|
|
|
<programlisting>
|
|
#timestamp #pid #message
|
|
980127.17:52:14.173 [29271] StartTransactionCommand
|
|
980127.17:52:14.174 [29271] ProcessUtility: drop table t;
|
|
980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
|
|
980127.17:52:14.186 [29286] Async_NotifyHandler
|
|
980127.17:52:14.186 [29286] Waking up sleeping backend process
|
|
980127.19:52:14.292 [29286] Async_NotifyFrontEnd
|
|
980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
|
|
980127.19:52:14.466 [29286] Async_NotifyHandler done
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
This format improves readability of the logs and allows people to understand
|
|
exactly which backend is doing what and at which time. It also makes
|
|
easier to write simple awk or perl scripts which monitor the log to
|
|
detect database errors or problem, or to compute transaction time statistics.
|
|
</para>
|
|
<para>
|
|
Messages printed to syslog use the log facility LOG_LOCAL0.
|
|
The use of syslog can be controlled with the syslog pg_option.
|
|
Unfortunately many functions call directly <function>printf()</function>
|
|
to print their messages to stdout or stderr and this output can't be
|
|
redirected to syslog or have timestamps in it.
|
|
It would be advisable that all calls to printf would be replaced with the
|
|
PRINTF macro and output to stderr be changed to use EPRINTF instead so that
|
|
we can control all output in a uniform way.
|
|
</Para>
|
|
|
|
<para>
|
|
The format of the <filename>pg_options</filename> file is as follows:
|
|
|
|
<programlisting>
|
|
# <replaceable>comment</replaceable>
|
|
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable>
|
|
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1
|
|
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1
|
|
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0
|
|
</programlisting>
|
|
|
|
Note that <replaceable class="parameter">keyword</replaceable> can also be
|
|
an abbreviation of the option name defined in
|
|
<filename>backend/utils/misc/trace.c</filename>.
|
|
|
|
<example>
|
|
<title>pg_options File</title>
|
|
|
|
<para>
|
|
For example my pg_options file contains the following values:
|
|
|
|
<programlisting>
|
|
verbose=2
|
|
query
|
|
hostlookup
|
|
showportnumber
|
|
</programlisting>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Recognized Options</title>
|
|
|
|
<Para>
|
|
The options currently defined are:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
all
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Global trace flag. Allowed values are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
0
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Trace messages enabled individually
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
1
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enable all trace messages
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
-1
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Disable all trace messages
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
verbose
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Verbosity flag. Allowed values are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
0
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
No messages. This is the default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
1
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print information messages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
2
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print more information messages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
query
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Query trace flag. Allowed values are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
0
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Don't print query.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
1
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print a condensed query in one line.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
4
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print the full query.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
plan
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print query plan.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
parse
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print parser output.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
rewritten
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print rewritten query.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
parserstats
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print parser statistics.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
plannerstats
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print planner statistics.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
executorstats
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print executor statistics.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
shortlocks
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Currently unused but needed to enable features in the future.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
locks
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Trace locks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
userlocks
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Trace user locks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
spinlocks
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Trace spin locks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
notify
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Trace notify functions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
malloc
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Currently unused.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
palloc
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Currently unused.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
lock_debug_oidmin
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Minimum relation oid traced by locks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
lock_debug_relid
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
oid, if not zero, of relation traced by locks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
lock_read_priority
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Currently unused.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
deadlock_timeout
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Deadlock check timer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
syslog
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
syslog flag. Allowed values are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
0
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Messages to stdout/stderr.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
1
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Messages to stdout/stderr and syslog.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
2
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Messages only to syslog.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
hostlookup
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enable hostname lookup in ps_status.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
showportnumber
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Show port number in ps_status.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
notifyunlock
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Unlock of pg_listener after notify.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
notifyhack
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Remove duplicate tuples from pg_listener.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
</Chapter>
|
|
|
|
<!-- 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:
|
|
-->
|