begriffs open source - ai-pg/blob - full-docs/txt/config-setting.txt

   1
   2 19.1. Setting Parameters #
   3
   4    19.1.1. Parameter Names and Values
   5    19.1.2. Parameter Interaction via the Configuration File
   6    19.1.3. Parameter Interaction via SQL
   7    19.1.4. Parameter Interaction via the Shell
   8    19.1.5. Managing Configuration File Contents
   9
  10 19.1.1. Parameter Names and Values #
  11
  12    All parameter names are case-insensitive. Every parameter takes a value
  13    of one of five types: boolean, string, integer, floating point, or
  14    enumerated (enum). The type determines the syntax for setting the
  15    parameter:
  16      * Boolean: Values can be written as on, off, true, false, yes, no, 1,
  17        0 (all case-insensitive) or any unambiguous prefix of one of these.
  18      * String: In general, enclose the value in single quotes, doubling
  19        any single quotes within the value. Quotes can usually be omitted
  20        if the value is a simple number or identifier, however. (Values
  21        that match an SQL keyword require quoting in some contexts.)
  22      * Numeric (integer and floating point): Numeric parameters can be
  23        specified in the customary integer and floating-point formats;
  24        fractional values are rounded to the nearest integer if the
  25        parameter is of integer type. Integer parameters additionally
  26        accept hexadecimal input (beginning with 0x) and octal input
  27        (beginning with 0), but these formats cannot have a fraction. Do
  28        not use thousands separators. Quotes are not required, except for
  29        hexadecimal input.
  30      * Numeric with Unit: Some numeric parameters have an implicit unit,
  31        because they describe quantities of memory or time. The unit might
  32        be bytes, kilobytes, blocks (typically eight kilobytes),
  33        milliseconds, seconds, or minutes. An unadorned numeric value for
  34        one of these settings will use the setting's default unit, which
  35        can be learned from pg_settings.unit. For convenience, settings can
  36        be given with a unit specified explicitly, for example '120 ms' for
  37        a time value, and they will be converted to whatever the
  38        parameter's actual unit is. Note that the value must be written as
  39        a string (with quotes) to use this feature. The unit name is
  40        case-sensitive, and there can be whitespace between the numeric
  41        value and the unit.
  42           + Valid memory units are B (bytes), kB (kilobytes), MB
  43             (megabytes), GB (gigabytes), and TB (terabytes). The
  44             multiplier for memory units is 1024, not 1000.
  45           + Valid time units are us (microseconds), ms (milliseconds), s
  46             (seconds), min (minutes), h (hours), and d (days).
  47        If a fractional value is specified with a unit, it will be rounded
  48        to a multiple of the next smaller unit if there is one. For
  49        example, 30.1 GB will be converted to 30822 MB not 32319628902 B.
  50        If the parameter is of integer type, a final rounding to integer
  51        occurs after any unit conversion.
  52      * Enumerated: Enumerated-type parameters are written in the same way
  53        as string parameters, but are restricted to have one of a limited
  54        set of values. The values allowable for such a parameter can be
  55        found from pg_settings.enumvals. Enum parameter values are
  56        case-insensitive.
  57
  58 19.1.2. Parameter Interaction via the Configuration File #
  59
  60    The most fundamental way to set these parameters is to edit the file
  61    postgresql.conf, which is normally kept in the data directory. A
  62    default copy is installed when the database cluster directory is
  63    initialized. An example of what this file might look like is:
  64 # This is a comment
  65 log_connections = all
  66 log_destination = 'syslog'
  67 search_path = '"$user", public'
  68 shared_buffers = 128MB
  69
  70    One parameter is specified per line. The equal sign between name and
  71    value is optional. Whitespace is insignificant (except within a quoted
  72    parameter value) and blank lines are ignored. Hash marks (#) designate
  73    the remainder of the line as a comment. Parameter values that are not
  74    simple identifiers or numbers must be single-quoted. To embed a single
  75    quote in a parameter value, write either two quotes (preferred) or
  76    backslash-quote. If the file contains multiple entries for the same
  77    parameter, all but the last one are ignored.
  78
  79    Parameters set in this way provide default values for the cluster. The
  80    settings seen by active sessions will be these values unless they are
  81    overridden. The following sections describe ways in which the
  82    administrator or user can override these defaults.
  83
  84    The configuration file is reread whenever the main server process
  85    receives a SIGHUP signal; this signal is most easily sent by running
  86    pg_ctl reload from the command line or by calling the SQL function
  87    pg_reload_conf(). The main server process also propagates this signal
  88    to all currently running server processes, so that existing sessions
  89    also adopt the new values (this will happen after they complete any
  90    currently-executing client command). Alternatively, you can send the
  91    signal to a single server process directly. Some parameters can only be
  92    set at server start; any changes to their entries in the configuration
  93    file will be ignored until the server is restarted. Invalid parameter
  94    settings in the configuration file are likewise ignored (but logged)
  95    during SIGHUP processing.
  96
  97    In addition to postgresql.conf, a PostgreSQL data directory contains a
  98    file postgresql.auto.conf, which has the same format as postgresql.conf
  99    but is intended to be edited automatically, not manually. This file
 100    holds settings provided through the ALTER SYSTEM command. This file is
 101    read whenever postgresql.conf is, and its settings take effect in the
 102    same way. Settings in postgresql.auto.conf override those in
 103    postgresql.conf.
 104
 105    External tools may also modify postgresql.auto.conf. It is not
 106    recommended to do this while the server is running unless
 107    allow_alter_system is set to off, since a concurrent ALTER SYSTEM
 108    command could overwrite such changes. Such tools might simply append
 109    new settings to the end, or they might choose to remove duplicate
 110    settings and/or comments (as ALTER SYSTEM will).
 111
 112    The system view pg_file_settings can be helpful for pre-testing changes
 113    to the configuration files, or for diagnosing problems if a SIGHUP
 114    signal did not have the desired effects.
 115
 116 19.1.3. Parameter Interaction via SQL #
 117
 118    PostgreSQL provides three SQL commands to establish configuration
 119    defaults. The already-mentioned ALTER SYSTEM command provides an
 120    SQL-accessible means of changing global defaults; it is functionally
 121    equivalent to editing postgresql.conf. In addition, there are two
 122    commands that allow setting of defaults on a per-database or per-role
 123    basis:
 124      * The ALTER DATABASE command allows global settings to be overridden
 125        on a per-database basis.
 126      * The ALTER ROLE command allows both global and per-database settings
 127        to be overridden with user-specific values.
 128
 129    Values set with ALTER DATABASE and ALTER ROLE are applied only when
 130    starting a fresh database session. They override values obtained from
 131    the configuration files or server command line, and constitute defaults
 132    for the rest of the session. Note that some settings cannot be changed
 133    after server start, and so cannot be set with these commands (or the
 134    ones listed below).
 135
 136    Once a client is connected to the database, PostgreSQL provides two
 137    additional SQL commands (and equivalent functions) to interact with
 138    session-local configuration settings:
 139      * The SHOW command allows inspection of the current value of any
 140        parameter. The corresponding SQL function is
 141        current_setting(setting_name text) (see Section 9.28.1).
 142      * The SET command allows modification of the current value of those
 143        parameters that can be set locally to a session; it has no effect
 144        on other sessions. Many parameters can be set this way by any user,
 145        but some can only be set by superusers and users who have been
 146        granted SET privilege on that parameter. The corresponding SQL
 147        function is set_config(setting_name, new_value, is_local) (see
 148        Section 9.28.1).
 149
 150    In addition, the system view pg_settings can be used to view and change
 151    session-local values:
 152      * Querying this view is similar to using SHOW ALL but provides more
 153        detail. It is also more flexible, since it's possible to specify
 154        filter conditions or join against other relations.
 155      * Using UPDATE on this view, specifically updating the setting
 156        column, is the equivalent of issuing SET commands. For example, the
 157        equivalent of
 158 SET configuration_parameter TO DEFAULT;
 159
 160        is:
 161 UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter
 162 ';
 163
 164 19.1.4. Parameter Interaction via the Shell #
 165
 166    In addition to setting global defaults or attaching overrides at the
 167    database or role level, you can pass settings to PostgreSQL via shell
 168    facilities. Both the server and libpq client library accept parameter
 169    values via the shell.
 170      * During server startup, parameter settings can be passed to the
 171        postgres command via the -c name=value command-line parameter, or
 172        its equivalent --name=value variation. For example,
 173 postgres -c log_connections=all --log-destination='syslog'
 174
 175        Settings provided in this way override those set via
 176        postgresql.conf or ALTER SYSTEM, so they cannot be changed globally
 177        without restarting the server.
 178      * When starting a client session via libpq, parameter settings can be
 179        specified using the PGOPTIONS environment variable. Settings
 180        established in this way constitute defaults for the life of the
 181        session, but do not affect other sessions. For historical reasons,
 182        the format of PGOPTIONS is similar to that used when launching the
 183        postgres command; specifically, the -c, or prepended --, before the
 184        name must be specified. For example,
 185 env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql
 186
 187        Other clients and libraries might provide their own mechanisms, via
 188        the shell or otherwise, that allow the user to alter session
 189        settings without direct use of SQL commands.
 190
 191 19.1.5. Managing Configuration File Contents #
 192
 193    PostgreSQL provides several features for breaking down complex
 194    postgresql.conf files into sub-files. These features are especially
 195    useful when managing multiple servers with related, but not identical,
 196    configurations.
 197
 198    In addition to individual parameter settings, the postgresql.conf file
 199    can contain include directives, which specify another file to read and
 200    process as if it were inserted into the configuration file at this
 201    point. This feature allows a configuration file to be divided into
 202    physically separate parts. Include directives simply look like:
 203 include 'filename'
 204
 205    If the file name is not an absolute path, it is taken as relative to
 206    the directory containing the referencing configuration file. Inclusions
 207    can be nested.
 208
 209    There is also an include_if_exists directive, which acts the same as
 210    the include directive, except when the referenced file does not exist
 211    or cannot be read. A regular include will consider this an error
 212    condition, but include_if_exists merely logs a message and continues
 213    processing the referencing configuration file.
 214
 215    The postgresql.conf file can also contain include_dir directives, which
 216    specify an entire directory of configuration files to include. These
 217    look like
 218 include_dir 'directory'
 219
 220    Non-absolute directory names are taken as relative to the directory
 221    containing the referencing configuration file. Within the specified
 222    directory, only non-directory files whose names end with the suffix
 223    .conf will be included. File names that start with the . character are
 224    also ignored, to prevent mistakes since such files are hidden on some
 225    platforms. Multiple files within an include directory are processed in
 226    file name order (according to C locale rules, i.e., numbers before
 227    letters, and uppercase letters before lowercase ones).
 228
 229    Include files or directories can be used to logically separate portions
 230    of the database configuration, rather than having a single large
 231    postgresql.conf file. Consider a company that has two database servers,
 232    each with a different amount of memory. There are likely elements of
 233    the configuration both will share, for things such as logging. But
 234    memory-related parameters on the server will vary between the two. And
 235    there might be server specific customizations, too. One way to manage
 236    this situation is to break the custom configuration changes for your
 237    site into three files. You could add this to the end of your
 238    postgresql.conf file to include them:
 239 include 'shared.conf'
 240 include 'memory.conf'
 241 include 'server.conf'
 242
 243    All systems would have the same shared.conf. Each server with a
 244    particular amount of memory could share the same memory.conf; you might
 245    have one for all servers with 8GB of RAM, another for those having
 246    16GB. And finally server.conf could have truly server-specific
 247    configuration information in it.
 248
 249    Another possibility is to create a configuration file directory and put
 250    this information into files there. For example, a conf.d directory
 251    could be referenced at the end of postgresql.conf:
 252 include_dir 'conf.d'
 253
 254    Then you could name the files in the conf.d directory like this:
 255 00shared.conf
 256 01memory.conf
 257 02server.conf
 258
 259    This naming convention establishes a clear order in which these files
 260    will be loaded. This is important because only the last setting
 261    encountered for a particular parameter while the server is reading
 262    configuration files will be used. In this example, something set in
 263    conf.d/02server.conf would override a value set in
 264    conf.d/01memory.conf.
 265
 266    You might instead use this approach to naming the files descriptively:
 267 00shared.conf
 268 01memory-8GB.conf
 269 02server-foo.conf
 270
 271    This sort of arrangement gives a unique name for each configuration
 272    file variation. This can help eliminate ambiguity when several servers
 273    have their configurations all stored in one place, such as in a version
 274    control repository. (Storing database configuration files under version
 275    control is another good practice to consider.)