Skip to content

Commit 817ec1b

Browse files
tglsfdctglsfdc
committed
Improve discussion of setting server parameters.
Rewrite description of "include_if_exists" for clarity. Add subsection headings to make the structure of the page a little clearer. A couple other minor improvements too. Josh Kupershmidt and Tom Lane
1 parent ee24de4 commit 817ec1b

File tree

1 file changed

+163
-141
lines changed

1 file changed

+163
-141
lines changed

‎doc/src/sgml/config.sgml‎

Lines changed: 163 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -18,178 +18,200 @@
1818
<sect1 id="config-setting">
1919
<title>Setting Parameters</title>
2020

21-
<para>
22-
All parameter names are case-insensitive. Every parameter takes a
23-
value of one of five types: Boolean, integer, floating point,
24-
string or enum. Boolean values can be written as <literal>on</literal>,
25-
<literal>off</literal>, <literal>true</literal>,
26-
<literal>false</literal>, <literal>yes</literal>,
27-
<literal>no</literal>, <literal>1</literal>, <literal>0</literal>
28-
(all case-insensitive) or any unambiguous prefix of these.
29-
</para>
21+
<sect2 id="config-setting-names-values">
22+
<title>Parameter Names and Values</title>
3023

31-
<para>
32-
Some settings specify a memory or time value. Each of these has an
33-
implicit unit, which is either kilobytes, blocks (typically eight
34-
kilobytes), milliseconds, seconds, or minutes. Default units can be
35-
found by referencing <structname>pg_settings</>.<structfield>unit</>.
36-
For convenience,
37-
a different unit can also be specified explicitly. Valid memory units
38-
are <literal>kB</literal> (kilobytes), <literal>MB</literal>
39-
(megabytes), and <literal>GB</literal> (gigabytes); valid time units
40-
are <literal>ms</literal> (milliseconds), <literal>s</literal>
41-
(seconds), <literal>min</literal> (minutes), <literal>h</literal>
42-
(hours), and <literal>d</literal> (days). Note that the multiplier
43-
for memory units is 1024, not 1000.
44-
</para>
24+
<para>
25+
All parameter names are case-insensitive. Every parameter takes a
26+
value of one of five types: Boolean, integer, floating point,
27+
string or enum. Boolean values can be written as <literal>on</literal>,
28+
<literal>off</literal>, <literal>true</literal>,
29+
<literal>false</literal>, <literal>yes</literal>,
30+
<literal>no</literal>, <literal>1</literal>, <literal>0</literal>
31+
(all case-insensitive) or any unambiguous prefix of these.
32+
</para>
4533

46-
<para>
47-
Parameters of type <quote>enum</> are specified in the same way as string
48-
parameters, but are restricted to a limited set of values. The allowed
49-
values can be found
50-
from <structname>pg_settings</>.<structfield>enumvals</>.
51-
Enum parameter values are case-insensitive.
52-
</para>
34+
<para>
35+
Some settings specify a memory or time value. Each of these has an
36+
implicit unit, which is either kilobytes, blocks (typically eight
37+
kilobytes), milliseconds, seconds, or minutes. Default units can be
38+
found by referencing <structname>pg_settings</>.<structfield>unit</>.
39+
For convenience,
40+
a different unit can also be specified explicitly. Valid memory units
41+
are <literal>kB</literal> (kilobytes), <literal>MB</literal>
42+
(megabytes), and <literal>GB</literal> (gigabytes); valid time units
43+
are <literal>ms</literal> (milliseconds), <literal>s</literal>
44+
(seconds), <literal>min</literal> (minutes), <literal>h</literal>
45+
(hours), and <literal>d</literal> (days). Note that the multiplier
46+
for memory units is 1024, not 1000.
47+
</para>
5348

54-
<para>
55-
One way to set these parameters is to edit the file
56-
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
57-
which is normally kept in the data directory. (A default copy is
58-
installed there when the database cluster directory is
59-
initialized.) An example of what this file might look like is:
49+
<para>
50+
Parameters of type <quote>enum</> are specified in the same way as string
51+
parameters, but are restricted to a limited set of values. The allowed
52+
values can be found
53+
from <structname>pg_settings</>.<structfield>enumvals</>.
54+
Enum parameter values are case-insensitive.
55+
</para>
56+
</sect2>
57+
58+
<sect2 id="config-setting-configuration-file">
59+
<title>Setting Parameters via the Configuration File</title>
60+
61+
<para>
62+
One way to set these parameters is to edit the file
63+
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
64+
which is normally kept in the data directory. (A default copy is
65+
installed there when the database cluster directory is
66+
initialized.) An example of what this file might look like is:
6067
<programlisting>
6168
# This is a comment
6269
log_connections = yes
6370
log_destination = 'syslog'
6471
search_path = '"$user", public'
6572
shared_buffers = 128MB
6673
</programlisting>
67-
One parameter is specified per line. The equal sign between name and
68-
value is optional. Whitespace is insignificant and blank lines are
69-
ignored. Hash marks (<literal>#</literal>) designate the rest of the
70-
line as a comment. Parameter values that are not simple identifiers or
71-
numbers must be single-quoted. To embed a single quote in a parameter
72-
value, write either two quotes (preferred) or backslash-quote.
73-
</para>
74+
One parameter is specified per line. The equal sign between name and
75+
value is optional. Whitespace is insignificant and blank lines are
76+
ignored. Hash marks (<literal>#</literal>) designate the remainder of the
77+
line as a comment. Parameter values that are not simple identifiers or
78+
numbers must be single-quoted. To embed a single quote in a parameter
79+
value, write either two quotes (preferred) or backslash-quote.
80+
</para>
7481

75-
<para>
76-
<indexterm>
77-
<primary><literal>include</></primary>
78-
<secondary>in configuration file</secondary>
79-
</indexterm>
80-
In addition to parameter settings, the <filename>postgresql.conf</>
81-
file can contain <firstterm>include directives</>, which specify
82-
another file to read and process as if it were inserted into the
83-
configuration file at this point. Include directives simply look like:
82+
<para>
83+
<indexterm>
84+
<primary><literal>include</></primary>
85+
<secondary>in configuration file</secondary>
86+
</indexterm>
87+
In addition to parameter settings, the <filename>postgresql.conf</>
88+
file can contain <firstterm>include directives</>, which specify
89+
another file to read and process as if it were inserted into the
90+
configuration file at this point. This feature allows a configuration
91+
file to be divided into physically separate parts.
92+
Include directives simply look like:
8493
<programlisting>
8594
include 'filename'
8695
</programlisting>
87-
If the file name is not an absolute path, it is taken as relative to
88-
the directory containing the referencing configuration file.
89-
Inclusions can be nested.
90-
</para>
96+
If the file name is not an absolute path, it is taken as relative to
97+
the directory containing the referencing configuration file.
98+
Inclusions can be nested.
99+
</para>
91100

92-
<para>
93-
<indexterm>
94-
<primary><literal>include_if_exists</></primary>
95-
<secondary>in configuration file</secondary>
96-
</indexterm>
97-
Use the same approach as the <literal>include</> directive, continuing
98-
normally if the file does not exist. A regular <literal>include</>
99-
will stop with an error if the referenced file is missing, while
100-
<literal>include_if_exists</> does not. A warning about the missing
101-
file will be logged.
102-
</para>
101+
<para>
102+
<indexterm>
103+
<primary><literal>include_if_exists</></primary>
104+
<secondary>in configuration file</secondary>
105+
</indexterm>
106+
There is also an <literal>include_if_exists</> directive, which acts
107+
the same as the <literal>include</> directive, except for the behavior
108+
when the referenced file does not exist or cannot be read. A regular
109+
<literal>include</> will consider this an error condition, but
110+
<literal>include_if_exists</> merely logs a message and continues
111+
processing the referencing configuration file.
112+
</para>
103113

104-
<para>
105-
<indexterm>
106-
<primary>SIGHUP</primary>
107-
</indexterm>
108-
The configuration file is reread whenever the main server process receives a
109-
<systemitem>SIGHUP</> signal (which is most easily sent by means
110-
of <literal>pg_ctl reload</>). The main server process
111-
also propagates this signal to all currently running server
112-
processes so that existing sessions also get the new
113-
value. Alternatively, you can send the signal to a single server
114-
process directly. Some parameters can only be set at server start;
115-
any changes to their entries in the configuration file will be ignored
116-
until the server is restarted. Invalid parameter settings in the
117-
configuration file are likewise ignored (but logged) during
118-
<systemitem>SIGHUP</> processing.
119-
</para>
114+
<para>
115+
<indexterm>
116+
<primary>SIGHUP</primary>
117+
</indexterm>
118+
The configuration file is reread whenever the main server process
119+
receives a
120+
<systemitem>SIGHUP</> signal (which is most easily sent by means
121+
of <literal>pg_ctl reload</>). The main server process
122+
also propagates this signal to all currently running server
123+
processes so that existing sessions also get the new
124+
value. Alternatively, you can send the signal to a single server
125+
process directly. Some parameters can only be set at server start;
126+
any changes to their entries in the configuration file will be ignored
127+
until the server is restarted. Invalid parameter settings in the
128+
configuration file are likewise ignored (but logged) during
129+
<systemitem>SIGHUP</> processing.
130+
</para>
131+
</sect2>
120132

121-
<para>
122-
A second way to set these configuration parameters is to give them
123-
as a command-line option to the <command>postgres</command> command, such as:
133+
<sect2 id="config-setting-other-methods">
134+
<title>Other Ways to Set Parameters</title>
135+
136+
<para>
137+
A second way to set these configuration parameters is to give them
138+
as a command-line option to the <command>postgres</command> command,
139+
such as:
124140
<programlisting>
125141
postgres -c log_connections=yes -c log_destination='syslog'
126142
</programlisting>
127-
Command-line options override any conflicting settings in
128-
<filename>postgresql.conf</filename>. Note that this means you won't
129-
be able to change the value on-the-fly by editing
130-
<filename>postgresql.conf</filename>, so while the command-line
131-
method might be convenient, it can cost you flexibility later.
132-
</para>
143+
Command-line options override any conflicting settings in
144+
<filename>postgresql.conf</filename>. Note that this means you won't
145+
be able to change the value on-the-fly by editing
146+
<filename>postgresql.conf</filename>, so while the command-line
147+
method might be convenient, it can cost you flexibility later.
148+
</para>
133149

134-
<para>
135-
Occasionally it is useful to give a command line option to
136-
one particular session only. The environment variable
137-
<envar>PGOPTIONS</envar> can be used for this purpose on the
138-
client side:
150+
<para>
151+
Occasionally it is useful to give a command line option to
152+
one particular session only. The environment variable
153+
<envar>PGOPTIONS</envar> can be used for this purpose on the
154+
client side:
139155
<programlisting>
140156
env PGOPTIONS='-c geqo=off' psql
141157
</programlisting>
142-
(This works for any <application>libpq</>-based client application, not
143-
just <application>psql</application>.) Note that this won't work for
144-
parameters that are fixed when the server is started or that must be
145-
specified in <filename>postgresql.conf</filename>.
146-
</para>
158+
(This works for any <application>libpq</>-based client application, not
159+
just <application>psql</application>.) Note that this won't work for
160+
parameters that are fixed when the server is started or that must be
161+
specified in <filename>postgresql.conf</filename>.
162+
</para>
147163

148-
<para>
149-
Furthermore, it is possible to assign a set of parameter settings to
150-
a user or a database. Whenever a session is started, the default
151-
settings for the user and database involved are loaded. The
152-
commands <xref linkend="sql-alterrole">
153-
and <xref linkend="sql-alterdatabase">,
154-
respectively, are used to configure these settings. Per-database
155-
settings override anything received from the
156-
<command>postgres</command> command-line or the configuration
157-
file, and in turn are overridden by per-user settings; both are
158-
overridden by per-session settings.
159-
</para>
164+
<para>
165+
Furthermore, it is possible to assign a set of parameter settings to
166+
a user or a database. Whenever a session is started, the default
167+
settings for the user and database involved are loaded. The
168+
commands <xref linkend="sql-alterrole">
169+
and <xref linkend="sql-alterdatabase">,
170+
respectively, are used to configure these settings. Per-database
171+
settings override anything received from the
172+
<command>postgres</command> command-line or the configuration
173+
file, and in turn are overridden by per-user settings; both are
174+
overridden by per-session settings.
175+
</para>
160176

161-
<para>
162-
Some parameters can be changed in individual <acronym>SQL</acronym>
163-
sessions with the <xref linkend="SQL-SET">
164-
command, for example:
177+
<para>
178+
Some parameters can be changed in individual <acronym>SQL</acronym>
179+
sessions with the <xref linkend="SQL-SET">
180+
command, for example:
165181
<screen>
166182
SET ENABLE_SEQSCAN TO OFF;
167183
</screen>
168-
If <command>SET</> is allowed, it overrides all other sources of
169-
values for the parameter. Some parameters cannot be changed via
170-
<command>SET</command>: for example, if they control behavior that
171-
cannot be changed without restarting the entire
172-
<productname>PostgreSQL</productname> server. Also,
173-
some <command>SET</command> or <command>ALTER</> parameter modifications
174-
require superuser permission.
175-
</para>
184+
If <command>SET</> is allowed, it overrides all other sources of
185+
values for the parameter. Some parameters cannot be changed via
186+
<command>SET</command>: for example, if they control behavior that
187+
cannot be changed without restarting the entire
188+
<productname>PostgreSQL</productname> server. Also, some parameters
189+
require superuser permission to change via <command>SET</command> or
190+
<command>ALTER</>.
191+
</para>
192+
</sect2>
176193

177-
<para>
178-
The <xref linkend="SQL-SHOW">
179-
command allows inspection of the current values of all parameters.
180-
</para>
194+
<sect2 id="config-setting-examining">
195+
<title>Examining Parameter Settings</title>
181196

182-
<para>
183-
The virtual table <structname>pg_settings</structname> also allows
184-
displaying and updating session run-time parameters; see <xref
185-
linkend="view-pg-settings"> for details and a description of the
186-
different variable types and when they can be changed.
187-
<structname>pg_settings</structname> is equivalent to <command>SHOW</>
188-
and <command>SET</>, but can be more convenient
189-
to use because it can be joined with other tables, or selected from using
190-
any desired selection condition. It also contains more information about
191-
what values are allowed for the parameters.
192-
</para>
197+
<para>
198+
The <xref linkend="SQL-SHOW">
199+
command allows inspection of the current values of all parameters.
200+
</para>
201+
202+
<para>
203+
The virtual table <structname>pg_settings</structname> also allows
204+
displaying and updating session run-time parameters; see <xref
205+
linkend="view-pg-settings"> for details and a description of the
206+
different variable types and when they can be changed.
207+
<structname>pg_settings</structname> is equivalent to <command>SHOW</>
208+
and <command>SET</>, but can be more convenient
209+
to use because it can be joined with other tables, or selected from using
210+
any desired selection condition. It also contains more information about
211+
each parameter than is available from <command>SHOW</>.
212+
</para>
213+
214+
</sect2>
193215
</sect1>
194216

195217
<sect1 id="runtime-config-file-locations">

0 commit comments

Comments
 (0)