There are many configuration parameters that affect the behavior of
- the database system. In the first section of this chapter, we
- describe how to set configuration parameters. The subsequent sections
+ the database system. In the first section of this chapter we
+ describe how to interact with configuration parameters. The subsequent sections
discuss each parameter in detail.
All parameter names are case-insensitive. Every parameter takes a
- value of one of five types: Boolean, integer, floating point,
- string or enum. Boolean values can be written as on,
- off, true,
- false, yes,
- no, 1, 0
- (all case-insensitive) or any unambiguous prefix of these.
+ value of one of five types: boolean, integer, floating point,
+ string, or enum.
- Some settings specify a memory or time value. Each of these has an
- implicit unit, which is either kilobytes, blocks (typically eight
- kilobytes), milliseconds, seconds, or minutes. Default units can be
- found by referencing pg_settings.unit.
- For convenience,
- a different unit can also be specified explicitly. Valid memory units
- are kB (kilobytes), MB
- (megabytes), GB (gigabytes), and TB (terabytes); valid time units
- are ms (milliseconds), s
- (seconds), min (minutes), h
- (hours), and d (days). Note that the multiplier
- for memory units is 1024, not 1000.
-
+
- Parameters of type enum are specified in the same way as string
- parameters, but are restricted to a limited set of values. The allowed
- values can be found
- from pg_settings.enumvals.
- Enum parameter values are case-insensitive.
-
+
+ Boolean: Values can be written as
+ on,
+ off,
+ true,
+ false,
+ yes,
+ no,
+ 1,
+ 0
+ (all case-insensitive) or any unambiguous prefix of these.
+
+
+
+
+ String: Enclose the value in
+ single-quotes. Values are case-insensitive. If multiple values
+ are allowed, separate them with commas.
+
+
+
+
+ Numeric (integer and floating point): Do
+ not use single-quotes (unless otherwise required) or thousand
+ separators.
+
+
+
+
+ Numeric or String with Unit (Memory &
+ Time): These have an implicit unit, which is
+ either kilobytes, blocks (typically eight kilobytes),
+ milliseconds, seconds, or minutes. A unadorned numeric
+ value will use the default, which can be found by referencing
+ pg_settings.unit. For convenience,
+ a different unit can also be specified explicitly via a string
+ value. It is case-sensitive and may include whitespace between
+ the value and the unit.
+
+
+
+ Valid memory units are kB (kilobytes),
+ MB (megabytes), GB
+ (gigabytes), and TB (terabytes).
+ The multiplier for memory units is 1024, not 1000.
+
+
+
+
+ Valid time units are ms (milliseconds),
+ s (seconds), min (minutes),
+ h (hours), and d (days).
+
+
+
+
+
+
+
+ enum:
These are specified
+ in the same way as string parameters, but are restricted
+ to a limited set of values that can be queried from
+ pg_settings.enumvals:
+SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
+
+ Enum parameter values are case-insensitive.
+
+
+
-
<span class="marked">Setting Parameters via the</span> Configuration File
+
<span class="marked">Parameter Interaction via</span> Configuration File
- One way to set these parameters is to edit the file
+ The primary way to set these parameters is to edit the file
postgresql.confpostgresql.conf,
which is normally kept in the data directory. (A default copy is
- installed there when the database cluster directory is
- initialized.) An example of what this file might look like is:
+ installed when the database cluster directory is initialized.)
+ An example of what this file might look like is:
# This is a comment
log_connections = yes
One parameter is specified per line. The equal sign between name and
value is optional. Whitespace is insignificant and blank lines are
- ignored. Hash marks (#) designate the remainder of the
- line as a comment. Parameter values that are not simple identifiers or
- numbers must be single-quoted. To embed a single quote in a parameter
- value, write either two quotes (preferred) or backslash-quote.
+ ignored. Hash marks (#) designate the remainder
+ of the line as a comment. Parameter values that are not simple
+ identifiers or numbers must be single-quoted. To embed a single
+ quote in a parameter value write either two quotes (preferred)
+ or backslash-quote.
+
+
+ Parameters set in this way provide default values for the cluster.
+ The setting seen by active sessions will be this value unless
+ it is overridden. The following sections describe ways in which the
+ administrator or user can override these defaults.
The configuration file is reread whenever the main server process
receives a SIGHUP signal; this is most easily done by
running pg_ctl reload from the command-line or by calling
the SQL function pg_reload_conf(). The main
- server process
- also propagates this signal to all currently running server
- processes so that existing sessions also get the new
- value. Alternatively, you can send the signal to a single server
- process directly. Some parameters can only be set at server start;
- any changes to their entries in the configuration file will be ignored
- until the server is restarted. Invalid parameter settings in the
- configuration file are likewise ignored (but logged) during
- SIGHUP processing.
+ server process also propagates this signal to all currently running
+ server processes so that existing sessions also get the new value
+ when they complete their transactions. Alternatively, you can
+ send the signal to a single server process directly. Some parameters
+ can only be set at server start; any changes to their entries in the
+ configuration file will be ignored until the server is restarted.
+ Invalid parameter settings in the configuration file are likewise
+ ignored (but logged) during SIGHUP processing.
-
-
Other Ways to Set Parameters
+
+
Parameter Interaction via SQL
+
PostgreSQL provides three SQL
+ commands to establish configuration defaults that override those
+ configured globally. The evaluation of these defaults occurs
+ at the beginning of a new session, upon the user issuing
+ linkend="SQL-DISCARD">, or if the server forces the session to
+ reload its configuration after a SIGHUP
+ signal.
+
- A second way to set these configuration parameters is to give them
- as a command-line option to the postgres command,
- such as:
-postgres -c log_connections=yes -c log_destination='syslog'
-
- Command-line options override any conflicting settings in
- postgresql.conf. Note that this means you won't
- be able to change the value on-the-fly by editing
- postgresql.conf, so while the command-line
- method might be convenient, it can cost you flexibility later.
-
+
+
+ The command provides an
+ SQL-accessible means of changing global defaults.
+
+
- Occasionally it is useful to give a command line option to
- one particular session only. The environment variable
- PGOPTIONS can be used for this purpose on the
- client side:
-env PGOPTIONS='-c geqo=off' psql
-
- (This works for any
libpq-based client application, not- just
psql.) Note that this won't work for
- parameters that are fixed when the server is started or that must be
- specified in postgresql.conf.
-
+
+ The command allows database
+ administrators to override global settings on a per-database basis.
+
+
- Furthermore, it is possible to assign a set of parameter settings to
- a user or a database. Whenever a session is started, the default
- settings for the user and database involved are loaded. The
- commands
- and ,
- respectively, are used to configure these settings. Per-database
- settings override anything received from the
- postgres command-line or the configuration
- file, and in turn are overridden by per-user settings; both are
- overridden by per-session settings.
+
+ The command allows database
+ administrators to override both global and per-database settings
+ with user-specific values.
+
+
+
+
+ Once a client connects to the database PostgreSQL provides
+ two additional SQL commands to interact with session-local
+ configuration settings. Both of these commands have equivalent
+ system administration functions.
+
+
+ The command allows inspection of the
+ current value of all parameters. The corresponding function is
+ current_setting(setting_name text).
+
+
+
+
+ The command allows modification of the
+ current value of some parameters. The corresponding function is
+ set_config(setting_name, new_value, is_local).
+
+
+
+
- Some parameters can be changed in individual
SQL- sessions with the
- command, for example:
-
-SET ENABLE_SEQSCAN TO OFF;
-
- If SET is allowed, it overrides all other sources of
- values for the parameter. Some parameters cannot be changed via
- SET: for example, if they control behavior that
- cannot be changed without restarting the entire
-
PostgreSQL server. Also, some parameters
- require superuser permission to change via SET or
- ALTER.
+ Both SELECT and UPDATE
+ can be issued against the system view
+ linkend="view-pg-settings">pg_settings to view
+ and change session-local values.
- Another way to change configuration parameters persistently is by
- use of
- command, for example:
-
-ALTER SYSTEM SET checkpoint_timeout TO 600;
-
- This command will allow users to change values persistently
- through SQL command. The values will be effective after reload of server configuration
- (
SIGHUP) or server startup. The effect of this command is similar to when- user manually changes values in postgresql.conf.
+
+
+ Querying this view is the same as SHOW but provides
+ more detail, as well as allowing for joins against other relations
+ and the specification of filter criteria.
+
+
+
+
+ Using on this relation, specifically
+ updating the setting column, is the equivalent
+ of issuing SQL SET, though all values must be
+ single-quoted. Note that the equivalent of
+SET configuration_parameter TO DEFAULT;
+
+ is:
+UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
+
+
+
+
-
-
Examining Parameter Settings
+
+
Parameter Interaction via Shell
+ In addition to setting global defaults or attaching
+ overrides at the database or role level, you can pass settings to
+
PostgreSQL via shell facilities.
+ Both the server and
libpq client library+ accept parameter values via the shell.
+
- The
- command allows inspection of the current values of all parameters.
-
+
+
+ On the server, command-line options can be
+ passed to the postgres command directly via the
+
+postgres -c log_connections=yes -c log_destination='syslog'
+
+ Settings provided this way override those resolved globally (via
+ postgresql.conf or ALTER SYSTEM) but
+ are otherwise treated as being global for the purpose of database
+ and role overrides.
+
+
- The virtual table pg_settings also allows
- displaying and updating session run-time parameters; see
- linkend="view-pg-settings"> for details and a description of the
- different variable types and when they can be changed.
- pg_settings is equivalent to SHOW
- and SET, but can be more convenient
- to use because it can be joined with other tables, or selected from using
- any desired selection condition. It also contains more information about
- each parameter than is available from SHOW.
-
+
+ On the libpq-client, command-line options can be
+ specified using the PGOPTIONS environment variable.
+ When connecting to the server, the contents of this variable are
+ sent to the server as if they were being executed via SQL
+ linkend="SQL-SET"> at the beginning of the session.
+
+
+ However, the format of PGOPTIONS is similar to that
+ used when launching the postgres command.
+ Specifically, the
+env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql
+
+
+
+ Other clients and libraries might provide their own mechanisms,
+ via the shell or otherwise, that allow the user to alter session
+ settings without requiring the user to issue SQL commands.
+
+
+
projects / postgresql.git / commitdiff