+ linkend="sql-set-title" endterm="sql-set-title"> for a list.
- to its default value.
- default values.
- for details on allowed values and defaults.
- to manipulate variable values.
-
- SET
-
+ SET
SQL - 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
-
-
</div>
<div class="diff rem">- Inputs</div>
<div class="diff rem">-
+
Inputs
-
variable
- Settable global parameter.
+ A settable run-time parameter.
+
- 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.
-
-
-
-
-
-
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
-
-
-
-
-
- DATESTYLE
-
- Set the date/time representation style. Affects the output format,
- and in some cases it can affect the interpretation of input.
-
-
-
- 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 )
-
-
-
-
-
-
- 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 -o -e 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
-
-
-
-
-
-
-
- SEED
-
- Sets the internal seed for the random number generator.
-
-
-
- value
-
- The value for the seed to be used by the
- random catalog function. Significant
- values are floating point numbers between 0 and 1, which
- are then multiplied by RAND_MAX. This product will
- silently overflow if a number outside the range is used.
-
-
- The seed can also be set by invoking the
- setseed SQL function:
-
-SELECT setseed(value );
-
-
-
-
-
-
-
- This option is only available if MULTIBYTE support was enabled
- during the configure step of building Postgres.
-
-
-
-
-
- SERVER_ENCODING
-
- Sets the multi-byte server encoding to:
-
-
-
- value
-
- The identifying value for the 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
- DEFERRED and IMMEDIATE .
-
-
-
-
-
-
- In IMMEDIATE mode, foreign key constraints
- are checked at the end of each query.
-
-
- In DEFERRED mode, foreign key constraints
- marked as DEFERRABLE are checked only at
- transaction commit or until its mode is explicitly set to
- IMMEDIATE .
- This is actually only done for foreign key
- constraints, so it does not apply to UNIQUE or other
- constraints.
-
-
-
-
-
- TIME ZONE
- TIMEZONE
-
- The possible values for timezone depends on your operating
- system. For example on Linux /usr/lib/zoneinfo contains the
- database of timezones.
-
- Here are some valid values for timezone:
-
-
-
- PST8PDT
-
- set the timezone for California
-
-
-
-
- Portugal
-
- set time zone for Portugal.
-
-
-
-
- 'Europe/Rome'
-
- set time zone for Italy.
-
-
-
-
- DEFAULT
-
- set time zone to your local timezone
- (value of the TZ environment variable).
-
-
-
-
-
- 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
- set TIMEZONE to the value of PGTZ during connection startup.
-
-
-
-
-
- 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
-
-
-
-
-
-
-
+
+
+
+
Description
+ The SET command changes run-time configuration
+ parameters. The following parameters can be altered:
+
+
+
+ CLIENT_ENCODING
+ NAMES
+
+ Sets the multi-byte client encoding. The specified encoding
+ must be supported by the backend.
+
+
+ This option is only available if
+
Postgres is build with multibyte
+ support.
+
+
+
+
+
+ DATESTYLE
+
+ Choose the date/time representation style. Two separate
+ settings are made: the default date/time output and the
+ interpretation of ambiguous input.
+
+
+ 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 -o -e to
+ set dates to the European convention.
+
+
+
+ The DateStyle option is really only intended
+ for porting applications. To format your date/time values to
+ choice, use the to_char family of
+ functions.
+
+
+
- ENABLE_SEQSCAN
+ SEED
- 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).
-
-
-
+ Sets the internal seed for the random number generator.
-
- 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
+ value
- disables use of index scans.
+ The value for the seed to be used by the
+ random catalog function. Significant
+ values are floating point numbers between 0 and 1, which
+ are then multiplied by RAND_MAX. This product will
+ silently overflow if a number outside the range is used.
-
-
-
-
-
-
-
-
- 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.)
+ The seed can also be set by invoking the
+ setseed SQL function:
-
-
- ON
-
- enables use of sorts (default setting).
-
-
-
-
-
- OFF
-
- disables use of sorts.
+SELECT setseed(value );
+
+
- ENABLE_NESTLOOP
+ SERVER_ENCODING
- 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.
-
-
-
-
+ Sets the multi-byte server encoding.
-
-
-
- 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.
-
-
-
-
+ This option is only available if
+
Postgres was built with multibyte
+ support.
- ENABLE_HASHJOIN
+ TIME ZONE
+ TIMEZONE
- Enables or disables the planner's use of hashjoin plans.
-
-
-
- ON
-
- enables use of hash joins (default setting).
-
-
-
-
-
- OFF
-
- disables use of hash joins.
-
-
-
-
+ The possible values for timezone depends on your operating
+ system. For example, on Linux
+ /usr/share/zoneinfo contains the database
+ of time zones.
-
-
-
-
- GEQO
-
- Sets the threshold for using the genetic optimizer algorithm.
-
+ Here are some valid values for timezone:
+
- 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
+ PST8PDT
- disables the genetic optimizer algorithm .
+ Set the time zone for California .
-
-
-
- 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
+ Portugal
- enables this optimization .
+ Set time zone for Portugal .
-
- OFF
+ 'Europe/Rome'
- disables this optimization (default setting) .
+ Set time zone for Italy .
-
- DEFAULT
+ LOCAL
+ DEFAULT
- Equivalent to specifying SET KSQO=OFF .
+ Set the time zone to your local time zone (the one that
+ your operating system defaults to).
-
- The KSQO algorithm used to be absolutely essential for queries
- with many OR'ed AND clauses, but in Postgres 7.0 and later
- the standard planner handles these queries fairly successfully.
+ If an invalid time zone is specified, the time zone
+ becomes GMT (on most systems anyway).
-
-
-
-
- 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.
-
-
-
-
+ If the PGTZ environment variable is set in the frontend
+ environment of a client based on libpq, libpq will automatically
+ set TIMEZONE to the value of PGTZ during connection startup.
-
-
-
- 1998-09-24
-
-
</div>
<div class="diff rem">- Outputs</div>
<div class="diff rem">-
-
-
-
-
-SET VARIABLE
-
-
- Message returned if successful.
-
-
-
-
-
-
-NOTICE: Bad value for variable (value)
-
-
- If the command fails to set the specified variable.
-
-
-
-
-
-
-
-
-
-
-
- 1998-09-24
-
-
</div>
<div class="diff rem">- Description</div>
<div class="diff rem">-
- 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.
+ Use to show the
+ current setting of a parameters.
+
+
+
+
+
Diagnostics
- 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.
+
+
+
+ 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.
+
+
+
+
+
-
-
-
- 1998-09-24
-
-
</div>
<div class="diff rem">- Notes</div>
<div class="diff rem">-
- The SET variable
- statement is a
Postgres language extension.
-
- Refer to SHOW and RESET to
- display or reset the current values.
-
-
+
-
-
</div>
<div class="diff rem">- Usage</div>
<div class="diff rem">-
+
+
Examples
- Set the style of date to ISO (no quotes on the argument is required):
-
-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;
-
+ 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) :
-<programlisting >
+<screen >
SET TIME ZONE "PST8PDT";
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------
1998-03-31 07:41:21-08
-programlisting>
+screen>
Set the timezone for Italy (note the required single or double quotes to handle
the special characters):
-<programlisting >
+<screen >
SET TIME ZONE 'Europe/Rome';
SELECT CURRENT_TIMESTAMP AS today;
today
------------------------
1998-03-31 17:41:31+02
-programlisting>
+screen>
-
</div>
<div class="diff rem">- Compatibility</div>
<div class="diff rem">-
-
-
-
- 1998-09-24
-
-
</div>
<div class="diff rem">- SQL92</div>
<div class="diff rem">-
- 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
+
-
-
Runtime Environment
+
+
Server Runtime Environment
+
+ 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.
+
- This chapter outlines the interaction between
Postgres and
- the operating system.
+ 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.
-
-
Using <Productname>Postgres</Productname> from Unix
+ 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 -D 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 -D option, you can set
+ the environment variable PGDATA .
+
+
+ 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
+
+
- 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 refuse to run if the data directory
+ looks like it belongs to an already initialized installation.
+
+
+ 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.
+
+
+
+
+
Starting the database server
+
+ 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 -D 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 -D , the server will try to use the data
+ directory in the environment variable PGDATA ; if
+ neither of these works it will fail.
+
+
+ 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.
+
+
+ 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 -i option.
+
+
+ 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.
+
+
+ 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).
+
+
+ Here are a few more operating system specific suggestions.
+
+
+
+ Edit the file rc.local on
+
rc2.d on
Solaris to contain the
+ following single line:
+su postgres -c "/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data"
+
+
+
+
+
+ /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 .
+
+
+
-
-
-
Starting <Application>postmaster</Application>
-
- Nothing can happen to a database unless the
- 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 :
-
-% postmaster
-
+ 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
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.
-
+ 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.
+
+
+
+
Server 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?
+
+
+
+ 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 (-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.
+
+
+ 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
+ (-N switch), but you'll eventually want to
+ increase the kernel limit.
+
+
+
+
+
Client Connection Problems
+
+ 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.
+
+
+
+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
+ -i 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'?
+
+
+
+ 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
+ linkend="client-authentication-problems">.) Other error messages
+ such as Connection timed out may
+ indicate more fundamental problems, like lack of network
+ connectivity.
+
+
- pg-options">
- id="pg-options-title">Using pg_options
+ runtime-config">
+ >Run-time configuration
-
- 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
- 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.
+ 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 pg_options are initialized to zero at backend startup.
- New or modified options will be read by all new backends when they are started.
- To make effective any changes for all running backends we need to send a
- SIGHUP to the postmaster. The signal will be automatically sent to all the
- backends. We can also activate the changes only for a specific backend by
- sending the SIGHUP directly to it.
+ All parameter names are case-insensitive. Every parameter takes a
+ value of one of the four types boolean, integer, floating point,
+ string as described below. Boolean values are
+ ON , OFF ,
+ TRUE , FALSE ,
+ YES , NO ,
+ 1 , 0 (case-insensitive) or
+ any non-ambiguous prefix of these.
- pg_options can also be specified with the -T switch of
-postgres options -T "verbose=2,query,hostlookup-"
-
+ 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 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.
+ 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.
- 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
-
- For example my pg_options file contains the following values:
-
-verbose=2
-query
-hostlookup
-showportnumber
-
-
-
+ 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.
-
-
Recognized Options
-
- The options currently defined are:
-
-
-
-
- all
-
-
- Global trace flag. Allowed values are:
-
-
-
-
-
- 0
-
-
- Trace messages enabled individually
-
-
-
-
-
-
- 1
-
-
- Enable all trace messages
-
-
-
-
-
-
- -1
-
-
- Disable all trace messages
-
-
-
-
-
-
-
-
-
-
- verbose
-
-
- Verbosity flag. Allowed values are:
-
-
-
-
-
- 0
-
-
- No messages. This is the default.
-
-
-
+ 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.
+
-
-
- 1
-
-
- Print information messages.
-
-
-
+ 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.
+
-
-
- 2
-
-
- Print more information messages.
-
-
-
+
+
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.
+
-
+
-
- query
-
+ CPU_OPERATOR_COST (floating point )
- Query trace flag. Allowed values are:
+ Sets the optimizer's estimate of the cost of processing each
+ operator in a WHERE clause. This is measured as a fraction of
+ the cost of a sequential page fetch.
+
+
+
+
+ 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.
+
+
+
-
-
-
- 0
-
-
- Don't print query.
-
-
-
-
-
-
- 1
-
-
- Print a condensed query in one line.
-
-
-
-
-
-
- 4
-
-
- Print the full query.
-
-
-
-
-
+
+ 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.
+
-
- plan
-
+ ENABLE_INDEXSCAN (boolean )
- Print query plan.
+ Enables or disables the query planner's use of index scan plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
-
- parse
-
+ ENABLE_MERGEJOIN (boolean )
- Print parser output.
+ Enables or disables the query planner's use of merge-join plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
-
- rewritten
-
+ ENABLE_NESTLOOP (boolean )
- Print rewritten query.
+ Enables or disables the query planner's use of nested-loop
+ join plans. It's not possible to suppress nested-loop joins
+ entirely, but turning this variable off discourages the
+ planner from using one if there is any other method available.
+ The default is on. This is mostly useful to debug the query
+ planner.
-
- pretty_plan
-
+ ENABLE_SEQSCAN (boolean )
- Pretty-print query plan.
+ Enables or disables the query planner's use of sequential scan
+ plan types. It's not possible to suppress sequential scans
+ entirely, but turning this variable off discourages the
+ planner from using one if there is any other method available.
+ The default is on. This is mostly useful to debug the query
+ planner.
-
- pretty_parse
-
+ ENABLE_SORT (boolean )
- Pretty-print parser output.
+ Enables or disables the query planner's use of explicit sort
+ steps. It's not possible to suppress explicit sorts entirely,
+ but turning this variable off discourages the planner from
+ using one if there is any other method available. The default
+ is on. This is mostly useful to debug the query planner.
-
- pretty_rewritten
-
+ ENABLE_TIDSCAN (boolean )
- Pretty-print rewritten query.
+ Enables or disables the query planner's use of TID scan plan
+ types. The default is on. This is mostly useful to debug the
+ query planner.
-
- parserstats
-
+ GEQO (boolean )
- Print parser statistics.
+ Enables or disables genetic query optimization, which is an
+ algorithm that attempts to do query planning without
+ exhaustive search. This is on by default. See also the various
+ other GEQO_ settings.
-
- plannerstats
-
+ GEQO_EFFORT (integer )
+ GEQO_GENERATIONS (integer )
+ GEQO_POOL_SIZE (integer )
+ GEQO_RANDOM_SEED (integer )
+ GEQO_SELECTION_BIAS (floating point )
- Print planner statistics.
+ Various tuning parameters for the genetic query optimization
+ algorithm: The pool size is the number of individuals in one
+ population. Valid values are between 128 and 1024. If it is
+ set to 0 (the default) a pool size of 2^(QS+1), where QS
+ is the number of relations in the query, is taken. The effort
+ is used to calculate a default for generations. Valid values
+ are between 1 and 80, 40 being the default. Generations
+ specifies the number of iterations in the algorithm. The
+ number must be a positive integer. If 0 is specified then
+ Effort * Log2(PoolSize) is used. The run time of the algorithm
+ is roughly proportional to the sum of pool size and
+ generations. The selection bias is the selective pressure
+ within the population. Values can be from 1.50 to 2.00; the
+ latter is the default. The random seed can be set to get
+ reproduceable results from the algorithm. If it is set to -1
+ then the algorithm behaves non-deterministically.
-
- executorstats
-
+ GEQO_RELS (integer )
- Print executor statistics.
+ Only use genetic query optimization for queries with at least
+ this many relations involved. The default is 11. For less
+ relations it is probably more efficient to use the
+ deterministic, exhaustive planner.
-
- shortlocks
-
+ KSQO (boolean )
- Currently unused but needed to enable features in the future.
+ 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.
-
- locks
-
+ RANDOM_PAGE_COST (floating point )
- Trace locks.
+ Sets the query optimizer's estimate of the cost of a
+ nonsequentially fetched disk page. This is measured as a
+ multiple of the cost of a sequential page fetch.
+
+
+
+
+ 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
+
+
-
- userlocks
-
+ DEBUG_LEVEL (integer )
- Trace user locks.
+ 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.
-
+
-
- spinlocks
-
+ DEBUG_PRINT_PARSE (boolean )
+ DEBUG_PRINT_PLAN (boolean )
+ DEBUG_PRINT_REWRITTEN (boolean )
+ DEBUG_PRINT_QUERY (boolean )
+ DEBUG_PRETTY_PRINT (boolean )
- Trace spin locks.
+ For any executed query, prints either the query, the parse
+ tree, the execution plan, or the query rewriter output to the
+ server log. DEBUG_PRETTY_PRINT selects are
+ nicer but longer output format.
-
- notify
-
+ HOSTLOOKUP (boolean )
- Trace notify functions.
+ By default, connection logs only show the IP address of the
+ connecting host. If you want it to show the host name you can
+ turn this on, but depending on your host name resolution setup
+ it might impose a non-negligible performance penalty. This
+ option can only be set at server start.
-
- malloc
-
+ LOG_CONNECTIONS (boolean )
- Currently unused.
+ Prints a line informing about each successful connection to
+ the server log. This is off by default, although it is
+ probably very useful. This option can only be set at server
+ start.
-
- palloc
-
+ LOG_PID (boolean )
- Currently unused.
+ Prefixes each server log message with the process id of the
+ backend process. This is useful to sort out which messages
+ pertain to which connection. The default is off.
-
- lock_debug_oidmin
-
+ LOG_TIMESTAMP (boolean )
- Minimum relation oid traced by locks.
+ Prefixes each server log message with a timestamp. The default
+ is off.
-
- lock_debug_relid
-
+ SHOW_QUERY_STATS (boolean )
+ SHOW_PARSER_STATS (boolean )
+ SHOW_PLANNER_STATS (boolean )
+ SHOW_EXECUTOR_STATS (boolean )
- oid, if not zero, of relation traced by locks.
+ For each query, write performance statistics of the respective
+ module to the server log. This is a crude profiling
+ instrument.
-
- lock_read_priority
-
+ SHOWPORTNUMBER (boolean )
- Currently unused.
+ Shows the port number of the connecting host in the connection
+ log messages. You could trace back the port number to find out
+ what user initiated the connection. Other than that it's
+ pretty useless and therefore off by default. This option can
+ only be set at server start.
-
- deadlock_timeout
-
+ SYSLOG (integer )
- Deadlock check timer.
+
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 --enable-syslog option.
-
- syslog
-
+ TRACE_NOTIFY (boolean )
- syslog flag. Allowed values are:
+ Generates a great amount of debugging output for the
+ LISTEN and NOTIFY
+ commands.
+
+
+
+
+
-
-
-
- 0
-
-
- Messages to stdout/stderr.
-
-
-
+
+
General operation
-
-
- 1
-
-
- Messages to stdout/stderr and syslog.
-
-
-
+
+
+ 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.)
+
+
+
-
-
- 2
-
-
- Messages only to syslog.
-
-
-
+
+ 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.)
+
-
- hostlookup
-
+ NET_SERVER (boolean )
- Enable hostname lookup in ps_status.
+ If this is true, then the server will accept TCP/IP
+ connections. Otherwise only local Unix domain socket
+ connections are accepted. It is off by default. This option
+ can only be set at server start.
-
- showportnumber
-
+ PORT (integer )
- Show port number in ps_status.
+ The TCP port the server listens on; 5432 by default. This
+ option can only be set at server start.
-
- nofsync
-
+ SHMEM_BUFFERS (integer )
- Disable fsync on a per-backend basis.
+ Sets the number of shared memory buffers the database server
+ will use. The default is 64. Each buffer is typically 8192
+ bytes. This option can only be set at server start.
+
+ 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
+ -o 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.
+ 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:
+
+ The first number in the -L 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
+ 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
+ terminal session.
+
+
+
+++ /dev/null
-
-
-
-
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
- 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
- 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
-
-
-
-
-
-
-
-
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 database authentication 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 database TCP/IP address TCP/IP mask authentication 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
- 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
- (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
- 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:
-
-
-
- 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
-
-psql -h localhost -p 3333 -d mpw
-
-
- Note that you have to specify the -h 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.
-
-
-
-
-
-
-
+++ /dev/null
-
-
-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:
-
-
-
<productname>Postgres</productname> Signals
-Signals
-
-
-
-|
-
-Signal
-
-
-
-
-Server Action
-
-
-
-
-
-|
-
-SIGHUP
-
-
-kill(*,sighup)
-
-
-read_pg_options
-
-
-
-|
-
-SIGINT
-
-
-die
-
-
-cancel query
-
-
-
-|
-
-SIGQUIT
-
-
-kill(*,sigterm)
-
-
-handle_warn
-
-
-
-|
-
-SIGTERM
-
-
-kill(*,sigterm), kill(*,9), die
-
-
-die
-
-
-
-|
-
-SIGPIPE
-
-
-ignored
-
-
-die
-
-
-
-|
-
-SIGUSR1
-
-
-kill(*,sigusr1), die
-
-
-quickdie
-
-
-
-|
-
-SIGUSR2
-
-
-kill(*,sigusr2)
-
-
-async notify (SI flush)
-
-
-
-|
-
-SIGCHLD
-
-
-reaper
-
-
-ignored (alive test)
-
-
-
-|
-
-SIGTTIN
-
-
-ignored
-
-
-
-
-
-|
-
-SIGTTOU
-
-
-ignored
-
-
-
-
-
-|
-
-SIGCONT
-
-
-dumpstatus
-
-
-
-
-
-|
-
-SIGFPE
-
-
-
-
-FloatExceptionHandler
-
-
-
-
-
-
-
-
-"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
-
-
-
-
-
-
-
Adding and Deleting Users
-
-
createuser enables specific users to access
-
dropuser removes users and
- prevents them from accessing
Postgres .
-
-
- These commands only affect users with respect to
- they have no effect on a user's other privileges or status with regards
- to the underlying operating system.
-
-
-
Disk Management
+++ /dev/null
-
-
-
-
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
- 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 -T switch of
-
-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.
-
-
-
-
-
-
--- /dev/null
+
+
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 -U
+ 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.
+
+
+
+
+
projects / postgresql.git / commitdiff