diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml new file mode 100644 index 49547ee..156c264 *** a/doc/src/sgml/config.sgml --- b/doc/src/sgml/config.sgml *************** *** 11,17 **** 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 discuss each parameter in detail. --- 11,17 ---- There are many configuration parameters that affect the behavior of 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. *************** *** 23,69 **** 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. ! ! 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. ! ! Setting Parameters via the Configuration File ! One 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: # This is a comment log_connections = yes --- 23,121 ---- 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. ! ! ! ! ! ! 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. An 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. ! ! ! ! Parameter Interaction via Configuration 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 when the database cluster directory is initialized.) ! An example of what this file might look like is: # This is a comment log_connections = yes *************** log_destination = 'syslog' *** 71,197 **** search_path = '"$user", public' shared_buffers = 128MB ! 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. ! SIGHUP 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. ! ! Other Ways to Set Parameters ! ! 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. ! ! ! 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. ! ! ! 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. ! 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. ! ! 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. ! ! Examining Parameter Settings ! ! The ! command allows inspection of the current values of all parameters. ! ! ! The virtual table pg_settings also allows ! displaying and updating session run-time parameters; see 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. ! --- 123,310 ---- search_path = '"$user", public' shared_buffers = 128MB ! 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 lines as comments. 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. ! SIGHUP 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 ! 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. ! ! 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 , or if the server forces the session to ! reload its configuration after a SIGHUP ! signal. ! ! ! ! ! The command provides an ! SQL-accessible means of changing global defaults. ! ! ! ! ! The command allows database ! administrators to override global settings on a per-database basis. ! ! ! ! ! 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). + + + + ! Both SELECT and UPDATE ! can be issued against the system view pg_settings to view ! and change session-local values. ! ! ! ! Querying this view is the sames 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'; ! + + + ! ! Parameter Interaction via Shell ! ! In addition to setting global defaults or attaching ! overrides at the database or role level, you can pass setting to ! PostgreSQL via shell facilities. ! Both the server and libpq client library ! accept parameter values via the shell. ! ! ! ! ! On the server, command-line options can be ! passed to the postgres command directly via the ! ! ! ! ! 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 at the beginning of the session. ! ! ! ! However, the format of PGOPTIONS is similar to that ! used when launching the postgres command. ! Specifically, the ! ! ! 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. ! ! !