#
#
# IDENTIFICATION
-# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.14 2000/05/02 20:01:51 thomas Exp $
+# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.15 2000/06/18 21:24:51 petere Exp $
#
#----------------------------------------------------------------------------
insert.sgml listen.sgml load.sgml lock.sgml move.sgml \
notify.sgml \
reindex.sgml reset.sgml revoke.sgml rollback.sgml \
- select.sgml select_into.sgml set.sgml show.sgml \
+ select.sgml select_into.sgml set.sgml set_constraints.sgml set_transaction.sgml show.sgml \
truncate.sgml unlisten.sgml update.sgml vacuum.sgml
FUNCTIONS= current_date.sgml current_time.sgml current_timestamp.sgml current_user.sgml
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.22 2000/05/02 20:01:51 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.23 2000/06/18 21:24:51 petere Exp $
Postgres Administrator's Guide.
Derived from postgres.sgml.
<!entity regress SYSTEM "regress.sgml">
<!entity release SYSTEM "release.sgml">
<!entity runtime SYSTEM "runtime.sgml">
-<!entity security SYSTEM "security.sgml">
+<!entity client-auth SYSTEM "client-auth.sgml">
+<!entity user-manag SYSTEM "user-manag.sgml">
<!entity start-ag SYSTEM "start-ag.sgml">
<!entity trouble SYSTEM "trouble.sgml">
&install;
&installw;
&runtime;
- &security;
+ &client-auth;
+ &user-manag;
&start-ag;
&manage-ag;
- &trouble;
&recovery;
®ress;
&release;
--- /dev/null
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/client-auth.sgml,v 1.1 2000/06/18 21:24:51 petere Exp $ -->
+
+<chapter id="client-authentication">
+ <title>Client Authentication</title>
+
+ <para>
+ User names from the operating system and from a
+ <productname>Postgres</productname> database installation are
+ logically separate. When a client application connects, it specifies
+ which database user name it wants to connect as, similar to how one
+ logs into a Unix computer. Within the SQL environment the active
+ database user name determines various access privileges to database
+ objects -- see <xref linkend="user-manag"> for more information
+ about that. It is therefore obviously essential to restrict what
+ database user name a given client can connect as.
+ </para>
+
+ <para>
+ <firstterm>Authentication</firstterm> is the process by which the
+ database server establishes the identity of the client, and by
+ extension determines whether the client application (or the user
+ which runs the client application) is permitted to connect with the
+ user name that was requested.
+ </para>
+
+ <para>
+ <productname>Postgres</productname> offers client authentication by
+ (client) host and by database, with a number of different
+ authentication methods available.
+ </para>
+
+ <sect1 id="pg-hba.conf">
+ <title>The <filename>pg_hba.conf</filename> file</title>
+
+ <para>
+ Client authentication is controlled by the file
+ <filename>pg_hba.conf</filename> in the data directory, e.g.,
+ <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. (HBA =
+ host-based authentication) A default file is installed when the
+ data area is initialized by <application>initdb</application>.
+ </para>
+
+ <para>
+ The general format of the <filename>pg_hba.conf</filename> file is
+ of a set of records, one per line. Blank lines and lines beginning
+ with a hash character (<quote>#</quote>) are ignored. A record is
+ made up of a number of fields which are separated by spaces and/or
+ tabs.
+ </para>
+
+ <para>
+ A record may have one of the two formats
+ <synopsis>
+local <replaceable>database</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+host <replaceable>database</replaceable> <replaceable>IP-address</replaceable> <replaceable>IP-mask</replaceable> <replaceable>authentication-method</replaceable> [ <replaceable>authentication-option</replaceable> ]
+ </synopsis>
+ The meaning of the fields is as follows:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>local</literal></term>
+ <listitem>
+ <para>
+ This record pertains to connection attempts over Unix domain
+ sockets.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>host</literal></term>
+ <listitem>
+ <para>
+ This record pertains to connection attempts over TCP/IP
+ networks. Note that TCP/IP connections are completely disabled
+ unless the server is started with the <option>-i</option> or
+ the equivalent configuration parameter is set.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>database</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the database that this record applies to. The value
+ <literal>all</literal> specifies that it applies to all
+ databases.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>IP address</replaceable></term>
+ <term><replaceable>IP mask</replaceable></term>
+ <listitem>
+ <para>
+ These two fields control to which hosts a
+ <literal>host</literal> record applies, based on their IP
+ address. (Of course IP addresses can be spoofed but this
+ consideration is beyond the scope of
+ <productname>Postgres</productname>.) The precise logic is that
+ <blockquote>
+ <informalfigure>
+ <programlisting>(<replaceable>actual-IP-address</replaceable> xor <replaceable>IP-address-field</replaceable>) and <replaceable>IP-mask-field</replaceable></programlisting>
+ </informalfigure>
+ </blockquote>
+ must be zero for the record to match.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>authentication method</replaceable></term>
+ <listitem>
+ <para>
+ Specifies the method a user must use to authenticate themselves
+ when connecting to that database.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable>authentication option</replaceable></term>
+ <listitem>
+ <para>
+ This field is interpreted differently depending on the
+ authentication method.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ The first record that matches a connection attempt is used. Note
+ that there is no <quote>fall-through</quote> or
+ <quote>backup</quote>, that is, if one record is chosen and the
+ authentication fails, the following records are not considered. If
+ no record matches, the access will be denied.
+ </para>
+
+ <para>
+ The <filename>pg_hba.conf</filename> file is re-read before each
+ connection attempt. It is therefore easily possible to modify
+ access permissions while the server is running.
+ </para>
+
+ <para>
+ An example of a <filename>pg_hba.conf</filename> file is shown in
+ <xref linkend="example-pg-hba.conf">. See below for details on the
+ different authentication methods.
+
+ <example id="example-pg-hba.conf">
+ <title>An example <filename>pg_hba.conf</filename> file</title>
+<programlisting>
+# Trust any connection via Unix domain sockets.
+local trust
+# Trust any connection via TCP/IP from this machine.
+host all 127.0.0.1 255.255.255.255 trust
+# We don't like this machine.
+host all 192.168.0.10 255.255.255.0 reject
+# This machine can't encrypt so we ask for passwords in clear.
+host all 192.168.0.3 255.255.255.0 password
+# The rest of this group of machines should provide encrypted passwords.
+host all 192.168.0.0 255.255.255.0 crypt
+# Authenticate these networks using ident
+host all 192.168.1.0 255.255.255.0 ident usermap
+host all 192.168.2.0 255.255.255.0 ident othermap
+</programlisting>
+ </example>
+ </para>
+ </sect1>
+
+ <sect1 id="auth-methods">
+ <title>Authentication methods</title>
+ <para>
+ The following authentication methods are supported. They are
+ descibed in detail below.
+
+ <variablelist>
+ <varlistentry>
+ <term>trust</term>
+ <listitem>
+ <para>
+ The connection is allowed unconditionally. This method allows
+ any user that has login access to the client host to connect as
+ any user whatsoever. Use with care.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>reject</term>
+ <listitem>
+ <para>
+ The connection is rejected unconditionally. This is mostly
+ useful to <quote>filter out</quote> certain hosts from a group.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>password</term>
+ <listitem>
+ <para>
+ The client is required to supply a password for the connection
+ attempt which is required to match the password that was set up
+ for the user. (These passwords are separate from any operating
+ sytem password.)
+ </para>
+ <para>
+ An optional password file may be specified after the
+ <literal>password</literal> keyword to obtain the password from
+ that file rather than the pg_shadow system catalog.
+ </para>
+ <para>
+ The password is sent over the wire in clear text. For better
+ protection, use the <literal>crypt</literal> method.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>crypt</term>
+ <listitem>
+ <para>
+ Like the <literal>password</literal> method, but the password
+ is sent over the wire encrypted using a simple
+ challenge-response protocol. Note that this is still not
+ cryptographically secure but it protects against incidental
+ wire-sniffing. Interestingly enough, the
+ <literal>crypt</literal> does not support secondary password
+ files.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>krb4</term>
+ <listitem>
+ <para>
+ Kerberos V4 is used to authenticate the user. This is only
+ available for TCP/IP connections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>krb5</term>
+ <listitem>
+ <para>
+ Kerberos V5 is used to authenticate the user. This is only
+ available for TCP/IP connections.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ident</term>
+ <listitem>
+ <para>
+ The ident server on the client host is asked for the identity
+ of the connecting user. <productname>Postgres</productname>
+ then verifies whether the so identified operating system user
+ is allowed to connect as the database user that is requested.
+ The <replaceable>authentication option</replaceable> following
+ the <literal>ident</> keyword specifies the name of an
+ <firstterm>ident map</firstterm> that specifies which operating
+ system users equate with which database users. See below for
+ details.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <sect2>
+ <title>Password authentication</title>
+ <para>
+ Ordinarily, the password for each database user is stored in the
+ pg_shadow system catalog table. Passwords can be managed with the
+ query language commands <command>CREATE USER</command> and
+ <command>ALTER USER</command>, e.g., <userinput>CREATE USER foo
+ WITH PASSWORD 'secret';</userinput>. By default, that is, if no
+ password has explicitly been set up, the stored password is
+ <quote>NULL</quote> and password authentication will always fail
+ for that user.
+ </para>
+
+ <para>
+ Secondary password files can be used if a given set of passwords
+ should only apply to a particular database or set thereof.
+ Secondary password files have a format similar to the standard
+ Unix password file <filename>/etc/passwd</filename>, that is,
+ <synopsis>
+<replaceable>username</replaceable>:<replaceable>password</replaceable>
+ </synopsis>
+ Any extra colon separated fields following the password are
+ ignored. The password is expected to be encrypted using the
+ system's <function>crypt()</function> function. The utility
+ program <application>pg_passwd</application> that is installed
+ with <productname>Postgres</productname> can be used to manage
+ these password files.
+ </para>
+
+ <para>
+ Secondary password files can also be used to restrict certain
+ users from connecting to certain databases at all. This is
+ currently not possible to achieve using the normal password
+ mechanism (because users and passwords are global across all
+ databases). If a user is not listed in the applicable password
+ file the connection will be refused.
+ </para>
+
+ <para>
+ Note that using secondary password files means that one can no
+ longer use <command>ALTER USER</command> to change one's password.
+ It will still appear to work but the password one is actually
+ changing is not the password that the system will end up using.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Kerberos authentication</title>
+
+ <para>
+ <productname>Kerberos</productname> is an industry-standard secure
+ authentication system suitable for distributed computing over a
+ public network. A description of the
+ <productname>Kerberos</productname> system is far beyond the scope
+ of this document; in all generality it can be quite complex. The
+ <ulink url="http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html">Kerberos <acronym>FAQ</></ulink>
+ can be a good starting point for exploration.
+ </para>
+
+ <para>
+ In order to use <productname>Kerberos</>, support for it must be
+ enable at build time. Both Kerberos 4 and 5 are supported.
+ </para>
+
+ <para>
+ <productname>Postgres</> should operate like a normal Kerberos
+ service. The name of the service principal is normally
+ <literal>postgres</literal>, unless it was changed during the
+ build. Make sure that your server keytab file is readable (and
+ preferrably only readable) by the Postgres server account (see
+ <xref linkend="postgres-user">). The location of the keytab file
+ is specified at build time. By default it is
+ <filename>/etc/srvtab</filename> in Kerberos 4 and
+ <filename>FILE:/usr/local/postgres/krb5.keytab</filename> in
+ Kerberos 5.
+ </para>
+<!-- Note from Peter E.: Some of the Kerberos usage information is
+still in config.sgml and some in doc/README.kerberos. It should be
+integrated here. -->
+ </sect2>
+
+ <sect2>
+ <title>Ident-based authentication</title>
+
+ <para>
+ The <quote>Identification Protocol</quote> is described in
+ <citetitle>RFC 1413</citetitle>. Virtually every Unix-like
+ operating systems ships with an ident server that listens on TCP
+ port 113 by default. The basic functionality of the ident server
+ is to answer questions like <quote>What user initiated the
+ connection that goes out of your port <replaceable>X</replaceable>
+ and connects to my port <replaceable>Y</replaceable>?</quote>.
+ Since both <replaceable>X</replaceable> and
+ <replaceable>Y</replaceable> are known,
+ <productname>Postgres</productname> could theoretically determine
+ the operating system user for any given connection this way.
+ </para>
+
+ <para>
+ The drawback of this procedure is that it depends on the integrity
+ of the client: if the client machine is untrusted or compromised
+ an attacker could run just about any program on port 113 and
+ return any user name he chooses. This authentication method is
+ therefore only appropriate for closed networks where each client
+ machine is under tight control and where the database and system
+ administrators operate in close contact. Heed the warning:
+ <blockquote>
+ <attribution>RFC 1413</attribution>
+ <para>
+ The Identification Protocol is not intended as an authorization
+ or access control protocol.
+ </para>
+ </blockquote>
+ </para>
+
+ <para>
+ When using ident-based authentication, after having determined the
+ operating system user that initiated the connection,
+ <productname>Postgres</productname> determines as what database
+ system user he may connect. This is controlled by the ident map
+ argument that follows the <literal>ident</> keyword in the
+ <filename>pg_hba.conf</filename> file. The simplest ident map is
+ <literal>sameuser</literal>, which allows any operating system
+ user to connect as the database user of the same name (if the
+ latter exists). Other maps must be created manually.
+ </para>
+
+ <para>
+ Ident maps are held in the file <filename>pg_ident.conf</filename>
+ in the data directory, which contains lines of the general form:
+<synopsis>
+<replaceable>map-name</> <replaceable>ident-username</> <replaceable>database-username</>
+</synopsis>
+ Comments and whitespace are handled in the usual way.
+ The <replaceable>map-name</> is an arbitrary name that will be
+ used to refer to this mapping in <filename>pg_hba.conf</filename>.
+ The other two fields specify which operating system user is
+ allowed to connect as which database user. The same
+ <replaceable>map-name</> can be used repeatedly to specify more
+ user-mappings. There is also no restriction regarding how many
+ database users a given operating system may correspond to and vice
+ versa.
+ </para>
+
+ <para>
+ A <filename>pg_ident.conf</filename> file that could be used in
+ conjunction with the <filename>pg_hba.conf</> file in <xref
+ linkend="example-pg-hba.conf"> is shown in <xref
+ linkend="example-pg-ident.conf">. In that example setup, anyone
+ logged in to a machine on the 192.168.1 network that does not have
+ the a user name joe, robert, or ann would not be granted access.
+ Unix user robert would only be allowed access when he tries to
+ connect as <quote>bob</quote>, not as <quote>robert</quote> or
+ anyone else. <quote>ann</quote> and <quote>joe</quote> would only
+ be allowed to connect <quote>as themselves</quote>. On the
+ 192.168.2 network, however, a user <quote>ann</quote> would not be
+ allowed to connect at all, only the user <quote>bob</> can connect
+ as <quote>bob</> and some user <quote>karl</> can connect as
+ <quote>joe</> as well.
+ </para>
+
+ <example id="example-pg-ident.conf">
+ <title>An example <filename>pg_ident.conf</> file</title>
+<programlisting>
+usermap joe joe
+# bob has username robert on these machines
+usermap robert bob
+usermap ann ann
+
+othermap joe joe
+othermap bob bob
+othermap karl joe
+</programlisting>
+ </example>
+ </sect2>
+ </sect1>
+
+ <sect1 id="client-authentication-problems">
+ <title>Authentication problems</title>
+
+ <para>
+ Genuine authentication failures and related problems generally
+ manifest themselves through error messages like the following.
+ </para>
+
+ <para>
+<ProgramListing>
+No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
+</ProgramListing>
+ This is what you are most likely to get if you succeed in
+ contacting the server, but it doesn't want to talk to you. As the
+ message suggests, the server refused the connection request
+ because it found no authorizing entry in its <filename>pg_hba.conf</filename>
+ configuration file.
+ </para>
+
+ <para>
+<ProgramListing>
+Password authentication failed for user 'joeblow'
+</ProgramListing>
+ Messages like this indicate that you contacted the server, and
+ it's willing to talk to you, but not until you pass the
+ authorization method specified in the
+ <filename>pg_hba.conf</filename> file. Check the password you're
+ providing, or check your Kerberos or IDENT software if the
+ complaint mentions one of those authentication types.
+ </para>
+
+ <para>
+<ProgramListing>
+FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow'
+</ProgramListing>
+ This is the fancy way of saying that the user doesn't exist at all.
+ </para>
+
+ <para>
+<ProgramListing>
+FATAL 1: Database testdb does not exist in pg_database
+</ProgramListing>
+ The database you're trying to connect to doesn't exist. Note that
+ if you don't specify a database name, it defaults to the database
+ user name, which may or may not be the right thing.
+ </para>
+ </sect1>
+
+ </chapter>
+
+++ /dev/null
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/pg_options.sgml,v 1.5 2000/03/31 03:27:41 thomas Exp $
--->
-
- <Chapter Id="pg-options-dev">
- <DocInfo>
- <AuthorGroup>
- <Author>
- <FirstName>Massimo</FirstName>
- <Surname>Dal Zotto</Surname>
- </Author>
- </AuthorGroup>
- <Date>Transcribed 1998-10-16</Date>
- </DocInfo>
-
- <Title>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.
- What makes this file interesting is the fact that it 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.
- New options and parameters must be defined in
- <filename>backend/utils/misc/trace.c</filename> and
- <filename>backend/include/utils/trace.h</filename>.
- </para>
- <Para>
- For example suppose we want to add conditional trace messages and a tunable
- numeric parameter to the code in file <filename>foo.c</filename>.
- All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
- <filename>backend/include/utils/trace.h</filename>:
-
- <programlisting>
-/* file trace.h */
-enum pg_option_enum {
- ...
- TRACE_FOO, /* trace foo functions */
- OPT_FOO_PARAM, /* foo tunable parameter */
-
- NUM_PG_OPTIONS /* must be the last item of enum */
-};
- </programlisting>
-
- and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
-
- <programlisting>
-/* file trace.c */
-static char *opt_names[] = {
- ...
- "foo", /* trace foo functions */
- "fooparam" /* foo tunable parameter */
-};
- </programlisting>
-
- Options in the two files must be specified in exactly the same order.
- In the foo source files we can now reference the new flags with:
-
- <programlisting>
-/* file foo.c */
-#include "trace.h"
-#define foo_param pg_options[OPT_FOO_PARAM]
-
-int
-foo_function(int x, int y)
-{
- TPRINTF(TRACE_FOO, "entering foo_function, foo_param=%d", foo_param);
- if (foo_param > 10) {
- do_more_foo(x, y);
- }
-}
- </programlisting>
- </para>
- <para>
- Existing files using private trace flags can be changed by simply adding
- the following code:
-
- <programlisting>
-#include "trace.h"
-/* int my_own_flag = 0; -- removed */
-#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
- </programlisting>
- </para>
- <para>
- All pg_options are initialized to zero at backend startup. If we need a
- different default value we must add some initialization code at the beginning
- of <function>PostgresMain</function>.
-
- Now we can set the foo_param and enable foo trace by writing values into the
- <filename>data/pg_options</filename> file:
-
- <programlisting>
-# file pg_options
-...
-foo=1
-fooparam=17
- </programlisting>
- </para>
- <para>
- The new options will be read by all new backends when they are started.
- To make effective the 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 new pg_options mechanism is more convenient than defining new backend
- option switches because:
-
- <ItemizedList Mark="bullet" Spacing="compact">
- <ListItem>
- <Para>
- we don't have to define a different switch for each thing we want to control.
- All options are defined as keywords in an external file stored in the data
- directory.
- </Para>
- </ListItem>
-
- <ListItem>
- <Para>
- we don't have to restart <productname>Postgres</productname> to change
- the setting of some option.
- Normally backend options are specified to the postmaster and passed to each
- backend when it is started. Now they are read from a file.
- </Para>
- </ListItem>
-
- <ListItem>
- <Para>
- we can change options on the fly while a backend is running. We can thus
- investigate some problem by activating debug messages only when the problem
- appears. We can also try different values for tunable parameters.
- </Para>
- </ListItem>
- </ItemizedList>
-
- 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>.
- </Para>
-
- <para>
- Refer to <citetitle>The Administrator's Guide</citetitle> chapter
- on runtime options for a complete list of currently supported
- options.
- </para>
-
- <Para>
- Some of the existing code using private variables and option switches has
- been changed to make use of the pg_options feature, mainly in
- <filename>postgres.c</filename>. It would be advisable to modify
- all existing code
- in this way, so that we can get rid of many of the switches on
- the <productname>Postgres</productname> command line
- and can have more tunable options
- with a unique place to put option values.
- </Para>
-
- </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:
--->
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.37 2000/06/18 21:24:51 petere Exp $
-->
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!entity regress SYSTEM "regress.sgml">
<!entity release SYSTEM "release.sgml">
<!entity runtime SYSTEM "runtime.sgml">
-<!entity security SYSTEM "security.sgml">
+<!entity client-auth SYSTEM "client-auth.sgml">
+<!entity user-manag SYSTEM "user-manag.sgml">
<!entity start-ag SYSTEM "start-ag.sgml">
-<!entity trouble SYSTEM "trouble.sgml">
<!-- programmer's guide -->
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
<!entity index SYSTEM "index.sgml">
-<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
-<!entity signals SYSTEM "signals.sgml">
<!entity sources SYSTEM "sources.sgml">
]>
<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc -->
&install;
&installw;
&runtime;
- &security;
+ &client-auth;
+ &user-manag;
&start-ag;
&manage-ag;
- &trouble;
&recovery;
®ress;
&release;
</partintro>
&sources;
&arch-dev;
- &options;
&geqo;
<!--
This listing of Postgres catalogs is currently just a copy of the old
&catalogs;
-->
&protocol;
- &signals;
&compiler;
&bki;
&page;
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.26 2000/05/02 20:01:52 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.27 2000/06/18 21:24:51 petere Exp $
Postgres Programmer's Guide.
-->
<!entity cvs SYSTEM "cvs.sgml">
<!entity docguide SYSTEM "docguide.sgml">
<!entity geqo SYSTEM "geqo.sgml">
-<!entity options SYSTEM "pg_options.sgml">
<!entity page SYSTEM "page.sgml">
<!entity protocol SYSTEM "protocol.sgml">
-<!entity signals SYSTEM "signals.sgml">
<!entity sources SYSTEM "sources.sgml">
]>
&sources;
&arch-dev;
- &options;
&geqo;
<!--
This listing of Postgres catalogs is currently just a copy of the old
&catalogs;
-->
&protocol;
- &signals;
&compiler;
&bki;
&page;
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.18 2000/04/14 15:17:28 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.19 2000/06/18 21:24:51 petere Exp $
Postgres documentation
Complete list of usable sgml source files in this directory.
-->
<!entity select system "select.sgml">
<!entity selectInto system "select_into.sgml">
<!entity set system "set.sgml">
+<!entity setConstraints system "set_constraints.sgml">
+<!entity setTransaction system "set_transaction.sgml">
<!entity show system "show.sgml">
<!entity truncate system "truncate.sgml">
<!entity unlisten system "unlisten.sgml">
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/commands.sgml,v 1.25 2000/04/14 15:17:28 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/Attic/commands.sgml,v 1.26 2000/06/18 21:24:51 petere Exp $
Postgres documentation
-->
&select;
&selectInto;
&set;
+ &setConstraints;
+ &setTransaction;
&show;
&truncate;
&unlisten;
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.8 2000/04/08 02:39:02 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/reset.sgml,v 1.9 2000/06/18 21:24:51 petere Exp $
Postgres documentation
-->
<refentry id="SQL-RESET">
<refmeta>
- <refentrytitle id="SQL-RESET-TITLE">
- RESET
- </refentrytitle>
+ <refentrytitle id="SQL-RESET-TITLE">RESET</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
- <refname>
- RESET
- </refname>
- <refpurpose>
- Restores run-time parameters for session to default values
- </refpurpose>
+ <refname>RESET</refname>
+ <refpurpose>Restores run-time parameters to default values</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <refsynopsisdivinfo>
- <date>1999-07-20</date>
- </refsynopsisdivinfo>
<synopsis>
RESET <replaceable class="PARAMETER">variable</replaceable>
</synopsis>
<refsect2 id="R2-SQL-RESET-1">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Inputs
- </title>
+ <title>Inputs</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">variable</replaceable></term>
<listitem>
<para>
- Refer to
- <xref linkend="sql-set-title" endterm="sql-set-title">
- for more information on available variables.
+ The name of a run-time parameter. See <xref
+ linkend="sql-set-title" endterm="sql-set-title"> for a list.
</para>
</listitem>
</varlistentry>
</para>
</refsect2>
- <refsect2 id="R2-SQL-RESET-2">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Outputs
- </title>
- <para>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>
-RESET VARIABLE
- </computeroutput></term>
- <listitem>
- <para>
- Message returned if
- <replaceable class="PARAMETER">variable</replaceable> is successfully reset
- to its default value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </refsect2>
</refsynopsisdiv>
- <refsect1 id="R1-SQL-RESET-1">
- <refsect1info>
- <date>1998-09-24</date>
- </refsect1info>
- <title>
- Description
- </title>
+ <refsect1>
+ <title>Description</title>
<para>
- <command>RESET</command> restores variables to their
- default values.
- Refer to
+ <command>RESET</command> restores run-time parameters to their
+ default values. Refer to
<xref linkend="sql-set-title" endterm="sql-set-title">
- for details on allowed values and defaults.
- <command>RESET</command> is an alternate form for
+ for details. <command>RESET</command> is an alternate form for
<synopsis>
-SET <replaceable class="parameter">variable</replaceable> = DEFAULT
+SET <replaceable class="parameter">variable</replaceable> TO DEFAULT
</synopsis>
</para>
+ </refsect1>
- <refsect2 id="R2-SQL-RESET-3">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Notes
- </title>
-
- <para>
- See also
- <xref linkend="sql-set-title" endterm="sql-set-title"> and
- <xref linkend="sql-show-title" endterm="sql-show-title">
- to manipulate variable values.
- </para>
- </refsect2>
+ <refsect1>
+ <title>Diagnostics</title>
+ <para>
+ See under the <xref linkend="sql-set-title"
+ endterm="sql-set-title"> command.
+ </para>
</refsect1>
-
- <refsect1 id="R1-SQL-RESET-2">
- <title>
- Usage
- </title>
+
+ <refsect1>
+ <title>Examples</title>
<para>
Set DateStyle to its default value:
- <programlisting>
+<screen>
RESET DateStyle;
- </programlisting>
+</screen>
</para>
<para>
Set Geqo to its default value:
- <programlisting>
+<screen>
RESET GEQO;
- </programlisting>
+</screen>
</para>
</refsect1>
- <refsect1 id="R1-SQL-RESET-3">
- <title>
- Compatibility
- </title>
+ <refsect1>
+ <title>Compatibility</title>
- <refsect2 id="R2-SQL-RESET-4">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- SQL92
- </title>
- <para>
- There is no <command>RESET</command> in <acronym>SQL92</acronym>.
- </para>
- </refsect2>
+ <para>
+ <command>RESET</command> is a <productname>Postgres</productname> extension.
+ </para>
</refsect1>
</refentry>
<!--
-<<<<<<< set.sgml
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.44 2000/06/09 01:44:00 momjian Exp $
-=======
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.44 2000/06/09 01:44:00 momjian Exp $
->>>>>>> 1.43
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.45 2000/06/18 21:24:52 petere Exp $
Postgres documentation
-->
<refentry id="SQL-SET">
<refmeta>
- <refentrytitle id="SQL-SET-TITLE">
- SET
- </refentrytitle>
+ <refentrytitle id="SQL-SET-TITLE">SET</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
- <refname>
- SET
- </refname>
- <refpurpose>
- Set run-time parameters for session
- </refpurpose>
+ <refname>SET</refname>
+ <refpurpose>Set run-time parameters</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <refsynopsisdivinfo>
- <date>1999-07-20</date>
- </refsynopsisdivinfo>
<synopsis>
SET <replaceable class="PARAMETER">variable</replaceable> { TO | = } { <replaceable class="PARAMETER">value</replaceable> | '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT }
-SET CONSTRAINTS {ALL | <replaceable class="parameter">constraintlist</replaceable>} <replaceable>mode</replaceable>
SET TIME ZONE { '<replaceable class="PARAMETER">timezone</replaceable>' | LOCAL | DEFAULT }
-SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
</synopsis>
<refsect2 id="R2-SQL-SET-1">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Inputs
- </title>
+ <title>Inputs</title>
<para>
-
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">variable</replaceable></term>
<listitem>
<para>
- Settable global parameter.
+ A settable run-time parameter.
</para>
</listitem>
</varlistentry>
</varlistentry>
</variablelist>
</para>
+ </refsect2>
- <para>
- The possible variables and allowed values are:
-
- <variablelist>
- <varlistentry>
- <term>CLIENT_ENCODING | NAMES</term>
- <listitem>
- <para>
- Sets the multi-byte client encoding. Parameters are:
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">value</replaceable></term>
- <listitem>
- <para>
- Sets the multi-byte client encoding to
- <replaceable class="parameter">value</replaceable>.
- The specified encoding must be supported by the backend.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DATESTYLE</term>
- <listitem>
- <para>
- Set the date/time representation style. Affects the output format,
- and in some cases it can affect the interpretation of input.
-
- <variablelist>
- <varlistentry>
- <term>ISO</term>
- <listitem>
- <para>
- use ISO 8601-style dates and times
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>SQL</term>
- <listitem>
- <para>
- use Oracle/Ingres-style dates and times
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Postgres</term>
- <listitem>
- <para>
- use traditional <productname>Postgres</productname> format
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>European</term>
- <listitem>
- <para>
- use <literal>dd/mm/yyyy</literal> for numeric date representations.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>NonEuropean</term>
- <listitem>
- <para>
- use <literal>mm/dd/yyyy</literal> for numeric date representations.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>German</term>
- <listitem>
- <para>
- use <literal>dd.mm.yyyy</literal> for numeric date representations.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>US</term>
- <listitem>
- <para>
- same as <literal>NonEuropean</literal>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DEFAULT</term>
- <listitem>
- <para>
- restores the default values (<literal>ISO</literal>)
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- Date format initialization may be done by:
- <simplelist>
- <member>
- Setting the <envar>PGDATESTYLE</envar> environment variable.
- If PGDATESTYLE is set in the frontend environment of a client
- based on libpq, libpq will automatically set DATESTYLE to the
- value of PGDATESTYLE during connection startup.
- </member>
- <member>
- Running postmaster using the option <option>-o -e</option> to set
- dates to the <literal>European</literal> convention.
- Note that this affects only some combinations of date styles; for example
- the ISO style is not affected by this parameter.
- </member>
- <member>
- Changing variables in
- <filename>src/backend/utils/init/globals.c</filename>.
- </member>
- </simplelist>
- </para>
- <para>
- The variables in <filename>globals.c</filename> which can be changed are:
- <simplelist>
- <member>
- bool EuroDates = false | true
- </member>
- <member>
- int DateStyle = USE_ISO_DATES | USE_POSTGRES_DATES | USE_SQL_DATES | USE_GERMAN_DATES
- </member>
- </simplelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SEED</term>
- <listitem>
- <para>
- Sets the internal seed for the random number generator.
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">value</replaceable></term>
- <listitem>
- <para>
- The value for the seed to be used by the
- <function>random</function> catalog function. Significant
- values are floating point numbers between 0 and 1, which
- are then multiplied by RAND_MAX. This product will
- silently overflow if a number outside the range is used.
- </para>
-
- <para>
- The seed can also be set by invoking the
- <function>setseed</function> SQL function:
-
- <programlisting>
-SELECT setseed(<replaceable>value</replaceable>);
- </programlisting>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SERVER_ENCODING</term>
- <listitem>
- <para>
- Sets the multi-byte server encoding to:
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">value</replaceable></term>
- <listitem>
- <para>
- The identifying value for the server encoding.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>CONSTRAINTS</term>
- <listitem>
- <para>
- SET CONSTRAINTS affects the behavior of constraint evaluation
- in the current transaction.
- SET CONSTRAINTS, specified
- in SQL3, has these allowed parameters:
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">constraintlist</replaceable></term>
- <listitem>
- <para>
- Comma separated list of deferrable constraint names.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><replaceable class="parameter">mode</replaceable></term>
- <listitem>
- <para>
- The constraint mode. Allowed values are
- <option>DEFERRED</option> and <option>IMMEDIATE</option>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- In <option>IMMEDIATE</option> mode, foreign key constraints
- are checked at the end of each query.
- </para>
-
- <para>
- In <option>DEFERRED</option> mode, foreign key constraints
- marked as <option>DEFERRABLE</option> are checked only at
- transaction commit or until its mode is explicitly set to
- <option>IMMEDIATE</option>.
- This is actually only done for foreign key
- constraints, so it does not apply to UNIQUE or other
- constraints.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>TIME ZONE</term>
- <term>TIMEZONE</term>
- <listitem>
- <para>
- The possible values for timezone depends on your operating
- system. For example on Linux /usr/lib/zoneinfo contains the
- database of timezones.
- </para>
- <para>
- Here are some valid values for timezone:
-
- <variablelist>
- <varlistentry>
- <term>PST8PDT</term>
- <listitem>
- <para>
- set the timezone for California
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Portugal</term>
- <listitem>
- <para>
- set time zone for Portugal.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>'Europe/Rome'</term>
- <listitem>
- <para>
- set time zone for Italy.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DEFAULT</term>
- <listitem>
- <para>
- set time zone to your local timezone
- (value of the TZ environment variable).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- If an invalid time zone is specified, the time zone
- becomes GMT (on most systems anyway).
- </para>
- <para>
- The second syntax shown above, allows one to set the timezone
- with a syntax similar to SQL92 <command>SET TIME ZONE</command>.
- The LOCAL keyword is just an alternate form
- of DEFAULT for SQL92 compatibility.
- </para>
- <para>
- If the PGTZ environment variable is set in the frontend
- environment of a client based on libpq, libpq will automatically
- set TIMEZONE to the value of PGTZ during connection startup.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>TRANSACTION ISOLATION LEVEL</term>
- <listitem>
- <para>
- Sets the isolation level for the current transaction.
-
- <variablelist>
- <varlistentry>
- <term>READ COMMITTED</term>
- <listitem>
- <para>
- The current transaction queries read only rows committed
- before a query began. READ COMMITTED is the default.
- </para>
-
- <note>
- <para>
- <acronym>SQL92</acronym> standard requires
- SERIALIZABLE to be the default isolation level.
- </para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SERIALIZABLE</term>
- <listitem>
- <para>
- The current transaction queries read only rows committed
- before first DML statement
- (<command>SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO</command>)
- was executed in this transaction.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- There are also several internal or optimization
- parameters which can be specified
- by the <command>SET</command> command:
-
- <variablelist>
- <varlistentry>
- <term>PG_OPTIONS</term>
- <listitem>
- <para>
- Sets various backend parameters.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>RANDOM_PAGE_COST</term>
- <listitem>
- <para>
- Sets the optimizer's estimate of the cost of a nonsequentially
- fetched disk page. This is measured as a multiple of the cost
- of a sequential page fetch.
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">float8</replaceable></term>
- <listitem>
- <para>
- Set the cost of a random page access
- to the specified floating-point value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>CPU_TUPLE_COST</term>
- <listitem>
- <para>
- Sets the optimizer's estimate of the cost of processing each
- tuple during a query. This is measured as a fraction of the cost
- of a sequential page fetch.
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">float8</replaceable></term>
- <listitem>
- <para>
- Set the cost of per-tuple CPU processing
- to the specified floating-point value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>CPU_INDEX_TUPLE_COST</term>
- <listitem>
- <para>
- Sets the optimizer's estimate of the cost of processing each
- index tuple during an index scan. This is measured as a fraction
- of the cost of a sequential page fetch.
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">float8</replaceable></term>
- <listitem>
- <para>
- Set the cost of per-index-tuple CPU processing
- to the specified floating-point value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>CPU_OPERATOR_COST</term>
- <listitem>
- <para>
- Sets the optimizer's estimate of the cost of processing each
- operator in a WHERE clause. This is measured as a fraction
- of the cost of a sequential page fetch.
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">float8</replaceable></term>
- <listitem>
- <para>
- Set the cost of per-operator CPU processing
- to the specified floating-point value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>EFFECTIVE_CACHE_SIZE</term>
- <listitem>
- <para>
- Sets the optimizer's assumption about the effective size of the
- disk cache (that is, the portion of the kernel's disk cache that
- will be used for Postgres data files). This is measured in disk
- pages, which are normally 8Kb apiece.
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">float8</replaceable></term>
- <listitem>
- <para>
- Set the assumed cache size
- to the specified floating-point value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>EXAMINE_SUBCLASS</term>
- <listitem>
- <para>
- Changes the behaviour of SELECT so that it no longer automatically
- examines sub-classes. (See SELECT). By default a SELECT on a table
- will also return subclass tuples unless specifying ONLY tablename.
- Setting this returns postgres to the traditional behaviour of
- only returning subclasses when appending "*" to the tablename.
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- Returns SELECT to the behaviour of automatically returning
- results from sub-classes.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
- <listitem>
- <para>
- Prevents SELECT from returning sub-classes unless the "*" follows the table name
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-SQL-SET-1">
+ <title>Description</title>
+ <para>
+ The <command>SET</command> command changes run-time configuration
+ parameters. The following parameters can be altered:
+
+ <variablelist>
+ <varlistentry>
+ <term>CLIENT_ENCODING</term>
+ <term>NAMES</term>
+ <listitem>
+ <para>
+ Sets the multi-byte client encoding. The specified encoding
+ must be supported by the backend.
+ </para>
+
+ <para>
+ This option is only available if
+ <productname>Postgres</productname> is build with multibyte
+ support.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DATESTYLE</term>
+ <listitem>
+ <para>
+ Choose the date/time representation style. Two separate
+ settings are made: the default date/time output and the
+ interpretation of ambiguous input.
+ </para>
+
+ <para>
+ The following are date/time output styles:
+
+ <variablelist>
+ <varlistentry>
+ <term>ISO</term>
+ <listitem>
+ <para>
+ Use ISO 8601-style dates and times (<literal>YYYY-MM-DD
+ HH:MM:SS</literal>). This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SQL</term>
+ <listitem>
+ <para>
+ Use Oracle/Ingres-style dates and times. Note that this
+ style has nothing to do with SQL (which mandates ISO 8601
+ style), the naming of this option is a historical accident.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Postgres</term>
+ <listitem>
+ <para>
+ Use traditional <productname>Postgres</productname> format.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>German</term>
+ <listitem>
+ <para>
+ Use <literal>dd.mm.yyyy</literal> for numeric date representations.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ The following two options determine both a substyle of the
+ <quote>SQL</quote> and <quote>Postgres</quote> output formats
+ and the preferred interpretation of ambiguous date input.
+
+ <variablelist>
+ <varlistentry>
+ <term>European</term>
+ <listitem>
+ <para>
+ Use <literal>dd/mm/yyyy</literal> for numeric date representations.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>NonEuropean</term>
+ <term>US</term>
+ <listitem>
+ <para>
+ Use <literal>mm/dd/yyyy</literal> for numeric date representations.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ A value for <command>SET DATESTYLE</command> can be one from
+ the first list (output styles), or one from the second list
+ (substyles), or one from each separated by a comma.
+ </para>
+
+ <para>
+ Date format initialization may be done by:
+ <simplelist>
+ <member>
+ Setting the <envar>PGDATESTYLE</envar> environment variable.
+ If PGDATESTYLE is set in the frontend environment of a client
+ based on libpq, libpq will automatically set DATESTYLE to the
+ value of PGDATESTYLE during connection startup.
+ </member>
+ <member>
+ Running postmaster using the option <option>-o -e</option> to
+ set dates to the <literal>European</literal> convention.
+ </member>
+ </simplelist>
+ </para>
+ <para>
+ The <option>DateStyle</option> option is really only intended
+ for porting applications. To format your date/time values to
+ choice, use the <function>to_char</function> family of
+ functions.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
- <term>ENABLE_SEQSCAN</term>
+ <term>SEED</term>
<listitem>
<para>
- Enables or disables the planner's use of sequential scan plan types.
- (It's not possible to suppress sequential scans entirely, but turning
- this variable OFF discourages the planner from using one if there is
- any other method available.)
-
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of sequential scans (default setting).
- </para>
- </listitem>
- </varlistentry>
+ Sets the internal seed for the random number generator.
- <varlistentry>
- <term>OFF</term>
- <listitem>
- <para>
- disables use of sequential scans.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ENABLE_INDEXSCAN</term>
- <listitem>
- <para>
- Enables or disables the planner's use of index scan plan types.
-
<variablelist>
<varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of index scans (default setting).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
+ <term><replaceable class="parameter">value</replaceable></term>
<listitem>
<para>
- disables use of index scans.
+ The value for the seed to be used by the
+ <function>random</function> catalog function. Significant
+ values are floating point numbers between 0 and 1, which
+ are then multiplied by RAND_MAX. This product will
+ silently overflow if a number outside the range is used.
</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ENABLE_TIDSCAN</term>
- <listitem>
- <para>
- Enables or disables the planner's use of TID scan plan types.
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of TID scans (default setting).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
- <listitem>
<para>
- disables use of TID scans.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ENABLE_SORT</term>
- <listitem>
- <para>
- Enables or disables the planner's use of explicit sort steps.
- (It's not possible to suppress explicit sorts entirely, but turning
- this variable OFF discourages the planner from using one if there is
- any other method available.)
+ The seed can also be set by invoking the
+ <function>setseed</function> SQL function:
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of sorts (default setting).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
- <listitem>
- <para>
- disables use of sorts.
+ <programlisting>
+SELECT setseed(<replaceable>value</replaceable>);
+ </programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
+
</listitem>
</varlistentry>
<varlistentry>
- <term>ENABLE_NESTLOOP</term>
+ <term>SERVER_ENCODING</term>
<listitem>
<para>
- Enables or disables the planner's use of nested-loop join plans.
- (It's not possible to suppress nested-loop joins entirely, but turning
- this variable OFF discourages the planner from using one if there is
- any other method available.)
-
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of nested-loop joins (default setting).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
- <listitem>
- <para>
- disables use of nested-loop joins.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ Sets the multi-byte server encoding.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ENABLE_MERGEJOIN</term>
- <listitem>
<para>
- Enables or disables the planner's use of mergejoin plans.
-
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of merge joins (default setting).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
- <listitem>
- <para>
- disables use of merge joins.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ This option is only available if
+ <productname>Postgres</productname> was built with multibyte
+ support.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>ENABLE_HASHJOIN</term>
+ <term>TIME ZONE</term>
+ <term>TIMEZONE</term>
<listitem>
<para>
- Enables or disables the planner's use of hashjoin plans.
-
- <variablelist>
- <varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables use of hash joins (default setting).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
- <listitem>
- <para>
- disables use of hash joins.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ The possible values for timezone depends on your operating
+ system. For example, on Linux
+ <filename>/usr/share/zoneinfo</filename> contains the database
+ of time zones.
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>GEQO</term>
- <listitem>
<para>
- Sets the threshold for using the genetic optimizer algorithm.
-
+ Here are some valid values for timezone:
+
<variablelist>
<varlistentry>
- <term>ON</term>
- <listitem>
- <para>
- enables the genetic optimizer algorithm
- for statements with 11 or more tables.
- (This is also the DEFAULT setting.)
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ON=<replaceable class="parameter">#</replaceable></term>
- <listitem>
- <para>
- Takes an integer argument to enable the genetic optimizer algorithm
- for statements with <replaceable class="parameter">#</replaceable>
- or more tables in the query.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>OFF</term>
+ <term>PST8PDT</term>
<listitem>
<para>
- disables the genetic optimizer algorithm.
+ Set the time zone for California.
</para>
</listitem>
</varlistentry>
- </variablelist>
- </para>
-
- <para>
- See the chapter on GEQO in the Programmer's Guide
- for more information about query optimization.
- </para>
- <para>
- If the PGGEQO environment variable is set in the frontend
- environment of a client based on libpq, libpq will automatically
- set GEQO to the value of PGGEQO during connection startup.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>KSQO</term>
- <listitem>
- <para>
- <firstterm>Key Set Query Optimizer</firstterm> causes the query
- planner to convert queries whose WHERE clause contains many
- OR'ed AND clauses (such as "WHERE (a=1 AND b=2) OR (a=2 AND b=3) ...")
- into a UNION query. This method can be faster than the default
- implementation, but it doesn't necessarily give exactly the same
- results, since UNION implicitly adds a SELECT DISTINCT clause to
- eliminate identical output rows. KSQO is commonly used when
- working with products like <productname>MicroSoft
- Access</productname>, which tend to generate queries of this form.
-
- <variablelist>
<varlistentry>
- <term>ON</term>
+ <term>Portugal</term>
<listitem>
<para>
- enables this optimization.
+ Set time zone for Portugal.
</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term>OFF</term>
+ <term>'Europe/Rome'</term>
<listitem>
<para>
- disables this optimization (default setting).
+ Set time zone for Italy.
</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term>DEFAULT</term>
+ <term>LOCAL</term>
+ <term>DEFAULT</term>
<listitem>
<para>
- Equivalent to specifying <command>SET KSQO=OFF</command>.
+ Set the time zone to your local time zone (the one that
+ your operating system defaults to).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
-
<para>
- The KSQO algorithm used to be absolutely essential for queries
- with many OR'ed AND clauses, but in Postgres 7.0 and later
- the standard planner handles these queries fairly successfully.
+ If an invalid time zone is specified, the time zone
+ becomes GMT (on most systems anyway).
</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>MAX_EXPR_DEPTH</term>
- <listitem>
<para>
- Sets the maximum expression nesting depth that the parser will
- accept. The default value is high enough for any normal query,
- but you can raise it if you need to. (But if you raise it too high,
- you run the risk of backend crashes due to stack overflow.)
-
- <variablelist>
- <varlistentry>
- <term><replaceable class="parameter">integer</replaceable></term>
- <listitem>
- <para>
- Maximum depth.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ If the PGTZ environment variable is set in the frontend
+ environment of a client based on libpq, libpq will automatically
+ set TIMEZONE to the value of PGTZ during connection startup.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
- </refsect2>
- <refsect2 id="R2-SQL-SET-2">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Outputs
- </title>
- <para>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>
-SET VARIABLE
- </computeroutput></term>
- <listitem>
- <para>
- Message returned if successful.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>
-NOTICE: Bad value for <replaceable class="parameter">variable</replaceable> (<replaceable class="parameter">value</replaceable>)
- </computeroutput></term>
- <listitem>
- <para>
- If the command fails to set the specified variable.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </refsect2>
- </refsynopsisdiv>
-
- <refsect1 id="R1-SQL-SET-1">
- <refsect1info>
- <date>1998-09-24</date>
- </refsect1info>
- <title>
- Description
- </title>
<para>
- <command>SET</command> will modify configuration parameters for variable during
- a session.
+ An extended list of other run-time parameters can be found in the
+ <citetitle>Administrator's Guide</citetitle>.
</para>
+
<para>
- Current values can be obtained using <command>SHOW</command>, and values
- can be restored to the defaults using <command>RESET</command>.
- Parameters and values are case-insensitive. Note that the value
- field is always specified as a string, so is enclosed in
- single-quotes.
+ Use <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title"> to show the
+ current setting of a parameters.
</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Diagnostics</title>
<para>
- <command>SET TIME ZONE</command> changes the session's
- default time zone offset.
- An SQL-session always begins with an initial default time zone
- offset.
- The <command>SET TIME ZONE</command> statement is used to change the default
- time zone offset for the current SQL session.
+
+ <variablelist>
+ <varlistentry>
+ <term><computeroutput>SET VARIABLE</computeroutput></term>
+ <listitem>
+ <para>
+ Message returned if successful.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>ERROR: not a valid option name: <replaceable>name</replaceable></computeroutput></term>
+ <listitem>
+ <para>
+ The parameter you tried to set does not exist.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>ERROR: permission denied</computeroutput></term>
+ <listitem>
+ <para>
+ You must be a superuser to have access to certain settings.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><computeroutput>ERROR: <replaceable>name</replaceable> can only be set at startup</computeroutput></term>
+ <listitem>
+ <para>
+ Some parameters are fixed once the server is started.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
</para>
-
- <refsect2 id="R2-SQL-SET-3">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Notes
- </title>
- <para>
- The <command>SET <replaceable class="parameter">variable</replaceable></command>
- statement is a <productname>Postgres</productname> language extension.
- </para>
- <para>
- Refer to <command>SHOW</command> and <command>RESET</command> to
- display or reset the current values.
- </para>
- </refsect2>
</refsect1>
+
- <refsect1 id="R1-SQL-SET-2">
- <title>
- Usage
- </title>
+ <refsect1>
+ <title>Examples</title>
<para>
- Set the style of date to ISO (no quotes on the argument is required):
-
- <programlisting>
-SET DATESTYLE TO ISO;
- </programlisting>
-
- Enable GEQO for queries with 4 or more tables (note the use of
- single quotes to handle the equal sign inside the value argument):
-
- <programlisting>
-SET GEQO = 'ON=4';
- </programlisting>
-
- Set GEQO to default:
-
- <programlisting>
-SET GEQO = DEFAULT;
- </programlisting>
+ Set the style of date to traditional Postgres with European conventions:
+<screen>
+SET DATESTYLE TO Postgres,European;
+</screen>
Set the timezone for Berkeley, California, using double quotes to
- preserve the uppercase
- attributes of the time zone specifier:
+ preserve the uppercase attributes of the time zone specifier (note
+ that the date/time format is ISO here):
-<programlisting>
+<screen>
SET TIME ZONE "PST8PDT";
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------
1998-03-31 07:41:21-08
-</programlisting>
+</screen>
Set the timezone for Italy (note the required single or double quotes to handle
the special characters):
-<programlisting>
+<screen>
SET TIME ZONE 'Europe/Rome';
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------
1998-03-31 17:41:31+02
-</programlisting>
+</screen>
</para>
</refsect1>
<refsect1 id="R1-SQL-SET-3">
- <title>
- Compatibility
- </title>
-
- <refsect2 id="R2-SQL-SET-4">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- SQL92
- </title>
- <para>
- There is no general
- <command>SET <replaceable class="parameter">variable</replaceable></command>
- in <acronym>SQL92</acronym> (with the exception of
- <command>SET TRANSACTION ISOLATION LEVEL</command>).
+ <title>Compatibility</title>
- The <acronym>SQL92</acronym> syntax for <command>SET TIME ZONE</command>
- is slightly different,
- allowing only a single integer value for time zone specification:
-
- <synopsis>
-SET TIME ZONE { interval_value_expression | LOCAL }
- </synopsis>
- </para>
- </refsect2>
+ <para>
+ The second syntax shown above (<literal>SET TIME ZONE</literal>)
+ attempts to mimic <acronym>SQL92</acronym>. However, SQL allows
+ only numeric time zone offsets. All other parameter settings as
+ well as the first syntax shown above are a
+ <productname>Postgres</productname> extension.
+ </para>
</refsect1>
</refentry>
--- /dev/null
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_constraints.sgml,v 1.1 2000/06/18 21:24:54 petere Exp $ -->
+<refentry id="SQL-SET-CONSTRAINTS">
+ <refmeta>
+ <refentrytitle id="SQL-SET-CONSTRAINTS-title">SET CONSTRAINTS</refentrytitle>
+ <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>SET CONSTRAINTS</refname>
+ <refpurpose>Set the constraint mode of the current SQL-transaction</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <refsynopsisdivinfo>
+ <date>2000-06-01</date>
+ </refsynopsisdivinfo>
+ <synopsis>
+SET CONSTRAINTS { ALL | <replaceable class="parameter">constraint</replaceable> [, ...] } { DEFERRED | IMMEDIATE }
+ </synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ <command>SET CONSTRAINTS</command> sets the behavior of constraint
+ evaluation in the current transaction. In
+ <option>IMMEDIATE</option> mode, constraints are checked at the end
+ of each statement. In <option>DEFERRED</option> mode, constraints
+ are not checked until transaction commit.
+ </para>
+
+ <para>
+ Upon creation, a constraint is always give one of three
+ characteristics: <option>INITIALLY DEFERRED</option>,
+ <option>INITIALLY IMMEDIATE DEFERRABLE</option>, or
+ <option>INITIALLY IMMEDIATE NOT DEFERRABLE</option>. The third
+ class is not affected by the <command>SET CONSTRAINTS</command>
+ command.
+ </para>
+
+ <para>
+ Currently, only foreign key constraints are affected by this
+ setting. Check and unique constraints are always effectively
+ initially immediate not deferrable.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Compatibility</title>
+ <para>
+ SQL92, SQL99
+ </para>
+ </refsect1>
+</refentry>
--- /dev/null
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_transaction.sgml,v 1.1 2000/06/18 21:24:54 petere Exp $ -->
+<refentry id="SQL-SET-TRANSACTION">
+ <refmeta>
+ <refentrytitle id="SQL-SET-TRANSACTION-title">SET TRANSACTION</refentrytitle>
+ <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>SET TRANSACTION</refname>
+ <refpurpose>Set the characteristics of the current SQL-transaction</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <refsynopsisdivinfo>
+ <date>2000-06-01</date>
+ </refsynopsisdivinfo>
+ <synopsis>
+SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
+ </synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ The <command>SET TRANSACTION</command> command sets the
+ characteristics for the current SQL-transaction. It has no effect
+ on any subsequent transactions. This command cannot be used after
+ the first DML statement (<command>SELECT</command>,
+ <command>INSERT</command>, <command>DELETE</command>,
+ <command>UPDATE</command>, <command>FETCH</command>,
+ <command>COPY</command>) of a transaction has been executed.
+ </para>
+
+ <para>
+ The isolation level of a transaction determines what data the
+ transaction can see when other transactions are running concurrently.
+
+ <variablelist>
+ <varlistentry>
+ <term>READ COMMITTED</term>
+ <listitem>
+ <para>
+ A statement can only see rows committed before it began. This
+ is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERIALIZABLE</term>
+ <listitem>
+ <para>
+ The current transaction can only see rows committed before
+ first DML statement was executed in this transaction.
+ </para>
+ <tip>
+ <para>
+ Intuitively, serializable means that two concurrent
+ transactions will leave the database in the same state as if
+ the two has been executed strictly after one another in either
+ order.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Compatibility</title>
+
+ <para>
+ SQL92, SQL99
+ </para>
+
+ <para>
+ SERIALIZABLE is the default level in <acronym>SQL</acronym>.
+ Postgres does not provide the isolation levels <option>READ
+ UNCOMMITTED</option> and <option>REPEATABLE READ</option>. Because
+ of multi-version concurrency control, the serializable level is not
+ truly serializable. See the <citetitle>User's Guide</citetitle> for
+ details.
+ </para>
+
+ <para>
+ In <acronym>SQL</acronym> there are two other transaction
+ characteristics that can be set with this command: whether the
+ transaction is read-only and the size of the diagnostics area.
+ Neither of these concepts are supported in Postgres.
+ </para>
+ </refsect1>
+</refentry>
+
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.9 2000/04/08 02:39:02 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/show.sgml,v 1.10 2000/06/18 21:24:54 petere Exp $
Postgres documentation
-->
<refentry id="SQL-SHOW">
<refmeta>
- <refentrytitle id="SQL-SHOW-TITLE">
- SHOW
- </refentrytitle>
+ <refentrytitle id="SQL-SHOW-TITLE">SHOW</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
- <refname>
- SHOW
- </refname>
- <refpurpose>
- Shows run-time parameters for session
- </refpurpose>
+ <refname>SHOW</refname>
+ <refpurpose>Shows run-time parameters</refpurpose>
</refnamediv>
<refsynopsisdiv>
- <refsynopsisdivinfo>
- <date>1999-07-20</date>
- </refsynopsisdivinfo>
<synopsis>
-SHOW <replaceable class="PARAMETER">keyword</replaceable>
+SHOW <replaceable class="PARAMETER">name</replaceable>
</synopsis>
<refsect2 id="R2-SQL-SHOW-1">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Inputs
- </title>
+ <title>Inputs</title>
<para>
<variablelist>
<varlistentry>
- <term><replaceable class="PARAMETER">keyword</replaceable></term>
+ <term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
- Refer to
+ The name of a run-time parameter. See
<xref linkend="sql-set-title" endterm="sql-set-title">
- for more information on available variables.
+ for a list.
</para>
</listitem>
</varlistentry>
</para>
</refsect2>
- <refsect2 id="R2-SQL-SHOW-2">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Outputs
- </title>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-SQL-SHOW-1">
+ <title>Description</title>
+ <para>
+ <command>SHOW</command> will display the current setting of a
+ run-time parameter. These variables can be set using the
+ <command>SET</command> statement or are determined at server start.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
- <term><computeroutput>
-NOTICE: <replaceable class="PARAMETER">variable</replaceable> is <replaceable>value</replaceable>
- </computeroutput></term>
+ <term><computeroutput>ERROR: not a valid option name: <replaceable>name</replaceable></computeroutput></term>
<listitem>
<para>
- Message returned if successful.
+ Message returned if <replaceable>variable</replaceable> does
+ not stand for an existing parameter.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><computeroutput>
-NOTICE: Unrecognized variable <replaceable>value</replaceable>
- </computeroutput></term>
+ <term><computeroutput>ERROR: permission denied</computeroutput></term>
<listitem>
<para>
- Message returned if <returnvalue>variable</returnvalue> does not exist.
+ You must be a superuser to be allowed to see certain settings.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><computeroutput>
-NOTICE: Time zone is unknown
- </computeroutput></term>
+ <term><computeroutput>NOTICE: Time zone is unknown</computeroutput></term>
<listitem>
<para>
If the <envar>TZ</envar> or <envar>PGTZ</envar> environment
</varlistentry>
</variablelist>
</para>
- </refsect2>
- </refsynopsisdiv>
-
- <refsect1 id="R1-SQL-SHOW-1">
- <refsect1info>
- <date>1998-09-24</date>
- </refsect1info>
- <title>
- Description
- </title>
- <para>
- <command>SHOW</command> will display the current setting of a
- run-time parameter during a session.
- </para>
- <para>
- These variables can be set using the <command>SET</command> statement,
- and
- can be restored to the default values using the <command>RESET</command>
- statement.
- Parameters and values are case-insensitive.
- </para>
-
- <refsect2 id="R2-SQL-SHOW-3">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- Notes
- </title>
- <para>
- See also
- <xref linkend="sql-set-title" endterm="sql-set-title"> and
- <xref linkend="sql-reset-title" endterm="sql-reset-title">
- to manipulate variable values.
- </para>
- </refsect2>
</refsect1>
<refsect1 id="R1-SQL-SHOW-2">
- <title>
- Usage
- </title>
+ <title>Examples</title>
<para>
Show the current <literal>DateStyle</literal> setting:
- <programlisting>
+<screen>
SHOW DateStyle;
NOTICE: DateStyle is ISO with US (NonEuropean) conventions
- </programlisting>
+</screen>
</para>
<para>
Show the current genetic optimizer (<literal>geqo</literal>) setting:
- <programlisting>
+<screen>
SHOW GEQO;
-NOTICE: GEQO is ON beginning with 11 relations
- </programlisting>
+NOTICE: geqo = true
+</screen>
</para>
</refsect1>
<refsect1 id="R1-SQL-SHOW-3">
- <title>
- Compatibility
- </title>
+ <title>Compatibility</title>
- <refsect2 id="R2-SQL-SHOW-4">
- <refsect2info>
- <date>1998-09-24</date>
- </refsect2info>
- <title>
- SQL92
- </title>
- <para>
- There is no <command>SHOW</command> defined in <acronym>SQL92</acronym>.
- </para>
- </refsect2>
+ <para>
+ The <command>SHOW</command> command is a
+ <productname>Postgres</productname> extension.
+ </para>
</refsect1>
</refentry>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.10 2000/05/02 20:01:52 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.11 2000/06/18 21:24:51 petere Exp $
-->
- <Chapter Id="runtime">
- <Title>Runtime Environment</Title>
+<Chapter Id="runtime">
+ <Title>Server Runtime Environment</Title>
+
+ <Para>
+ This chapter discusses how to set up and run the database server
+ and the interactions with the operating system.
+ </para>
+
+ <sect1 id="postgres-user">
+ <title>The Postgres user account</title>
+
+ <para>
+ As with any other server daemon that is connected to the world at
+ large, it is advisable to run Postgres under a separate user
+ account. This user account should only own the data itself that is
+ being managed by the server, and should not be shared with other
+ daemons. (Thus, using the user <quote>nobody</quote> is a bad
+ idea.) It is not advisable to install the executables as owned by
+ this user account because that runs the risk of user-defined
+ functions gone astray or any other exploits compromising the
+ executable programs.
+ </para>
- <Para>
- This chapter outlines the interaction between <Productname>Postgres</Productname> and
- the operating system.
+ <para>
+ To add a user account to your system, look for a command
+ <command>useradd</command> or <command>adduser</command>. The user
+ name <quote>postgres</quote> is often used but by no means
+ required.
+ </para>
+ </sect1>
+
+ <sect1 id="creating-cluster">
+ <title>Creating a database cluster</title>
+
+ <para>
+ Before you can do anything, you must initialize a database storage
+ area on disk. We call this a <firstterm>database
+ cluster</firstterm>. (<acronym>SQL</acronym> speaks of a catalog
+ cluster instead.) A database cluster is a collection of databases
+ that will be accessible through a single instance of a running
+ database server. After initialization, a database cluster will
+ contain one database named <literal>template1</literal>. As the
+ name suggests, this will be used as a template for any subsequently
+ created database; it should not be used for actual work.
</para>
- <sect1>
- <title>Using <Productname>Postgres</Productname> from Unix</title>
+ <para>
+ In file system terms, a database cluster will be a single directory
+ under which all data will be stored. We call this the
+ <firstterm>data directory</firstterm> or <firstterm>data
+ area</firstterm>. It is completely up to you where you choose to
+ store your data, there is no default, although locations such as
+ <filename>/usr/local/pgsql/data</filename> or
+ <filename>/var/lib/pgsql/data</filename> are popular. To initialize
+ a database cluster, use the command <command>initdb</command>,
+ which is installed with <productname>PostgreSQL</productname>. The
+ desired file system location of your database system is indicated
+ by the <option>-D</option> option, for example
+<screen>
+> <userinput>initdb -D /usr/local/pgsql/data</userinput>
+</screen>
+ Note that you must execute this command while being logged in to
+ the Postgres user account, which is described in the previous
+ section.
+ </para>
+ <tip>
<para>
- All <Productname>Postgres</Productname> commands that are executed
- directly from a Unix shell are
- found in the directory <filename>.../bin</filename>. Including this directory in
- your search path will make executing the commands easier.
+ As an alternative to the <option>-D</option> option, you can set
+ the environment variable <envar>PGDATA</envar>.
</para>
+ </tip>
+
+ <para>
+ <command>initdb</command> will attempt to create the directory you
+ specify if it does not already exist. It is likely that it won't
+ have the permission to do so (if you followed our advice and
+ created an unprivileged account). In that case you can create the
+ directory yourself (as root) and transfer ownership of it or grant
+ write access to it. Here is how this might work:
+<screen>
+root# <userinput>mkdir /usr/local/pgsql/data</userinput>
+root# <userinput>chown postgres /usr/local/pgsql/data</userinput>
+root# <userinput>su postgres</userinput>
+postgres> <userinput>initdb -D /usr/local/pgsql/data</userinput>
+</screen>
+ </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>
+ <command>initdb</command> will refuse to run if the data directory
+ looks like it belongs to an already initialized installation.
+ </para>
+
+ <para>
+ Because the data directory contains all the data stored in the
+ database it is essential that it be well secured from unauthorized
+ access. <command>initdb</command> therefore revokes access
+ permissions from everyone but the Postgres user account.
+ </para>
+ </sect1>
+
+ <sect1 id="postmaster-start">
+ <title>Starting the database server</title>
+
+ <para>
+ Before anyone can access the database you must start the database
+ server. The database server is called
+ <firstterm>postmaster</firstterm>.
+ The postmaster must know where to find the data it is supposed
+ to work on. This is done with the <option>-D</option> option. Thus,
+ the simplest way to start the server is, for example,
+<screen>
+> <userinput>postmaster -D /usr/local/pgsql/data</userinput>
+</screen>
+ which will leave the server running in the foreground. This must
+ again be done while logged in to the Postgres user account. Without
+ a <option>-D</option>, the server will try to use the data
+ directory in the environment variable <envar>PGDATA</envar>; if
+ neither of these works it will fail.
+ </para>
+
+ <para>
+ To start the <application>postmaster</application> in the
+ background, use the usual shell syntax:
+<screen>
+> <userinput>postmaster -D /usr/local/pgsql/data > logfile 1>&2 &</userinput>
+</screen>
+ It is an extremely good idea to keep the server output around
+ somewhere, as indicated here. It will help both for auditing
+ purposes and to diagnose problems.
+ </para>
+
+ <para>
+ The postmaster also takes a number of other command line options.
+ For more information see the reference page and below under runtime
+ configuration. In particular, in order for the postmaster to accept
+ TCP/IP connections (rather than just Unix domain socket ones), you
+ must also specify the <option>-i</option> option.
+ </para>
+
+ <para>
+ Normally, you will want to start the database server when the
+ computer boots up. This is not required; the
+ <productname>PostgreSQL</productname> server can be run
+ successfully from non-privileged accounts without root
+ intervention.
+ </para>
+
+ <para>
+ Different systems have different conventions for starting up
+ daemons at boot time, so you are advised to familiarize yourself
+ with them. Many systems have a file
+ <filename>/etc/rc.local</filename> or
+ <filename>/etc/rc.d/rc.local</filename> which is almost certainly
+ no bad place to put such a command. Whatever you do, postmaster
+ must be run by the <productname>Postgres</productname> user account
+ <emphasis>and not by root</emphasis> or any other user. Therefore
+ you probably always want to form your command lines along the lines
+ of <literal>su -c '...' postgres</literal>, for example:
+<programlisting>
+nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
+</programlisting>
+ (using the program <application>nohup</application> to prevent the
+ server from dying when you log out).
+ </para>
+
+ <para>
+ Here are a few more operating system specific suggestions.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Edit the file <filename>rc.local</filename> on
+ <productname>NetBSD</productname> or file
+ <filename>rc2.d</filename> on <productname>Solaris</productname> to contain the
+ following single line:
+<programlisting>
+su postgres -c "/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data"
+</programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ On <productname>FreeBSD</productname> edit
+ <filename>/usr/local/etc/rc.d/pgsql.sh</filename> to contain the
+ following lines and make it <literal>chmod 755</literal> and
+ <literal>chown root:bin</literal>.
+<programlisting>
+#!/bin/sh
+[ -x /usr/local/pgsql/bin/postmaster ] && {
+ su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
+ -D/usr/local/pgsql/data
+ -S -o -F > /usr/local/pgsql/errlog' &
+ echo -n ' pgsql'
+}
+</programlisting>
+ You may put the line breaks as shown above. The shell is smart
+ enough to keep parsing beyond end-of-line if there is an
+ expression unfinished. The exec saves one layer of shell under
+ the postmaster process so the parent is init.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ On <productname>RedHat Linux</productname> add a file
+ <filename>/etc/rc.d/init.d/postgres.init</filename>
+ which is based on the example in <filename>contrib/linux/</filename>.
+ Then make a softlink to this file from
+ <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
</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>
+ While the <application>postmaster</application> is running, it's
+ PID is in the file <filename>postmaster.pid</filename> in the data
+ directory. This is used as in interlock against multiple running
+ postmaster on the same data directory and can also be used for
+ shutting down the postmaster.
</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.
- No ampersand ("&") is required in this case, since the postmaster
- automatically detaches from the terminal when -S is specified.
- </Para>
+ The shell script wrapper <application>pg_ctl</application> that
+ comes with <productname>Postgres</productname> can also be used to
+ control starting (and stopping!) of the database server in
+ intelligent fashion.
+ </para>
+
+ <sect2 id="postmaster-start-failures">
+ <title>Server Startup Failures</title>
+
+ <para>
+ There are several common reasons for the postmaster to fail to
+ start up. Check the postmaster's log file, or start it by hand
+ (without redirecting standard output or standard error) to see
+ what complaint messages appear. Some of the possible error
+ messages are reasonably self-explanatory, but here are some that
+ are not.
+ </para>
+
+ <para>
+<screen>
+FATAL: StreamServerPort: bind() failed: Address already in use
+ Is another postmaster already running on that port?
+</screen>
+ This usually means just what it suggests: you accidentally
+ started a second postmaster on the same port where one is already
+ running. However, if the kernel error message is not
+ <computeroutput>Address already in use</computeroutput> or some
+ variant of that wording, there may be a different problem. For
+ example, trying to start a postmaster on a reserved port number
+ may draw something like
+<screen>
+> <userinput>postmaster -i -p 666</userinput>
+FATAL: StreamServerPort: bind() failed: Permission denied
+ Is another postmaster already running on that port?
+</screen>
+ </para>
+
+ <para>
+ A message like
+<screen>
+IpcMemoryCreate: shmget(5440001, 83918612, 01600) failed: Invalid argument
+FATAL 1: ShmemCreate: cannot create region
+</screen>
+ probably means that your kernel's limit on the size of shared
+ memory areas is smaller than the buffer area that Postgres is
+ trying to create (83918612 bytes in this example). Or it could
+ mean that you don't have SysV-style shared memory support
+ configured into your kernel at all. As a temporary workaround,
+ you can try starting the postmaster with a smaller-than-normal
+ number of buffers (<option>-B</option> switch). You will
+ eventually want to reconfigure your kernel to increase the
+ allowed shared memory size, however. You may see this message
+ when trying to start multiple postmasters on the same machine, if
+ their total space requests exceed the kernel limit.
+ </para>
+
+ <para>
+ An error like
+<screen>
+IpcSemaphoreCreate: semget(5440026, 16, 0600) failed: No space left on device
+</screen>
+ does <emphasis>not</emphasis> mean that you've run out of disk
+ space; it means that your kernel's limit on the number of SysV
+ semaphores is smaller than the number
+ <productname>Postgres</productname> wants to create. As above,
+ you may be able to work around the problem by starting the
+ postmaster with a reduced number of backend processes
+ (<option>-N</option> switch), but you'll eventually want to
+ increase the kernel limit.
+ </para>
+ </sect2>
+
+ <sect2 id="client-connection-problems">
+ <title>Client Connection Problems</title>
+
+ <para>
+ Although the possible error conditions on the client side are
+ both virtually infinite and application dependent, a few of them
+ might be directly related to how the server was started up.
+ Conditions other than those shown below should be documented with
+ the respective client application.
+ </para>
+
+ <para>
+<screen>
+connectDB() -- connect() failed: Connection refused
+Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'?
+</screen>
+ This is the generic <quote>I couldn't find a server to talk
+ to</quote> failure. It looks like the above when TCP/IP
+ communication is attempted. A common mistake is to forget the
+ <option>-i</option> to the postmaster to allow TCP/IP
+ connections.
+ </para>
+
+ <para>
+ Alternatively, you'll get this when attempting
+ Unix-socket communication to a local postmaster:
+<screen>
+connectDB() -- connect() failed: No such file or directory
+Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'?
+</screen>
+ </para>
+
+ <para>
+ The last line is useful in verifying that the client is trying to
+ connect where it is supposed to. If there is in fact no
+ postmaster running there, the kernel error message will typically
+ be either <computeroutput>Connection refused</computeroutput> or
+ <computeroutput>No such file or directory</computeroutput>, as
+ illustrated. (It is particularly important to realize that
+ <computeroutput>Connection refused</computeroutput> in this
+ context does <emphasis>not</emphasis> mean that the postmaster
+ got your connection request and rejected it -- that case will
+ produce a different message, as shown in <xref
+ linkend="client-authentication-problems">.) Other error messages
+ such as <computeroutput>Connection timed out</computeroutput> may
+ indicate more fundamental problems, like lack of network
+ connectivity.
+ </para>
+ </sect2>
</sect1>
- <sect1 Id="pg-options">
- <Title id="pg-options-title">Using pg_options</Title>
+ <sect1 Id="runtime-config">
+ <Title>Run-time configuration</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>
+ There are a lot of configuration parameters that affect the
+ behavior of the database system in some way or other. Here we
+ describe how to set them and the following subsections will
+ discuss each of them.
</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.
+ All parameter names are case-insensitive. Every parameter takes a
+ value of one of the four types boolean, integer, floating point,
+ string as described below. Boolean values are
+ <literal>ON</literal>, <literal>OFF</literal>,
+ <literal>TRUE</literal>, <literal>FALSE</literal>,
+ <literal>YES</literal>, <literal>NO</literal>,
+ <literal>1</literal>, <literal>0</literal> (case-insensitive) or
+ any non-ambiguous prefix of these.
</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>
+ One way to set these options is to create a file
+ <filename>postgresql.conf</filename> in the data directory (e.g.,
+ <filename>/usr/local/pgsql/data</filename>). An example of how
+ this file could look like is this:
+<programlisting>
+# This is a comment
+log_connections = yes
+syslog = 2
+</programlisting>
+ As you see, options are one per line. The equal sign between name
+ and value is optional. White space is insignificant, blank lines
+ are ignored. Hash marks (<quote>#</quote>) introduce comments
+ anywhere.
</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.
+ The configuration file is reread whenever the postmaster receives
+ a SIGHUP signal. This signal is also propagated to all running
+ backend processes, so that running sessions get the new default.
+ Alternatively, you can send the signal to only one backend process
+ directly.
</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>
+ A second way to set these configuration parameters is to give them
+ as a command line option to the postmaster, such as
+<programlisting>
+postmaster --log-connections=yes --syslog=2
+</programlisting>
+ which would have the same effect as the previous 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>
+ <para>
+ Occasionally it is also useful to give a command line option to
+ one particular backend session only. The environment variable
+ <envar>PGOPTIONS</envar> can be used for this purpose on the
+ client side:
+<programlisting>
+env PGOPTIONS='--geqo=off' psql
+</programlisting>
+ (This works for any client application, not just
+ <application>psql</application>.) Note that this won't work for
+ options that are necessarily fixed once the server is started,
+ such as the port number.
+ </para>
- <varlistentry>
- <term>
- 1
- </term>
- <listitem>
- <para>
- Print information messages.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ Finally, some options can be changed in individual SQL sessions
+ with the <command>SET</command> command, for example
+<screen>
+=> <userinput>SET ENABLE_SEQSCAN TO OFF;</userinput>
+</screen>
+ See the SQL command language reference for details on the syntax.
+ </para>
- <varlistentry>
- <term>
- 2
- </term>
- <listitem>
- <para>
- Print more information messages.
- </para>
- </listitem>
- </varlistentry>
+ <sect2 id="runtime-config-optimizer">
+ <title>Planner and Optimizer Tuning</title>
- </variablelist>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>CPU_INDEX_TUPLE_COST (<type>floating point</type>)</term>
+ <listitem>
+ <para>
+ Sets the query optimizer's estimate of the cost of processing
+ each index tuple during an index scan. This is measured as a
+ fraction of the cost of a sequential page fetch.
+ </para>
</listitem>
</varlistentry>
-
+
<varlistentry>
- <term>
- query
- </term>
+ <term>CPU_OPERATOR_COST (<type>floating point</type>)</term>
<listitem>
<para>
- Query trace flag. Allowed values are:
+ Sets the optimizer's estimate of the cost of processing each
+ operator in a WHERE clause. This is measured as a fraction of
+ the cost of a sequential page fetch.
</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>CPU_TUPLE_COST (<type>floating point</type>)</term>
+ <listitem>
+ <para>
+ Sets the query optimizer's estimate of the cost of processing
+ each tuple during a query. This is measured as a fraction of
+ the cost of a sequential page fetch.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>EFFECTIVE_CACHE_SIZE (<type>floating point</type>)</term>
+ <listitem>
+ <para>
+ Sets the optimizer's assumption about the effective size of
+ the disk cache (that is, the portion of the kernel's disk
+ cache that will be used for
+ <productname>Postgres</productname> data files). This is
+ measured in disk pages, which are normally 8kB apiece.
+ </para>
+ </listitem>
+ </varlistentry>
- <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>
+ <varlistentry>
+ <term>ENABLE_HASHJOIN (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Enables or disables the query planner's use of hash-join plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- plan
- </term>
+ <term>ENABLE_INDEXSCAN (<type>boolean</type>)</term>
<listitem>
<para>
- Print query plan.
+ Enables or disables the query planner's use of index scan plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- parse
- </term>
+ <term>ENABLE_MERGEJOIN (<type>boolean</type>)</term>
<listitem>
<para>
- Print parser output.
+ Enables or disables the query planner's use of merge-join plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- rewritten
- </term>
+ <term>ENABLE_NESTLOOP (<type>boolean</type>)</term>
<listitem>
<para>
- Print rewritten query.
+ Enables or disables the query planner's use of nested-loop
+ join plans. It's not possible to suppress nested-loop joins
+ entirely, but turning this variable off discourages the
+ planner from using one if there is any other method available.
+ The default is on. This is mostly useful to debug the query
+ planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- pretty_plan
- </term>
+ <term>ENABLE_SEQSCAN (<type>boolean</type>)</term>
<listitem>
<para>
- Pretty-print query plan.
+ Enables or disables the query planner's use of sequential scan
+ plan types. It's not possible to suppress sequential scans
+ entirely, but turning this variable off discourages the
+ planner from using one if there is any other method available.
+ The default is on. This is mostly useful to debug the query
+ planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- pretty_parse
- </term>
+ <term>ENABLE_SORT (<type>boolean</type>)</term>
<listitem>
<para>
- Pretty-print parser output.
+ Enables or disables the query planner's use of explicit sort
+ steps. It's not possible to suppress explicit sorts entirely,
+ but turning this variable off discourages the planner from
+ using one if there is any other method available. The default
+ is on. This is mostly useful to debug the query planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- pretty_rewritten
- </term>
+ <term>ENABLE_TIDSCAN (<type>boolean</type>)</term>
<listitem>
<para>
- Pretty-print rewritten query.
+ Enables or disables the query planner's use of TID scan plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- parserstats
- </term>
+ <term>GEQO (<type>boolean</type>)</term>
<listitem>
<para>
- Print parser statistics.
+ Enables or disables genetic query optimization, which is an
+ algorithm that attempts to do query planning without
+ exhaustive search. This is on by default. See also the various
+ other GEQO_ settings.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- plannerstats
- </term>
+ <term>GEQO_EFFORT (<type>integer</type>)</term>
+ <term>GEQO_GENERATIONS (<type>integer</type>)</term>
+ <term>GEQO_POOL_SIZE (<type>integer</type>)</term>
+ <term>GEQO_RANDOM_SEED (<type>integer</type>)</term>
+ <term>GEQO_SELECTION_BIAS (<type>floating point</type>)</term>
<listitem>
<para>
- Print planner statistics.
+ Various tuning parameters for the genetic query optimization
+ algorithm: The pool size is the number of individuals in one
+ population. Valid values are between 128 and 1024. If it is
+ set to 0 (the default) a pool size of 2^(QS+1), where QS
+ is the number of relations in the query, is taken. The effort
+ is used to calculate a default for generations. Valid values
+ are between 1 and 80, 40 being the default. Generations
+ specifies the number of iterations in the algorithm. The
+ number must be a positive integer. If 0 is specified then
+ Effort * Log2(PoolSize) is used. The run time of the algorithm
+ is roughly proportional to the sum of pool size and
+ generations. The selection bias is the selective pressure
+ within the population. Values can be from 1.50 to 2.00; the
+ latter is the default. The random seed can be set to get
+ reproduceable results from the algorithm. If it is set to -1
+ then the algorithm behaves non-deterministically.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- executorstats
- </term>
+ <term>GEQO_RELS (<type>integer</type>)</term>
<listitem>
<para>
- Print executor statistics.
+ Only use genetic query optimization for queries with at least
+ this many relations involved. The default is 11. For less
+ relations it is probably more efficient to use the
+ deterministic, exhaustive planner.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- shortlocks
- </term>
+ <term>KSQO (<type>boolean</type>)</term>
<listitem>
<para>
- Currently unused but needed to enable features in the future.
+ The <firstterm>Key Set Query Optimizer</firstterm>
+ (<abbrev>KSQO</abbrev>) causes the query planner to convert
+ queries whose WHERE clause contains many OR'ed AND clauses
+ (such as <literal>WHERE (a=1 AND b=2) OR (a=2 AND b=3)
+ ...</literal>) into a UNION query. This method can be faster
+ than the default implementation, but it doesn't necessarily
+ give exactly the same results, since UNION implicitly adds a
+ SELECT DISTINCT clause to eliminate identical output rows.
+ KSQO is commonly used when working with products like
+ <productname>Microsoft Access</productname>, which tend to
+ generate queries of this form.
+ </para>
+
+ <para>
+ The KSQO algorithm used to be absolutely essential for queries
+ with many OR'ed AND clauses, but in
+ <productname>Postgres</productname> 7.0 and later the standard
+ planner handles these queries fairly successfully. Hence the
+ default is OFF.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- locks
- </term>
+ <term>RANDOM_PAGE_COST (<type>floating point</type>)</term>
<listitem>
<para>
- Trace locks.
+ Sets the query optimizer's estimate of the cost of a
+ nonsequentially fetched disk page. This is measured as a
+ multiple of the cost of a sequential page fetch.
</para>
</listitem>
</varlistentry>
+ </variablelist>
+ </para>
+
+ <note>
+ <para>
+ Unfortunately, there is no well-defined method of determining
+ ideal values for the family of <quote>COST</quote> variables that
+ were just described. You are encouraged to experiment and share
+ your findings.
+ </para>
+ </note>
+
+ </sect2>
+ <sect2 id="logging">
+ <title>Logging and Debugging</title>
+
+ <para>
+ <variablelist>
<varlistentry>
- <term>
- userlocks
- </term>
+ <term>DEBUG_LEVEL (<type>integer</type>)</term>
<listitem>
<para>
- Trace user locks.
+ The higher this value is set, the more
+ <quote>debugging</quote> output of various sorts is generated
+ in the server log during operation. This option is 0 by
+ default, which means no debugging output. Values up to about 4
+ currently make sense.
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
- <term>
- spinlocks
- </term>
+ <term>DEBUG_PRINT_PARSE (<type>boolean</type>)</term>
+ <term>DEBUG_PRINT_PLAN (<type>boolean</type>)</term>
+ <term>DEBUG_PRINT_REWRITTEN (<type>boolean</type>)</term>
+ <term>DEBUG_PRINT_QUERY (<type>boolean</type>)</term>
+ <term>DEBUG_PRETTY_PRINT (<type>boolean</type>)</term>
<listitem>
<para>
- Trace spin locks.
+ For any executed query, prints either the query, the parse
+ tree, the execution plan, or the query rewriter output to the
+ server log. <option>DEBUG_PRETTY_PRINT</option> selects are
+ nicer but longer output format.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- notify
- </term>
+ <term>HOSTLOOKUP (<type>boolean</type>)</term>
<listitem>
<para>
- Trace notify functions.
+ By default, connection logs only show the IP address of the
+ connecting host. If you want it to show the host name you can
+ turn this on, but depending on your host name resolution setup
+ it might impose a non-negligible performance penalty. This
+ option can only be set at server start.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- malloc
- </term>
+ <term>LOG_CONNECTIONS (<type>boolean</type>)</term>
<listitem>
<para>
- Currently unused.
+ Prints a line informing about each successful connection to
+ the server log. This is off by default, although it is
+ probably very useful. This option can only be set at server
+ start.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- palloc
- </term>
+ <term>LOG_PID (<type>boolean</type>)</term>
<listitem>
<para>
- Currently unused.
+ Prefixes each server log message with the process id of the
+ backend process. This is useful to sort out which messages
+ pertain to which connection. The default is off.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- lock_debug_oidmin
- </term>
+ <term>LOG_TIMESTAMP (<type>boolean</type>)</term>
<listitem>
<para>
- Minimum relation oid traced by locks.
+ Prefixes each server log message with a timestamp. The default
+ is off.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- lock_debug_relid
- </term>
+ <term>SHOW_QUERY_STATS (<type>boolean</type>)</term>
+ <term>SHOW_PARSER_STATS (<type>boolean</type>)</term>
+ <term>SHOW_PLANNER_STATS (<type>boolean</type>)</term>
+ <term>SHOW_EXECUTOR_STATS (<type>boolean</type>)</term>
<listitem>
<para>
- oid, if not zero, of relation traced by locks.
+ For each query, write performance statistics of the respective
+ module to the server log. This is a crude profiling
+ instrument.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- lock_read_priority
- </term>
+ <term>SHOWPORTNUMBER (<type>boolean</type>)</term>
<listitem>
<para>
- Currently unused.
+ Shows the port number of the connecting host in the connection
+ log messages. You could trace back the port number to find out
+ what user initiated the connection. Other than that it's
+ pretty useless and therefore off by default. This option can
+ only be set at server start.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- deadlock_timeout
- </term>
+ <term>SYSLOG (<type>integer</type>)</term>
<listitem>
<para>
- Deadlock check timer.
+ <productname>Postgres</productname> allows the use of
+ <application>syslog</application> for logging. If this option
+ is set to 1, messages go both to syslog and the standard
+ output. A setting of 2 sends output only to syslog. (Some
+ messages will still go to the standard output/error.) The
+ default is 0, which means syslog is off. This option must be
+ set at server start.
+ </para>
+ <para>
+ To use syslog, the build of
+ <productname>Postgres</productname> must be configured with
+ the <option>--enable-syslog</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- syslog
- </term>
+ <term>TRACE_NOTIFY (<type>boolean</type>)</term>
<listitem>
<para>
- syslog flag. Allowed values are:
+ Generates a great amount of debugging output for the
+ <command>LISTEN</command> and <command>NOTIFY</command>
+ commands.
</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
- <variablelist>
- <varlistentry>
- <term>
- 0
- </term>
- <listitem>
- <para>
- Messages to stdout/stderr.
- </para>
- </listitem>
- </varlistentry>
+ <sect2 id="runtime-config-general">
+ <title>General operation</title>
- <varlistentry>
- <term>
- 1
- </term>
- <listitem>
- <para>
- Messages to stdout/stderr and syslog.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>DEADLOCK_TIMEOUT (<type>integer</type>)</term>
+ <listitem>
+ <para>
+ <productname>Postgres</productname> assumes that if
+ transactions are stuck for this many milliseconds then a
+ deadlock has occurred. Although it is technically possible to
+ detect deadlocks <quote>properly</quote>, the present
+ optimistic approach is much more efficient in practice. If you get
+ too many deadlock detected messages when you provably did not
+ have one, you might want to try raising this value. The
+ default is 1000 (i.e., one second). This option can only be
+ set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FSYNC (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ When this is on (default), an <function>fsync()</function>
+ call is done after each transaction. Turning this off
+ increases performance but an operating system crash or power
+ outage might cause data corruption. (Note that a crash of
+ <productname>Postgres</productname> itself is not affected.)
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- 2
- </term>
- <listitem>
- <para>
- Messages only to syslog.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>MAX_BACKENDS (<type>integer</type>)</term>
+ <listitem>
+ <para>
+ Determines how many concurrent connections the database server
+ will allow. The default is 32. Note that there is also a
+ compiled-in hard limit on this option, which is currently
+ 1024. This parameter can only be set at server start.
+ </para>
+ </listitem>
+ </varlistentry>
- </variablelist>
+ <varlistentry>
+ <term>MAX_EXPR_DEPTH (<type>integer</type>)</term>
+ <listitem>
+ <para>
+ Sets the maximum expression nesting depth that the parser will
+ accept. The default value is high enough for any normal query,
+ but you can raise it if you need to. (But if you raise it too
+ high, you run the risk of backend crashes due to stack
+ overflow.)
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- hostlookup
- </term>
+ <term>NET_SERVER (<type>boolean</type>)</term>
<listitem>
<para>
- Enable hostname lookup in ps_status.
+ If this is true, then the server will accept TCP/IP
+ connections. Otherwise only local Unix domain socket
+ connections are accepted. It is off by default. This option
+ can only be set at server start.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- showportnumber
- </term>
+ <term>PORT (<type>integer</type>)</term>
<listitem>
<para>
- Show port number in ps_status.
+ The TCP port the server listens on; 5432 by default. This
+ option can only be set at server start.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>
- nofsync
- </term>
+ <term>SHMEM_BUFFERS (<type>integer</type>)</term>
<listitem>
<para>
- Disable fsync on a per-backend basis.
+ Sets the number of shared memory buffers the database server
+ will use. The default is 64. Each buffer is typically 8192
+ bytes. This option can only be set at server start.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>SORT_MEM (<type>integer</type>)</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 memory as this value specifies before it starts to put
+ data into temporary files.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
- </para>
+ </para>
</sect2>
- </sect1>
+
+ <sect2 id="runtime-config-short">
+ <title>Short options</title>
+ <para>
+ For convenience there are also single letter option switches
+ available for many parameters. They are described in the following
+ table.
+
+ <table>
+ <title>Short option key</title>
+ <tgroup cols="3">
+ <colspec colnum="3" align="center">
+ <thead>
+ <row>
+ <entry>Short option</entry>
+ <entry>Equivalent</entry>
+ <entry>Remark</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-B <replaceable>x</replaceable></entry>
+ <entry>shmem_buffers = <replaceable>x</replaceable></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>-d <replaceable>x</replaceable></entry>
+ <entry>debug_level = <replaceable>x</replaceable></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>-F</entry>
+ <entry>fsync = off</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>-i</entry>
+ <entry>net_server = on</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>-N <replaceable>x</replaceable></entry>
+ <entry>max_backends = <replaceable>x</replaceable></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>-p <replaceable>x</replaceable></entry>
+ <entry>port = <replaceable>x</replaceable></entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>-fi, -fh, -fm, -fn, -fs, -ft</entry>
+ <entry>enable_indexscan=off, enable_hashjoin=off,
+ enable_mergejoin=off, enable_nestloop=off, enable_seqscan=off,
+ enable_tidscan=off</entry>
+ <entry>*</entry>
+ </row>
+ <row>
+ <entry>-S <replaceable>x</replaceable></entry>
+ <entry>sort_mem = <replaceable>x</replaceable></entry>
+ <entry>*</entry>
+ </row>
+ <row>
+ <entry>-s</entry>
+ <entry>show_query_stats = on</entry>
+ <entry>*</entry>
+ </row>
+ <row>
+ <entry>-tpa, -tpl, -te</entry>
+ <entry>show_parser_stats=on, show_planner_stats=on, show_executor_stats=on</entry>
+ <entry>*</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ For historical reasons, options marked <quote>*</quote> must be
+ passed to the individual backend process via the
+ <option>-o</option> postmaster option, for example,
+<screen>
+> <userinput>postmaster -o '-S 1024 -s'</userinput>
+</screen>
+ or via <envar>PGOPTIONS</envar> from the client side, as explained
+ above.
+ </para>
+
+ </sect2>
+ </sect1>
+
+ <sect1 id="postmaster-shutdown">
+ <title>Shutting down the server</title>
+
+ <para>
+ Depending on your needs, there are several ways to shut down the
+ database server when your work is done. The differentiation is
+ done by what signal you send to the server process.
+ <variablelist>
+ <varlistentry>
+ <term>SIGTERM</term>
+ <listitem>
+ <para>
+ After receiving SIGTERM, the postmaster disallows new
+ connections but lets active backend end their work and shuts
+ down only after all of them terminated (by client request).
+ This is the <firstterm>Smart Shutdown</firstterm>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SIGINT</term>
+ <listitem>
+ <para>
+ The postmaster disallows new connections, sends all active
+ backends SIGTERM (which will cause them to abort immediately),
+ waits for children to exit and shuts down the data base. This
+ is the <firstterm>Fast Shutdown</firstterm>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SIGQUIT</term>
+ <listitem>
+ <para>
+ This is the <firstterm>Immediate Shutdown</firstterm> which
+ will cause the postmaster to send a SIGUSR1 to all backends and
+ exit immediately (without properly shutting down the database
+ system). When WAL is implemented, this will lead to recovery on
+ startup. Right now it's not recommendable to use this option.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <caution>
+ <para>
+ If at all possible, do not use SIGKILL to shut down the
+ postmaster. This can cause data corruption and will prevent the
+ cleaning up of shared memory resources, which you will have to
+ do yourself in that case.
+ </para>
+ </caution>
+
+ The PID of the postmaster process can be found using the
+ <application>ps</application> program, or from the file
+ <filename>postmaster.pid</filename> in the data directory. So for
+ example, to do a fast shutdown:
+<screen>
+> <userinput>kill -INT `cat /usr/local/pgsql/data/postmaster.pid`</userinput>
+</screen>
+ </para>
+ <para>
+ The program <application>pg_ctl</application> is a shell script
+ wrapper that provides a convenient interface to these functions.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Secure TCP/IP Connection with SSH</title>
+
+ <note>
+ <title>Acknowledgement</title>
+ <para>
+ Idea taken from an email by Gene Selkov, Jr.
+ (<email>selkovjr@mcs.anl.gov</>) written on 1999-09-08 in response
+ to a question from Eric Marsden.
+ </para>
+ </note>
+
+ <para>
+ One can use <productname>ssh</productname> to encrypt the network
+ connection between clients and a
+ <productname>Postgres</productname> server. Done properly, this
+ should lead to an adequately secure network connection.
+ </para>
+
+ <para>
+ First make sure that an <productname>ssh</productname> server is
+ running properly on the same machine as
+ <productname>Postgres</productname> and that you can log in using
+ ssh as some user. Then you can establish a secure tunnel with a
+ command like this from the client machine:
+<programlisting>
+> <userinput>ssh -L 3333:foo.com:5432 joe@foo.com</userinput>
+</programlisting>
+ The first number in the <option>-L</option> argument, 3333, is the
+ port number of your end of the tunnel; it can be chosen freely. The
+ second number, 5432, is the remote end of the tunnel -- the port
+ number your backend is using. The name or the address in between
+ the port numbers is the host with the database server you are going
+ to connect to. In order to connect to the database server using
+ this tunnel, you connect to port 3333 on the local machine:
+<programlisting>
+psql -h localhost -p 3333 template1
+</programlisting>
+ To the database server it will then look as though you are really
+ user <literal>joe@foo.com</literal> and it will use whatever
+ authentication procedure was set up for this user. In order for the
+ tunnel setup to succeed you must be allowed to connect via ssh as
+ joe@foo.com, just as if you had attempted to use ssh to set up a
+ terminal session.
+ </para>
+
+ </sect1>
</Chapter>
+++ /dev/null
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/security.sgml,v 1.9 2000/05/25 15:32:03 momjian Exp $
--->
-
- <chapter id="security">
- <Title>Security</Title>
-
- <Para>
- Database security is addressed at several levels:
-
- <itemizedlist>
- <listitem>
- <para>
- Data base file protection. All files stored within the database
- are protected from reading by any account other than the
- <productname>Postgres</productname> superuser account.
- </para>
- </listitem>
- <listitem>
- <para>
- Connections from a client to the database server are, by
- default, allowed only via a local Unix socket, not via TCP/IP
- sockets. The backend must be started with the
- <literal>-i</literal> option to allow non-local clients to connect.
- </para>
- </listitem>
- <listitem>
- <para>
- Client connections can be restricted by IP address and/or user
- name via the <filename>pg_hba.conf</filename> file in <envar>PG_DATA</envar>.
- </para>
- </listitem>
- <listitem>
- <para>
- Client connections may be authenticated via other external packages.
- </para>
- </listitem>
- <listitem>
- <para>
- Each user in <productname>Postgres</productname> is assigned a
- username and (optionally) a password. By default, users do not
- have write access to databases they did not create.
- </para>
- </listitem>
- <listitem>
- <para>
- Users may be assigned to <firstterm>groups</firstterm>, and
- table access may be restricted based on group privileges.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <Sect1>
- <Title>User Authentication</Title>
-
- <Para>
- <firstterm>Authentication</firstterm>
- is the process by which the backend server and
- <application>postmaster</application>
- ensure that the user requesting access to data is in fact who he/she
- claims to be.
- All users who invoke <Productname>Postgres</Productname> are checked against the
- contents of the <literal>pg_user</literal> class to ensure that they are
- authorized to do so. However, verification of the user's actual
- identity is performed in a variety of ways:
-
- <variablelist>
- <varlistentry>
- <term>
- From the user shell
- </term>
- <listitem>
- <para>
- A backend server started from a user shell notes the user's (effective)
- user-id before performing a
- <function>setuid</function>
- to the user-id of user <replaceable>postgres</replaceable>.
- The effective user-id is used
- as the basis for access control checks. No other authentication is
- conducted.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- From the network
- </term>
- <listitem>
- <para>
- If the <Productname>Postgres</Productname> system is built as distributed,
- access to the Internet TCP port of the
- <application>postmaster</application>
- process is available to anyone. The DBA configures the pg_hba.conf file
- in the PGDATA directory to specify what authentication system is to be used
- according to the host making the connection and which database it is
- connecting to. See <citetitle>pg_hba.conf(5)</citetitle>
- for a description of the authentication
- systems available. Of course, host-based authentication is not fool-proof in
- Unix, either. It is possible for determined intruders to also
- masquerade the origination host. Those security issues are beyond the
- scope of <Productname>Postgres</Productname>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <Sect2>
- <Title>Host-Based Access Control</Title>
-
- <Para>
- <firstterm>Host-based access control</firstterm>
- is the name for the basic controls PostgreSQL
- exercises on what clients are allowed to access a database and how
- the users on those clients must authenticate themselves.
- </para>
-
- <para>
- Each database system contains a file named
- <filename>pg_hba.conf</filename>, in its <envar>PGDATA</envar>
- directory, which controls who can connect to each database.
- </para>
-
- <para>
- Every client accessing a database
- <emphasis>must</emphasis>
- be covered by one of
- the entries in <filename>pg_hba.conf</filename>.
- Otherwise all attempted connections from that
- client will be rejected with a "User authentication failed" error
- message.
- </para>
-
- <para>
- The general format of the <filename>pg_hba.conf</filename>
- file is of a set of records, one per
- line. Blank lines and lines beginning with a hash character
- ("#") are ignored. A record is
- made up of a number of fields which are separated by spaces and/or tabs.
- </para>
-
- <para>
- Connections from clients can be made using Unix domain sockets or Internet
- domain sockets (ie. TCP/IP). Connections made using Unix domain sockets
- are controlled using records of the following format:
-
- <synopsis>
-local <replaceable>database</replaceable> <replaceable>authentication method</replaceable>
- </synopsis>
-
- where
-
- <simplelist>
- <member>
- <replaceable>database</replaceable>
- specifies the database that this record applies to. The value
- <literal>all</literal>
- specifies that it applies to all databases.
- </member>
- <member>
- <replaceable>authentication method</replaceable>
- specifies the method a user must use to authenticate themselves when
- connecting to that database using Unix domain sockets. The different methods
- are described below.
- </member>
- </simplelist>
- </para>
-
- <para>
- Connections made using Internet domain sockets are controlled using records
- of the following format.
-
- <synopsis>
-host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceable> <replaceable>TCP/IP mask</replaceable> <replaceable>authentication method</replaceable>
- </synopsis>
- </para>
-
- <para>
- The <replaceable>TCP/IP address</replaceable>
- is logically anded to both the specified
- <replaceable>TCP/IP mask</replaceable>
- and the TCP/IP address
- of the connecting client.
- If the two resulting values are equal then the
- record is used for this connection. If a connection matches more than one
- record then the earliest one in the file is used.
- Both the
- <replaceable>TCP/IP address</replaceable>
- and the
- <replaceable>TCP/IP mask</replaceable>
- are specified in dotted decimal notation.
- </para>
-
- <para>
- If a connection fails to match any record then the
- <firstterm>reject</firstterm>
- authentication method is applied (see below).
- </para>
-
- <sect3>
- <title>Authentication Methods</title>
-
- <para>
- The following authentication methods are supported for both Unix and TCP/IP
- domain sockets:
-
- <variablelist>
- <varlistentry>
- <term>trust</term>
- <listitem>
- <para>
- The connection is allowed unconditionally.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>reject</term>
- <listitem>
- <para>
- The connection is rejected unconditionally.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>crypt</term>
- <listitem>
- <para>
- The client is asked for a password for the user. This is sent encrypted
- (using <citetitle>crypt(3)</citetitle>)
- and compared against the password held in the
- <filename>pg_shadow</filename> table.
- If the passwords match, the connection is allowed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>password</term>
- <listitem>
- <para>
- The client is asked for a password for the user. This is sent in clear
- and compared against the password held in the
- <filename>pg_shadow</filename> table.
- If the passwords match, the connection is allowed. An optional password file
- may be specified after the
- <literal>password</literal>
- keyword which is used to match the supplied password rather than the pg_shadow
- table. See
- <citerefentry><refentrytitle>pg_passwd</refentrytitle></citerefentry>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- The following authentication methods are supported for TCP/IP
- domain sockets only:
-
- <variablelist>
- <varlistentry>
- <term>krb4</term>
- <listitem>
- <para>
- Kerberos V4 is used to authenticate the user.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>krb5</term>
- <listitem>
- <para>
- Kerberos V5 is used to authenticate the user.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ident</term>
- <listitem>
- <para>
- The ident server on the client is used to authenticate the user (RFC 1413).
- An optional map name may be specified after the
- <literal>ident</literal>
- keyword which allows ident user names to be mapped onto
- <productname>Postgres</productname> user names.
- Maps are held in the file
- <filename>$<envar>PGDATA</envar>/pg_ident.conf</filename>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </sect3>
-
- <sect3>
- <title>Examples</title>
-
- <para>
- <programlisting>
-# Trust any connection via Unix domain sockets.
-local trust
-# Trust any connection via TCP/IP from this machine.
-host all 127.0.0.1 255.255.255.255 trust
-# We don't like this machine.
-host all 192.168.0.10 255.255.255.0 reject
-# This machine can't encrypt so we ask for passwords in clear.
-host all 192.168.0.3 255.255.255.0 password
-# The rest of this group of machines should provide encrypted passwords.
-host all 192.168.0.0 255.255.255.0 crypt
- </programlisting>
- </para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <title>User Names and Groups</title>
-
- <para>
- To define a new user, run the
- <application>createuser</application> utility program.
- </para>
-
- <para>
- To assign a user or set of users to a new group, one must
- define the group itself, and assign users to that group. In
- <application>Postgres</application> these steps are not currently
- supported with a <command>create group</command> command. Instead,
- the groups are defined by inserting appropriate values into the
- <literal>pg_group</literal> system table, and then using the
- <command>grant</command> command to assign privileges to the
- group.
- </para>
-
- <sect2>
- <title>Creating Users</title>
-
- <para>
- </para>
- </sect2>
-
- <sect2>
- <title>Creating Groups</title>
-
- <para>
- Currently, there is no easy interface to set up user groups. You
- have to explicitly insert/update the <literal>pg_group table</literal>.
- For example:
-
- <programlisting>
-jolly=> insert into pg_group (groname, grosysid, grolist)
-jolly=> values ('posthackers', '1234', '{5443, 8261}');
-INSERT 548224
-jolly=> grant insert on foo to group posthackers;
-CHANGE
-jolly=>
- </programlisting>
- </para>
-
- <para>
- The fields in <filename>pg_group</filename> are:
-
- <variablelist>
- <varlistentry>
- <term>groname</term>
- <listitem>
- <para>
- The group name. This a name and should be purely
- alphanumeric. Do not include underscores or other punctuation.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>grosysid</term>
- <listitem>
- <para>
- The group id. This is an int4. This should be unique for
- each group.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>grolist</term>
- <listitem>
- <para>
- The list of pg_user id's that belong in the group. This
- is an int4[].
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </sect2>
-
- <sect2>
- <title>Assigning Users to Groups</title>
-
- <para>
- </para>
- </sect2>
-
- </sect1>
-
- <Sect1>
- <Title>Access Control</Title>
-
- <Para>
- <Productname>Postgres</Productname> provides mechanisms to allow users
- to limit the access to their data that is provided to other users.
-
- <variablelist>
- <varlistentry>
- <term>
- Database superusers
- </term>
- <listitem>
- <para>
- Database super-users (i.e., users who have <literal>pg_user.usesuper</literal>
- set) silently bypass all of the access controls described below with
- two exceptions: manual system catalog updates are not permitted if the
- user does not have <literal>pg_user.usecatupd</literal> set, and destruction of
- system catalogs (or modification of their schemas) is never allowed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- Access Privilege
- </term>
- <listitem>
- <para>
- The use of access privilege to limit reading, writing and setting
- of rules on classes is covered in
- <citetitle>grant/revoke(l)</citetitle>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- Class removal and schema modification
- </term>
- <listitem>
- <para>
- Commands that destroy or modify the structure of an existing class,
- such as <command>alter</command>,
- <command>drop table</command>,
- and
- <command>drop index</command>,
- only operate for the owner of the class. As mentioned above, these
- operations are <emphasis>never</emphasis>
- permitted on system catalogs.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </sect1>
-
- <Sect1>
- <Title>Functions and Rules</Title>
-
- <Para>
- Functions and rules allow users to insert code into the backend server
- that other users may execute without knowing it. Hence, both
- mechanisms permit users to <firstterm>trojan horse</firstterm>
- others with relative impunity. The only real protection is tight
- control over who can define functions (e.g., write to relations with
- SQL fields) and rules. Audit trails and alerters on
- <literal>pg_class</literal>, <literal>pg_user</literal>
- and <literal>pg_group</literal> are also recommended.
- </para>
-
- <Sect2>
- <Title>Functions</Title>
-
- <Para>
- Functions written in any language except SQL
- run inside the backend server
- process with the permissions of the user <replaceable>postgres</replaceable> (the
- backend server runs with its real and effective user-id set to
- <replaceable>postgres</replaceable>. It is possible for users to change the server's
- internal data structures from inside of trusted functions. Hence,
- among many other things, such functions can circumvent any system
- access controls. This is an inherent problem with user-defined C functions.
- </para>
- </sect2>
-
- <Sect2>
- <Title>Rules</Title>
-
- <Para>
- Like SQL functions, rules always run with the identity and
- permissions of the user who invoked the backend server.
- </para>
- </sect2>
-
- <sect2>
- <title>Caveats</title>
-
- <para>
- There are no plans to explicitly support encrypted data inside of
- <Productname>Postgres</Productname>
- (though there is nothing to prevent users from encrypting
- data within user-defined functions). There are no plans to explicitly
- support encrypted network connections, either, pending a total rewrite
- of the frontend/backend protocol.
- </para>
- <para>
- User names, group names and associated system identifiers (e.g., the
- contents of <literal>pg_user.usesysid</literal>) are assumed to be unique
- throughout a database. Unpredictable results may occur if they are
- not.
- </para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Secure TCP/IP Connection</title>
-
- <para>
- <note>
- <title>Author</title>
- <para>
- From e-mail by
- <ulink url="selkovjr@mcs.anl.gov">Gene Selkov, Jr.</ulink>
- written on 1999-09-08 in response to a
- question from Eric Marsden.
- </para>
- </note>
- </para>
-
- <para>
- One can use <productname>ssh</productname> to encrypt the network
- connection between clients and a
- <productname>Postgres</productname> server. Done properly, this
- should lead to an adequately secure network connection.
- </para>
-
- <para>
- The documentation for <productname>ssh</productname> provides most
- of the information to get started.
- Please refer to
- <ulink url="http://www.heimhardt.de/htdocs/ssh.html">http://www.heimhardt.de/htdocs/ssh.html</ulink>
- for better insight.
- </para>
-
- <para>
- A step-by-step explanation can be done in just two steps.
- </para>
-
- <procedure>
- <title>Running a secure tunnel via ssh</title>
-
- <para>
- A step-by-step explanation can be done in just two steps.
- </para>
-
- <step performance="required" id="establish-tunnel">
- <para>
- Establish a tunnel to the backend machine, like this:
-
- <programlisting>
-ssh -L 3333:wit.mcs.anl.gov:5432 postgres@wit.mcs.anl.gov
- </programlisting>
-
- The first number in the -L argument, 3333, is the port number of
- your end of the tunnel. The second number, 5432, is the remote
- end of the tunnel -- the port number your backend is using. The
- name or the address in between the port numbers belongs to the
- server machine, as does the last argument to ssh that also includes
- the optional user name. Without the user name, ssh will try the
- name you are currently logged on as on the client machine. You can
- use any user name the server machine will accept, not necessarily
- those related to postgres.
- </para>
- </step>
-
- <step performance="required">
- <para>
- Now that you have a running ssh session, you can connect a
- postgres client to your local host at the port number you
- specified in the previous step. If it's
- <application>psql</application>, you will need another shell
- because the shell session you used in
- <xref linkend="establish-tunnel"> is now occupied with
- <application>ssh</application>.
-
- <programlisting>
-psql -h localhost -p 3333 -d mpw
- </programlisting>
-
- Note that you have to specify the <option>-h</option> argument
- to cause your client to use the TCP socket instead of the Unix
- socket. You can omit the port argument if you chose 5432 as your
- end of the tunnel.
- </para>
- </step>
- </procedure>
- </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:
--->
+++ /dev/null
-<chapter id="signals">
-<DocInfo>
-<AuthorGroup>
-<Author>
-<FirstName>Massimo</FirstName>
-<Surname>Dal Zotto</Surname>
-</Author>
-</AuthorGroup>
-<Date>Transcribed 1998-10-16</Date>
-</DocInfo>
-
-<title><productname>Postgres</productname> Signals</title>
-
-<Para>
-<Note>
-<Para>
-Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
-</Para>
-</Note>
-</para>
-
-<para>
-<productname>Postgres</productname> uses the following signals for
- communication between the postmaster and backends:
-</para>
-
-<para>
-<table tocentry="1">
-<title><productname>Postgres</productname> Signals</title>
-<titleabbrev>Signals</titleabbrev>
-
-<tgroup cols="2">
-<thead>
-<row>
-<entry>
-Signal
-</entry>
-<entry>
-<application>postmaster</application> Action
-</entry>
-<entry>
-Server Action
-</entry>
-</row>
-</thead>
-
-<tbody>
-<row>
-<entry>
-SIGHUP
-</entry>
-<entry>
-kill(*,sighup)
-</entry>
-<entry>
-read_pg_options
-</entry>
-</row>
-
-<row>
-<entry>
-SIGINT
-</entry>
-<entry>
-die
-</entry>
-<entry>
-cancel query
-</entry>
-</row>
-
-<row>
-<entry>
-SIGQUIT
-</entry>
-<entry>
-kill(*,sigterm)
-</entry>
-<entry>
-handle_warn
-</entry>
-</row>
-
-<row>
-<entry>
-SIGTERM
-</entry>
-<entry>
-kill(*,sigterm), kill(*,9), die
-</entry>
-<entry>
-die
-</entry>
-</row>
-
-<row>
-<entry>
-SIGPIPE
-</entry>
-<entry>
-ignored
-</entry>
-<entry>
-die
-</entry>
-</row>
-
-<row>
-<entry>
-SIGUSR1
-</entry>
-<entry>
-kill(*,sigusr1), die
-</entry>
-<entry>
-quickdie
-</entry>
-</row>
-
-<row>
-<entry>
-SIGUSR2
-</entry>
-<entry>
-kill(*,sigusr2)
-</entry>
-<entry>
-async notify (SI flush)
-</entry>
-</row>
-
-<row>
-<entry>
-SIGCHLD
-</entry>
-<entry>
-reaper
-</entry>
-<entry>
-ignored (alive test)
-</entry>
-</row>
-
-<row>
-<entry>
-SIGTTIN
-</entry>
-<entry>
-ignored
-</entry>
-<entry>
-</entry>
-</row>
-
-<row>
-<entry>
-SIGTTOU
-</entry>
-<entry>
-ignored
-</entry>
-<entry>
-</entry>
-</row>
-
-<row>
-<entry>
-SIGCONT
-</entry>
-<entry>
-dumpstatus
-</entry>
-<entry>
-</entry>
-</row>
-
-<row>
-<entry>
-SIGFPE
-</entry>
-<entry>
-</entry>
-<entry>
-FloatExceptionHandler
-</entry>
-</row>
-
-</tbody>
-</tgroup>
-</table>
-
-<note>
-<para>
-"<literal>kill(*,signal)</literal>" means sending a signal to all backends.
-</para>
-</note>
-</para>
-
-<para>
-The main changes to the old signal handling are the use of SIGQUIT instead
-of SIGHUP to handle warns, SIGHUP to re-read the pg_options file and the
-redirection to all active backends of SIGHUP, SIGTERM, SIGUSR1 and SIGUSR2
-sent to the postmaster.
-In this way these signals sent to the postmaster can be sent
-automatically to all the backends without need to know their pids.
-To shut down postgres one needs only to send a SIGTERM to postmaster
-and it will stop automatically all the backends.
-</para>
-
-<para>
-The SIGUSR2 signal is also used to prevent SI cache table overflow
-which happens when some backend doesn't process SI cache for a long period.
-When a backend detects the SI table full at 70% it simply sends a signal
-to the postmaster which will wake up all idle backends and make them flush
-the cache.
-</para>
-
-<para>
-The typical use of signals by programmers could be the following:
-
-<programlisting>
-# stop postgres
-kill -TERM $postmaster_pid
-</programlisting>
-
-<programlisting>
-# kill all the backends
-kill -QUIT $postmaster_pid
-</programlisting>
-
-<programlisting>
-# kill only the postmaster
-kill -INT $postmaster_pid
-</programlisting>
-
-<programlisting>
-# change pg_options
-cat new_pg_options > $DATA_DIR/pg_options
-kill -HUP $postmaster_pid
-</programlisting>
-
-<programlisting>
-# change pg_options only for a backend
-cat new_pg_options > $DATA_DIR/pg_options
-kill -HUP $backend_pid
-cat old_pg_options > $DATA_DIR/pg_options
-</programlisting>
-</para>
-</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:
--->
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/start-ag.sgml,v 1.10 2000/03/31 03:27:41 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/start-ag.sgml,v 1.11 2000/06/18 21:24:51 petere Exp $
- This file currently contains several small chapters.
- Each chapter should be split off into a separate source file...
- - thomas 1998-02-24
-->
- <chapter id="newuser">
- <title>Adding and Deleting Users</title>
-
- <para>
- <application>createuser</application> enables specific users to access
- <productname>Postgres</productname>.
- <application>dropuser</application> removes users and
- prevents them from accessing <productname>Postgres</productname>.
- </para>
-
- <para>
- These commands only affect users with respect to
- <productname>Postgres</productname>;
- they have no effect on a user's other privileges or status with regards
- to the underlying operating system.
- </para>
- </chapter>
-
<chapter id="disk">
<title>Disk Management</title>
+++ /dev/null
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/trouble.sgml,v 2.6 2000/04/08 23:32:34 tgl Exp $
--->
-
- <Chapter Id="trouble">
- <Title>Troubleshooting</Title>
-
- <sect1>
- <title>Postmaster Startup Failures</title>
-
- <para>
- There are several common reasons for the postmaster to fail to start up.
- Check the postmaster's log file, or start it by hand (without redirecting
- standard output or standard error) to see what complaint messages appear.
- Some of the possible error messages are reasonably self-explanatory,
- but here are some that are not:
- </para>
-
- <para>
- <ProgramListing>
-FATAL: StreamServerPort: bind() failed: Address already in use
- Is another postmaster already running on that port?
- </ProgramListing>
- This usually means just what it suggests: you accidentally started a
- second postmaster on the same port where one is already running.
- However, if the kernel error
- message is not "Address already in use" or some variant of that wording,
- there may be a different problem. For example, trying to start a
- postmaster on a reserved port number may draw something like
- <ProgramListing>
-$ postmaster -i -p 666
-FATAL: StreamServerPort: bind() failed: Permission denied
- Is another postmaster already running on that port?
- </ProgramListing>
- </para>
-
- <para>
- <ProgramListing>
-IpcMemoryCreate: shmget failed (Invalid argument) key=5440001, size=83918612, permission=600
-FATAL 1: ShmemCreate: cannot create region
- </ProgramListing>
- A message like this probably means that your kernel's limit on the size
- of shared memory areas is smaller than the buffer area that Postgres
- is trying to create. (Or it could mean that you don't have SysV-style
- shared memory support configured into your kernel at all.) As a temporary
- workaround, you can try starting the postmaster with a smaller-than-normal
- number of buffers (-B switch). You will eventually want to reconfigure
- your kernel to increase the allowed shared memory size, however.
- You may see this message when trying to start multiple postmasters on
- the same machine, if their total space requests exceed the kernel limit.
- </para>
-
- <para>
- <ProgramListing>
-IpcSemaphoreCreate: semget failed (No space left on device) key=5440026, num=16, permission=600
- </ProgramListing>
- A message like this does <emphasis>not</emphasis> mean that you've run out
- of disk space; it means that your kernel's limit on the number of SysV
- semaphores is smaller than the number Postgres wants to create. As above,
- you may be able to work around the problem by starting the postmaster with
- a reduced number of backend processes (-N switch), but you'll eventually
- want to increase the kernel limit.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Client Connection Problems</title>
-
- <para>
- Once you have a running postmaster, trying to connect to it with
- client applications can fail for a variety of reasons. The sample
- error messages shown here are for clients based on recent versions
- of libpq --- clients based on other interface libraries may produce
- other messages with more or less information.
- </para>
-
- <para>
- <ProgramListing>
-connectDB() -- connect() failed: Connection refused
-Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'?
- </ProgramListing>
- This is the generic "I couldn't find a postmaster to talk to" failure.
- It looks like the above when TCP/IP communication is attempted, or like
- this when attempting Unix-socket communication to a local postmaster:
- <ProgramListing>
-connectDB() -- connect() failed: No such file or directory
-Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'?
- </ProgramListing>
- The last line is useful in verifying that the client is trying to connect
- where it is supposed to. If there is in fact no postmaster
- running there, the kernel error message will typically be either
- "Connection refused" or "No such file or directory", as illustrated.
- (It is particularly important to realize that "Connection refused" in
- this context does <emphasis>not</emphasis> mean that the postmaster
- got your connection request and rejected it --- that case will produce
- a different message, as shown below.)
- Other error messages such as "Connection timed out" may indicate more
- fundamental problems, like lack of network connectivity.
- </para>
-
- <para>
- <ProgramListing>
-No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
- </ProgramListing>
- This is what you are most likely to get if you succeed in contacting
- a postmaster, but it doesn't want to talk to you. As the message
- suggests, the postmaster refused the connection request because it
- found no authorizing entry in its pg_hba.conf configuration file.
- </para>
-
- <para>
- <ProgramListing>
-Password authentication failed for user 'joeblow'
- </ProgramListing>
- Messages like this indicate that you contacted the postmaster, and it's
- willing to talk to you, but not until you pass the authorization method
- specified in the pg_hba.conf file. Check the password you're providing,
- or check your Kerberos or IDENT software if the complaint mentions
- one of those authentication types.
- </para>
-
- <para>
- <ProgramListing>
-FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow'
- </ProgramListing>
- This is another variant of authentication failure: no Postgres create_user
- command has been executed for the given username.
- </para>
-
- <para>
- <ProgramListing>
-FATAL 1: Database testdb does not exist in pg_database
- </ProgramListing>
- There's no database by that name under the control of this postmaster.
- Note that if you don't specify a database name, it defaults to your
- Postgres username, which may or may not be the right thing.
- </para>
-
- <para>
- <ProgramListing>
-NOTICE: Unrecognized variable client_encoding
- </ProgramListing>
- This isn't an error; in fact, it's quite harmless. You'll see this
- message at startup if you use a client compiled with MULTIBYTE support
- to connect to a server compiled without it. (The client is trying
- to tell the server what character set encoding it wants, but the
- server has no idea what it's talking about.) If the message bothers
- you, use a client compiled with the same options as the server.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Debugging Messages</title>
-
- <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.
- No ampersand ("&") is required in this case, since the postmaster
- automatically detaches from the terminal when -S is specified.
- </Para>
-
- <sect2 Id="pg-options-trouble">
- <Title>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.
- What makes this file interesting is the fact that it 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.
- New options and parameters must be defined in
- <filename>backend/utils/misc/trace.c</filename> and
- <filename>backend/include/utils/trace.h</filename>.
- </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>.
- </Para>
-
- <Para>
- Refer to <xref linkend="pg-options-title" endterm="pg-options-title">
- for a complete list of option keywords and possible values.
- </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:
--->
--- /dev/null
+<Chapter id="user-manag">
+ <title>Database User and Permission Management</title>
+
+ <para>
+ Managing database users and their privileges is in concept similar
+ to that of Unix operating systems, but then again not identical
+ enough to not warrant explanation.
+ </para>
+
+ <sect1>
+ <title>Database Users</title>
+
+ <para>
+ Database users are conceptually completely separate from any
+ operating system users. In practice it might be convenient to
+ maintain a correspondence, but this is not required. Database user
+ names are global across a database cluster installation (and not
+ per individual database). To create a user use the <command>CREATE
+ USER</command> SQL command:
+<synopsis>
+CREATE USER <replaceable>name</replaceable>
+</synopsis>
+ <replaceable>name</replaceable> follows the rules for SQL
+ identifiers: either unadorned without special characters, or
+ double-quoted. To remove an existing user, use the analog
+ <command>DROP USER</command> command.
+ </para>
+
+ <para>
+ For convenience, the shell scripts <filename>createuser</filename>
+ and <filename>dropuser</filename> are wrappers around these SQL
+ commands.
+ </para>
+
+ <para>
+ In order to bootstrap the database system, a freshly initialized
+ system always contains one predefined user. This user will have
+ the same name as the operating system user that initialized the
+ area (and is presumably being used as the user that runs the
+ server). Thus, often an initial user <quote>postgres</quote>
+ exists. In order to create more users you have to first connect as
+ this initial user.
+ </para>
+
+ <para>
+ The user name to use for a particular database connection is
+ indicated by the client that is initiating the connection request
+ in an application-specific fashion. For example, the
+ <command>psql</command> program uses the <option>-U</option>
+ command line option to indicate the user to connect as. The set of
+ database users a given client connection may connect as is
+ determined by the client authentication setup, as explained in
+ <xref linkend="client-authentication">. (Thus, a client is not
+ necessarily limited to connect as the user with the same name as
+ its operating system user in the same way a person is not
+ constrained in its login name by her real name.)
+ </para>
+
+ <sect2>
+ <title>User attributes</title>
+
+ <para>
+ A database user may have a number of attributes that define its
+ privileges and interact with the client authentication system.
+
+ <variablelist>
+ <varlistentry>
+ <term>superuser</term>
+ <listitem>
+ <para>
+ A database superuser bypasses all permission checks. Also,
+ only a superuser can create new users. To create a database
+ superuser, use <literal>CREATE USER name
+ CREATEUSER</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>database creation</term>
+ <listitem>
+ <para>
+ A user must be explicitly given permission to create databases
+ (except for superusers, since those bypass all permission
+ checks). To create such a user, use <literal>CREATE USER name
+ CREATEDB</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>password</term>
+ <listitem>
+ <para>
+ A password is only significant if password authentication is
+ used for client authentication. Database passwords a separate
+ from any operating system passwords. Specify a password upon
+ user creating as in <literal>CREATE USER name WITH PASSWORD
+ 'string'</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ See the reference pages for <command>CREATE USER</command> and
+ <command>ALTER USER</command> for details.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Groups</title>
+
+ <para>
+ As in Unix, groups are a way of logically grouping users. To create
+ a group, use
+<synopsis>
+CREATE GROUP <replaceable>name</replaceable>
+</synopsis>
+ To add users to or remove users from a group, respectively, user
+<synopsis>
+ALTER GROUP <replaceable>name</replaceable> ADD USER <replaceable>uname1</replaceable>, ...
+ALTER GROUP <replaceable>name</replaceable> DROP USER <replaceable>uname1</replaceable>, ...
+</synopsis>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Privileges</title>
+
+ <para>
+ When a database object is created, it is assigned an owner. The
+ owner is the user that executed the creation statement. There is
+ currenty no polished interface for changing the owner of a database
+ object. By default, only an owner (or a superuser) can do anything
+ with the object. In order to allow other users to use it,
+ <firstterm>privileges</firstterm> must be granted.
+ </para>
+
+ <para>
+ Currently, there are four different privileges: select (read),
+ insert (append), and update/delete (write), as well as
+ <literal>RULE</literal>, the permission to create a rewrite rule on
+ a table. The right to modify or destroy an object is always the
+ privilege of the owner only. To assign privileges, the
+ <command>GRANT</command> command is used. So, if
+ <literal>joe</literal> is an existing user, and
+ <literal>accounts</literal> is an existing table, write access can
+ be granted with
+<programlisting>
+GRANT UPDATE ON accounts TO joe;
+</programlisting>
+ The user executing this command must be the owner of the table. To
+ grant a privilege to a group, use
+<programlisting>
+GRANT SELECT ON accounts TO GROUP staff;
+</programlisting>
+ The special <quote>user</quote> name <literal>PUBLIC</literal> can
+ be used to grant a privilege to every user on the system. Using
+ <literal>ALL</literal> in place of a privilege specifies that all
+ privileges will be granted.
+ </para>
+
+ <para>
+ To revoke a privilege, use the fittingly named
+ <command>REVOKE</command> command:
+<programlisting>
+REVOKE ALL ON accounts FROM PUBLIC;
+</programlisting>
+ The set of privileges held by the table owner is always implicit
+ and is never revokable.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Functions and Triggers</title>
+
+ <para>
+ Functions and triggers allow users to insert code into the backend
+ server that other users may execute without knowing it. Hence, both
+ mechanisms permit users to <firstterm>trojan horse</firstterm>
+ others with relative impunity. The only real protection is tight
+ control over who can define functions (e.g., write to relations
+ with SQL fields) and triggers. Audit trails and alerters on the
+ system catalogs <literal>pg_class</literal>,
+ <literal>pg_user</literal> and <literal>pg_group</literal> are also
+ possible.
+ </para>
+
+ <para>
+ Functions written in any language except SQL run inside the backend
+ server process with the operating systems permissions of the
+ database server daemon process. It is possible to change the
+ server's internal data structures from inside of trusted functions.
+ Hence, among many other things, such functions can circumvent any
+ system access controls. This is an inherent problem with
+ user-defined C functions.
+ </para>
+
+ </sect1>
+
+</Chapter>
projects / postgresql / commitdiff