diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index e99c145723f..bb43863c155 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -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
diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml
index 936ce863c6d..c8fb66b4112 100644
--- a/doc/src/sgml/admin.sgml
+++ b/doc/src/sgml/admin.sgml
@@ -1,5 +1,5 @@
+
+
+ Client Authentication
+
+
+ User names from the operating system and from a
+ Postgres 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 for more information
+ about that. It is therefore obviously essential to restrict what
+ database user name a given client can connect as.
+
+
+
+ Authentication 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.
+
+
+
+ Postgres offers client authentication by
+ (client) host and by database, with a number of different
+ authentication methods available.
+
+
+
+ The <filename>pg_hba.conf</filename> file
+
+
+ Client authentication is controlled by the file
+ pg_hba.conf in the data directory, e.g.,
+ /usr/local/pgsql/data/pg_hba.conf. (HBA =
+ host-based authentication) A default file is installed when the
+ data area is initialized by initdb.
+
+
+
+ The general format of the pg_hba.conf 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.
+
+
+
+ A record may have one of the two formats
+
+local databaseauthentication-method [ authentication-option ]
+host databaseIP-addressIP-maskauthentication-method [ authentication-option ]
+
+ The meaning of the fields is as follows:
+
+
+
+ local
+
+
+ This record pertains to connection attempts over Unix domain
+ sockets.
+
+
+
+
+
+ host
+
+
+ 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 or
+ the equivalent configuration parameter is set.
+
+
+
+
+
+ database
+
+
+ Specifies the database that this record applies to. The value
+ all specifies that it applies to all
+ databases.
+
+
+
+
+
+ IP address
+ IP mask
+
+
+ These two fields control to which hosts a
+ host record applies, based on their IP
+ address. (Of course IP addresses can be spoofed but this
+ consideration is beyond the scope of
+ Postgres.) The precise logic is that
+
+
+ (actual-IP-address xor IP-address-field) and IP-mask-field
+
+
+ must be zero for the record to match.
+
+
+
+
+
+ authentication method
+
+
+ Specifies the method a user must use to authenticate themselves
+ when connecting to that database.
+
+
+
+
+
+ authentication option
+
+
+ This field is interpreted differently depending on the
+ authentication method.
+
+
+
+
+
+ The first record that matches a connection attempt is used. Note
+ that there is no fall-through or
+ backup, 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.
+
+
+
+ The pg_hba.conf file is re-read before each
+ connection attempt. It is therefore easily possible to modify
+ access permissions while the server is running.
+
+
+
+ An example of a pg_hba.conf file is shown in
+ . See below for details on the
+ different authentication methods.
+
+
+ An example <filename>pg_hba.conf</filename> file
+
+# 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
+
+
+
+
+
+
+ Authentication methods
+
+ The following authentication methods are supported. They are
+ descibed in detail below.
+
+
+
+ trust
+
+
+ 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.
+
+
+
+
+
+ reject
+
+
+ The connection is rejected unconditionally. This is mostly
+ useful to filter out certain hosts from a group.
+
+
+
+
+
+ password
+
+
+ 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.)
+
+
+ An optional password file may be specified after the
+ password keyword to obtain the password from
+ that file rather than the pg_shadow system catalog.
+
+
+ The password is sent over the wire in clear text. For better
+ protection, use the crypt method.
+
+
+
+
+
+ crypt
+
+
+ Like the password 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
+ crypt does not support secondary password
+ files.
+
+
+
+
+
+ krb4
+
+
+ Kerberos V4 is used to authenticate the user. This is only
+ available for TCP/IP connections.
+
+
+
+
+
+ krb5
+
+
+ Kerberos V5 is used to authenticate the user. This is only
+ available for TCP/IP connections.
+
+
+
+
+
+ ident
+
+
+ The ident server on the client host is asked for the identity
+ of the connecting user. Postgres
+ then verifies whether the so identified operating system user
+ is allowed to connect as the database user that is requested.
+ The authentication option following
+ the ident keyword specifies the name of an
+ ident map that specifies which operating
+ system users equate with which database users. See below for
+ details.
+
+
+
+
+
+
+
+ Password authentication
+
+ 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 CREATE USER and
+ ALTER USER, e.g., CREATE USER foo
+ WITH PASSWORD 'secret';. By default, that is, if no
+ password has explicitly been set up, the stored password is
+ NULL and password authentication will always fail
+ for that user.
+
+
+
+ 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 /etc/passwd, that is,
+
+username:password
+
+ Any extra colon separated fields following the password are
+ ignored. The password is expected to be encrypted using the
+ system's crypt() function. The utility
+ program pg_passwd that is installed
+ with Postgres can be used to manage
+ these password files.
+
+
+
+ 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.
+
+
+
+ Note that using secondary password files means that one can no
+ longer use ALTER USER 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.
+
+
+
+
+ Kerberos authentication
+
+
+ Kerberos is an industry-standard secure
+ authentication system suitable for distributed computing over a
+ public network. A description of the
+ Kerberos system is far beyond the scope
+ of this document; in all generality it can be quite complex. The
+ Kerberos FAQ
+ can be a good starting point for exploration.
+
+
+
+ In order to use Kerberos, support for it must be
+ enable at build time. Both Kerberos 4 and 5 are supported.
+
+
+
+ Postgres should operate like a normal Kerberos
+ service. The name of the service principal is normally
+ postgres, 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
+ ). The location of the keytab file
+ is specified at build time. By default it is
+ /etc/srvtab in Kerberos 4 and
+ FILE:/usr/local/postgres/krb5.keytab in
+ Kerberos 5.
+
+
+
+
+
+ Ident-based authentication
+
+
+ The Identification Protocol is described in
+ RFC 1413. 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 What user initiated the
+ connection that goes out of your port X
+ and connects to my port Y?.
+ Since both X and
+ Y are known,
+ Postgres could theoretically determine
+ the operating system user for any given connection this way.
+
+
+
+ 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:
+
+ RFC 1413
+
+ The Identification Protocol is not intended as an authorization
+ or access control protocol.
+
+
+
+
+
+ When using ident-based authentication, after having determined the
+ operating system user that initiated the connection,
+ Postgres determines as what database
+ system user he may connect. This is controlled by the ident map
+ argument that follows the ident keyword in the
+ pg_hba.conf file. The simplest ident map is
+ sameuser, 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.
+
+
+
+ Ident maps are held in the file pg_ident.conf
+ in the data directory, which contains lines of the general form:
+
+map-name ident-username database-username
+
+ Comments and whitespace are handled in the usual way.
+ The map-name is an arbitrary name that will be
+ used to refer to this mapping in pg_hba.conf.
+ The other two fields specify which operating system user is
+ allowed to connect as which database user. The same
+ 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.
+
+
+
+ A pg_ident.conf file that could be used in
+ conjunction with the pg_hba.conf file in is shown in . 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 bob, not as robert or
+ anyone else. ann and joe would only
+ be allowed to connect as themselves. On the
+ 192.168.2 network, however, a user ann would not be
+ allowed to connect at all, only the user bob can connect
+ as bob and some user karl can connect as
+ joe as well.
+
+
+
+ An example <filename>pg_ident.conf</> file
+
+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
+
+
+
+
+
+
+ Authentication problems
+
+
+ Genuine authentication failures and related problems generally
+ manifest themselves through error messages like the following.
+
+
+
+
+No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
+
+ 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 pg_hba.conf
+ configuration file.
+
+
+
+
+Password authentication failed for user 'joeblow'
+
+ 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
+ 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.
+
+
+
+
+FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow'
+
+ This is the fancy way of saying that the user doesn't exist at all.
+
+
+
+
+FATAL 1: Database testdb does not exist in pg_database
+
+ 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.
+
+
+
+
+
diff --git a/doc/src/sgml/pg_options.sgml b/doc/src/sgml/pg_options.sgml
deleted file mode 100644
index 7bb2b0b839c..00000000000
--- a/doc/src/sgml/pg_options.sgml
+++ /dev/null
@@ -1,240 +0,0 @@
-
-
-
-
-
-
- Massimo
- Dal Zotto
-
-
- Transcribed 1998-10-16
-
-
- pg_options
-
-
-
-
- Contributed by Massimo Dal Zotto
-
-
-
-
- The optional file data/pg_options 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
- Postgres.
- The options specified in this file may be debugging flags used by the trace
- package (backend/utils/misc/trace.c) or numeric
- parameters which can be used by the backend to control its behaviour.
- New options and parameters must be defined in
- backend/utils/misc/trace.c and
- backend/include/utils/trace.h.
-
-
- For example suppose we want to add conditional trace messages and a tunable
- numeric parameter to the code in file foo.c.
- All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
- backend/include/utils/trace.h:
-
-
-/* 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 */
-};
-
-
- and a corresponding line in backend/utils/misc/trace.c:
-
-
-/* file trace.c */
-static char *opt_names[] = {
- ...
- "foo", /* trace foo functions */
- "fooparam" /* foo tunable parameter */
-};
-
-
- 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:
-
-
-/* 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);
- }
-}
-
-
-
- Existing files using private trace flags can be changed by simply adding
- the following code:
-
-
-#include "trace.h"
-/* int my_own_flag = 0; -- removed */
-#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
-
-
-
- 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 PostgresMain.
-
- Now we can set the foo_param and enable foo trace by writing values into the
- data/pg_options file:
-
-
-# file pg_options
-...
-foo=1
-fooparam=17
-
-
-
- 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.
-
-
- pg_options can also be specified with the switch of
- Postgres:
-
-
-postgres options -T "verbose=2,query,hostlookup-"
-
-
-
- The functions used for printing errors and debug messages can now make use
- of the syslog(2) facility. Message printed to stdout
- or stderr are prefixed by a timestamp containing also the backend pid:
-
-
-#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
-
-
-
- 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.
-
-
- 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 printf()
- 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.
-
-
-
- The new pg_options mechanism is more convenient than defining new backend
- option switches because:
-
-
-
-
- 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.
-
-
-
-
-
- we don't have to restart Postgres 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.
-
-
-
-
-
- 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.
-
-
-
-
- The format of the pg_options file is as follows:
-
-
-# comment
-option=integer_value # set value for option
-option # set option = 1
-option+ # set option = 1
-option- # set option = 0
-
-
- Note that keyword can also be
- an abbreviation of the option name defined in
- backend/utils/misc/trace.c.
-
-
-
- Refer to The Administrator's Guide chapter
- on runtime options for a complete list of currently supported
- options.
-
-
-
- Some of the existing code using private variables and option switches has
- been changed to make use of the pg_options feature, mainly in
- postgres.c. 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 Postgres command line
- and can have more tunable options
- with a unique place to put option values.
-
-
-
-
-
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 2f7d1502642..02abce94f2d 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,5 +1,5 @@
-
+
+
-
@@ -100,10 +100,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.36 2000/05/02 20:01:52 th
-
-
]>
@@ -225,10 +223,10 @@ Your name here...
&install;
&installw;
&runtime;
- &security;
+ &client-auth;
+ &user-manag;
&start-ag;
&manage-ag;
- &trouble;
&recovery;
®ress;
&release;
@@ -292,7 +290,6 @@ Your name here...
&sources;
&arch-dev;
- &options;
&geqo;
&protocol;
- &signals;
&compiler;
&bki;
&page;
diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml
index fae484a69e2..fe1fd3af996 100644
--- a/doc/src/sgml/programmer.sgml
+++ b/doc/src/sgml/programmer.sgml
@@ -1,5 +1,5 @@
@@ -50,10 +50,8 @@ Postgres Programmer's Guide.
-
-
]>
@@ -165,7 +163,6 @@ Disable it until we put in some info.
&sources;
&arch-dev;
- &options;
&geqo;
&protocol;
- &signals;
&compiler;
&bki;
&page;
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index aef598d8a3a..3611943dbe9 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
@@ -98,6 +98,8 @@ Complete list of usable sgml source files in this directory.
+
+
diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml
index 28f7f0cbde5..9f6ba8e70dd 100644
--- a/doc/src/sgml/ref/commands.sgml
+++ b/doc/src/sgml/ref/commands.sgml
@@ -1,5 +1,5 @@
@@ -72,6 +72,8 @@ Postgres documentation
&select;
&selectInto;
&set;
+ &setConstraints;
+ &setTransaction;
&show;
&truncate;
&unlisten;
diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml
index e8f98aba3b5..e9f515da7bf 100644
--- a/doc/src/sgml/ref/reset.sgml
+++ b/doc/src/sgml/ref/reset.sgml
@@ -1,47 +1,32 @@
-
- RESET
-
+ RESETSQL - Language Statements
-
- RESET
-
-
- Restores run-time parameters for session to default values
-
+ RESET
+ Restores run-time parameters to default values
-
- 1999-07-20
-
RESET variable
-
- 1998-09-24
-
-
- Inputs
-
+ Inputsvariable
- Refer to
-
- for more information on available variables.
+ The name of a run-time parameter. See for a list.
@@ -49,107 +34,55 @@ RESET variable
-
-
- 1998-09-24
-
-
- Outputs
-
-
-
-
-
-
-RESET VARIABLE
-
-
-
- Message returned if
- variable is successfully reset
- to its default value.
-
-
-
-
-
-
-
-
- 1998-09-24
-
-
- Description
-
+
+ Description
- RESET restores variables to their
- default values.
- Refer to
+ RESET restores run-time parameters to their
+ default values. Refer to
- for details on allowed values and defaults.
- RESET is an alternate form for
+ for details. RESET is an alternate form for
-SET variable = DEFAULT
+SET variable TO DEFAULT
-
-
-
- 1998-09-24
-
-
- Notes
-
-
-
- See also
- and
-
- to manipulate variable values.
-
-
-
-
-
- Usage
-
+
+
+ Diagnostics
+
+ See under the command.
+
+
+
+
+ Examples
Set DateStyle to its default value:
-
+
RESET DateStyle;
-
+
Set Geqo to its default value:
-
+
RESET GEQO;
-
+
-
-
- Compatibility
-
+
+ Compatibility
-
-
- 1998-09-24
-
-
- SQL92
-
-
- There is no RESET in SQL92.
-
-
+
+ RESET is a Postgres extension.
+
diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml
index 3d3884dd305..044cf8fd65b 100644
--- a/doc/src/sgml/ref/set.sgml
+++ b/doc/src/sgml/ref/set.sgml
@@ -1,53 +1,32 @@
-
- SET
-
+ SETSQL - Language Statements
-
- SET
-
-
- Set run-time parameters for session
-
+ SET
+ Set run-time parameters
-
- 1999-07-20
-
SET variable { TO | = } { value | 'value' | DEFAULT }
-SET CONSTRAINTS {ALL | constraintlist} mode
SET TIME ZONE { 'timezone' | LOCAL | DEFAULT }
-SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
-
- 1998-09-24
-
-
- Inputs
-
+ Inputs
-
variable
- Settable global parameter.
+ A settable run-time parameter.
@@ -64,147 +43,144 @@ SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
+
-
- The possible variables and allowed values are:
-
-
-
- CLIENT_ENCODING | NAMES
-
-
- Sets the multi-byte client encoding. Parameters are:
-
-
-
- value
-
-
- Sets the multi-byte client encoding to
- value.
- The specified encoding must be supported by the backend.
-
-
-
-
-
+
+
+
+ Description
+
+ The SET command changes run-time configuration
+ parameters. The following parameters can be altered:
-
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
-
-
-
+
+
+ CLIENT_ENCODING
+ NAMES
+
+
+ Sets the multi-byte client encoding. The specified encoding
+ must be supported by the backend.
+
-
- DATESTYLE
-
-
- Set the date/time representation style. Affects the output format,
- and in some cases it can affect the interpretation of input.
+
+ This option is only available if
+ Postgres is build with multibyte
+ support.
+
+
+
-
-
- ISO
-
-
- use ISO 8601-style dates and times
-
-
-
-
- SQL
-
-
- use Oracle/Ingres-style dates and times
-
-
-
-
- Postgres
-
-
- use traditional Postgres format
-
-
-
-
- European
-
-
- use dd/mm/yyyy for numeric date representations.
-
-
-
-
- NonEuropean
-
-
- use mm/dd/yyyy for numeric date representations.
-
-
-
-
- German
-
-
- use dd.mm.yyyy for numeric date representations.
-
-
-
-
- US
-
-
- same as NonEuropean
-
-
-
-
- DEFAULT
-
-
- restores the default values (ISO)
-
-
-
-
-
+
+ DATESTYLE
+
+
+ Choose the date/time representation style. Two separate
+ settings are made: the default date/time output and the
+ interpretation of ambiguous input.
+
-
- Date format initialization may be done by:
-
-
- Setting the PGDATESTYLE 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.
-
-
- Running postmaster using the option to set
- dates to the European convention.
- Note that this affects only some combinations of date styles; for example
- the ISO style is not affected by this parameter.
-
-
- Changing variables in
- src/backend/utils/init/globals.c.
-
-
-
-
- The variables in globals.c which can be changed are:
-
-
- bool EuroDates = false | true
-
-
- int DateStyle = USE_ISO_DATES | USE_POSTGRES_DATES | USE_SQL_DATES | USE_GERMAN_DATES
-
-
-
-
-
+
+ The following are date/time output styles:
+
+
+
+ ISO
+
+
+ Use ISO 8601-style dates and times (YYYY-MM-DD
+ HH:MM:SS). This is the default.
+
+
+
+
+
+ SQL
+
+
+ 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.
+
+
+
+
+
+ Postgres
+
+
+ Use traditional Postgres format.
+
+
+
+
+
+ German
+
+
+ Use dd.mm.yyyy for numeric date representations.
+
+
+
+
+
+
+
+ The following two options determine both a substyle of the
+ SQL and Postgres output formats
+ and the preferred interpretation of ambiguous date input.
+
+
+
+ European
+
+
+ Use dd/mm/yyyy for numeric date representations.
+
+
+
+
+
+ NonEuropean
+ US
+
+
+ Use mm/dd/yyyy for numeric date representations.
+
+
+
+
+
+
+
+ A value for SET DATESTYLE can be one from
+ the first list (output styles), or one from the second list
+ (substyles), or one from each separated by a comma.
+
+
+
+ Date format initialization may be done by:
+
+
+ Setting the PGDATESTYLE 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.
+
+
+ Running postmaster using the option to
+ set dates to the European convention.
+
+
+
+
+ The option is really only intended
+ for porting applications. To format your date/time values to
+ choice, use the to_char family of
+ functions.
+
+
+
SEED
@@ -237,10 +213,6 @@ SELECT setseed(value);
-
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
-
@@ -248,71 +220,13 @@ SELECT setseed(value);
SERVER_ENCODING
- Sets the multi-byte server encoding to:
-
-
-
- value
-
-
- The identifying value for the server encoding.
-
-
-
-
+ Sets the multi-byte server encoding.
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
-
-
-
-
-
- CONSTRAINTS
-
-
- SET CONSTRAINTS affects the behavior of constraint evaluation
- in the current transaction.
- SET CONSTRAINTS, specified
- in SQL3, has these allowed parameters:
-
-
-
- constraintlist
-
-
- Comma separated list of deferrable constraint names.
-
-
-
-
-
- mode
-
-
- The constraint mode. Allowed values are
- and .
-
-
-
-
-
-
-
- In mode, foreign key constraints
- are checked at the end of each query.
-
-
-
- In mode, foreign key constraints
- marked as are checked only at
- transaction commit or until its mode is explicitly set to
- .
- This is actually only done for foreign key
- constraints, so it does not apply to UNIQUE or other
- constraints.
+ This option is only available if
+ Postgres was built with multibyte
+ support.
@@ -323,8 +237,9 @@ SELECT setseed(value);
The possible values for timezone depends on your operating
- system. For example on Linux /usr/lib/zoneinfo contains the
- database of timezones.
+ system. For example, on Linux
+ /usr/share/zoneinfo contains the database
+ of time zones.
Here are some valid values for timezone:
@@ -334,7 +249,7 @@ SELECT setseed(value);
PST8PDT
- set the timezone for California
+ Set the time zone for California.
@@ -342,7 +257,7 @@ SELECT setseed(value);
Portugal
- set time zone for Portugal.
+ Set time zone for Portugal.
@@ -350,16 +265,17 @@ SELECT setseed(value);
'Europe/Rome'
- set time zone for Italy.
+ Set time zone for Italy.
- DEFAULT
+ LOCAL
+ DEFAULT
- set time zone to your local timezone
- (value of the TZ environment variable).
+ Set the time zone to your local time zone (the one that
+ your operating system defaults to).
@@ -369,12 +285,6 @@ SELECT setseed(value);
If an invalid time zone is specified, the time zone
becomes GMT (on most systems anyway).
-
- The second syntax shown above, allows one to set the timezone
- with a syntax similar to SQL92 SET TIME ZONE.
- The LOCAL keyword is just an alternate form
- of DEFAULT for SQL92 compatibility.
-
If the PGTZ environment variable is set in the frontend
environment of a client based on libpq, libpq will automatically
@@ -383,716 +293,112 @@ SELECT setseed(value);
-
- TRANSACTION ISOLATION LEVEL
-
-
- Sets the isolation level for the current transaction.
-
-
-
- READ COMMITTED
-
-
- The current transaction queries read only rows committed
- before a query began. READ COMMITTED is the default.
-
-
-
-
- SQL92 standard requires
- SERIALIZABLE to be the default isolation level.
-
-
-
-
-
-
- SERIALIZABLE
-
-
- The current transaction queries read only rows committed
- before first DML statement
- (SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO)
- was executed in this transaction.
-
-
-
-
-
-
-
-
-
- There are also several internal or optimization
- parameters which can be specified
- by the SET command:
-
-
-
- PG_OPTIONS
-
-
- Sets various backend parameters.
-
-
-
-
-
- RANDOM_PAGE_COST
-
-
- 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.
-
-
-
- float8
-
-
- Set the cost of a random page access
- to the specified floating-point value.
-
-
-
-
-
-
-
-
-
- CPU_TUPLE_COST
-
-
- 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.
-
-
-
- float8
-
-
- Set the cost of per-tuple CPU processing
- to the specified floating-point value.
-
-
-
-
-
-
-
-
-
- CPU_INDEX_TUPLE_COST
-
-
- 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.
-
-
-
- float8
-
-
- Set the cost of per-index-tuple CPU processing
- to the specified floating-point value.
-
-
-
-
-
-
-
-
-
- CPU_OPERATOR_COST
-
-
- 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.
-
-
-
- float8
-
-
- Set the cost of per-operator CPU processing
- to the specified floating-point value.
-
-
-
-
-
-
-
-
-
- EFFECTIVE_CACHE_SIZE
-
-
- 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.
-
-
-
- float8
-
-
- Set the assumed cache size
- to the specified floating-point value.
-
-
-
-
-
-
-
-
-
- EXAMINE_SUBCLASS
-
-
- 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.
-
-
- ON
-
-
- Returns SELECT to the behaviour of automatically returning
- results from sub-classes.
-
-
-
-
-
- OFF
-
-
- Prevents SELECT from returning sub-classes unless the "*" follows the table name
-
-
-
-
-
-
-
-
-
- ENABLE_SEQSCAN
-
-
- 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.)
-
-
-
- ON
-
-
- enables use of sequential scans (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of sequential scans.
-
-
-
-
-
-
-
-
-
- ENABLE_INDEXSCAN
-
-
- Enables or disables the planner's use of index scan plan types.
-
-
-
- ON
-
-
- enables use of index scans (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of index scans.
-
-
-
-
-
-
-
-
-
- ENABLE_TIDSCAN
-
-
- Enables or disables the planner's use of TID scan plan types.
-
-
-
- ON
-
-
- enables use of TID scans (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of TID scans.
-
-
-
-
-
-
-
-
-
- ENABLE_SORT
-
-
- 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.)
-
-
-
- ON
-
-
- enables use of sorts (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of sorts.
-
-
-
-
-
-
-
-
-
- ENABLE_NESTLOOP
-
-
- 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.)
-
-
-
- ON
-
-
- enables use of nested-loop joins (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of nested-loop joins.
-
-
-
-
-
-
-
-
-
- ENABLE_MERGEJOIN
-
-
- Enables or disables the planner's use of mergejoin plans.
-
-
-
- ON
-
-
- enables use of merge joins (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of merge joins.
-
-
-
-
-
-
-
-
-
- ENABLE_HASHJOIN
-
-
- Enables or disables the planner's use of hashjoin plans.
-
-
-
- ON
-
-
- enables use of hash joins (default setting).
-
-
-
-
-
- OFF
-
-
- disables use of hash joins.
-
-
-
-
-
-
-
-
-
- GEQO
-
-
- Sets the threshold for using the genetic optimizer algorithm.
-
-
-
- ON
-
-
- enables the genetic optimizer algorithm
- for statements with 11 or more tables.
- (This is also the DEFAULT setting.)
-
-
-
-
-
- ON=#
-
-
- Takes an integer argument to enable the genetic optimizer algorithm
- for statements with #
- or more tables in the query.
-
-
-
-
-
- OFF
-
-
- disables the genetic optimizer algorithm.
-
-
-
-
-
-
-
- See the chapter on GEQO in the Programmer's Guide
- for more information about query optimization.
-
-
- 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.
-
-
-
-
-
- KSQO
-
-
- Key Set Query Optimizer 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 MicroSoft
- Access, which tend to generate queries of this form.
-
-
-
- ON
-
-
- enables this optimization.
-
-
-
-
-
- OFF
-
-
- disables this optimization (default setting).
-
-
-
-
-
- DEFAULT
-
-
- Equivalent to specifying SET KSQO=OFF.
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
- MAX_EXPR_DEPTH
-
-
- 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.)
-
-
-
- integer
-
-
- Maximum depth.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 1998-09-24
-
-
- Outputs
-
-
-
-
-
-
-SET VARIABLE
-
-
-
- Message returned if successful.
-
-
-
-
-
-
-NOTICE: Bad value for variable (value)
-
-
-
- If the command fails to set the specified variable.
-
-
-
-
-
-
-
-
-
-
-
- 1998-09-24
-
-
- Description
-
- SET will modify configuration parameters for variable during
- a session.
+ An extended list of other run-time parameters can be found in the
+ Administrator's Guide.
+
- Current values can be obtained using SHOW, and values
- can be restored to the defaults using RESET.
- Parameters and values are case-insensitive. Note that the value
- field is always specified as a string, so is enclosed in
- single-quotes.
-
-
- SET TIME ZONE changes the session's
- default time zone offset.
- An SQL-session always begins with an initial default time zone
- offset.
- The SET TIME ZONE statement is used to change the default
- time zone offset for the current SQL session.
+ Use to show the
+ current setting of a parameters.
-
-
- 1998-09-24
-
-
- Notes
-
-
- The SET variable
- statement is a Postgres language extension.
-
-
- Refer to SHOW and RESET to
- display or reset the current values.
-
-
-
-
-
- Usage
-
+
+
+ Diagnostics
- Set the style of date to ISO (no quotes on the argument is required):
+
+
+
+ SET VARIABLE
+
+
+ Message returned if successful.
+
+
+
+
+
+ ERROR: not a valid option name: name
+
+
+ The parameter you tried to set does not exist.
+
+
+
+
+
+ ERROR: permission denied
+
+
+ You must be a superuser to have access to certain settings.
+
+
+
+
+
+ ERROR: name can only be set at startup
+
+
+ Some parameters are fixed once the server is started.
+
+
+
+
+
+
+
-
-SET DATESTYLE TO ISO;
-
-
- Enable GEQO for queries with 4 or more tables (note the use of
- single quotes to handle the equal sign inside the value argument):
-
-
-SET GEQO = 'ON=4';
-
-
- Set GEQO to default:
-
-
-SET GEQO = DEFAULT;
-
+
+
+ Examples
+
+ Set the style of date to traditional Postgres with European conventions:
+
+SET DATESTYLE TO Postgres,European;
+
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):
-
+
SET TIME ZONE "PST8PDT";
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------
1998-03-31 07:41:21-08
-
+
Set the timezone for Italy (note the required single or double quotes to handle
the special characters):
-
+
SET TIME ZONE 'Europe/Rome';
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------
1998-03-31 17:41:31+02
-
+
-
- Compatibility
-
-
-
-
- 1998-09-24
-
-
- SQL92
-
-
- There is no general
- SET variable
- in SQL92 (with the exception of
- SET TRANSACTION ISOLATION LEVEL).
+ Compatibility
- The SQL92 syntax for SET TIME ZONE
- is slightly different,
- allowing only a single integer value for time zone specification:
-
-
-SET TIME ZONE { interval_value_expression | LOCAL }
-
-
-
+
+ The second syntax shown above (SET TIME ZONE)
+ attempts to mimic SQL92. However, SQL allows
+ only numeric time zone offsets. All other parameter settings as
+ well as the first syntax shown above are a
+ Postgres extension.
+
diff --git a/doc/src/sgml/ref/set_constraints.sgml b/doc/src/sgml/ref/set_constraints.sgml
new file mode 100644
index 00000000000..3cdb5d67a21
--- /dev/null
+++ b/doc/src/sgml/ref/set_constraints.sgml
@@ -0,0 +1,53 @@
+
+
+
+ SET CONSTRAINTS
+ SQL - Language Statements
+
+
+ SET CONSTRAINTS
+ Set the constraint mode of the current SQL-transaction
+
+
+
+ 2000-06-01
+
+
+SET CONSTRAINTS { ALL | constraint [, ...] } { DEFERRED | IMMEDIATE }
+
+
+
+
+ Description
+
+
+ SET CONSTRAINTS sets the behavior of constraint
+ evaluation in the current transaction. In
+ mode, constraints are checked at the end
+ of each statement. In mode, constraints
+ are not checked until transaction commit.
+
+
+
+ Upon creation, a constraint is always give one of three
+ characteristics: ,
+ , or
+ . The third
+ class is not affected by the SET CONSTRAINTS
+ command.
+
+
+
+ Currently, only foreign key constraints are affected by this
+ setting. Check and unique constraints are always effectively
+ initially immediate not deferrable.
+
+
+
+
+ Compatibility
+
+ SQL92, SQL99
+
+
+
diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml
new file mode 100644
index 00000000000..e5de2e7f5b4
--- /dev/null
+++ b/doc/src/sgml/ref/set_transaction.sgml
@@ -0,0 +1,93 @@
+
+
+
+ SET TRANSACTION
+ SQL - Language Statements
+
+
+ SET TRANSACTION
+ Set the characteristics of the current SQL-transaction
+
+
+
+ 2000-06-01
+
+
+SET TRANSACTION ISOLATION LEVEL { READ COMMITTED | SERIALIZABLE }
+
+
+
+
+ Description
+
+
+ The SET TRANSACTION 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 (SELECT,
+ INSERT, DELETE,
+ UPDATE, FETCH,
+ COPY) of a transaction has been executed.
+
+
+
+ The isolation level of a transaction determines what data the
+ transaction can see when other transactions are running concurrently.
+
+
+
+ READ COMMITTED
+
+
+ A statement can only see rows committed before it began. This
+ is the default.
+
+
+
+
+
+ SERIALIZABLE
+
+
+ The current transaction can only see rows committed before
+ first DML statement was executed in this transaction.
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+ Compatibility
+
+
+ SQL92, SQL99
+
+
+
+ SERIALIZABLE is the default level in SQL.
+ Postgres does not provide the isolation levels and . Because
+ of multi-version concurrency control, the serializable level is not
+ truly serializable. See the User's Guide for
+ details.
+
+
+
+ In SQL 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.
+
+
+
+
diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml
index 7cacd634e7b..fdfc8057f63 100644
--- a/doc/src/sgml/ref/show.sgml
+++ b/doc/src/sgml/ref/show.sgml
@@ -1,48 +1,34 @@
-
- SHOW
-
+ SHOWSQL - Language Statements
-
- SHOW
-
-
- Shows run-time parameters for session
-
+ SHOW
+ Shows run-time parameters
-
- 1999-07-20
-
-SHOW keyword
+SHOW name
-
- 1998-09-24
-
-
- Inputs
-
+ Inputs
- keyword
+ name
- Refer to
+ The name of a run-time parameter. See
- for more information on available variables.
+ for a list.
@@ -50,41 +36,43 @@ SHOW keyword
-
-
- 1998-09-24
-
-
- Outputs
-
+
+
+
+ Description
+
+ SHOW will display the current setting of a
+ run-time parameter. These variables can be set using the
+ SET statement or are determined at server start.
+
+
+
+
+ Diagnostics
-
-NOTICE: variable is value
-
+ ERROR: not a valid option name: name
- Message returned if successful.
-
-
-
-
-
-NOTICE: Unrecognized variable value
-
-
-
- Message returned if variable does not exist.
+ Message returned if variable does
+ not stand for an existing parameter.
-
-NOTICE: Time zone is unknown
-
+ ERROR: permission denied
+
+
+ You must be a superuser to be allowed to see certain settings.
+
+
+
+
+
+ NOTICE: Time zone is unknown
If the TZ or PGTZ environment
@@ -94,82 +82,35 @@ NOTICE: Time zone is unknown
-
-
-
-
-
- 1998-09-24
-
-
- Description
-
-
- SHOW will display the current setting of a
- run-time parameter during a session.
-
-
- These variables can be set using the SET statement,
- and
- can be restored to the default values using the RESET
- statement.
- Parameters and values are case-insensitive.
-
-
-
-
- 1998-09-24
-
-
- Notes
-
-
- See also
- and
-
- to manipulate variable values.
-
-
-
- Usage
-
+ Examples
Show the current DateStyle setting:
-
+
SHOW DateStyle;
NOTICE: DateStyle is ISO with US (NonEuropean) conventions
-
+
Show the current genetic optimizer (geqo) setting:
-
+
SHOW GEQO;
-NOTICE: GEQO is ON beginning with 11 relations
-
+NOTICE: geqo = true
+
-
- Compatibility
-
+ Compatibility
-
-
- 1998-09-24
-
-
- SQL92
-
-
- There is no SHOW defined in SQL92.
-
-
+
+ The SHOW command is a
+ Postgres extension.
+
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index dbe984c7b3f..b92a1cc67b2 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,642 +1,1128 @@
-
- Runtime Environment
+
+ Server Runtime Environment
-
- This chapter outlines the interaction between Postgres and
- the operating system.
+
+ This chapter discusses how to set up and run the database server
+ and the interactions with the operating system.
+
+
+
+ The Postgres user account
+
+
+ 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 nobody 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.
-
- Using <Productname>Postgres</Productname> from Unix
+
+ To add a user account to your system, look for a command
+ useradd or adduser. The user
+ name postgres is often used but by no means
+ required.
+
+
+
+ Creating a database cluster
+
+
+ Before you can do anything, you must initialize a database storage
+ area on disk. We call this a database
+ cluster. (SQL 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 template1. As the
+ name suggests, this will be used as a template for any subsequently
+ created database; it should not be used for actual work.
+
+
+
+ In file system terms, a database cluster will be a single directory
+ under which all data will be stored. We call this the
+ data directory or data
+ area. It is completely up to you where you choose to
+ store your data, there is no default, although locations such as
+ /usr/local/pgsql/data or
+ /var/lib/pgsql/data are popular. To initialize
+ a database cluster, use the command initdb,
+ which is installed with PostgreSQL. The
+ desired file system location of your database system is indicated
+ by the option, for example
+
+> initdb -D /usr/local/pgsql/data
+
+ Note that you must execute this command while being logged in to
+ the Postgres user account, which is described in the previous
+ section.
+
+
+
- All Postgres commands that are executed
- directly from a Unix shell are
- found in the directory .../bin. Including this directory in
- your search path will make executing the commands easier.
+ As an alternative to the option, you can set
+ the environment variable PGDATA.
+
-
- A collection of system catalogs exist at each site. These include a
- class (pg_user) that contains an instance for each valid
- Postgres user. The instance specifies a set of
- Postgres privileges, such as
- the ability to act as Postgres super-user,
- the ability to create/destroy
- databases, and the ability to update the system catalogs. A Unix
- user cannot do anything with Postgres
- until an appropriate instance is
- installed in this class. Further information on the system catalogs
- is available by running queries on the appropriate classes.
-
-
+
+ initdb 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:
+
+root# mkdir /usr/local/pgsql/data
+root# chown postgres /usr/local/pgsql/data
+root# su postgres
+postgres> initdb -D /usr/local/pgsql/data
+
+
-
- Starting <Application>postmaster</Application>
+
+ initdb will refuse to run if the data directory
+ looks like it belongs to an already initialized installation.
+
-
- Nothing can happen to a database unless the
- postmaster
- process is running. As the site administrator, there
- are a number of things you should remember before
- starting the postmaster.
- These are discussed in the installation and configuration sections
- of this manual.
- However, if Postgres has been installed by following
- the installation instructions exactly as written, the
- following simple command is all you should
- need to start the postmaster:
+
+ Because the data directory contains all the data stored in the
+ database it is essential that it be well secured from unauthorized
+ access. initdb therefore revokes access
+ permissions from everyone but the Postgres user account.
+
+
-
-% postmaster
-
-
+
+ Starting the database server
-
- The postmaster occasionally prints out
- messages which
- are often helpful during troubleshooting. If you wish
- to view debugging messages from the postmaster,
- you can
- start it with the -d option and redirect the output to
- the log file:
+
+ Before anyone can access the database you must start the database
+ server. The database server is called
+ postmaster.
+ The postmaster must know where to find the data it is supposed
+ to work on. This is done with the option. Thus,
+ the simplest way to start the server is, for example,
+
+> postmaster -D /usr/local/pgsql/data
+
+ which will leave the server running in the foreground. This must
+ again be done while logged in to the Postgres user account. Without
+ a , the server will try to use the data
+ directory in the environment variable PGDATA; if
+ neither of these works it will fail.
+
-
-% postmaster -d > pm.log 2>&1 &
-
+
+ To start the postmaster in the
+ background, use the usual shell syntax:
+
+> postmaster -D /usr/local/pgsql/data > logfile 1>&2 &
+
+ 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.
+
- If you do not wish to see these messages, you can type
-
-% postmaster -S
-
- and the postmaster will be "S"ilent.
- No ampersand ("&") is required in this case, since the postmaster
- automatically detaches from the terminal when -S is specified.
-
-
+
+ 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.
+
-
- Using pg_options
+
+ Normally, you will want to start the database server when the
+ computer boots up. This is not required; the
+ PostgreSQL server can be run
+ successfully from non-privileged accounts without root
+ intervention.
+
-
-
-
- Contributed by Massimo Dal Zotto
-
-
-
-
- The optional file data/pg_options 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
- Postgres.
- The options specified in this file may be debugging flags used by the trace
- package (backend/utils/misc/trace.c) or numeric
- parameters which can be used by the backend to control its behaviour.
-
+
+ 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
+ /etc/rc.local or
+ /etc/rc.d/rc.local which is almost certainly
+ no bad place to put such a command. Whatever you do, postmaster
+ must be run by the Postgres user account
+ and not by root or any other user. Therefore
+ you probably always want to form your command lines along the lines
+ of su -c '...' postgres, for example:
+
+nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
+
+ (using the program nohup to prevent the
+ server from dying when you log out).
+
-
- 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.
-
-
- pg_options can also be specified with the switch of
- Postgres:
-
-
-postgres options -T "verbose=2,query,hostlookup-"
-
-
-
-
- The functions used for printing errors and debug messages can now make use
- of the syslog(2) facility. Message printed to stdout
- or stderr are prefixed by a timestamp containing also the backend pid:
-
-
-#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
-
-
-
- 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.
-
-
- 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 printf()
- 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.
-
-
-
- The format of the pg_options file is as follows:
-
-
-# comment
-option=integer_value # set value for option
-option # set option = 1
-option+ # set option = 1
-option- # set option = 0
-
-
- Note that keyword can also be
- an abbreviation of the option name defined in
- backend/utils/misc/trace.c.
-
-
- pg_options File
+
+ Here are a few more operating system specific suggestions.
+
+
- For example my pg_options file contains the following values:
-
-
-verbose=2
-query
-hostlookup
-showportnumber
-
+ Edit the file rc.local on
+ NetBSD or file
+ rc2.d on Solaris to contain the
+ following single line:
+
+su postgres -c "/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data"
+
-
+
+
+
+
+ On FreeBSD edit
+ /usr/local/etc/rc.d/pgsql.sh to contain the
+ following lines and make it chmod 755 and
+ chown root:bin.
+
+#!/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'
+}
+
+ 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.
+
+
+
+
+
+ On RedHat Linux add a file
+ /etc/rc.d/init.d/postgres.init
+ which is based on the example in contrib/linux/.
+ Then make a softlink to this file from
+ /etc/rc.d/rc5.d/S98postgres.init.
+
+
+
-
- Recognized Options
+
+ While the postmaster is running, it's
+ PID is in the file postmaster.pid 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.
+
-
- The options currently defined are:
+
+ The shell script wrapper pg_ctl that
+ comes with Postgres can also be used to
+ control starting (and stopping!) of the database server in
+ intelligent fashion.
+
-
-
-
- all
-
-
-
- Global trace flag. Allowed values are:
-
+
+ Server Startup Failures
-
-
-
- 0
-
-
-
- Trace messages enabled individually
-
-
-
+
+ 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.
+
-
-
- 1
-
-
-
- Enable all trace messages
-
-
-
-
-
-
- -1
-
-
-
- Disable all trace messages
-
-
-
+
+
+FATAL: StreamServerPort: bind() failed: Address already in use
+ Is another postmaster already running on that port?
+
+ 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
+
+> postmaster -i -p 666
+FATAL: StreamServerPort: bind() failed: Permission denied
+ Is another postmaster already running on that port?
+
+
-
-
-
+
+ A message like
+
+IpcMemoryCreate: shmget(5440001, 83918612, 01600) failed: Invalid argument
+FATAL 1: ShmemCreate: cannot create region
+
+ 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 ( 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.
+
-
-
- verbose
-
-
-
- Verbosity flag. Allowed values are:
-
+
+ An error like
+
+IpcSemaphoreCreate: semget(5440026, 16, 0600) failed: No space left on device
+
+ does not 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
+ ( switch), but you'll eventually want to
+ increase the kernel limit.
+
+
-
-
-
- 0
-
-
-
- No messages. This is the default.
-
-
-
+
+ Client Connection Problems
-
-
- 1
-
-
-
- Print information messages.
-
-
-
+
+ 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.
+
-
-
- 2
-
-
-
- Print more information messages.
-
-
-
+
+
+connectDB() -- connect() failed: Connection refused
+Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'?
+
+ This is the generic I couldn't find a server to talk
+ to failure. It looks like the above when TCP/IP
+ communication is attempted. A common mistake is to forget the
+ to the postmaster to allow TCP/IP
+ connections.
+
-
-
-
+
+ Alternatively, you'll get this when attempting
+ Unix-socket communication to a local postmaster:
+
+connectDB() -- connect() failed: No such file or directory
+Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'?
+
+
-
-
- query
-
-
-
- Query trace flag. Allowed values are:
-
-
-
-
-
- 0
-
-
-
- Don't print query.
-
-
-
-
-
-
- 1
-
-
-
- Print a condensed query in one line.
-
-
-
-
-
-
- 4
-
-
-
- Print the full query.
-
-
-
-
-
-
-
-
-
-
- plan
-
-
-
- Print query plan.
-
-
-
-
-
-
- parse
-
-
-
- Print parser output.
-
-
-
-
-
-
- rewritten
-
-
-
- Print rewritten query.
-
-
-
-
-
-
- pretty_plan
-
-
-
- Pretty-print query plan.
-
-
-
-
-
-
- pretty_parse
-
-
-
- Pretty-print parser output.
-
-
-
-
-
-
- pretty_rewritten
-
-
-
- Pretty-print rewritten query.
-
-
-
-
-
-
- parserstats
-
-
-
- Print parser statistics.
-
-
-
-
-
-
- plannerstats
-
-
-
- Print planner statistics.
-
-
-
-
-
-
- executorstats
-
-
-
- Print executor statistics.
-
-
-
-
-
-
- shortlocks
-
-
-
- Currently unused but needed to enable features in the future.
-
-
-
-
-
-
- locks
-
-
-
- Trace locks.
-
-
-
-
-
-
- userlocks
-
-
-
- Trace user locks.
-
-
-
-
-
-
- spinlocks
-
-
-
- Trace spin locks.
-
-
-
-
-
-
- notify
-
-
-
- Trace notify functions.
-
-
-
-
-
-
- malloc
-
-
-
- Currently unused.
-
-
-
-
-
-
- palloc
-
-
-
- Currently unused.
-
-
-
-
-
-
- lock_debug_oidmin
-
-
-
- Minimum relation oid traced by locks.
-
-
-
-
-
-
- lock_debug_relid
-
-
-
- oid, if not zero, of relation traced by locks.
-
-
-
-
-
-
- lock_read_priority
-
-
-
- Currently unused.
-
-
-
-
-
-
- deadlock_timeout
-
-
-
- Deadlock check timer.
-
-
-
-
-
-
- syslog
-
-
-
- syslog flag. Allowed values are:
-
-
-
-
-
- 0
-
-
-
- Messages to stdout/stderr.
-
-
-
-
-
-
- 1
-
-
-
- Messages to stdout/stderr and syslog.
-
-
-
-
-
-
- 2
-
-
-
- Messages only to syslog.
-
-
-
-
-
-
-
-
-
-
- hostlookup
-
-
-
- Enable hostname lookup in ps_status.
-
-
-
-
-
-
- showportnumber
-
-
-
- Show port number in ps_status.
-
-
-
-
-
-
- nofsync
-
-
-
- Disable fsync on a per-backend basis.
-
-
-
-
-
+
+ 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 not mean that the postmaster
+ got your connection request and rejected it -- that case will
+ produce a different message, as shown in .) Other error messages
+ such as Connection timed out may
+ indicate more fundamental problems, like lack of network
+ connectivity.
+
+ Run-time configuration
+
+
+ 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.
+
+
+
+ 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
+ ON, OFF,
+ TRUE, FALSE,
+ YES, NO,
+ 1, 0 (case-insensitive) or
+ any non-ambiguous prefix of these.
+
+
+
+ One way to set these options is to create a file
+ postgresql.conf in the data directory (e.g.,
+ /usr/local/pgsql/data). An example of how
+ this file could look like is this:
+
+# This is a comment
+log_connections = yes
+syslog = 2
+
+ 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 (#) introduce comments
+ anywhere.
+
+
+
+ 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.
+
+
+
+ A second way to set these configuration parameters is to give them
+ as a command line option to the postmaster, such as
+
+postmaster --log-connections=yes --syslog=2
+
+ which would have the same effect as the previous example.
+
+
+
+ Occasionally it is also useful to give a command line option to
+ one particular backend session only. The environment variable
+ PGOPTIONS can be used for this purpose on the
+ client side:
+
+env PGOPTIONS='--geqo=off' psql
+
+ (This works for any client application, not just
+ psql.) Note that this won't work for
+ options that are necessarily fixed once the server is started,
+ such as the port number.
+
+
+
+ Finally, some options can be changed in individual SQL sessions
+ with the SET command, for example
+
+=> SET ENABLE_SEQSCAN TO OFF;
+
+ See the SQL command language reference for details on the syntax.
+
+
+
+ Planner and Optimizer Tuning
+
+
+
+
+ CPU_INDEX_TUPLE_COST (floating point)
+
+
+ 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.
+
+
+
+
+
+ CPU_OPERATOR_COST (floating point)
+
+
+ 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.
+
+
+
+
+
+ CPU_TUPLE_COST (floating point)
+
+
+ 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.
+
+
+
+
+
+ EFFECTIVE_CACHE_SIZE (floating point)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_HASHJOIN (boolean)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_INDEXSCAN (boolean)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_MERGEJOIN (boolean)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_NESTLOOP (boolean)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_SEQSCAN (boolean)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_SORT (boolean)
+
+
+ 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.
+
+
+
+
+
+ ENABLE_TIDSCAN (boolean)
+
+
+ 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.
+
+
+
+
+
+ GEQO (boolean)
+
+
+ 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.
+
+
+
+
+
+ GEQO_EFFORT (integer)
+ GEQO_GENERATIONS (integer)
+ GEQO_POOL_SIZE (integer)
+ GEQO_RANDOM_SEED (integer)
+ GEQO_SELECTION_BIAS (floating point)
+
+
+ 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.
+
+
+
+
+
+ GEQO_RELS (integer)
+
+
+ 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.
+
+
+
+
+
+ KSQO (boolean)
+
+
+ The Key Set Query Optimizer
+ (KSQO) 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
+ Microsoft Access, which tend to
+ generate queries of this form.
+
+
+
+ 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. Hence the
+ default is OFF.
+
+
+
+
+
+ RANDOM_PAGE_COST (floating point)
+
+
+ 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.
+
+
+
+
+
+
+
+
+ Unfortunately, there is no well-defined method of determining
+ ideal values for the family of COST variables that
+ were just described. You are encouraged to experiment and share
+ your findings.
+
+
+
+
+
+
+ Logging and Debugging
+
+
+
+
+ DEBUG_LEVEL (integer)
+
+
+ The higher this value is set, the more
+ debugging 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.
+
+
+
+
+
+ DEBUG_PRINT_PARSE (boolean)
+ DEBUG_PRINT_PLAN (boolean)
+ DEBUG_PRINT_REWRITTEN (boolean)
+ DEBUG_PRINT_QUERY (boolean)
+ DEBUG_PRETTY_PRINT (boolean)
+
+
+ For any executed query, prints either the query, the parse
+ tree, the execution plan, or the query rewriter output to the
+ server log. selects are
+ nicer but longer output format.
+
+
+
+
+
+ HOSTLOOKUP (boolean)
+
+
+ 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.
+
+
+
+
+
+ LOG_CONNECTIONS (boolean)
+
+
+ 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.
+
+
+
+
+
+ LOG_PID (boolean)
+
+
+ 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.
+
+
+
+
+
+ LOG_TIMESTAMP (boolean)
+
+
+ Prefixes each server log message with a timestamp. The default
+ is off.
+
+
+
+
+
+ SHOW_QUERY_STATS (boolean)
+ SHOW_PARSER_STATS (boolean)
+ SHOW_PLANNER_STATS (boolean)
+ SHOW_EXECUTOR_STATS (boolean)
+
+
+ For each query, write performance statistics of the respective
+ module to the server log. This is a crude profiling
+ instrument.
+
+
+
+
+
+ SHOWPORTNUMBER (boolean)
+
+
+ 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.
+
+
+
+
+
+ SYSLOG (integer)
+
+
+ Postgres allows the use of
+ syslog 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.
+
+
+ To use syslog, the build of
+ Postgres must be configured with
+ the option.
+
+
+
+
+
+ TRACE_NOTIFY (boolean)
+
+
+ Generates a great amount of debugging output for the
+ LISTEN and NOTIFY
+ commands.
+
+
+
+
+
+
+
+
+ General operation
+
+
+
+
+ DEADLOCK_TIMEOUT (integer)
+
+
+ Postgres assumes that if
+ transactions are stuck for this many milliseconds then a
+ deadlock has occurred. Although it is technically possible to
+ detect deadlocks properly, 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.
+
+
+
+
+
+ FSYNC (boolean)
+
+
+ When this is on (default), an fsync()
+ 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
+ Postgres itself is not affected.)
+
+
+
+
+
+ MAX_BACKENDS (integer)
+
+
+ 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.
+
+
+
+
+
+ MAX_EXPR_DEPTH (integer)
+
+
+ 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.)
+
+
+
+
+
+ NET_SERVER (boolean)
+
+
+ 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.
+
+
+
+
+
+ PORT (integer)
+
+
+ The TCP port the server listens on; 5432 by default. This
+ option can only be set at server start.
+
+
+
+
+
+ SHMEM_BUFFERS (integer)
+
+
+ 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.
+
+
+
+
+
+ SORT_MEM (integer)
+
+
+ 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.
+
+
+
+
+
+
+
+
+ Short options
+
+ For convenience there are also single letter option switches
+ available for many parameters. They are described in the following
+ table.
+
+
+ Short option key
+
+
+
+
+ Short option
+ Equivalent
+ Remark
+
+
+
+
+ -B x
+ shmem_buffers = x
+
+
+
+ -d x
+ debug_level = x
+
+
+
+ -F
+ fsync = off
+
+
+
+ -i
+ net_server = on
+
+
+
+ -N x
+ max_backends = x
+
+
+
+ -p x
+ port = x
+
+
+
+
+ -fi, -fh, -fm, -fn, -fs, -ft
+ enable_indexscan=off, enable_hashjoin=off,
+ enable_mergejoin=off, enable_nestloop=off, enable_seqscan=off,
+ enable_tidscan=off
+ *
+
+
+ -S x
+ sort_mem = x
+ *
+
+
+ -s
+ show_query_stats = on
+ *
+
+
+ -tpa, -tpl, -te
+ show_parser_stats=on, show_planner_stats=on, show_executor_stats=on
+ *
+
+
+
+
+ For historical reasons, options marked * must be
+ passed to the individual backend process via the
+ postmaster option, for example,
+
+> postmaster -o '-S 1024 -s'
+
+ or via PGOPTIONS from the client side, as explained
+ above.
+
+
+
+
+
+
+ Shutting down the server
+
+
+ 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.
+
+
+ SIGTERM
+
+
+ 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 Smart Shutdown.
+
+
+
+
+
+ SIGINT
+
+
+ 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 Fast Shutdown.
+
+
+
+
+
+ SIGQUIT
+
+
+ This is the Immediate Shutdown 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.
+
+
+
+
+
+
+
+ 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.
+
+
+
+ The PID of the postmaster process can be found using the
+ ps program, or from the file
+ postmaster.pid in the data directory. So for
+ example, to do a fast shutdown:
+
+> kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
+
+
+
+ The program pg_ctl is a shell script
+ wrapper that provides a convenient interface to these functions.
+
+
+
+
+ Secure TCP/IP Connection with SSH
+
+
+ Acknowledgement
+
+ Idea taken from an email by Gene Selkov, Jr.
+ (selkovjr@mcs.anl.gov) written on 1999-09-08 in response
+ to a question from Eric Marsden.
+
+
+
+
+ One can use ssh to encrypt the network
+ connection between clients and a
+ Postgres server. Done properly, this
+ should lead to an adequately secure network connection.
+
+
+
+ First make sure that an ssh server is
+ running properly on the same machine as
+ Postgres 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:
+
+> ssh -L 3333:foo.com:5432 joe@foo.com
+
+ The first number in the 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:
+
+psql -h localhost -p 3333 template1
+
+ To the database server it will then look as though you are really
+ user joe@foo.com 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.
+
+
+
+
-
-
- Security
-
-
- Database security is addressed at several levels:
-
-
-
-
- Data base file protection. All files stored within the database
- are protected from reading by any account other than the
- Postgres superuser account.
-
-
-
-
- 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
- -i option to allow non-local clients to connect.
-
-
-
-
- Client connections can be restricted by IP address and/or user
- name via the pg_hba.conf file in PG_DATA.
-
-
-
-
- Client connections may be authenticated via other external packages.
-
-
-
-
- Each user in Postgres is assigned a
- username and (optionally) a password. By default, users do not
- have write access to databases they did not create.
-
-
-
-
- Users may be assigned to groups, and
- table access may be restricted based on group privileges.
-
-
-
-
-
-
- User Authentication
-
-
- Authentication
- is the process by which the backend server and
- postmaster
- ensure that the user requesting access to data is in fact who he/she
- claims to be.
- All users who invoke Postgres are checked against the
- contents of the pg_user 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:
-
-
-
-
- From the user shell
-
-
-
- A backend server started from a user shell notes the user's (effective)
- user-id before performing a
- setuid
- to the user-id of user postgres.
- The effective user-id is used
- as the basis for access control checks. No other authentication is
- conducted.
-
-
-
-
-
-
- From the network
-
-
-
- If the Postgres system is built as distributed,
- access to the Internet TCP port of the
- postmaster
- 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 pg_hba.conf(5)
- 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 Postgres.
-
-
-
-
-
-
-
- Host-Based Access Control
-
-
- Host-based access control
- 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.
-
-
-
- Each database system contains a file named
- pg_hba.conf, in its PGDATA
- directory, which controls who can connect to each database.
-
-
-
- Every client accessing a database
- must
- be covered by one of
- the entries in pg_hba.conf.
- Otherwise all attempted connections from that
- client will be rejected with a "User authentication failed" error
- message.
-
-
-
- The general format of the pg_hba.conf
- 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.
-
-
-
- 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:
-
-
-local databaseauthentication method
-
-
- where
-
-
-
- database
- specifies the database that this record applies to. The value
- all
- specifies that it applies to all databases.
-
-
- authentication method
- 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.
-
-
-
-
-
- Connections made using Internet domain sockets are controlled using records
- of the following format.
-
-
-host databaseTCP/IP addressTCP/IP maskauthentication method
-
-
-
-
- The TCP/IP address
- is logically anded to both the specified
- TCP/IP mask
- 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
- TCP/IP address
- and the
- TCP/IP mask
- are specified in dotted decimal notation.
-
-
-
- If a connection fails to match any record then the
- reject
- authentication method is applied (see below).
-
-
-
- Authentication Methods
-
-
- The following authentication methods are supported for both Unix and TCP/IP
- domain sockets:
-
-
-
- trust
-
-
- The connection is allowed unconditionally.
-
-
-
-
-
- reject
-
-
- The connection is rejected unconditionally.
-
-
-
-
-
- crypt
-
-
- The client is asked for a password for the user. This is sent encrypted
- (using crypt(3))
- and compared against the password held in the
- pg_shadow table.
- If the passwords match, the connection is allowed.
-
-
-
-
-
- password
-
-
- The client is asked for a password for the user. This is sent in clear
- and compared against the password held in the
- pg_shadow table.
- If the passwords match, the connection is allowed. An optional password file
- may be specified after the
- password
- keyword which is used to match the supplied password rather than the pg_shadow
- table. See
- pg_passwd.
-
-
-
-
-
-
-
- The following authentication methods are supported for TCP/IP
- domain sockets only:
-
-
-
- krb4
-
-
- Kerberos V4 is used to authenticate the user.
-
-
-
-
-
- krb5
-
-
- Kerberos V5 is used to authenticate the user.
-
-
-
-
-
- ident
-
-
- The ident server on the client is used to authenticate the user (RFC 1413).
- An optional map name may be specified after the
- ident
- keyword which allows ident user names to be mapped onto
- Postgres user names.
- Maps are held in the file
- $PGDATA/pg_ident.conf.
-
-
-
-
-
-
-
-
- Examples
-
-
-
-# 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
-
-
-
-
-
-
-
- User Names and Groups
-
-
- To define a new user, run the
- createuser utility program.
-
-
-
- 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
- Postgres these steps are not currently
- supported with a create group command. Instead,
- the groups are defined by inserting appropriate values into the
- pg_group system table, and then using the
- grant command to assign privileges to the
- group.
-
-
-
- Creating Users
-
-
-
-
-
-
- Creating Groups
-
-
- Currently, there is no easy interface to set up user groups. You
- have to explicitly insert/update the pg_group table.
- For example:
-
-
-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=>
-
-
-
-
- The fields in pg_group are:
-
-
-
- groname
-
-
- The group name. This a name and should be purely
- alphanumeric. Do not include underscores or other punctuation.
-
-
-
-
-
- grosysid
-
-
- The group id. This is an int4. This should be unique for
- each group.
-
-
-
-
-
- grolist
-
-
- The list of pg_user id's that belong in the group. This
- is an int4[].
-
-
-
-
-
-
-
-
- Assigning Users to Groups
-
-
-
-
-
-
-
-
- Access Control
-
-
- Postgres provides mechanisms to allow users
- to limit the access to their data that is provided to other users.
-
-
-
-
- Database superusers
-
-
-
- Database super-users (i.e., users who have pg_user.usesuper
- 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 pg_user.usecatupd set, and destruction of
- system catalogs (or modification of their schemas) is never allowed.
-
-
-
-
-
-
- Access Privilege
-
-
-
- The use of access privilege to limit reading, writing and setting
- of rules on classes is covered in
- grant/revoke(l).
-
-
-
-
-
-
- Class removal and schema modification
-
-
-
- Commands that destroy or modify the structure of an existing class,
- such as alter,
- drop table,
- and
- drop index,
- only operate for the owner of the class. As mentioned above, these
- operations are never
- permitted on system catalogs.
-
-
-
-
-
-
-
-
- Functions and Rules
-
-
- 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 trojan horse
- 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
- pg_class, pg_user
- and pg_group are also recommended.
-
-
-
- Functions
-
-
- Functions written in any language except SQL
- run inside the backend server
- process with the permissions of the user postgres (the
- backend server runs with its real and effective user-id set to
- postgres. 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.
-
-
-
-
- Rules
-
-
- Like SQL functions, rules always run with the identity and
- permissions of the user who invoked the backend server.
-
-
-
-
- Caveats
-
-
- There are no plans to explicitly support encrypted data inside of
- Postgres
- (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.
-
-
- User names, group names and associated system identifiers (e.g., the
- contents of pg_user.usesysid) are assumed to be unique
- throughout a database. Unpredictable results may occur if they are
- not.
-
-
-
-
-
- Secure TCP/IP Connection
-
-
-
- Author
-
- From e-mail by
- Gene Selkov, Jr.
- written on 1999-09-08 in response to a
- question from Eric Marsden.
-
-
-
-
-
- One can use ssh to encrypt the network
- connection between clients and a
- Postgres server. Done properly, this
- should lead to an adequately secure network connection.
-
-
-
- The documentation for ssh provides most
- of the information to get started.
- Please refer to
- http://www.heimhardt.de/htdocs/ssh.html
- for better insight.
-
-
-
- A step-by-step explanation can be done in just two steps.
-
-
-
- Running a secure tunnel via ssh
-
-
- A step-by-step explanation can be done in just two steps.
-
-
-
-
- Establish a tunnel to the backend machine, like this:
-
-
-ssh -L 3333:wit.mcs.anl.gov:5432 postgres@wit.mcs.anl.gov
-
-
- 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.
-
-
-
-
-
- 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
- psql, you will need another shell
- because the shell session you used in
- is now occupied with
- ssh.
-
-
-psql -h localhost -p 3333 -d mpw
-
-
- Note that you have to specify the 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.
-
-
-
-
-
-
-
diff --git a/doc/src/sgml/signals.sgml b/doc/src/sgml/signals.sgml
deleted file mode 100644
index 7f7e597e0b8..00000000000
--- a/doc/src/sgml/signals.sgml
+++ /dev/null
@@ -1,266 +0,0 @@
-
-
-
-
-Massimo
-Dal Zotto
-
-
-Transcribed 1998-10-16
-
-
-<productname>Postgres</productname> Signals
-
-
-
-
-Contributed by Massimo Dal Zotto
-
-
-
-
-
-Postgres uses the following signals for
- communication between the postmaster and backends:
-
-
-
-
-
-
-
-"kill(*,signal)" means sending a signal to all backends.
-
-
-
-
-
-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.
-
-
-
-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.
-
-
-
-The typical use of signals by programmers could be the following:
-
-
-# stop postgres
-kill -TERM $postmaster_pid
-
-
-
-# kill all the backends
-kill -QUIT $postmaster_pid
-
-
-
-# kill only the postmaster
-kill -INT $postmaster_pid
-
-
-
-# change pg_options
-cat new_pg_options > $DATA_DIR/pg_options
-kill -HUP $postmaster_pid
-
-
-
-# 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
-
-
-
-
-
diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml
index 0e6bd867c30..939100ff541 100644
--- a/doc/src/sgml/start-ag.sgml
+++ b/doc/src/sgml/start-ag.sgml
@@ -1,28 +1,10 @@
-
- Adding and Deleting Users
-
-
- createuser enables specific users to access
- Postgres.
- dropuser removes users and
- prevents them from accessing Postgres.
-
-
-
- These commands only affect users with respect to
- Postgres;
- they have no effect on a user's other privileges or status with regards
- to the underlying operating system.
-
-
-
Disk Management
diff --git a/doc/src/sgml/trouble.sgml b/doc/src/sgml/trouble.sgml
deleted file mode 100644
index 3e3d9622413..00000000000
--- a/doc/src/sgml/trouble.sgml
+++ /dev/null
@@ -1,289 +0,0 @@
-
-
-
- Troubleshooting
-
-
- Postmaster Startup Failures
-
-
- 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:
-
-
-
-
-FATAL: StreamServerPort: bind() failed: Address already in use
- Is another postmaster already running on that port?
-
- 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
-
-$ postmaster -i -p 666
-FATAL: StreamServerPort: bind() failed: Permission denied
- Is another postmaster already running on that port?
-
-
-
-
-
-IpcMemoryCreate: shmget failed (Invalid argument) key=5440001, size=83918612, permission=600
-FATAL 1: ShmemCreate: cannot create region
-
- 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.
-
-
-
-
-IpcSemaphoreCreate: semget failed (No space left on device) key=5440026, num=16, permission=600
-
- A message like this does not 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.
-
-
-
-
-
- Client Connection Problems
-
-
- 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.
-
-
-
-
-connectDB() -- connect() failed: Connection refused
-Is the postmaster running (with -i) at 'server.joe.com' and accepting connections on TCP/IP port '5432'?
-
- 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:
-
-connectDB() -- connect() failed: No such file or directory
-Is the postmaster running at 'localhost' and accepting connections on Unix socket '5432'?
-
- 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 not 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.
-
-
-
-
-No pg_hba.conf entry for host 123.123.123.123, user joeblow, database testdb
-
- 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.
-
-
-
-
-Password authentication failed for user 'joeblow'
-
- 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.
-
-
-
-
-FATAL 1: SetUserId: user 'joeblow' is not in 'pg_shadow'
-
- This is another variant of authentication failure: no Postgres create_user
- command has been executed for the given username.
-
-
-
-
-FATAL 1: Database testdb does not exist in pg_database
-
- 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.
-
-
-
-
-NOTICE: Unrecognized variable client_encoding
-
- 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.
-
-
-
-
-
- Debugging Messages
-
-
- The postmaster occasionally prints out
- messages which
- are often helpful during troubleshooting. If you wish
- to view debugging messages from the postmaster,
- you can
- start it with the -d option and redirect the output to
- the log file:
-
-
-% postmaster -d > pm.log 2>&1 &
-
-
- If you do not wish to see these messages, you can type
-
-% postmaster -S
-
- and the postmaster will be "S"ilent.
- No ampersand ("&") is required in this case, since the postmaster
- automatically detaches from the terminal when -S is specified.
-
-
-
- pg_options
-
-
-
-
- Contributed by Massimo Dal Zotto
-
-
-
-
- The optional file data/pg_options 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
- Postgres.
- The options specified in this file may be debugging flags used by the trace
- package (backend/utils/misc/trace.c) or numeric
- parameters which can be used by the backend to control its behaviour.
- New options and parameters must be defined in
- backend/utils/misc/trace.c and
- backend/include/utils/trace.h.
-
-
-
- pg_options can also be specified with the switch of
- Postgres:
-
-
-postgres options -T "verbose=2,query,hostlookup-"
-
-
-
-
- The functions used for printing errors and debug messages can now make use
- of the syslog(2) facility. Message printed to stdout
- or stderr are prefixed by a timestamp containing also the backend pid:
-
-
-#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
-
-
-
-
- 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.
-
-
-
- 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 printf()
- 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.
-
-
-
- The format of the pg_options file is as follows:
-
-
-# comment
-option=integer_value # set value for option
-option # set option = 1
-option+ # set option = 1
-option- # set option = 0
-
-
- Note that keyword can also be
- an abbreviation of the option name defined in
- backend/utils/misc/trace.c.
-
-
-
- Refer to
- for a complete list of option keywords and possible values.
-
-
-
-
-
-
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
new file mode 100644
index 00000000000..255b5f9801a
--- /dev/null
+++ b/doc/src/sgml/user-manag.sgml
@@ -0,0 +1,202 @@
+
+ Database User and Permission Management
+
+
+ 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.
+
+
+
+ Database Users
+
+
+ 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 CREATE
+ USER SQL command:
+
+CREATE USER name
+
+ name follows the rules for SQL
+ identifiers: either unadorned without special characters, or
+ double-quoted. To remove an existing user, use the analog
+ DROP USER command.
+
+
+
+ For convenience, the shell scripts createuser
+ and dropuser are wrappers around these SQL
+ commands.
+
+
+
+ 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 postgres
+ exists. In order to create more users you have to first connect as
+ this initial user.
+
+
+
+ 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
+ psql program uses the
+ 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
+ . (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.)
+
+
+
+ User attributes
+
+
+ A database user may have a number of attributes that define its
+ privileges and interact with the client authentication system.
+
+
+
+ superuser
+
+
+ A database superuser bypasses all permission checks. Also,
+ only a superuser can create new users. To create a database
+ superuser, use CREATE USER name
+ CREATEUSER.
+
+
+
+
+
+ database creation
+
+
+ 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 CREATE USER name
+ CREATEDB.
+
+
+
+
+
+ password
+
+
+ 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 CREATE USER name WITH PASSWORD
+ 'string'.
+
+
+
+
+
+ See the reference pages for CREATE USER and
+ ALTER USER for details.
+
+
+
+
+
+ Groups
+
+
+ As in Unix, groups are a way of logically grouping users. To create
+ a group, use
+
+CREATE GROUP name
+
+ To add users to or remove users from a group, respectively, user
+
+ALTER GROUP name ADD USER uname1, ...
+ALTER GROUP name DROP USER uname1, ...
+
+
+
+
+
+ Privileges
+
+
+ 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,
+ privileges must be granted.
+
+
+
+ Currently, there are four different privileges: select (read),
+ insert (append), and update/delete (write), as well as
+ RULE, 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
+ GRANT command is used. So, if
+ joe is an existing user, and
+ accounts is an existing table, write access can
+ be granted with
+
+GRANT UPDATE ON accounts TO joe;
+
+ The user executing this command must be the owner of the table. To
+ grant a privilege to a group, use
+
+GRANT SELECT ON accounts TO GROUP staff;
+
+ The special user name PUBLIC can
+ be used to grant a privilege to every user on the system. Using
+ ALL in place of a privilege specifies that all
+ privileges will be granted.
+
+
+
+ To revoke a privilege, use the fittingly named
+ REVOKE command:
+
+REVOKE ALL ON accounts FROM PUBLIC;
+
+ The set of privileges held by the table owner is always implicit
+ and is never revokable.
+
+
+
+
+ Functions and Triggers
+
+
+ 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 trojan horse
+ 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 pg_class,
+ pg_user and pg_group are also
+ possible.
+
+
+
+ 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.
+
+
+
+
+