Skip to content

P
Postgres FD Implementation
Commit 2c0edb3c authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Separated set constraints and set transaction reference pages, revised set 

reference page to new configuration system. Big update to administrator's
guide, chapters Runtime environment, Client authentication, and User
management, the latter two were part of the old Security chapter.
parent b4e906f1
Hide whitespace changes
Inline Side-by-side
Showing with 2104 additions and 3031 deletions
doc/src/sgml/Makefile
View file @ 2c0edb3c
......@@ -8,7 +8,7 @@
#
#
# 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 $
#
#----------------------------------------------------------------------------
......@@ -104,7 +104,7 @@ COMMANDS= abort.sgml alter_group.sgml alter_table.sgml alter_user.sgml \
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
......
doc/src/sgml/admin.sgml
View file @ 2c0edb3c
<!--
$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.
......@@ -27,7 +27,8 @@ 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">
......@@ -111,10 +112,10 @@ Your name here...
&install;
&installw;
&runtime;
&security;
&client-auth;
&user-manag;
&start-ag;
&manage-ag;
&trouble;
&recovery;
&regress;
&release;
......
doc/src/sgml/client-auth.sgml 0 → 100644
View file @ 2c0edb3c
<!-- $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>
doc/src/sgml/pg_options.sgml deleted 100644 → 0
View file @ b4e906f1
<!--
$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:
-->
doc/src/sgml/postgres.sgml
View file @ 2c0edb3c
<!--
$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" [
......@@ -58,9 +58,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 th
<!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">
......@@ -100,10 +100,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 th
<!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 -->
......@@ -225,10 +223,10 @@ Your name here...
&install;
&installw;
&runtime;
&security;
&client-auth;
&user-manag;
&start-ag;
&manage-ag;
&trouble;
&recovery;
&regress;
&release;
......@@ -292,7 +290,6 @@ Your name here...
</partintro>
&sources;
&arch-dev;
&options;
&geqo;
<!--
This listing of Postgres catalogs is currently just a copy of the old
......@@ -301,7 +298,6 @@ Your name here...
&catalogs;
-->
&protocol;
&signals;
&compiler;
&bki;
&page;
......
doc/src/sgml/programmer.sgml
View file @ 2c0edb3c
<!--
$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.
-->
......@@ -50,10 +50,8 @@ 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">
]>
......@@ -165,7 +163,6 @@ Disable it until we put in some info.
&sources;
&arch-dev;
&options;
&geqo;
<!--
This listing of Postgres catalogs is currently just a copy of the old
......@@ -174,7 +171,6 @@ Disable it until we put in some info.
&catalogs;
-->
&protocol;
&signals;
&compiler;
&bki;
&page;
......
doc/src/sgml/ref/allfiles.sgml
View file @ 2c0edb3c
<!--
$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.
-->
......@@ -98,6 +98,8 @@ 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">
......
doc/src/sgml/ref/commands.sgml
View file @ 2c0edb3c
<!--
$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
-->
......@@ -72,6 +72,8 @@ Postgres documentation
&select;
&selectInto;
&set;
&setConstraints;
&setTransaction;
&show;
&truncate;
&unlisten;
......
doc/src/sgml/ref/reset.sgml
View file @ 2c0edb3c
<!--
$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>
......@@ -49,107 +34,55 @@ RESET <replaceable class="PARAMETER">variable</replaceable>
</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>
......
doc/src/sgml/ref/set.sgml
View file @ 2c0edb3c
<!--
<<<<<<< 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>
......@@ -64,1035 +43,362 @@ SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
</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>
......
doc/src/sgml/ref/set_constraints.sgml 0 → 100644
View file @ 2c0edb3c
<!-- $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>
doc/src/sgml/ref/set_transaction.sgml 0 → 100644
View file @ 2c0edb3c
<!-- $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>
doc/src/sgml/ref/show.sgml
View file @ 2c0edb3c
<!--
$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>
......@@ -50,41 +36,43 @@ SHOW <replaceable class="PARAMETER">keyword</replaceable>
</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
......@@ -94,82 +82,35 @@ NOTICE: Time zone is unknown
</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>
......
doc/src/sgml/runtime.sgml
View file @ 2c0edb3c
<!--
$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>
&gt; <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&gt; <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>
&gt; <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>
&gt; <userinput>postmaster -D /usr/local/pgsql/data &gt; logfile 1&gt;&amp;2 &amp;</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 ("&amp") 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>
&gt; <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>
=&gt; <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>
&gt; <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>
&gt; <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>
&gt; <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>
......
doc/src/sgml/security.sgml deleted 100644 → 0
View file @ b4e906f1
<!--
$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:
-->
doc/src/sgml/signals.sgml deleted 100644 → 0
View file @ b4e906f1
<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:
-->
doc/src/sgml/start-ag.sgml
View file @ 2c0edb3c
<!--
$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>
......
doc/src/sgml/trouble.sgml deleted 100644 → 0
View file @ b4e906f1
<!--
$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 ("&amp") 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:
-->
doc/src/sgml/user-manag.sgml 0 → 100644
View file @ 2c0edb3c
<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>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment