| 1 |
<!-- doc/src/sgml/config.sgml --> |
| 2 |
|
| 3 |
<chapter id="runtime-config"> |
| 4 |
<title>Server Configuration</title> |
| 5 |
|
| 6 |
<indexterm> |
| 7 |
<primary>configuration</primary> |
| 8 |
<secondary>of the server</secondary> |
| 9 |
</indexterm> |
| 10 |
|
| 11 |
<para> |
| 12 |
There are many configuration parameters that affect the behavior of |
| 13 |
the database system. In the first section of this chapter we |
| 14 |
describe how to interact with configuration parameters. The subsequent sections |
| 15 |
discuss each parameter in detail. |
| 16 |
</para> |
| 17 |
|
| 18 |
<sect1 id="config-setting"> |
| 19 |
<title>Setting Parameters</title> |
| 20 |
|
| 21 |
<sect2 id="config-setting-names-values"> |
| 22 |
<title>Parameter Names and Values</title> |
| 23 |
|
| 24 |
<para> |
| 25 |
All parameter names are case-insensitive. Every parameter takes a |
| 26 |
value of one of five types: boolean, string, integer, floating point, |
| 27 |
or enumerated (enum). The type determines the syntax for setting the |
| 28 |
parameter: |
| 29 |
</para> |
| 30 |
|
| 31 |
<itemizedlist> |
| 32 |
<listitem> |
| 33 |
<para> |
| 34 |
<emphasis>Boolean:</emphasis> |
| 35 |
Values can be written as |
| 36 |
<literal>on</literal>, |
| 37 |
<literal>off</literal>, |
| 38 |
<literal>true</literal>, |
| 39 |
<literal>false</literal>, |
| 40 |
<literal>yes</literal>, |
| 41 |
<literal>no</literal>, |
| 42 |
<literal>1</literal>, |
| 43 |
<literal>0</literal> |
| 44 |
(all case-insensitive) or any unambiguous prefix of one of these. |
| 45 |
</para> |
| 46 |
</listitem> |
| 47 |
|
| 48 |
<listitem> |
| 49 |
<para> |
| 50 |
<emphasis>String:</emphasis> |
| 51 |
In general, enclose the value in single quotes, doubling any single |
| 52 |
quotes within the value. Quotes can usually be omitted if the value |
| 53 |
is a simple number or identifier, however. |
| 54 |
(Values that match an SQL keyword require quoting in some contexts.) |
| 55 |
</para> |
| 56 |
</listitem> |
| 57 |
|
| 58 |
<listitem> |
| 59 |
<para> |
| 60 |
<emphasis>Numeric (integer and floating point):</emphasis> |
| 61 |
Numeric parameters can be specified in the customary integer and |
| 62 |
floating-point formats; fractional values are rounded to the nearest |
| 63 |
integer if the parameter is of integer type. Integer parameters |
| 64 |
additionally accept hexadecimal input (beginning |
| 65 |
with <literal>0x</literal>) and octal input (beginning |
| 66 |
with <literal>0</literal>), but these formats cannot have a fraction. |
| 67 |
Do not use thousands separators. |
| 68 |
Quotes are not required, except for hexadecimal input. |
| 69 |
</para> |
| 70 |
</listitem> |
| 71 |
|
| 72 |
<listitem> |
| 73 |
<para> |
| 74 |
<emphasis>Numeric with Unit:</emphasis> |
| 75 |
Some numeric parameters have an implicit unit, because they describe |
| 76 |
quantities of memory or time. The unit might be bytes, kilobytes, blocks |
| 77 |
(typically eight kilobytes), milliseconds, seconds, or minutes. |
| 78 |
An unadorned numeric value for one of these settings will use the |
| 79 |
setting's default unit, which can be learned from |
| 80 |
<structname>pg_settings</structname>.<structfield>unit</structfield>. |
| 81 |
For convenience, settings can be given with a unit specified explicitly, |
| 82 |
for example <literal>'120 ms'</literal> for a time value, and they will be |
| 83 |
converted to whatever the parameter's actual unit is. Note that the |
| 84 |
value must be written as a string (with quotes) to use this feature. |
| 85 |
The unit name is case-sensitive, and there can be whitespace between |
| 86 |
the numeric value and the unit. |
| 87 |
|
| 88 |
<itemizedlist> |
| 89 |
<listitem> |
| 90 |
<para> |
| 91 |
Valid memory units are <literal>B</literal> (bytes), |
| 92 |
<literal>kB</literal> (kilobytes), |
| 93 |
<literal>MB</literal> (megabytes), <literal>GB</literal> |
| 94 |
(gigabytes), and <literal>TB</literal> (terabytes). |
| 95 |
The multiplier for memory units is 1024, not 1000. |
| 96 |
</para> |
| 97 |
</listitem> |
| 98 |
|
| 99 |
<listitem> |
| 100 |
<para> |
| 101 |
Valid time units are |
| 102 |
<literal>us</literal> (microseconds), |
| 103 |
<literal>ms</literal> (milliseconds), |
| 104 |
<literal>s</literal> (seconds), <literal>min</literal> (minutes), |
| 105 |
<literal>h</literal> (hours), and <literal>d</literal> (days). |
| 106 |
</para> |
| 107 |
</listitem> |
| 108 |
</itemizedlist> |
| 109 |
|
| 110 |
If a fractional value is specified with a unit, it will be rounded |
| 111 |
to a multiple of the next smaller unit if there is one. |
| 112 |
For example, <literal>30.1 GB</literal> will be converted |
| 113 |
to <literal>30822 MB</literal> not <literal>32319628902 B</literal>. |
| 114 |
If the parameter is of integer type, a final rounding to integer |
| 115 |
occurs after any unit conversion. |
| 116 |
</para> |
| 117 |
</listitem> |
| 118 |
|
| 119 |
<listitem> |
| 120 |
<para> |
| 121 |
<emphasis>Enumerated:</emphasis> |
| 122 |
Enumerated-type parameters are written in the same way as string |
| 123 |
parameters, but are restricted to have one of a limited set of |
| 124 |
values. The values allowable for such a parameter can be found from |
| 125 |
<structname>pg_settings</structname>.<structfield>enumvals</structfield>. |
| 126 |
Enum parameter values are case-insensitive. |
| 127 |
</para> |
| 128 |
</listitem> |
| 129 |
</itemizedlist> |
| 130 |
</sect2> |
| 131 |
|
| 132 |
<sect2 id="config-setting-configuration-file"> |
| 133 |
<title>Parameter Interaction via the Configuration File</title> |
| 134 |
|
| 135 |
<para> |
| 136 |
The most fundamental way to set these parameters is to edit the file |
| 137 |
<filename>postgresql.conf</filename><indexterm><primary>postgresql.conf</primary></indexterm>, |
| 138 |
which is normally kept in the data directory. A default copy is |
| 139 |
installed when the database cluster directory is initialized. |
| 140 |
An example of what this file might look like is: |
| 141 |
<programlisting> |
| 142 |
# This is a comment |
| 143 |
log_connections = all |
| 144 |
log_destination = 'syslog' |
| 145 |
search_path = '"$user", public' |
| 146 |
shared_buffers = 128MB |
| 147 |
</programlisting> |
| 148 |
One parameter is specified per line. The equal sign between name and |
| 149 |
value is optional. Whitespace is insignificant (except within a quoted |
| 150 |
parameter value) and blank lines are |
| 151 |
ignored. Hash marks (<literal>#</literal>) designate the remainder |
| 152 |
of the line as a comment. Parameter values that are not simple |
| 153 |
identifiers or numbers must be single-quoted. To embed a single |
| 154 |
quote in a parameter value, write either two quotes (preferred) |
| 155 |
or backslash-quote. |
| 156 |
If the file contains multiple entries for the same parameter, |
| 157 |
all but the last one are ignored. |
| 158 |
</para> |
| 159 |
|
| 160 |
<para> |
| 161 |
Parameters set in this way provide default values for the cluster. |
| 162 |
The settings seen by active sessions will be these values unless they |
| 163 |
are overridden. The following sections describe ways in which the |
| 164 |
administrator or user can override these defaults. |
| 165 |
</para> |
| 166 |
|
| 167 |
<para> |
| 168 |
<indexterm> |
| 169 |
<primary>SIGHUP</primary> |
| 170 |
</indexterm> |
| 171 |
The configuration file is reread whenever the main server process |
| 172 |
receives a <systemitem>SIGHUP</systemitem> signal; this signal is most easily |
| 173 |
sent by running <literal>pg_ctl reload</literal> from the command line or by |
| 174 |
calling the SQL function <function>pg_reload_conf()</function>. The main |
| 175 |
server process also propagates this signal to all currently running |
| 176 |
server processes, so that existing sessions also adopt the new values |
| 177 |
(this will happen after they complete any currently-executing client |
| 178 |
command). Alternatively, you can |
| 179 |
send the signal to a single server process directly. Some parameters |
| 180 |
can only be set at server start; any changes to their entries in the |
| 181 |
configuration file will be ignored until the server is restarted. |
| 182 |
Invalid parameter settings in the configuration file are likewise |
| 183 |
ignored (but logged) during <systemitem>SIGHUP</systemitem> processing. |
| 184 |
</para> |
| 185 |
|
| 186 |
<para> |
| 187 |
In addition to <filename>postgresql.conf</filename>, |
| 188 |
a <productname>PostgreSQL</productname> data directory contains a file |
| 189 |
<filename>postgresql.auto.conf</filename><indexterm><primary>postgresql.auto.conf</primary></indexterm>, |
| 190 |
which has the same format as <filename>postgresql.conf</filename> but |
| 191 |
is intended to be edited automatically, not manually. This file holds |
| 192 |
settings provided through the <link linkend="sql-altersystem"><command>ALTER SYSTEM</command></link> command. |
| 193 |
This file is read whenever <filename>postgresql.conf</filename> is, |
| 194 |
and its settings take effect in the same way. Settings |
| 195 |
in <filename>postgresql.auto.conf</filename> override those |
| 196 |
in <filename>postgresql.conf</filename>. |
| 197 |
</para> |
| 198 |
|
| 199 |
<para> |
| 200 |
External tools may also |
| 201 |
modify <filename>postgresql.auto.conf</filename>. It is not |
| 202 |
recommended to do this while the server is running unless <xref |
| 203 |
linkend="guc-allow-alter-system"/> is set to <literal>off</literal>, since a |
| 204 |
concurrent <command>ALTER SYSTEM</command> command could overwrite |
| 205 |
such changes. Such tools might simply append new settings to the end, |
| 206 |
or they might choose to remove duplicate settings and/or comments |
| 207 |
(as <command>ALTER SYSTEM</command> will). |
| 208 |
</para> |
| 209 |
|
| 210 |
<para> |
| 211 |
The system view |
| 212 |
<link linkend="view-pg-file-settings"><structname>pg_file_settings</structname></link> |
| 213 |
can be helpful for pre-testing changes to the configuration files, or for |
| 214 |
diagnosing problems if a <systemitem>SIGHUP</systemitem> signal did not have the |
| 215 |
desired effects. |
| 216 |
</para> |
| 217 |
</sect2> |
| 218 |
|
| 219 |
<sect2 id="config-setting-sql"> |
| 220 |
<title>Parameter Interaction via SQL</title> |
| 221 |
|
| 222 |
<para> |
| 223 |
<productname>PostgreSQL</productname> provides three SQL |
| 224 |
commands to establish configuration defaults. |
| 225 |
The already-mentioned <command>ALTER SYSTEM</command> command |
| 226 |
provides an SQL-accessible means of changing global defaults; it is |
| 227 |
functionally equivalent to editing <filename>postgresql.conf</filename>. |
| 228 |
In addition, there are two commands that allow setting of defaults |
| 229 |
on a per-database or per-role basis: |
| 230 |
</para> |
| 231 |
|
| 232 |
<itemizedlist> |
| 233 |
<listitem> |
| 234 |
<para> |
| 235 |
The <link linkend="sql-alterdatabase"><command>ALTER DATABASE</command></link> command allows global |
| 236 |
settings to be overridden on a per-database basis. |
| 237 |
</para> |
| 238 |
</listitem> |
| 239 |
|
| 240 |
<listitem> |
| 241 |
<para> |
| 242 |
The <link linkend="sql-alterrole"><command>ALTER ROLE</command></link> command allows both global and |
| 243 |
per-database settings to be overridden with user-specific values. |
| 244 |
</para> |
| 245 |
</listitem> |
| 246 |
</itemizedlist> |
| 247 |
|
| 248 |
<para> |
| 249 |
Values set with <command>ALTER DATABASE</command> and <command>ALTER ROLE</command> |
| 250 |
are applied only when starting a fresh database session. They |
| 251 |
override values obtained from the configuration files or server |
| 252 |
command line, and constitute defaults for the rest of the session. |
| 253 |
Note that some settings cannot be changed after server start, and |
| 254 |
so cannot be set with these commands (or the ones listed below). |
| 255 |
</para> |
| 256 |
|
| 257 |
<para> |
| 258 |
Once a client is connected to the database, <productname>PostgreSQL</productname> |
| 259 |
provides two additional SQL commands (and equivalent functions) to |
| 260 |
interact with session-local configuration settings: |
| 261 |
</para> |
| 262 |
|
| 263 |
<itemizedlist> |
| 264 |
<listitem> |
| 265 |
<para> |
| 266 |
The <link linkend="sql-show"><command>SHOW</command></link> command allows inspection of the |
| 267 |
current value of any parameter. The corresponding SQL function is |
| 268 |
<function>current_setting(setting_name text)</function> |
| 269 |
(see <xref linkend="functions-admin-set"/>). |
| 270 |
</para> |
| 271 |
</listitem> |
| 272 |
|
| 273 |
<listitem> |
| 274 |
<para> |
| 275 |
The <link linkend="sql-set"><command>SET</command></link> command allows modification of the |
| 276 |
current value of those parameters that can be set locally to a |
| 277 |
session; it has no effect on other sessions. |
| 278 |
Many parameters can be set this way by any user, but some can |
| 279 |
only be set by superusers and users who have been |
| 280 |
granted <literal>SET</literal> privilege on that parameter. |
| 281 |
The corresponding SQL function is |
| 282 |
<function>set_config(setting_name, new_value, is_local)</function> |
| 283 |
(see <xref linkend="functions-admin-set"/>). |
| 284 |
</para> |
| 285 |
</listitem> |
| 286 |
</itemizedlist> |
| 287 |
|
| 288 |
<para> |
| 289 |
In addition, the system view <link |
| 290 |
linkend="view-pg-settings"><structname>pg_settings</structname></link> can be |
| 291 |
used to view and change session-local values: |
| 292 |
</para> |
| 293 |
|
| 294 |
<itemizedlist> |
| 295 |
<listitem> |
| 296 |
<para> |
| 297 |
Querying this view is similar to using <command>SHOW ALL</command> but |
| 298 |
provides more detail. It is also more flexible, since it's possible |
| 299 |
to specify filter conditions or join against other relations. |
| 300 |
</para> |
| 301 |
</listitem> |
| 302 |
|
| 303 |
<listitem> |
| 304 |
<para> |
| 305 |
Using <command>UPDATE</command> on this view, specifically |
| 306 |
updating the <structname>setting</structname> column, is the equivalent |
| 307 |
of issuing <command>SET</command> commands. For example, the equivalent of |
| 308 |
<programlisting> |
| 309 |
SET configuration_parameter TO DEFAULT; |
| 310 |
</programlisting> |
| 311 |
is: |
| 312 |
<programlisting> |
| 313 |
UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter'; |
| 314 |
</programlisting> |
| 315 |
</para> |
| 316 |
</listitem> |
| 317 |
</itemizedlist> |
| 318 |
|
| 319 |
</sect2> |
| 320 |
|
| 321 |
<sect2 id="config-setting-shell"> |
| 322 |
<title>Parameter Interaction via the Shell</title> |
| 323 |
|
| 324 |
<para> |
| 325 |
In addition to setting global defaults or attaching |
| 326 |
overrides at the database or role level, you can pass settings to |
| 327 |
<productname>PostgreSQL</productname> via shell facilities. |
| 328 |
Both the server and <application>libpq</application> client library |
| 329 |
accept parameter values via the shell. |
| 330 |
</para> |
| 331 |
|
| 332 |
<itemizedlist> |
| 333 |
<listitem> |
| 334 |
<para> |
| 335 |
During server startup, parameter settings can be |
| 336 |
passed to the <command>postgres</command> command via the |
| 337 |
<option>-c name=value</option> command-line parameter, or its equivalent |
| 338 |
<option>--name=value</option> variation. For example, |
| 339 |
<programlisting> |
| 340 |
postgres -c log_connections=all --log-destination='syslog' |
| 341 |
</programlisting> |
| 342 |
Settings provided in this way override those set via |
| 343 |
<filename>postgresql.conf</filename> or <command>ALTER SYSTEM</command>, |
| 344 |
so they cannot be changed globally without restarting the server. |
| 345 |
</para> |
| 346 |
</listitem> |
| 347 |
|
| 348 |
<listitem> |
| 349 |
<para> |
| 350 |
When starting a client session via <application>libpq</application>, |
| 351 |
parameter settings can be |
| 352 |
specified using the <envar>PGOPTIONS</envar> environment variable. |
| 353 |
Settings established in this way constitute defaults for the life |
| 354 |
of the session, but do not affect other sessions. |
| 355 |
For historical reasons, the format of <envar>PGOPTIONS</envar> is |
| 356 |
similar to that used when launching the <command>postgres</command> |
| 357 |
command; specifically, the <option>-c</option>, or prepended |
| 358 |
<literal>--</literal>, before the name must be specified. For example, |
| 359 |
<programlisting> |
| 360 |
env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql |
| 361 |
</programlisting> |
| 362 |
</para> |
| 363 |
|
| 364 |
<para> |
| 365 |
Other clients and libraries might provide their own mechanisms, |
| 366 |
via the shell or otherwise, that allow the user to alter session |
| 367 |
settings without direct use of SQL commands. |
| 368 |
</para> |
| 369 |
</listitem> |
| 370 |
</itemizedlist> |
| 371 |
|
| 372 |
</sect2> |
| 373 |
|
| 374 |
<sect2 id="config-includes"> |
| 375 |
<title>Managing Configuration File Contents</title> |
| 376 |
|
| 377 |
<para> |
| 378 |
<productname>PostgreSQL</productname> provides several features for breaking |
| 379 |
down complex <filename>postgresql.conf</filename> files into sub-files. |
| 380 |
These features are especially useful when managing multiple servers |
| 381 |
with related, but not identical, configurations. |
| 382 |
</para> |
| 383 |
|
| 384 |
<para> |
| 385 |
<indexterm> |
| 386 |
<primary><literal>include</literal></primary> |
| 387 |
<secondary>in configuration file</secondary> |
| 388 |
</indexterm> |
| 389 |
In addition to individual parameter settings, |
| 390 |
the <filename>postgresql.conf</filename> file can contain <firstterm>include |
| 391 |
directives</firstterm>, which specify another file to read and process as if |
| 392 |
it were inserted into the configuration file at this point. This |
| 393 |
feature allows a configuration file to be divided into physically |
| 394 |
separate parts. Include directives simply look like: |
| 395 |
<programlisting> |
| 396 |
include 'filename' |
| 397 |
</programlisting> |
| 398 |
If the file name is not an absolute path, it is taken as relative to |
| 399 |
the directory containing the referencing configuration file. |
| 400 |
Inclusions can be nested. |
| 401 |
</para> |
| 402 |
|
| 403 |
<para> |
| 404 |
<indexterm> |
| 405 |
<primary><literal>include_if_exists</literal></primary> |
| 406 |
<secondary>in configuration file</secondary> |
| 407 |
</indexterm> |
| 408 |
There is also an <literal>include_if_exists</literal> directive, which acts |
| 409 |
the same as the <literal>include</literal> directive, except |
| 410 |
when the referenced file does not exist or cannot be read. A regular |
| 411 |
<literal>include</literal> will consider this an error condition, but |
| 412 |
<literal>include_if_exists</literal> merely logs a message and continues |
| 413 |
processing the referencing configuration file. |
| 414 |
</para> |
| 415 |
|
| 416 |
<para> |
| 417 |
<indexterm> |
| 418 |
<primary><literal>include_dir</literal></primary> |
| 419 |
<secondary>in configuration file</secondary> |
| 420 |
</indexterm> |
| 421 |
The <filename>postgresql.conf</filename> file can also contain |
| 422 |
<literal>include_dir</literal> directives, which specify an entire |
| 423 |
directory of configuration files to include. These look like |
| 424 |
<programlisting> |
| 425 |
include_dir 'directory' |
| 426 |
</programlisting> |
| 427 |
Non-absolute directory names are taken as relative to the directory |
| 428 |
containing the referencing configuration file. Within the specified |
| 429 |
directory, only non-directory files whose names end with the |
| 430 |
suffix <literal>.conf</literal> will be included. File names that |
| 431 |
start with the <literal>.</literal> character are also ignored, to |
| 432 |
prevent mistakes since such files are hidden on some platforms. Multiple |
| 433 |
files within an include directory are processed in file name order |
| 434 |
(according to C locale rules, i.e., numbers before letters, and |
| 435 |
uppercase letters before lowercase ones). |
| 436 |
</para> |
| 437 |
|
| 438 |
<para> |
| 439 |
Include files or directories can be used to logically separate portions |
| 440 |
of the database configuration, rather than having a single large |
| 441 |
<filename>postgresql.conf</filename> file. Consider a company that has two |
| 442 |
database servers, each with a different amount of memory. There are |
| 443 |
likely elements of the configuration both will share, for things such |
| 444 |
as logging. But memory-related parameters on the server will vary |
| 445 |
between the two. And there might be server specific customizations, |
| 446 |
too. One way to manage this situation is to break the custom |
| 447 |
configuration changes for your site into three files. You could add |
| 448 |
this to the end of your <filename>postgresql.conf</filename> file to include |
| 449 |
them: |
| 450 |
<programlisting> |
| 451 |
include 'shared.conf' |
| 452 |
include 'memory.conf' |
| 453 |
include 'server.conf' |
| 454 |
</programlisting> |
| 455 |
All systems would have the same <filename>shared.conf</filename>. Each |
| 456 |
server with a particular amount of memory could share the |
| 457 |
same <filename>memory.conf</filename>; you might have one for all servers |
| 458 |
with 8GB of RAM, another for those having 16GB. And |
| 459 |
finally <filename>server.conf</filename> could have truly server-specific |
| 460 |
configuration information in it. |
| 461 |
</para> |
| 462 |
|
| 463 |
<para> |
| 464 |
Another possibility is to create a configuration file directory and |
| 465 |
put this information into files there. For example, a <filename>conf.d</filename> |
| 466 |
directory could be referenced at the end of <filename>postgresql.conf</filename>: |
| 467 |
<programlisting> |
| 468 |
include_dir 'conf.d' |
| 469 |
</programlisting> |
| 470 |
Then you could name the files in the <filename>conf.d</filename> directory |
| 471 |
like this: |
| 472 |
<programlisting> |
| 473 |
00shared.conf |
| 474 |
01memory.conf |
| 475 |
02server.conf |
| 476 |
</programlisting> |
| 477 |
This naming convention establishes a clear order in which these |
| 478 |
files will be loaded. This is important because only the last |
| 479 |
setting encountered for a particular parameter while the server is |
| 480 |
reading configuration files will be used. In this example, |
| 481 |
something set in <filename>conf.d/02server.conf</filename> would override a |
| 482 |
value set in <filename>conf.d/01memory.conf</filename>. |
| 483 |
</para> |
| 484 |
|
| 485 |
<para> |
| 486 |
You might instead use this approach to naming the files |
| 487 |
descriptively: |
| 488 |
<programlisting> |
| 489 |
00shared.conf |
| 490 |
01memory-8GB.conf |
| 491 |
02server-foo.conf |
| 492 |
</programlisting> |
| 493 |
This sort of arrangement gives a unique name for each configuration file |
| 494 |
variation. This can help eliminate ambiguity when several servers have |
| 495 |
their configurations all stored in one place, such as in a version |
| 496 |
control repository. (Storing database configuration files under version |
| 497 |
control is another good practice to consider.) |
| 498 |
</para> |
| 499 |
</sect2> |
| 500 |
</sect1> |
| 501 |
|
| 502 |
<sect1 id="runtime-config-file-locations"> |
| 503 |
<title>File Locations</title> |
| 504 |
|
| 505 |
<para> |
| 506 |
In addition to the <filename>postgresql.conf</filename> file |
| 507 |
already mentioned, <productname>PostgreSQL</productname> uses |
| 508 |
two other manually-edited configuration files, which control |
| 509 |
client authentication (their use is discussed in <xref |
| 510 |
linkend="client-authentication"/>). By default, all three |
| 511 |
configuration files are stored in the database cluster's data |
| 512 |
directory. The parameters described in this section allow the |
| 513 |
configuration files to be placed elsewhere. (Doing so can ease |
| 514 |
administration. In particular it is often easier to ensure that |
| 515 |
the configuration files are properly backed-up when they are |
| 516 |
kept separate.) |
| 517 |
</para> |
| 518 |
|
| 519 |
<variablelist> |
| 520 |
<varlistentry id="guc-data-directory" xreflabel="data_directory"> |
| 521 |
<term><varname>data_directory</varname> (<type>string</type>) |
| 522 |
<indexterm> |
| 523 |
<primary><varname>data_directory</varname> configuration parameter</primary> |
| 524 |
</indexterm> |
| 525 |
</term> |
| 526 |
<listitem> |
| 527 |
<para> |
| 528 |
Specifies the directory to use for data storage. |
| 529 |
This parameter can only be set at server start. |
| 530 |
</para> |
| 531 |
</listitem> |
| 532 |
</varlistentry> |
| 533 |
|
| 534 |
<varlistentry id="guc-config-file" xreflabel="config_file"> |
| 535 |
<term><varname>config_file</varname> (<type>string</type>) |
| 536 |
<indexterm> |
| 537 |
<primary><varname>config_file</varname> configuration parameter</primary> |
| 538 |
</indexterm> |
| 539 |
</term> |
| 540 |
<listitem> |
| 541 |
<para> |
| 542 |
Specifies the main server configuration file |
| 543 |
(customarily called <filename>postgresql.conf</filename>). |
| 544 |
This parameter can only be set on the <command>postgres</command> command line. |
| 545 |
</para> |
| 546 |
</listitem> |
| 547 |
</varlistentry> |
| 548 |
|
| 549 |
<varlistentry id="guc-hba-file" xreflabel="hba_file"> |
| 550 |
<term><varname>hba_file</varname> (<type>string</type>) |
| 551 |
<indexterm> |
| 552 |
<primary><varname>hba_file</varname> configuration parameter</primary> |
| 553 |
</indexterm> |
| 554 |
</term> |
| 555 |
<listitem> |
| 556 |
<para> |
| 557 |
Specifies the configuration file for host-based authentication |
| 558 |
(customarily called <filename>pg_hba.conf</filename>). |
| 559 |
This parameter can only be set at server start. |
| 560 |
</para> |
| 561 |
</listitem> |
| 562 |
</varlistentry> |
| 563 |
|
| 564 |
<varlistentry id="guc-ident-file" xreflabel="ident_file"> |
| 565 |
<term><varname>ident_file</varname> (<type>string</type>) |
| 566 |
<indexterm> |
| 567 |
<primary><varname>ident_file</varname> configuration parameter</primary> |
| 568 |
</indexterm> |
| 569 |
</term> |
| 570 |
<listitem> |
| 571 |
<para> |
| 572 |
Specifies the configuration file for user name mapping |
| 573 |
(customarily called <filename>pg_ident.conf</filename>). |
| 574 |
This parameter can only be set at server start. |
| 575 |
See also <xref linkend="auth-username-maps"/>. |
| 576 |
</para> |
| 577 |
</listitem> |
| 578 |
</varlistentry> |
| 579 |
|
| 580 |
<varlistentry id="guc-external-pid-file" xreflabel="external_pid_file"> |
| 581 |
<term><varname>external_pid_file</varname> (<type>string</type>) |
| 582 |
<indexterm> |
| 583 |
<primary><varname>external_pid_file</varname> configuration parameter</primary> |
| 584 |
</indexterm> |
| 585 |
</term> |
| 586 |
<listitem> |
| 587 |
<para> |
| 588 |
Specifies the name of an additional process-ID (PID) file that the |
| 589 |
server should create for use by server administration programs. |
| 590 |
This parameter can only be set at server start. |
| 591 |
</para> |
| 592 |
</listitem> |
| 593 |
</varlistentry> |
| 594 |
</variablelist> |
| 595 |
|
| 596 |
<para> |
| 597 |
In a default installation, none of the above parameters are set |
| 598 |
explicitly. Instead, the |
| 599 |
data directory is specified by the <option>-D</option> command-line |
| 600 |
option or the <envar>PGDATA</envar> environment variable, and the |
| 601 |
configuration files are all found within the data directory. |
| 602 |
</para> |
| 603 |
|
| 604 |
<para> |
| 605 |
If you wish to keep the configuration files elsewhere than the |
| 606 |
data directory, the <command>postgres</command> <option>-D</option> |
| 607 |
command-line option or <envar>PGDATA</envar> environment variable |
| 608 |
must point to the directory containing the configuration files, |
| 609 |
and the <varname>data_directory</varname> parameter must be set in |
| 610 |
<filename>postgresql.conf</filename> (or on the command line) to show |
| 611 |
where the data directory is actually located. Notice that |
| 612 |
<varname>data_directory</varname> overrides <option>-D</option> and |
| 613 |
<envar>PGDATA</envar> for the location |
| 614 |
of the data directory, but not for the location of the configuration |
| 615 |
files. |
| 616 |
</para> |
| 617 |
|
| 618 |
<para> |
| 619 |
If you wish, you can specify the configuration file names and locations |
| 620 |
individually using the parameters <varname>config_file</varname>, |
| 621 |
<varname>hba_file</varname> and/or <varname>ident_file</varname>. |
| 622 |
<varname>config_file</varname> can only be specified on the |
| 623 |
<command>postgres</command> command line, but the others can be |
| 624 |
set within the main configuration file. If all three parameters plus |
| 625 |
<varname>data_directory</varname> are explicitly set, then it is not necessary |
| 626 |
to specify <option>-D</option> or <envar>PGDATA</envar>. |
| 627 |
</para> |
| 628 |
|
| 629 |
<para> |
| 630 |
When setting any of these parameters, a relative path will be interpreted |
| 631 |
with respect to the directory in which <command>postgres</command> |
| 632 |
is started. |
| 633 |
</para> |
| 634 |
</sect1> |
| 635 |
|
| 636 |
<sect1 id="runtime-config-connection"> |
| 637 |
<title>Connections and Authentication</title> |
| 638 |
|
| 639 |
<sect2 id="runtime-config-connection-settings"> |
| 640 |
<title>Connection Settings</title> |
| 641 |
|
| 642 |
<variablelist> |
| 643 |
|
| 644 |
<varlistentry id="guc-listen-addresses" xreflabel="listen_addresses"> |
| 645 |
<term><varname>listen_addresses</varname> (<type>string</type>) |
| 646 |
<indexterm> |
| 647 |
<primary><varname>listen_addresses</varname> configuration parameter</primary> |
| 648 |
</indexterm> |
| 649 |
</term> |
| 650 |
<listitem> |
| 651 |
<para> |
| 652 |
Specifies the TCP/IP address(es) on which the server is |
| 653 |
to listen for connections from client applications. |
| 654 |
The value takes the form of a comma-separated list of host names |
| 655 |
and/or numeric IP addresses. The special entry <literal>*</literal> |
| 656 |
corresponds to all available IP interfaces. The entry |
| 657 |
<literal>0.0.0.0</literal> allows listening for all IPv4 addresses and |
| 658 |
<literal>::</literal> allows listening for all IPv6 addresses. |
| 659 |
If the list is empty, the server does not listen on any IP interface |
| 660 |
at all, in which case only Unix-domain sockets can be used to connect |
| 661 |
to it. If the list is not empty, the server will start if it |
| 662 |
can listen on at least one TCP/IP address. A warning will be |
| 663 |
emitted for any TCP/IP address which cannot be opened. |
| 664 |
The default value is <systemitem class="systemname">localhost</systemitem>, |
| 665 |
which allows only local TCP/IP <quote>loopback</quote> connections to be |
| 666 |
made. |
| 667 |
</para> |
| 668 |
<para> |
| 669 |
While client authentication (<xref |
| 670 |
linkend="client-authentication"/>) allows fine-grained control |
| 671 |
over who can access the server, <varname>listen_addresses</varname> |
| 672 |
controls which interfaces accept connection attempts, which |
| 673 |
can help prevent repeated malicious connection requests on |
| 674 |
insecure network interfaces. This parameter can only be set |
| 675 |
at server start. |
| 676 |
</para> |
| 677 |
</listitem> |
| 678 |
</varlistentry> |
| 679 |
|
| 680 |
<varlistentry id="guc-port" xreflabel="port"> |
| 681 |
<term><varname>port</varname> (<type>integer</type>) |
| 682 |
<indexterm> |
| 683 |
<primary><varname>port</varname> configuration parameter</primary> |
| 684 |
</indexterm> |
| 685 |
</term> |
| 686 |
<listitem> |
| 687 |
<para> |
| 688 |
The TCP port the server listens on; 5432 by default. Note that the |
| 689 |
same port number is used for all IP addresses the server listens on. |
| 690 |
This parameter can only be set at server start. |
| 691 |
</para> |
| 692 |
</listitem> |
| 693 |
</varlistentry> |
| 694 |
|
| 695 |
<varlistentry id="guc-max-connections" xreflabel="max_connections"> |
| 696 |
<term><varname>max_connections</varname> (<type>integer</type>) |
| 697 |
<indexterm> |
| 698 |
<primary><varname>max_connections</varname> configuration parameter</primary> |
| 699 |
</indexterm> |
| 700 |
</term> |
| 701 |
<listitem> |
| 702 |
<para> |
| 703 |
Determines the maximum number of concurrent connections to the |
| 704 |
database server. The default is typically 100 connections, but |
| 705 |
might be less if your kernel settings will not support it (as |
| 706 |
determined during <application>initdb</application>). This parameter can |
| 707 |
only be set at server start. |
| 708 |
</para> |
| 709 |
|
| 710 |
<para> |
| 711 |
<productname>PostgreSQL</productname> sizes certain resources based directly on the value of |
| 712 |
<varname>max_connections</varname>. Increasing its value leads to |
| 713 |
higher allocation of those resources, including shared memory. |
| 714 |
</para> |
| 715 |
|
| 716 |
<para> |
| 717 |
When running a standby server, you must set this parameter to the |
| 718 |
same or higher value than on the primary server. Otherwise, queries |
| 719 |
will not be allowed in the standby server. |
| 720 |
</para> |
| 721 |
</listitem> |
| 722 |
</varlistentry> |
| 723 |
|
| 724 |
<varlistentry id="guc-reserved-connections" xreflabel="reserved_connections"> |
| 725 |
<term><varname>reserved_connections</varname> (<type>integer</type>) |
| 726 |
<indexterm> |
| 727 |
<primary><varname>reserved_connections</varname> configuration parameter</primary> |
| 728 |
</indexterm> |
| 729 |
</term> |
| 730 |
<listitem> |
| 731 |
<para> |
| 732 |
Determines the number of connection <quote>slots</quote> that are |
| 733 |
reserved for connections by roles with privileges of the |
| 734 |
<xref linkend="predefined-role-pg-use-reserved-connections"/> |
| 735 |
role. Whenever the number of free connection slots is greater than |
| 736 |
<xref linkend="guc-superuser-reserved-connections"/> but less than or |
| 737 |
equal to the sum of <varname>superuser_reserved_connections</varname> |
| 738 |
and <varname>reserved_connections</varname>, new connections will be |
| 739 |
accepted only for superusers and roles with privileges of |
| 740 |
<literal>pg_use_reserved_connections</literal>. If |
| 741 |
<varname>superuser_reserved_connections</varname> or fewer connection |
| 742 |
slots are available, new connections will be accepted only for |
| 743 |
superusers. |
| 744 |
</para> |
| 745 |
|
| 746 |
<para> |
| 747 |
The default value is zero connections. The value must be less than |
| 748 |
<varname>max_connections</varname> minus |
| 749 |
<varname>superuser_reserved_connections</varname>. This parameter can |
| 750 |
only be set at server start. |
| 751 |
</para> |
| 752 |
</listitem> |
| 753 |
</varlistentry> |
| 754 |
|
| 755 |
<varlistentry id="guc-superuser-reserved-connections" |
| 756 |
xreflabel="superuser_reserved_connections"> |
| 757 |
<term><varname>superuser_reserved_connections</varname> |
| 758 |
(<type>integer</type>) |
| 759 |
<indexterm> |
| 760 |
<primary><varname>superuser_reserved_connections</varname> configuration parameter</primary> |
| 761 |
</indexterm> |
| 762 |
</term> |
| 763 |
<listitem> |
| 764 |
<para> |
| 765 |
Determines the number of connection <quote>slots</quote> that |
| 766 |
are reserved for connections by <productname>PostgreSQL</productname> |
| 767 |
superusers. At most <xref linkend="guc-max-connections"/> |
| 768 |
connections can ever be active simultaneously. Whenever the |
| 769 |
number of active concurrent connections is at least |
| 770 |
<varname>max_connections</varname> minus |
| 771 |
<varname>superuser_reserved_connections</varname>, new |
| 772 |
connections will be accepted only for superusers. The connection slots |
| 773 |
reserved by this parameter are intended as final reserve for emergency |
| 774 |
use after the slots reserved by |
| 775 |
<xref linkend="guc-reserved-connections"/> have been exhausted. |
| 776 |
</para> |
| 777 |
|
| 778 |
<para> |
| 779 |
The default value is three connections. The value must be less |
| 780 |
than <varname>max_connections</varname> minus |
| 781 |
<varname>reserved_connections</varname>. |
| 782 |
This parameter can only be set at server start. |
| 783 |
</para> |
| 784 |
</listitem> |
| 785 |
</varlistentry> |
| 786 |
|
| 787 |
<varlistentry id="guc-unix-socket-directories" xreflabel="unix_socket_directories"> |
| 788 |
<term><varname>unix_socket_directories</varname> (<type>string</type>) |
| 789 |
<indexterm> |
| 790 |
<primary><varname>unix_socket_directories</varname> configuration parameter</primary> |
| 791 |
</indexterm> |
| 792 |
</term> |
| 793 |
<listitem> |
| 794 |
<para> |
| 795 |
Specifies the directory of the Unix-domain socket(s) on which the |
| 796 |
server is to listen for connections from client applications. |
| 797 |
Multiple sockets can be created by listing multiple directories |
| 798 |
separated by commas. Whitespace between entries is |
| 799 |
ignored; surround a directory name with double quotes if you need |
| 800 |
to include whitespace or commas in the name. |
| 801 |
An empty value |
| 802 |
specifies not listening on any Unix-domain sockets, in which case |
| 803 |
only TCP/IP sockets can be used to connect to the server. |
| 804 |
</para> |
| 805 |
|
| 806 |
<para> |
| 807 |
A value that starts with <literal>@</literal> specifies that a |
| 808 |
Unix-domain socket in the abstract namespace should be created |
| 809 |
(currently supported on Linux only). In that case, this value |
| 810 |
does not specify a <quote>directory</quote> but a prefix from which |
| 811 |
the actual socket name is computed in the same manner as for the |
| 812 |
file-system namespace. While the abstract socket name prefix can be |
| 813 |
chosen freely, since it is not a file-system location, the convention |
| 814 |
is to nonetheless use file-system-like values such as |
| 815 |
<literal>@/tmp</literal>. |
| 816 |
</para> |
| 817 |
|
| 818 |
<para> |
| 819 |
The default value is normally |
| 820 |
<filename>/tmp</filename>, but that can be changed at build time. |
| 821 |
On Windows, the default is empty, which means no Unix-domain socket is |
| 822 |
created by default. |
| 823 |
This parameter can only be set at server start. |
| 824 |
</para> |
| 825 |
|
| 826 |
<para> |
| 827 |
In addition to the socket file itself, which is named |
| 828 |
<literal>.s.PGSQL.<replaceable>nnnn</replaceable></literal> where |
| 829 |
<replaceable>nnnn</replaceable> is the server's port number, an ordinary file |
| 830 |
named <literal>.s.PGSQL.<replaceable>nnnn</replaceable>.lock</literal> will be |
| 831 |
created in each of the <varname>unix_socket_directories</varname> directories. |
| 832 |
Neither file should ever be removed manually. |
| 833 |
For sockets in the abstract namespace, no lock file is created. |
| 834 |
</para> |
| 835 |
</listitem> |
| 836 |
</varlistentry> |
| 837 |
|
| 838 |
<varlistentry id="guc-unix-socket-group" xreflabel="unix_socket_group"> |
| 839 |
<term><varname>unix_socket_group</varname> (<type>string</type>) |
| 840 |
<indexterm> |
| 841 |
<primary><varname>unix_socket_group</varname> configuration parameter</primary> |
| 842 |
</indexterm> |
| 843 |
</term> |
| 844 |
<listitem> |
| 845 |
<para> |
| 846 |
Sets the owning group of the Unix-domain socket(s). (The owning |
| 847 |
user of the sockets is always the user that starts the |
| 848 |
server.) In combination with the parameter |
| 849 |
<varname>unix_socket_permissions</varname> this can be used as |
| 850 |
an additional access control mechanism for Unix-domain connections. |
| 851 |
By default this is the empty string, which uses the default |
| 852 |
group of the server user. This parameter can only be set at |
| 853 |
server start. |
| 854 |
</para> |
| 855 |
|
| 856 |
<para> |
| 857 |
This parameter is not supported on Windows. Any setting will be |
| 858 |
ignored. Also, sockets in the abstract namespace have no file owner, |
| 859 |
so this setting is also ignored in that case. |
| 860 |
</para> |
| 861 |
</listitem> |
| 862 |
</varlistentry> |
| 863 |
|
| 864 |
<varlistentry id="guc-unix-socket-permissions" xreflabel="unix_socket_permissions"> |
| 865 |
<term><varname>unix_socket_permissions</varname> (<type>integer</type>) |
| 866 |
<indexterm> |
| 867 |
<primary><varname>unix_socket_permissions</varname> configuration parameter</primary> |
| 868 |
</indexterm> |
| 869 |
</term> |
| 870 |
<listitem> |
| 871 |
<para> |
| 872 |
Sets the access permissions of the Unix-domain socket(s). Unix-domain |
| 873 |
sockets use the usual Unix file system permission set. |
| 874 |
The parameter value is expected to be a numeric mode |
| 875 |
specified in the format accepted by the |
| 876 |
<function>chmod</function> and <function>umask</function> |
| 877 |
system calls. (To use the customary octal format the number |
| 878 |
must start with a <literal>0</literal> (zero).) |
| 879 |
</para> |
| 880 |
|
| 881 |
<para> |
| 882 |
The default permissions are <literal>0777</literal>, meaning |
| 883 |
anyone can connect. Reasonable alternatives are |
| 884 |
<literal>0770</literal> (only user and group, see also |
| 885 |
<varname>unix_socket_group</varname>) and <literal>0700</literal> |
| 886 |
(only user). (Note that for a Unix-domain socket, only write |
| 887 |
permission matters, so there is no point in setting or revoking |
| 888 |
read or execute permissions.) |
| 889 |
</para> |
| 890 |
|
| 891 |
<para> |
| 892 |
This access control mechanism is independent of the one |
| 893 |
described in <xref linkend="client-authentication"/>. |
| 894 |
</para> |
| 895 |
|
| 896 |
<para> |
| 897 |
This parameter can only be set at server start. |
| 898 |
</para> |
| 899 |
|
| 900 |
<para> |
| 901 |
This parameter is irrelevant on systems, notably Solaris as of Solaris |
| 902 |
10, that ignore socket permissions entirely. There, one can achieve a |
| 903 |
similar effect by pointing <varname>unix_socket_directories</varname> to a |
| 904 |
directory having search permission limited to the desired audience. |
| 905 |
</para> |
| 906 |
|
| 907 |
<para> |
| 908 |
Sockets in the abstract namespace have no file permissions, so this |
| 909 |
setting is also ignored in that case. |
| 910 |
</para> |
| 911 |
</listitem> |
| 912 |
</varlistentry> |
| 913 |
|
| 914 |
<varlistentry id="guc-bonjour" xreflabel="bonjour"> |
| 915 |
<term><varname>bonjour</varname> (<type>boolean</type>) |
| 916 |
<indexterm> |
| 917 |
<primary><varname>bonjour</varname> configuration parameter</primary> |
| 918 |
</indexterm> |
| 919 |
</term> |
| 920 |
<listitem> |
| 921 |
<para> |
| 922 |
Enables advertising the server's existence via |
| 923 |
<productname>Bonjour</productname>. The default is off. |
| 924 |
This parameter can only be set at server start. |
| 925 |
</para> |
| 926 |
</listitem> |
| 927 |
</varlistentry> |
| 928 |
|
| 929 |
<varlistentry id="guc-bonjour-name" xreflabel="bonjour_name"> |
| 930 |
<term><varname>bonjour_name</varname> (<type>string</type>) |
| 931 |
<indexterm> |
| 932 |
<primary><varname>bonjour_name</varname> configuration parameter</primary> |
| 933 |
</indexterm> |
| 934 |
</term> |
| 935 |
<listitem> |
| 936 |
<para> |
| 937 |
Specifies the <productname>Bonjour</productname> service |
| 938 |
name. The computer name is used if this parameter is set to the |
| 939 |
empty string <literal>''</literal> (which is the default). This parameter is |
| 940 |
ignored if the server was not compiled with |
| 941 |
<productname>Bonjour</productname> support. |
| 942 |
This parameter can only be set at server start. |
| 943 |
</para> |
| 944 |
</listitem> |
| 945 |
</varlistentry> |
| 946 |
</variablelist> |
| 947 |
</sect2> |
| 948 |
|
| 949 |
<sect2 id="runtime-config-tcp-settings"> |
| 950 |
<title>TCP Settings</title> |
| 951 |
|
| 952 |
<variablelist> |
| 953 |
|
| 954 |
<varlistentry id="guc-tcp-keepalives-idle" xreflabel="tcp_keepalives_idle"> |
| 955 |
<term><varname>tcp_keepalives_idle</varname> (<type>integer</type>) |
| 956 |
<indexterm> |
| 957 |
<primary><varname>tcp_keepalives_idle</varname> configuration parameter</primary> |
| 958 |
</indexterm> |
| 959 |
</term> |
| 960 |
<listitem> |
| 961 |
<para> |
| 962 |
Specifies the amount of time with no network activity after which |
| 963 |
the operating system should send a TCP keepalive message to the client. |
| 964 |
If this value is specified without units, it is taken as seconds. |
| 965 |
A value of 0 (the default) selects the operating system's default. |
| 966 |
On Windows, setting a value of 0 will set this parameter to 2 hours, |
| 967 |
since Windows does not provide a way to read the system default value. |
| 968 |
This parameter is supported only on systems that support |
| 969 |
<symbol>TCP_KEEPIDLE</symbol> or an equivalent socket option, and on |
| 970 |
Windows; on other systems, it must be zero. |
| 971 |
In sessions connected via a Unix-domain socket, this parameter is |
| 972 |
ignored and always reads as zero. |
| 973 |
</para> |
| 974 |
</listitem> |
| 975 |
</varlistentry> |
| 976 |
|
| 977 |
<varlistentry id="guc-tcp-keepalives-interval" xreflabel="tcp_keepalives_interval"> |
| 978 |
<term><varname>tcp_keepalives_interval</varname> (<type>integer</type>) |
| 979 |
<indexterm> |
| 980 |
<primary><varname>tcp_keepalives_interval</varname> configuration parameter</primary> |
| 981 |
</indexterm> |
| 982 |
</term> |
| 983 |
<listitem> |
| 984 |
<para> |
| 985 |
Specifies the amount of time after which a TCP keepalive message |
| 986 |
that has not been acknowledged by the client should be retransmitted. |
| 987 |
If this value is specified without units, it is taken as seconds. |
| 988 |
A value of 0 (the default) selects the operating system's default. |
| 989 |
On Windows, setting a value of 0 will set this parameter to 1 second, |
| 990 |
since Windows does not provide a way to read the system default value. |
| 991 |
This parameter is supported only on systems that support |
| 992 |
<symbol>TCP_KEEPINTVL</symbol> or an equivalent socket option, and on |
| 993 |
Windows; on other systems, it must be zero. |
| 994 |
In sessions connected via a Unix-domain socket, this parameter is |
| 995 |
ignored and always reads as zero. |
| 996 |
</para> |
| 997 |
</listitem> |
| 998 |
</varlistentry> |
| 999 |
|
| 1000 |
<varlistentry id="guc-tcp-keepalives-count" xreflabel="tcp_keepalives_count"> |
| 1001 |
<term><varname>tcp_keepalives_count</varname> (<type>integer</type>) |
| 1002 |
<indexterm> |
| 1003 |
<primary><varname>tcp_keepalives_count</varname> configuration parameter</primary> |
| 1004 |
</indexterm> |
| 1005 |
</term> |
| 1006 |
<listitem> |
| 1007 |
<para> |
| 1008 |
Specifies the number of TCP keepalive messages that can be lost before |
| 1009 |
the server's connection to the client is considered dead. |
| 1010 |
A value of 0 (the default) selects the operating system's default. |
| 1011 |
This parameter is supported only on systems that support |
| 1012 |
<symbol>TCP_KEEPCNT</symbol> or an equivalent socket option (which does not include Windows); |
| 1013 |
on other systems, it must be zero. |
| 1014 |
In sessions connected via a Unix-domain socket, this parameter is |
| 1015 |
ignored and always reads as zero. |
| 1016 |
</para> |
| 1017 |
</listitem> |
| 1018 |
</varlistentry> |
| 1019 |
|
| 1020 |
<varlistentry id="guc-tcp-user-timeout" xreflabel="tcp_user_timeout"> |
| 1021 |
<term><varname>tcp_user_timeout</varname> (<type>integer</type>) |
| 1022 |
<indexterm> |
| 1023 |
<primary><varname>tcp_user_timeout</varname> configuration parameter</primary> |
| 1024 |
</indexterm> |
| 1025 |
</term> |
| 1026 |
<listitem> |
| 1027 |
<para> |
| 1028 |
Specifies the amount of time that transmitted data may |
| 1029 |
remain unacknowledged before the TCP connection is forcibly closed. |
| 1030 |
If this value is specified without units, it is taken as milliseconds. |
| 1031 |
A value of 0 (the default) selects the operating system's default. |
| 1032 |
This parameter is supported only on systems that support |
| 1033 |
<symbol>TCP_USER_TIMEOUT</symbol> (which does not include Windows); on other systems, it must be zero. |
| 1034 |
In sessions connected via a Unix-domain socket, this parameter is |
| 1035 |
ignored and always reads as zero. |
| 1036 |
</para> |
| 1037 |
</listitem> |
| 1038 |
</varlistentry> |
| 1039 |
|
| 1040 |
<varlistentry id="guc-client-connection-check-interval" xreflabel="client_connection_check_interval"> |
| 1041 |
<term><varname>client_connection_check_interval</varname> (<type>integer</type>) |
| 1042 |
<indexterm> |
| 1043 |
<primary><varname>client_connection_check_interval</varname> configuration parameter</primary> |
| 1044 |
</indexterm> |
| 1045 |
</term> |
| 1046 |
<listitem> |
| 1047 |
<para> |
| 1048 |
Sets the time interval between optional checks that the client is still |
| 1049 |
connected, while running queries. The check is performed by polling |
| 1050 |
the socket, and allows long running queries to be aborted sooner if |
| 1051 |
the kernel reports that the connection is closed. |
| 1052 |
</para> |
| 1053 |
<para> |
| 1054 |
This option relies on kernel events exposed by Linux, macOS, illumos |
| 1055 |
and the BSD family of operating systems, and is not currently available |
| 1056 |
on other systems. |
| 1057 |
</para> |
| 1058 |
<para> |
| 1059 |
If the value is specified without units, it is taken as milliseconds. |
| 1060 |
The default value is <literal>0</literal>, which disables connection |
| 1061 |
checks. Without connection checks, the server will detect the loss of |
| 1062 |
the connection only at the next interaction with the socket, when it |
| 1063 |
waits for, receives or sends data. |
| 1064 |
</para> |
| 1065 |
<para> |
| 1066 |
For the kernel itself to detect lost TCP connections reliably and within |
| 1067 |
a known timeframe in all scenarios including network failure, it may |
| 1068 |
also be necessary to adjust the TCP keepalive settings of the operating |
| 1069 |
system, or the <xref linkend="guc-tcp-keepalives-idle"/>, |
| 1070 |
<xref linkend="guc-tcp-keepalives-interval"/> and |
| 1071 |
<xref linkend="guc-tcp-keepalives-count"/> settings of |
| 1072 |
<productname>PostgreSQL</productname>. |
| 1073 |
</para> |
| 1074 |
</listitem> |
| 1075 |
</varlistentry> |
| 1076 |
|
| 1077 |
</variablelist> |
| 1078 |
</sect2> |
| 1079 |
|
| 1080 |
<sect2 id="runtime-config-connection-authentication"> |
| 1081 |
<title>Authentication</title> |
| 1082 |
|
| 1083 |
<variablelist> |
| 1084 |
<varlistentry id="guc-authentication-timeout" xreflabel="authentication_timeout"> |
| 1085 |
<term><varname>authentication_timeout</varname> (<type>integer</type>) |
| 1086 |
<indexterm><primary>timeout</primary><secondary>client authentication</secondary></indexterm> |
| 1087 |
<indexterm><primary>client authentication</primary><secondary>timeout during</secondary></indexterm> |
| 1088 |
<indexterm> |
| 1089 |
<primary><varname>authentication_timeout</varname> configuration parameter</primary> |
| 1090 |
</indexterm> |
| 1091 |
</term> |
| 1092 |
|
| 1093 |
<listitem> |
| 1094 |
<para> |
| 1095 |
Maximum amount of time allowed to complete client authentication. If a |
| 1096 |
would-be client has not completed the authentication protocol in |
| 1097 |
this much time, the server closes the connection. This prevents |
| 1098 |
hung clients from occupying a connection indefinitely. |
| 1099 |
If this value is specified without units, it is taken as seconds. |
| 1100 |
The default is one minute (<literal>1m</literal>). |
| 1101 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1102 |
file or on the server command line. |
| 1103 |
</para> |
| 1104 |
</listitem> |
| 1105 |
</varlistentry> |
| 1106 |
|
| 1107 |
<varlistentry id="guc-password-encryption" xreflabel="password_encryption"> |
| 1108 |
<term><varname>password_encryption</varname> (<type>enum</type>) |
| 1109 |
<indexterm> |
| 1110 |
<primary><varname>password_encryption</varname> configuration parameter</primary> |
| 1111 |
</indexterm> |
| 1112 |
</term> |
| 1113 |
<listitem> |
| 1114 |
<para> |
| 1115 |
When a password is specified in <xref linkend="sql-createrole"/> or |
| 1116 |
<xref linkend="sql-alterrole"/>, this parameter determines the |
| 1117 |
algorithm to use to encrypt the password. Possible values are |
| 1118 |
<literal>scram-sha-256</literal>, which will encrypt the password with |
| 1119 |
SCRAM-SHA-256, and <literal>md5</literal>, which stores the password |
| 1120 |
as an MD5 hash. The default is <literal>scram-sha-256</literal>. |
| 1121 |
</para> |
| 1122 |
<para> |
| 1123 |
Note that older clients might lack support for the SCRAM authentication |
| 1124 |
mechanism, and hence not work with passwords encrypted with |
| 1125 |
SCRAM-SHA-256. See <xref linkend="auth-password"/> for more details. |
| 1126 |
</para> |
| 1127 |
<warning> |
| 1128 |
<para> |
| 1129 |
Support for MD5-encrypted passwords is deprecated and will be removed |
| 1130 |
in a future release of <productname>PostgreSQL</productname>. Refer |
| 1131 |
to <xref linkend="auth-password"/> for details about migrating to |
| 1132 |
another password type. |
| 1133 |
</para> |
| 1134 |
</warning> |
| 1135 |
</listitem> |
| 1136 |
</varlistentry> |
| 1137 |
|
| 1138 |
<varlistentry id="guc-scram-iterations" xreflabel="scram_iterations"> |
| 1139 |
<term><varname>scram_iterations</varname> (<type>integer</type>) |
| 1140 |
<indexterm> |
| 1141 |
<primary><varname>scram_iterations</varname> configuration parameter</primary> |
| 1142 |
</indexterm> |
| 1143 |
</term> |
| 1144 |
<listitem> |
| 1145 |
<para> |
| 1146 |
The number of computational iterations to be performed when encrypting |
| 1147 |
a password using SCRAM-SHA-256. The default is <literal>4096</literal>. |
| 1148 |
A higher number of iterations provides additional protection against |
| 1149 |
brute-force attacks on stored passwords, but makes authentication |
| 1150 |
slower. Changing the value has no effect on existing passwords |
| 1151 |
encrypted with SCRAM-SHA-256 as the iteration count is fixed at the |
| 1152 |
time of encryption. In order to make use of a changed value, a new |
| 1153 |
password must be set. |
| 1154 |
</para> |
| 1155 |
<note> |
| 1156 |
<para> |
| 1157 |
If a role password was created with a different iteration count than |
| 1158 |
the value of <literal>scram_iterations</literal> specified in the |
| 1159 |
<filename>postgresql.conf</filename> file or on the server command |
| 1160 |
line, an unauthenticated user can discern the existence of the role by |
| 1161 |
observing discrepancies in the server's responses to connection |
| 1162 |
attempts. If you find this concerning, ensure that all role passwords |
| 1163 |
are created with <literal>scram_iterations</literal> set to the value |
| 1164 |
specified in the <filename>postgresql.conf</filename> file or on the |
| 1165 |
server command line. |
| 1166 |
</para> |
| 1167 |
</note> |
| 1168 |
</listitem> |
| 1169 |
</varlistentry> |
| 1170 |
|
| 1171 |
<varlistentry id="guc-md5-password-warnings" xreflabel="md5_password_warnings"> |
| 1172 |
<term><varname>md5_password_warnings</varname> (<type>boolean</type>) |
| 1173 |
<indexterm> |
| 1174 |
<primary><varname>md5_password_warnings</varname> configuration parameter</primary> |
| 1175 |
</indexterm> |
| 1176 |
</term> |
| 1177 |
<listitem> |
| 1178 |
<para> |
| 1179 |
Controls whether a <literal>WARNING</literal> about MD5 password |
| 1180 |
deprecation is produced when a <command>CREATE ROLE</command> or |
| 1181 |
<command>ALTER ROLE</command> statement sets an MD5-encrypted password. |
| 1182 |
The default value is <literal>on</literal>. |
| 1183 |
</para> |
| 1184 |
</listitem> |
| 1185 |
</varlistentry> |
| 1186 |
|
| 1187 |
<varlistentry id="guc-krb-server-keyfile" xreflabel="krb_server_keyfile"> |
| 1188 |
<term><varname>krb_server_keyfile</varname> (<type>string</type>) |
| 1189 |
<indexterm> |
| 1190 |
<primary><varname>krb_server_keyfile</varname> configuration parameter</primary> |
| 1191 |
</indexterm> |
| 1192 |
</term> |
| 1193 |
<listitem> |
| 1194 |
<para> |
| 1195 |
Sets the location of the server's Kerberos key file. The default is |
| 1196 |
<filename>FILE:/usr/local/pgsql/etc/krb5.keytab</filename> |
| 1197 |
(where the directory part is whatever was specified |
| 1198 |
as <varname>sysconfdir</varname> at build time; use |
| 1199 |
<literal>pg_config --sysconfdir</literal> to determine that). |
| 1200 |
If this parameter is set to an empty string, it is ignored and a |
| 1201 |
system-dependent default is used. |
| 1202 |
This parameter can only be set in the |
| 1203 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 1204 |
See <xref linkend="gssapi-auth"/> for more information. |
| 1205 |
</para> |
| 1206 |
</listitem> |
| 1207 |
</varlistentry> |
| 1208 |
|
| 1209 |
<varlistentry id="guc-krb-caseins-users" xreflabel="krb_caseins_users"> |
| 1210 |
<term><varname>krb_caseins_users</varname> (<type>boolean</type>) |
| 1211 |
<indexterm> |
| 1212 |
<primary><varname>krb_caseins_users</varname> configuration parameter</primary> |
| 1213 |
</indexterm> |
| 1214 |
</term> |
| 1215 |
<listitem> |
| 1216 |
<para> |
| 1217 |
Sets whether GSSAPI user names should be treated |
| 1218 |
case-insensitively. |
| 1219 |
The default is <literal>off</literal> (case sensitive). This parameter can only be |
| 1220 |
set in the <filename>postgresql.conf</filename> file or on the server command line. |
| 1221 |
</para> |
| 1222 |
</listitem> |
| 1223 |
</varlistentry> |
| 1224 |
|
| 1225 |
<varlistentry id="guc-gss-accept-delegation" xreflabel="gss_accept_delegation"> |
| 1226 |
<term><varname>gss_accept_delegation</varname> (<type>boolean</type>) |
| 1227 |
<indexterm> |
| 1228 |
<primary><varname>gss_accept_delegation</varname> configuration parameter</primary> |
| 1229 |
</indexterm> |
| 1230 |
</term> |
| 1231 |
<listitem> |
| 1232 |
<para> |
| 1233 |
Sets whether GSSAPI delegation should be accepted from the client. |
| 1234 |
The default is <literal>off</literal> meaning credentials from the client will |
| 1235 |
<emphasis>not</emphasis> be accepted. Changing this to <literal>on</literal> will make the server |
| 1236 |
accept credentials delegated to it from the client. This parameter can only be |
| 1237 |
set in the <filename>postgresql.conf</filename> file or on the server command line. |
| 1238 |
</para> |
| 1239 |
</listitem> |
| 1240 |
</varlistentry> |
| 1241 |
|
| 1242 |
<varlistentry id="guc-oauth-validator-libraries" xreflabel="oauth_validator_libraries"> |
| 1243 |
<term><varname>oauth_validator_libraries</varname> (<type>string</type>) |
| 1244 |
<indexterm> |
| 1245 |
<primary><varname>oauth_validator_libraries</varname> configuration parameter</primary> |
| 1246 |
</indexterm> |
| 1247 |
</term> |
| 1248 |
<listitem> |
| 1249 |
<para> |
| 1250 |
The library/libraries to use for validating OAuth connection tokens. If |
| 1251 |
only one validator library is provided, it will be used by default for |
| 1252 |
any OAuth connections; otherwise, all |
| 1253 |
<link linkend="auth-oauth"><literal>oauth</literal> HBA entries</link> |
| 1254 |
must explicitly set a <literal>validator</literal> chosen from this |
| 1255 |
list. If set to an empty string (the default), OAuth connections will be |
| 1256 |
refused. This parameter can only be set in the |
| 1257 |
<filename>postgresql.conf</filename> file. |
| 1258 |
</para> |
| 1259 |
<para> |
| 1260 |
Validator modules must be implemented/obtained separately; |
| 1261 |
<productname>PostgreSQL</productname> does not ship with any default |
| 1262 |
implementations. For more information on implementing OAuth validators, |
| 1263 |
see <xref linkend="oauth-validators" />. |
| 1264 |
</para> |
| 1265 |
</listitem> |
| 1266 |
</varlistentry> |
| 1267 |
</variablelist> |
| 1268 |
</sect2> |
| 1269 |
|
| 1270 |
<sect2 id="runtime-config-connection-ssl"> |
| 1271 |
<title>SSL</title> |
| 1272 |
|
| 1273 |
<para> |
| 1274 |
See <xref linkend="ssl-tcp"/> for more information about setting up |
| 1275 |
<acronym>SSL</acronym>. The configuration parameters for controlling |
| 1276 |
transfer encryption using <acronym>TLS</acronym> protocols are named |
| 1277 |
<literal>ssl</literal> for historic reasons, even though support for |
| 1278 |
the <acronym>SSL</acronym> protocol has been deprecated. |
| 1279 |
<acronym>SSL</acronym> is in this context used interchangeably with |
| 1280 |
<acronym>TLS</acronym>. |
| 1281 |
</para> |
| 1282 |
|
| 1283 |
<variablelist> |
| 1284 |
<varlistentry id="guc-ssl" xreflabel="ssl"> |
| 1285 |
<term><varname>ssl</varname> (<type>boolean</type>) |
| 1286 |
<indexterm> |
| 1287 |
<primary><varname>ssl</varname> configuration parameter</primary> |
| 1288 |
</indexterm> |
| 1289 |
</term> |
| 1290 |
<listitem> |
| 1291 |
<para> |
| 1292 |
Enables <acronym>SSL</acronym> connections. |
| 1293 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1294 |
file or on the server command line. |
| 1295 |
The default is <literal>off</literal>. |
| 1296 |
</para> |
| 1297 |
</listitem> |
| 1298 |
</varlistentry> |
| 1299 |
|
| 1300 |
<varlistentry id="guc-ssl-ca-file" xreflabel="ssl_ca_file"> |
| 1301 |
<term><varname>ssl_ca_file</varname> (<type>string</type>) |
| 1302 |
<indexterm> |
| 1303 |
<primary><varname>ssl_ca_file</varname> configuration parameter</primary> |
| 1304 |
</indexterm> |
| 1305 |
</term> |
| 1306 |
<listitem> |
| 1307 |
<para> |
| 1308 |
Specifies the name of the file containing the SSL server certificate |
| 1309 |
authority (CA). |
| 1310 |
Relative paths are relative to the data directory. |
| 1311 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1312 |
file or on the server command line. |
| 1313 |
The default is empty, meaning no CA file is loaded, |
| 1314 |
and client certificate verification is not performed. |
| 1315 |
</para> |
| 1316 |
</listitem> |
| 1317 |
</varlistentry> |
| 1318 |
|
| 1319 |
<varlistentry id="guc-ssl-cert-file" xreflabel="ssl_cert_file"> |
| 1320 |
<term><varname>ssl_cert_file</varname> (<type>string</type>) |
| 1321 |
<indexterm> |
| 1322 |
<primary><varname>ssl_cert_file</varname> configuration parameter</primary> |
| 1323 |
</indexterm> |
| 1324 |
</term> |
| 1325 |
<listitem> |
| 1326 |
<para> |
| 1327 |
Specifies the name of the file containing the SSL server certificate. |
| 1328 |
Relative paths are relative to the data directory. |
| 1329 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1330 |
file or on the server command line. |
| 1331 |
The default is <filename>server.crt</filename>. |
| 1332 |
</para> |
| 1333 |
</listitem> |
| 1334 |
</varlistentry> |
| 1335 |
|
| 1336 |
<varlistentry id="guc-ssl-crl-file" xreflabel="ssl_crl_file"> |
| 1337 |
<term><varname>ssl_crl_file</varname> (<type>string</type>) |
| 1338 |
<indexterm> |
| 1339 |
<primary><varname>ssl_crl_file</varname> configuration parameter</primary> |
| 1340 |
</indexterm> |
| 1341 |
</term> |
| 1342 |
<listitem> |
| 1343 |
<para> |
| 1344 |
Specifies the name of the file containing the SSL client certificate |
| 1345 |
revocation list (CRL). |
| 1346 |
Relative paths are relative to the data directory. |
| 1347 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1348 |
file or on the server command line. |
| 1349 |
The default is empty, meaning no CRL file is loaded (unless |
| 1350 |
<xref linkend="guc-ssl-crl-dir"/> is set). |
| 1351 |
</para> |
| 1352 |
</listitem> |
| 1353 |
</varlistentry> |
| 1354 |
|
| 1355 |
<varlistentry id="guc-ssl-crl-dir" xreflabel="ssl_crl_dir"> |
| 1356 |
<term><varname>ssl_crl_dir</varname> (<type>string</type>) |
| 1357 |
<indexterm> |
| 1358 |
<primary><varname>ssl_crl_dir</varname> configuration parameter</primary> |
| 1359 |
</indexterm> |
| 1360 |
</term> |
| 1361 |
<listitem> |
| 1362 |
<para> |
| 1363 |
Specifies the name of the directory containing the SSL client |
| 1364 |
certificate revocation list (CRL). Relative paths are relative to the |
| 1365 |
data directory. This parameter can only be set in |
| 1366 |
the <filename>postgresql.conf</filename> file or on the server command |
| 1367 |
line. The default is empty, meaning no CRLs are used (unless |
| 1368 |
<xref linkend="guc-ssl-crl-file"/> is set). |
| 1369 |
</para> |
| 1370 |
|
| 1371 |
<para> |
| 1372 |
The directory needs to be prepared with the |
| 1373 |
<productname>OpenSSL</productname> command |
| 1374 |
<literal>openssl rehash</literal> or <literal>c_rehash</literal>. See |
| 1375 |
its documentation for details. |
| 1376 |
</para> |
| 1377 |
|
| 1378 |
<para> |
| 1379 |
When using this setting, CRLs in the specified directory are loaded |
| 1380 |
on-demand at connection time. New CRLs can be added to the directory |
| 1381 |
and will be used immediately. This is unlike <xref |
| 1382 |
linkend="guc-ssl-crl-file"/>, which causes the CRL in the file to be |
| 1383 |
loaded at server start time or when the configuration is reloaded. |
| 1384 |
Both settings can be used together. |
| 1385 |
</para> |
| 1386 |
</listitem> |
| 1387 |
</varlistentry> |
| 1388 |
|
| 1389 |
<varlistentry id="guc-ssl-key-file" xreflabel="ssl_key_file"> |
| 1390 |
<term><varname>ssl_key_file</varname> (<type>string</type>) |
| 1391 |
<indexterm> |
| 1392 |
<primary><varname>ssl_key_file</varname> configuration parameter</primary> |
| 1393 |
</indexterm> |
| 1394 |
</term> |
| 1395 |
<listitem> |
| 1396 |
<para> |
| 1397 |
Specifies the name of the file containing the SSL server private key. |
| 1398 |
Relative paths are relative to the data directory. |
| 1399 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1400 |
file or on the server command line. |
| 1401 |
The default is <filename>server.key</filename>. |
| 1402 |
</para> |
| 1403 |
</listitem> |
| 1404 |
</varlistentry> |
| 1405 |
|
| 1406 |
<varlistentry id="guc-ssl-tls13-ciphers" xreflabel="ssl_tls13_ciphers"> |
| 1407 |
<term><varname>ssl_tls13_ciphers</varname> (<type>string</type>) |
| 1408 |
<indexterm> |
| 1409 |
<primary><varname>ssl_tls13_ciphers</varname> configuration parameter</primary> |
| 1410 |
</indexterm> |
| 1411 |
</term> |
| 1412 |
<listitem> |
| 1413 |
<para> |
| 1414 |
Specifies a list of cipher suites that are allowed by connections using |
| 1415 |
<acronym>TLS</acronym> version 1.3. Multiple cipher suites can be |
| 1416 |
specified by using a colon separated list. If left blank, the default |
| 1417 |
set of cipher suites in <productname>OpenSSL</productname> will be used. |
| 1418 |
</para> |
| 1419 |
|
| 1420 |
<para> |
| 1421 |
This parameter can only be set in the |
| 1422 |
<filename>postgresql.conf</filename> file or on the server command |
| 1423 |
line. |
| 1424 |
</para> |
| 1425 |
</listitem> |
| 1426 |
</varlistentry> |
| 1427 |
|
| 1428 |
<varlistentry id="guc-ssl-ciphers" xreflabel="ssl_ciphers"> |
| 1429 |
<term><varname>ssl_ciphers</varname> (<type>string</type>) |
| 1430 |
<indexterm> |
| 1431 |
<primary><varname>ssl_ciphers</varname> configuration parameter</primary> |
| 1432 |
</indexterm> |
| 1433 |
</term> |
| 1434 |
<listitem> |
| 1435 |
<para> |
| 1436 |
Specifies a list of <acronym>SSL</acronym> ciphers that are allowed by |
| 1437 |
connections using TLS version 1.2 and lower, see |
| 1438 |
<xref linkend="guc-ssl-tls13-ciphers"/> for TLS version 1.3 connections. See |
| 1439 |
the <citerefentry><refentrytitle>ciphers</refentrytitle></citerefentry> |
| 1440 |
manual page in the <productname>OpenSSL</productname> package for the |
| 1441 |
syntax of this setting and a list of supported values. The default value |
| 1442 |
is <literal>HIGH:MEDIUM:+3DES:!aNULL</literal>. The default is usually a |
| 1443 |
reasonable choice unless you have specific security requirements. |
| 1444 |
</para> |
| 1445 |
|
| 1446 |
<para> |
| 1447 |
This parameter can only be set in the |
| 1448 |
<filename>postgresql.conf</filename> file or on the server command |
| 1449 |
line. |
| 1450 |
</para> |
| 1451 |
|
| 1452 |
<para> |
| 1453 |
Explanation of the default value: |
| 1454 |
<variablelist> |
| 1455 |
<varlistentry id="guc-ssl-ciphers-high"> |
| 1456 |
<term><literal>HIGH</literal></term> |
| 1457 |
<listitem> |
| 1458 |
<para> |
| 1459 |
Cipher suites that use ciphers from <literal>HIGH</literal> group (e.g., |
| 1460 |
AES, Camellia, 3DES) |
| 1461 |
</para> |
| 1462 |
</listitem> |
| 1463 |
</varlistentry> |
| 1464 |
|
| 1465 |
<varlistentry id="guc-ssl-ciphers-medium"> |
| 1466 |
<term><literal>MEDIUM</literal></term> |
| 1467 |
<listitem> |
| 1468 |
<para> |
| 1469 |
Cipher suites that use ciphers from <literal>MEDIUM</literal> group |
| 1470 |
(e.g., RC4, SEED) |
| 1471 |
</para> |
| 1472 |
</listitem> |
| 1473 |
</varlistentry> |
| 1474 |
|
| 1475 |
<varlistentry id="guc-ssl-ciphers-plus-3des"> |
| 1476 |
<term><literal>+3DES</literal></term> |
| 1477 |
<listitem> |
| 1478 |
<para> |
| 1479 |
The <productname>OpenSSL</productname> default order for |
| 1480 |
<literal>HIGH</literal> is problematic because it orders 3DES |
| 1481 |
higher than AES128. This is wrong because 3DES offers less |
| 1482 |
security than AES128, and it is also much slower. |
| 1483 |
<literal>+3DES</literal> reorders it after all other |
| 1484 |
<literal>HIGH</literal> and <literal>MEDIUM</literal> ciphers. |
| 1485 |
</para> |
| 1486 |
</listitem> |
| 1487 |
</varlistentry> |
| 1488 |
|
| 1489 |
<varlistentry id="guc-ssl-ciphers-not-anull"> |
| 1490 |
<term><literal>!aNULL</literal></term> |
| 1491 |
<listitem> |
| 1492 |
<para> |
| 1493 |
Disables anonymous cipher suites that do no authentication. Such |
| 1494 |
cipher suites are vulnerable to <acronym>MITM</acronym> attacks and |
| 1495 |
therefore should not be used. |
| 1496 |
</para> |
| 1497 |
</listitem> |
| 1498 |
</varlistentry> |
| 1499 |
</variablelist> |
| 1500 |
</para> |
| 1501 |
|
| 1502 |
<para> |
| 1503 |
Available cipher suite details will vary across |
| 1504 |
<productname>OpenSSL</productname> versions. Use the command |
| 1505 |
<literal>openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL'</literal> to |
| 1506 |
see actual details for the currently installed |
| 1507 |
<productname>OpenSSL</productname> version. Note that this list is |
| 1508 |
filtered at run time based on the server key type. |
| 1509 |
</para> |
| 1510 |
</listitem> |
| 1511 |
</varlistentry> |
| 1512 |
|
| 1513 |
<varlistentry id="guc-ssl-prefer-server-ciphers" xreflabel="ssl_prefer_server_ciphers"> |
| 1514 |
<term><varname>ssl_prefer_server_ciphers</varname> (<type>boolean</type>) |
| 1515 |
<indexterm> |
| 1516 |
<primary><varname>ssl_prefer_server_ciphers</varname> configuration parameter</primary> |
| 1517 |
</indexterm> |
| 1518 |
</term> |
| 1519 |
<listitem> |
| 1520 |
<para> |
| 1521 |
Specifies whether to use the server's SSL cipher preferences, rather |
| 1522 |
than the client's. |
| 1523 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1524 |
file or on the server command line. |
| 1525 |
The default is <literal>on</literal>. |
| 1526 |
</para> |
| 1527 |
|
| 1528 |
<para> |
| 1529 |
<productname>PostgreSQL</productname> versions before 9.4 do not have |
| 1530 |
this setting and always use the client's preferences. This setting is |
| 1531 |
mainly for backward compatibility with those versions. Using the |
| 1532 |
server's preferences is usually better because it is more likely that |
| 1533 |
the server is appropriately configured. |
| 1534 |
</para> |
| 1535 |
</listitem> |
| 1536 |
</varlistentry> |
| 1537 |
|
| 1538 |
<varlistentry id="guc-ssl-groups" xreflabel="ssl_groups"> |
| 1539 |
<term><varname>ssl_groups</varname> (<type>string</type>) |
| 1540 |
<indexterm> |
| 1541 |
<primary><varname>ssl_groups</varname> configuration parameter</primary> |
| 1542 |
</indexterm> |
| 1543 |
</term> |
| 1544 |
<listitem> |
| 1545 |
<para> |
| 1546 |
Specifies the named group to use for <acronym>TLS</acronym> key |
| 1547 |
exchange. It needs to be supported by all clients that |
| 1548 |
connect. Multiple groups can be specified by using a colon-separated |
| 1549 |
list. It does not need to match the key type used by the server |
| 1550 |
certificate. This parameter can only be set in the |
| 1551 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 1552 |
The default is <literal>X25519:prime256v1</literal>. |
| 1553 |
</para> |
| 1554 |
|
| 1555 |
<para> |
| 1556 |
<productname>OpenSSL</productname> names for the most common groups |
| 1557 |
are: |
| 1558 |
<literal>prime256v1</literal> (NIST P-256), |
| 1559 |
<literal>secp384r1</literal> (NIST P-384), |
| 1560 |
<literal>secp521r1</literal> (NIST P-521). |
| 1561 |
An incomplete list of available groups can be shown with the command |
| 1562 |
<command>openssl ecparam -list_curves</command>. Not all of them are |
| 1563 |
usable with <acronym>TLS</acronym> though, and many supported group |
| 1564 |
names and aliases are omitted. |
| 1565 |
</para> |
| 1566 |
|
| 1567 |
<para> |
| 1568 |
In <productname>PostgreSQL</productname> versions before 18.0 this |
| 1569 |
setting was named <literal>ssl_ecdh_curve</literal> and only accepted |
| 1570 |
a single value. |
| 1571 |
</para> |
| 1572 |
</listitem> |
| 1573 |
</varlistentry> |
| 1574 |
|
| 1575 |
<varlistentry id="guc-ssl-min-protocol-version" xreflabel="ssl_min_protocol_version"> |
| 1576 |
<term><varname>ssl_min_protocol_version</varname> (<type>enum</type>) |
| 1577 |
<indexterm> |
| 1578 |
<primary><varname>ssl_min_protocol_version</varname> configuration parameter</primary> |
| 1579 |
</indexterm> |
| 1580 |
</term> |
| 1581 |
<listitem> |
| 1582 |
<para> |
| 1583 |
Sets the minimum SSL/TLS protocol version to use. Valid values are |
| 1584 |
currently: <literal>TLSv1</literal>, <literal>TLSv1.1</literal>, |
| 1585 |
<literal>TLSv1.2</literal>, <literal>TLSv1.3</literal>. Older |
| 1586 |
versions of the <productname>OpenSSL</productname> library do not |
| 1587 |
support all values; an error will be raised if an unsupported setting |
| 1588 |
is chosen. Protocol versions before TLS 1.0, namely SSL version 2 and |
| 1589 |
3, are always disabled. |
| 1590 |
</para> |
| 1591 |
|
| 1592 |
<para> |
| 1593 |
The default is <literal>TLSv1.2</literal>, which satisfies industry |
| 1594 |
best practices as of this writing. |
| 1595 |
</para> |
| 1596 |
|
| 1597 |
<para> |
| 1598 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1599 |
file or on the server command line. |
| 1600 |
</para> |
| 1601 |
</listitem> |
| 1602 |
</varlistentry> |
| 1603 |
|
| 1604 |
<varlistentry id="guc-ssl-max-protocol-version" xreflabel="ssl_max_protocol_version"> |
| 1605 |
<term><varname>ssl_max_protocol_version</varname> (<type>enum</type>) |
| 1606 |
<indexterm> |
| 1607 |
<primary><varname>ssl_max_protocol_version</varname> configuration parameter</primary> |
| 1608 |
</indexterm> |
| 1609 |
</term> |
| 1610 |
<listitem> |
| 1611 |
<para> |
| 1612 |
Sets the maximum SSL/TLS protocol version to use. Valid values are as |
| 1613 |
for <xref linkend="guc-ssl-min-protocol-version"/>, with addition of |
| 1614 |
an empty string, which allows any protocol version. The default is to |
| 1615 |
allow any version. Setting the maximum protocol version is mainly |
| 1616 |
useful for testing or if some component has issues working with a |
| 1617 |
newer protocol. |
| 1618 |
</para> |
| 1619 |
|
| 1620 |
<para> |
| 1621 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1622 |
file or on the server command line. |
| 1623 |
</para> |
| 1624 |
</listitem> |
| 1625 |
</varlistentry> |
| 1626 |
|
| 1627 |
<varlistentry id="guc-ssl-dh-params-file" xreflabel="ssl_dh_params_file"> |
| 1628 |
<term><varname>ssl_dh_params_file</varname> (<type>string</type>) |
| 1629 |
<indexterm> |
| 1630 |
<primary><varname>ssl_dh_params_file</varname> configuration parameter</primary> |
| 1631 |
</indexterm> |
| 1632 |
</term> |
| 1633 |
<listitem> |
| 1634 |
<para> |
| 1635 |
Specifies the name of the file containing Diffie-Hellman parameters |
| 1636 |
used for so-called ephemeral DH family of SSL ciphers. The default is |
| 1637 |
empty, in which case compiled-in default DH parameters used. Using |
| 1638 |
custom DH parameters reduces the exposure if an attacker manages to |
| 1639 |
crack the well-known compiled-in DH parameters. You can create your own |
| 1640 |
DH parameters file with the command |
| 1641 |
<command>openssl dhparam -out dhparams.pem 2048</command>. |
| 1642 |
</para> |
| 1643 |
|
| 1644 |
<para> |
| 1645 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1646 |
file or on the server command line. |
| 1647 |
</para> |
| 1648 |
</listitem> |
| 1649 |
</varlistentry> |
| 1650 |
|
| 1651 |
<varlistentry id="guc-ssl-passphrase-command" xreflabel="ssl_passphrase_command"> |
| 1652 |
<term><varname>ssl_passphrase_command</varname> (<type>string</type>) |
| 1653 |
<indexterm> |
| 1654 |
<primary><varname>ssl_passphrase_command</varname> configuration parameter</primary> |
| 1655 |
</indexterm> |
| 1656 |
</term> |
| 1657 |
<listitem> |
| 1658 |
<para> |
| 1659 |
Sets an external command to be invoked when a passphrase for |
| 1660 |
decrypting an SSL file such as a private key needs to be obtained. By |
| 1661 |
default, this parameter is empty, which means the built-in prompting |
| 1662 |
mechanism is used. |
| 1663 |
</para> |
| 1664 |
<para> |
| 1665 |
The command must print the passphrase to the standard output and exit |
| 1666 |
with code 0. In the parameter value, <literal>%p</literal> is |
| 1667 |
replaced by a prompt string. (Write <literal>%%</literal> for a |
| 1668 |
literal <literal>%</literal>.) Note that the prompt string will |
| 1669 |
probably contain whitespace, so be sure to quote adequately. A single |
| 1670 |
newline is stripped from the end of the output if present. |
| 1671 |
</para> |
| 1672 |
<para> |
| 1673 |
The command does not actually have to prompt the user for a |
| 1674 |
passphrase. It can read it from a file, obtain it from a keychain |
| 1675 |
facility, or similar. It is up to the user to make sure the chosen |
| 1676 |
mechanism is adequately secure. |
| 1677 |
</para> |
| 1678 |
<para> |
| 1679 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1680 |
file or on the server command line. |
| 1681 |
</para> |
| 1682 |
</listitem> |
| 1683 |
</varlistentry> |
| 1684 |
|
| 1685 |
<varlistentry id="guc-ssl-passphrase-command-supports-reload" xreflabel="ssl_passphrase_command_supports_reload"> |
| 1686 |
<term><varname>ssl_passphrase_command_supports_reload</varname> (<type>boolean</type>) |
| 1687 |
<indexterm> |
| 1688 |
<primary><varname>ssl_passphrase_command_supports_reload</varname> configuration parameter</primary> |
| 1689 |
</indexterm> |
| 1690 |
</term> |
| 1691 |
<listitem> |
| 1692 |
<para> |
| 1693 |
This parameter determines whether the passphrase command set by |
| 1694 |
<varname>ssl_passphrase_command</varname> will also be called during a |
| 1695 |
configuration reload if a key file needs a passphrase. If this |
| 1696 |
parameter is <literal>off</literal> (the default), then |
| 1697 |
<varname>ssl_passphrase_command</varname> will be ignored during a |
| 1698 |
reload and the SSL configuration will not be reloaded if a passphrase |
| 1699 |
is needed. That setting is appropriate for a command that requires a |
| 1700 |
TTY for prompting, which might not be available when the server is |
| 1701 |
running. Setting this parameter to on might be appropriate if the |
| 1702 |
passphrase is obtained from a file, for example. |
| 1703 |
</para> |
| 1704 |
<para> |
| 1705 |
This parameter must be set to <literal>on</literal> when running on |
| 1706 |
<systemitem class="osname">Windows</systemitem> since all connections |
| 1707 |
will perform a configuration reload due to the different process model |
| 1708 |
of that platform. |
| 1709 |
</para> |
| 1710 |
<para> |
| 1711 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 1712 |
file or on the server command line. |
| 1713 |
</para> |
| 1714 |
</listitem> |
| 1715 |
</varlistentry> |
| 1716 |
</variablelist> |
| 1717 |
</sect2> |
| 1718 |
</sect1> |
| 1719 |
|
| 1720 |
<sect1 id="runtime-config-resource"> |
| 1721 |
<title>Resource Consumption</title> |
| 1722 |
|
| 1723 |
<sect2 id="runtime-config-resource-memory"> |
| 1724 |
<title>Memory</title> |
| 1725 |
|
| 1726 |
<variablelist> |
| 1727 |
<varlistentry id="guc-shared-buffers" xreflabel="shared_buffers"> |
| 1728 |
<term><varname>shared_buffers</varname> (<type>integer</type>) |
| 1729 |
<indexterm> |
| 1730 |
<primary><varname>shared_buffers</varname> configuration parameter</primary> |
| 1731 |
</indexterm> |
| 1732 |
</term> |
| 1733 |
<listitem> |
| 1734 |
<para> |
| 1735 |
Sets the amount of memory the database server uses for shared |
| 1736 |
memory buffers. The default is typically 128 megabytes |
| 1737 |
(<literal>128MB</literal>), but might be less if your kernel settings will |
| 1738 |
not support it (as determined during <application>initdb</application>). |
| 1739 |
This setting must be at least 128 kilobytes. However, |
| 1740 |
settings significantly higher than the minimum are usually needed |
| 1741 |
for good performance. |
| 1742 |
If this value is specified without units, it is taken as blocks, |
| 1743 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 1744 |
(Non-default values of <symbol>BLCKSZ</symbol> change the minimum |
| 1745 |
value.) |
| 1746 |
This parameter can only be set at server start. |
| 1747 |
</para> |
| 1748 |
|
| 1749 |
<para> |
| 1750 |
If you have a dedicated database server with 1GB or more of RAM, a |
| 1751 |
reasonable starting value for <varname>shared_buffers</varname> is 25% |
| 1752 |
of the memory in your system. There are some workloads where even |
| 1753 |
larger settings for <varname>shared_buffers</varname> are effective, but |
| 1754 |
because <productname>PostgreSQL</productname> also relies on the |
| 1755 |
operating system cache, it is unlikely that an allocation of more than |
| 1756 |
40% of RAM to <varname>shared_buffers</varname> will work better than a |
| 1757 |
smaller amount. Larger settings for <varname>shared_buffers</varname> |
| 1758 |
usually require a corresponding increase in |
| 1759 |
<varname>max_wal_size</varname>, in order to spread out the |
| 1760 |
process of writing large quantities of new or changed data over a |
| 1761 |
longer period of time. |
| 1762 |
</para> |
| 1763 |
|
| 1764 |
<para> |
| 1765 |
On systems with less than 1GB of RAM, a smaller percentage of RAM is |
| 1766 |
appropriate, so as to leave adequate space for the operating system. |
| 1767 |
</para> |
| 1768 |
|
| 1769 |
</listitem> |
| 1770 |
</varlistentry> |
| 1771 |
|
| 1772 |
<varlistentry id="guc-huge-pages" xreflabel="huge_pages"> |
| 1773 |
<term><varname>huge_pages</varname> (<type>enum</type>) |
| 1774 |
<indexterm> |
| 1775 |
<primary><varname>huge_pages</varname> configuration parameter</primary> |
| 1776 |
</indexterm> |
| 1777 |
</term> |
| 1778 |
<listitem> |
| 1779 |
<para> |
| 1780 |
Controls whether huge pages are requested for the main shared memory |
| 1781 |
area. Valid values are <literal>try</literal> (the default), |
| 1782 |
<literal>on</literal>, and <literal>off</literal>. |
| 1783 |
This parameter can only be set at server start. With |
| 1784 |
<varname>huge_pages</varname> set to <literal>try</literal>, the |
| 1785 |
server will try to request huge pages, but fall back to the default if |
| 1786 |
that fails. With <literal>on</literal>, failure to request huge pages |
| 1787 |
will prevent the server from starting up. With <literal>off</literal>, |
| 1788 |
huge pages will not be requested. The actual state of huge pages is |
| 1789 |
indicated by the server variable |
| 1790 |
<xref linkend="guc-huge-pages-status"/>. |
| 1791 |
</para> |
| 1792 |
|
| 1793 |
<para> |
| 1794 |
At present, this setting is supported only on Linux and Windows. The |
| 1795 |
setting is ignored on other systems when set to |
| 1796 |
<literal>try</literal>. On Linux, it is only supported when |
| 1797 |
<varname>shared_memory_type</varname> is set to <literal>mmap</literal> |
| 1798 |
(the default). |
| 1799 |
</para> |
| 1800 |
|
| 1801 |
<para> |
| 1802 |
The use of huge pages results in smaller page tables and less CPU time |
| 1803 |
spent on memory management, increasing performance. For more details about |
| 1804 |
using huge pages on Linux, see <xref linkend="linux-huge-pages"/>. |
| 1805 |
</para> |
| 1806 |
|
| 1807 |
<para> |
| 1808 |
Huge pages are known as large pages on Windows. To use them, you need to |
| 1809 |
assign the user right <quote>Lock pages in memory</quote> to the Windows user account |
| 1810 |
that runs <productname>PostgreSQL</productname>. |
| 1811 |
You can use Windows Group Policy tool (gpedit.msc) to assign the user right |
| 1812 |
<quote>Lock pages in memory</quote>. |
| 1813 |
To start the database server on the command prompt as a standalone process, |
| 1814 |
not as a Windows service, the command prompt must be run as an administrator or |
| 1815 |
User Access Control (UAC) must be disabled. When the UAC is enabled, the normal |
| 1816 |
command prompt revokes the user right <quote>Lock pages in memory</quote> when started. |
| 1817 |
</para> |
| 1818 |
|
| 1819 |
<para> |
| 1820 |
Note that this setting only affects the main shared memory area. |
| 1821 |
Operating systems such as Linux, FreeBSD, and Illumos can also use |
| 1822 |
huge pages (also known as <quote>super</quote> pages or |
| 1823 |
<quote>large</quote> pages) automatically for normal memory |
| 1824 |
allocation, without an explicit request from |
| 1825 |
<productname>PostgreSQL</productname>. On Linux, this is called |
| 1826 |
<quote>transparent huge pages</quote><indexterm><primary>transparent |
| 1827 |
huge pages</primary></indexterm> (THP). That feature has been known to |
| 1828 |
cause performance degradation with |
| 1829 |
<productname>PostgreSQL</productname> for some users on some Linux |
| 1830 |
versions, so its use is currently discouraged (unlike explicit use of |
| 1831 |
<varname>huge_pages</varname>). |
| 1832 |
</para> |
| 1833 |
</listitem> |
| 1834 |
</varlistentry> |
| 1835 |
|
| 1836 |
<varlistentry id="guc-huge-page-size" xreflabel="huge_page_size"> |
| 1837 |
<term><varname>huge_page_size</varname> (<type>integer</type>) |
| 1838 |
<indexterm> |
| 1839 |
<primary><varname>huge_page_size</varname> configuration parameter</primary> |
| 1840 |
</indexterm> |
| 1841 |
</term> |
| 1842 |
<listitem> |
| 1843 |
<para> |
| 1844 |
Controls the size of huge pages, when they are enabled with |
| 1845 |
<xref linkend="guc-huge-pages"/>. |
| 1846 |
The default is zero (<literal>0</literal>). |
| 1847 |
When set to <literal>0</literal>, the default huge page size on the |
| 1848 |
system will be used. This parameter can only be set at server start. |
| 1849 |
</para> |
| 1850 |
<para> |
| 1851 |
Some commonly available page sizes on modern 64 bit server architectures include: |
| 1852 |
<literal>2MB</literal> and <literal>1GB</literal> (Intel and AMD), <literal>16MB</literal> and |
| 1853 |
<literal>16GB</literal> (IBM POWER), and <literal>64kB</literal>, <literal>2MB</literal>, |
| 1854 |
<literal>32MB</literal> and <literal>1GB</literal> (ARM). For more information |
| 1855 |
about usage and support, see <xref linkend="linux-huge-pages"/>. |
| 1856 |
</para> |
| 1857 |
<para> |
| 1858 |
Non-default settings are currently supported only on Linux. |
| 1859 |
</para> |
| 1860 |
</listitem> |
| 1861 |
</varlistentry> |
| 1862 |
|
| 1863 |
<varlistentry id="guc-temp-buffers" xreflabel="temp_buffers"> |
| 1864 |
<term><varname>temp_buffers</varname> (<type>integer</type>) |
| 1865 |
<indexterm> |
| 1866 |
<primary><varname>temp_buffers</varname> configuration parameter</primary> |
| 1867 |
</indexterm> |
| 1868 |
</term> |
| 1869 |
<listitem> |
| 1870 |
<para> |
| 1871 |
Sets the maximum amount of memory used for temporary buffers within |
| 1872 |
each database session. These are session-local buffers used only |
| 1873 |
for access to temporary tables. |
| 1874 |
If this value is specified without units, it is taken as blocks, |
| 1875 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 1876 |
The default is eight megabytes (<literal>8MB</literal>). |
| 1877 |
(If <symbol>BLCKSZ</symbol> is not 8kB, the default value scales |
| 1878 |
proportionally to it.) |
| 1879 |
This setting can be changed within individual |
| 1880 |
sessions, but only before the first use of temporary tables |
| 1881 |
within the session; subsequent attempts to change the value will |
| 1882 |
have no effect on that session. |
| 1883 |
</para> |
| 1884 |
|
| 1885 |
<para> |
| 1886 |
A session will allocate temporary buffers as needed up to the limit |
| 1887 |
given by <varname>temp_buffers</varname>. The cost of setting a large |
| 1888 |
value in sessions that do not actually need many temporary |
| 1889 |
buffers is only a buffer descriptor, or about 64 bytes, per |
| 1890 |
increment in <varname>temp_buffers</varname>. However if a buffer is |
| 1891 |
actually used an additional 8192 bytes will be consumed for it |
| 1892 |
(or in general, <symbol>BLCKSZ</symbol> bytes). |
| 1893 |
</para> |
| 1894 |
</listitem> |
| 1895 |
</varlistentry> |
| 1896 |
|
| 1897 |
<varlistentry id="guc-max-prepared-transactions" xreflabel="max_prepared_transactions"> |
| 1898 |
<term><varname>max_prepared_transactions</varname> (<type>integer</type>) |
| 1899 |
<indexterm> |
| 1900 |
<primary><varname>max_prepared_transactions</varname> configuration parameter</primary> |
| 1901 |
</indexterm> |
| 1902 |
</term> |
| 1903 |
<listitem> |
| 1904 |
<para> |
| 1905 |
Sets the maximum number of transactions that can be in the |
| 1906 |
<quote>prepared</quote> state simultaneously (see <xref |
| 1907 |
linkend="sql-prepare-transaction"/>). |
| 1908 |
Setting this parameter to zero (which is the default) |
| 1909 |
disables the prepared-transaction feature. |
| 1910 |
This parameter can only be set at server start. |
| 1911 |
</para> |
| 1912 |
|
| 1913 |
<para> |
| 1914 |
If you are not planning to use prepared transactions, this parameter |
| 1915 |
should be set to zero to prevent accidental creation of prepared |
| 1916 |
transactions. If you are using prepared transactions, you will |
| 1917 |
probably want <varname>max_prepared_transactions</varname> to be at |
| 1918 |
least as large as <xref linkend="guc-max-connections"/>, so that every |
| 1919 |
session can have a prepared transaction pending. |
| 1920 |
</para> |
| 1921 |
|
| 1922 |
<para> |
| 1923 |
When running a standby server, you must set this parameter to the |
| 1924 |
same or higher value than on the primary server. Otherwise, queries |
| 1925 |
will not be allowed in the standby server. |
| 1926 |
</para> |
| 1927 |
</listitem> |
| 1928 |
</varlistentry> |
| 1929 |
|
| 1930 |
<varlistentry id="guc-work-mem" xreflabel="work_mem"> |
| 1931 |
<term><varname>work_mem</varname> (<type>integer</type>) |
| 1932 |
<indexterm> |
| 1933 |
<primary><varname>work_mem</varname> configuration parameter</primary> |
| 1934 |
</indexterm> |
| 1935 |
</term> |
| 1936 |
<listitem> |
| 1937 |
<para> |
| 1938 |
Sets the base maximum amount of memory to be used by a query operation |
| 1939 |
(such as a sort or hash table) before writing to temporary disk files. |
| 1940 |
If this value is specified without units, it is taken as kilobytes. |
| 1941 |
The default value is four megabytes (<literal>4MB</literal>). |
| 1942 |
Note that a complex query might perform several sort and hash |
| 1943 |
operations at the same time, with each operation generally being |
| 1944 |
allowed to use as much memory as this value specifies before |
| 1945 |
it starts |
| 1946 |
to write data into temporary files. Also, several running |
| 1947 |
sessions could be doing such operations concurrently. |
| 1948 |
Therefore, the total memory used could be many times the value |
| 1949 |
of <varname>work_mem</varname>; it is necessary to keep this |
| 1950 |
fact in mind when choosing the value. Sort operations are used |
| 1951 |
for <literal>ORDER BY</literal>, <literal>DISTINCT</literal>, |
| 1952 |
and merge joins. |
| 1953 |
Hash tables are used in hash joins, hash-based aggregation, memoize |
| 1954 |
nodes and hash-based processing of <literal>IN</literal> subqueries. |
| 1955 |
</para> |
| 1956 |
<para> |
| 1957 |
Hash-based operations are generally more sensitive to memory |
| 1958 |
availability than equivalent sort-based operations. The |
| 1959 |
memory limit for a hash table is computed by multiplying |
| 1960 |
<varname>work_mem</varname> by |
| 1961 |
<varname>hash_mem_multiplier</varname>. This makes it |
| 1962 |
possible for hash-based operations to use an amount of memory |
| 1963 |
that exceeds the usual <varname>work_mem</varname> base |
| 1964 |
amount. |
| 1965 |
</para> |
| 1966 |
</listitem> |
| 1967 |
</varlistentry> |
| 1968 |
|
| 1969 |
<varlistentry id="guc-hash-mem-multiplier" xreflabel="hash_mem_multiplier"> |
| 1970 |
<term><varname>hash_mem_multiplier</varname> (<type>floating point</type>) |
| 1971 |
<indexterm> |
| 1972 |
<primary><varname>hash_mem_multiplier</varname> configuration parameter</primary> |
| 1973 |
</indexterm> |
| 1974 |
</term> |
| 1975 |
<listitem> |
| 1976 |
<para> |
| 1977 |
Used to compute the maximum amount of memory that hash-based |
| 1978 |
operations can use. The final limit is determined by |
| 1979 |
multiplying <varname>work_mem</varname> by |
| 1980 |
<varname>hash_mem_multiplier</varname>. The default value is |
| 1981 |
2.0, which makes hash-based operations use twice the usual |
| 1982 |
<varname>work_mem</varname> base amount. |
| 1983 |
</para> |
| 1984 |
<para> |
| 1985 |
Consider increasing <varname>hash_mem_multiplier</varname> in |
| 1986 |
environments where spilling by query operations is a regular |
| 1987 |
occurrence, especially when simply increasing |
| 1988 |
<varname>work_mem</varname> results in memory pressure (memory |
| 1989 |
pressure typically takes the form of intermittent out of |
| 1990 |
memory errors). The default setting of 2.0 is often effective with |
| 1991 |
mixed workloads. Higher settings in the range of 2.0 - 8.0 or |
| 1992 |
more may be effective in environments where |
| 1993 |
<varname>work_mem</varname> has already been increased to 40MB |
| 1994 |
or more. |
| 1995 |
</para> |
| 1996 |
</listitem> |
| 1997 |
</varlistentry> |
| 1998 |
|
| 1999 |
<varlistentry id="guc-maintenance-work-mem" xreflabel="maintenance_work_mem"> |
| 2000 |
<term><varname>maintenance_work_mem</varname> (<type>integer</type>) |
| 2001 |
<indexterm> |
| 2002 |
<primary><varname>maintenance_work_mem</varname> configuration parameter</primary> |
| 2003 |
</indexterm> |
| 2004 |
</term> |
| 2005 |
<listitem> |
| 2006 |
<para> |
| 2007 |
Specifies the maximum amount of memory to be used by maintenance |
| 2008 |
operations, such as <command>VACUUM</command>, <command>CREATE |
| 2009 |
INDEX</command>, and <command>ALTER TABLE ADD FOREIGN KEY</command>. |
| 2010 |
If this value is specified without units, it is taken as kilobytes. |
| 2011 |
It defaults |
| 2012 |
to 64 megabytes (<literal>64MB</literal>). Since only one of these |
| 2013 |
operations can be executed at a time by a database session, and |
| 2014 |
an installation normally doesn't have many of them running |
| 2015 |
concurrently, it's safe to set this value significantly larger |
| 2016 |
than <varname>work_mem</varname>. Larger settings might improve |
| 2017 |
performance for vacuuming and for restoring database dumps. |
| 2018 |
</para> |
| 2019 |
<para> |
| 2020 |
Note that when autovacuum runs, up to |
| 2021 |
<xref linkend="guc-autovacuum-max-workers"/> times this memory |
| 2022 |
may be allocated, so be careful not to set the default value |
| 2023 |
too high. It may be useful to control for this by separately |
| 2024 |
setting <xref linkend="guc-autovacuum-work-mem"/>. |
| 2025 |
</para> |
| 2026 |
</listitem> |
| 2027 |
</varlistentry> |
| 2028 |
|
| 2029 |
<varlistentry id="guc-autovacuum-work-mem" xreflabel="autovacuum_work_mem"> |
| 2030 |
<term><varname>autovacuum_work_mem</varname> (<type>integer</type>) |
| 2031 |
<indexterm> |
| 2032 |
<primary><varname>autovacuum_work_mem</varname> configuration parameter</primary> |
| 2033 |
</indexterm> |
| 2034 |
</term> |
| 2035 |
<listitem> |
| 2036 |
<para> |
| 2037 |
Specifies the maximum amount of memory to be used by each |
| 2038 |
autovacuum worker process. |
| 2039 |
If this value is specified without units, it is taken as kilobytes. |
| 2040 |
It defaults to -1, indicating that |
| 2041 |
the value of <xref linkend="guc-maintenance-work-mem"/> should |
| 2042 |
be used instead. The setting has no effect on the behavior of |
| 2043 |
<command>VACUUM</command> when run in other contexts. |
| 2044 |
This parameter can only be set in the |
| 2045 |
<filename>postgresql.conf</filename> file or on the server command |
| 2046 |
line. |
| 2047 |
</para> |
| 2048 |
</listitem> |
| 2049 |
</varlistentry> |
| 2050 |
|
| 2051 |
<varlistentry id="guc-vacuum-buffer-usage-limit" xreflabel="vacuum_buffer_usage_limit"> |
| 2052 |
<term> |
| 2053 |
<varname>vacuum_buffer_usage_limit</varname> (<type>integer</type>) |
| 2054 |
<indexterm> |
| 2055 |
<primary><varname>vacuum_buffer_usage_limit</varname> configuration parameter</primary> |
| 2056 |
</indexterm> |
| 2057 |
</term> |
| 2058 |
<listitem> |
| 2059 |
<para> |
| 2060 |
Specifies the size of the |
| 2061 |
<glossterm linkend="glossary-buffer-access-strategy">Buffer Access Strategy</glossterm> |
| 2062 |
used by the <command>VACUUM</command> and <command>ANALYZE</command> |
| 2063 |
commands. A setting of <literal>0</literal> will allow the operation |
| 2064 |
to use any number of <varname>shared_buffers</varname>. Otherwise |
| 2065 |
valid sizes range from <literal>128 kB</literal> to |
| 2066 |
<literal>16 GB</literal>. If the specified size would exceed 1/8 the |
| 2067 |
size of <varname>shared_buffers</varname>, the size is silently capped |
| 2068 |
to that value. The default value is <literal>2MB</literal>. If |
| 2069 |
this value is specified without units, it is taken as kilobytes. This |
| 2070 |
parameter can be set at any time. It can be overridden for |
| 2071 |
<xref linkend="sql-vacuum"/> and <xref linkend="sql-analyze"/> |
| 2072 |
when passing the <option>BUFFER_USAGE_LIMIT</option> option. Higher |
| 2073 |
settings can allow <command>VACUUM</command> and |
| 2074 |
<command>ANALYZE</command> to run more quickly, but having too large a |
| 2075 |
setting may cause too many other useful pages to be evicted from |
| 2076 |
shared buffers. |
| 2077 |
</para> |
| 2078 |
</listitem> |
| 2079 |
</varlistentry> |
| 2080 |
|
| 2081 |
<varlistentry id="guc-logical-decoding-work-mem" xreflabel="logical_decoding_work_mem"> |
| 2082 |
<term><varname>logical_decoding_work_mem</varname> (<type>integer</type>) |
| 2083 |
<indexterm> |
| 2084 |
<primary><varname>logical_decoding_work_mem</varname> configuration parameter</primary> |
| 2085 |
</indexterm> |
| 2086 |
</term> |
| 2087 |
<listitem> |
| 2088 |
<para> |
| 2089 |
Specifies the maximum amount of memory to be used by logical decoding, |
| 2090 |
before some of the decoded changes are written to local disk. This |
| 2091 |
limits the amount of memory used by logical streaming replication |
| 2092 |
connections. It defaults to 64 megabytes (<literal>64MB</literal>). |
| 2093 |
Since each replication connection only uses a single buffer of this size, |
| 2094 |
and an installation normally doesn't have many such connections |
| 2095 |
concurrently (as limited by <varname>max_wal_senders</varname>), it's |
| 2096 |
safe to set this value significantly higher than <varname>work_mem</varname>, |
| 2097 |
reducing the amount of decoded changes written to disk. |
| 2098 |
</para> |
| 2099 |
</listitem> |
| 2100 |
</varlistentry> |
| 2101 |
|
| 2102 |
<varlistentry id="guc-commit-timestamp-buffers" xreflabel="commit_timestamp_buffers"> |
| 2103 |
<term><varname>commit_timestamp_buffers</varname> (<type>integer</type>) |
| 2104 |
<indexterm> |
| 2105 |
<primary><varname>commit_timestamp_buffers</varname> configuration parameter</primary> |
| 2106 |
</indexterm> |
| 2107 |
</term> |
| 2108 |
<listitem> |
| 2109 |
<para> |
| 2110 |
Specifies the amount of memory to use to cache the contents of |
| 2111 |
<literal>pg_commit_ts</literal> (see |
| 2112 |
<xref linkend="pgdata-contents-table"/>). |
| 2113 |
If this value is specified without units, it is taken as blocks, |
| 2114 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2115 |
The default value is <literal>0</literal>, which requests |
| 2116 |
<varname>shared_buffers</varname>/512 up to 1024 blocks, |
| 2117 |
but not fewer than 16 blocks. |
| 2118 |
This parameter can only be set at server start. |
| 2119 |
</para> |
| 2120 |
</listitem> |
| 2121 |
</varlistentry> |
| 2122 |
|
| 2123 |
<varlistentry id="guc-multixact-member-buffers" xreflabel="multixact_member_buffers"> |
| 2124 |
<term><varname>multixact_member_buffers</varname> (<type>integer</type>) |
| 2125 |
<indexterm> |
| 2126 |
<primary><varname>multixact_member_buffers</varname> configuration parameter</primary> |
| 2127 |
</indexterm> |
| 2128 |
</term> |
| 2129 |
<listitem> |
| 2130 |
<para> |
| 2131 |
Specifies the amount of shared memory to use to cache the contents |
| 2132 |
of <literal>pg_multixact/members</literal> (see |
| 2133 |
<xref linkend="pgdata-contents-table"/>). |
| 2134 |
If this value is specified without units, it is taken as blocks, |
| 2135 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2136 |
The default value is <literal>32</literal>. |
| 2137 |
This parameter can only be set at server start. |
| 2138 |
</para> |
| 2139 |
</listitem> |
| 2140 |
</varlistentry> |
| 2141 |
|
| 2142 |
<varlistentry id="guc-multixact-offset-buffers" xreflabel="multixact_offset_buffers"> |
| 2143 |
<term><varname>multixact_offset_buffers</varname> (<type>integer</type>) |
| 2144 |
<indexterm> |
| 2145 |
<primary><varname>multixact_offset_buffers</varname> configuration parameter</primary> |
| 2146 |
</indexterm> |
| 2147 |
</term> |
| 2148 |
<listitem> |
| 2149 |
<para> |
| 2150 |
Specifies the amount of shared memory to use to cache the contents |
| 2151 |
of <literal>pg_multixact/offsets</literal> (see |
| 2152 |
<xref linkend="pgdata-contents-table"/>). |
| 2153 |
If this value is specified without units, it is taken as blocks, |
| 2154 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2155 |
The default value is <literal>16</literal>. |
| 2156 |
This parameter can only be set at server start. |
| 2157 |
</para> |
| 2158 |
</listitem> |
| 2159 |
</varlistentry> |
| 2160 |
|
| 2161 |
<varlistentry id="guc-notify-buffers" xreflabel="notify_buffers"> |
| 2162 |
<term><varname>notify_buffers</varname> (<type>integer</type>) |
| 2163 |
<indexterm> |
| 2164 |
<primary><varname>notify_buffers</varname> configuration parameter</primary> |
| 2165 |
</indexterm> |
| 2166 |
</term> |
| 2167 |
<listitem> |
| 2168 |
<para> |
| 2169 |
Specifies the amount of shared memory to use to cache the contents |
| 2170 |
of <literal>pg_notify</literal> (see |
| 2171 |
<xref linkend="pgdata-contents-table"/>). |
| 2172 |
If this value is specified without units, it is taken as blocks, |
| 2173 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2174 |
The default value is <literal>16</literal>. |
| 2175 |
This parameter can only be set at server start. |
| 2176 |
</para> |
| 2177 |
</listitem> |
| 2178 |
</varlistentry> |
| 2179 |
|
| 2180 |
<varlistentry id="guc-serializable-buffers" xreflabel="serializable_buffers"> |
| 2181 |
<term><varname>serializable_buffers</varname> (<type>integer</type>) |
| 2182 |
<indexterm> |
| 2183 |
<primary><varname>serializable_buffers</varname> configuration parameter</primary> |
| 2184 |
</indexterm> |
| 2185 |
</term> |
| 2186 |
<listitem> |
| 2187 |
<para> |
| 2188 |
Specifies the amount of shared memory to use to cache the contents |
| 2189 |
of <literal>pg_serial</literal> (see |
| 2190 |
<xref linkend="pgdata-contents-table"/>). |
| 2191 |
If this value is specified without units, it is taken as blocks, |
| 2192 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2193 |
The default value is <literal>32</literal>. |
| 2194 |
This parameter can only be set at server start. |
| 2195 |
</para> |
| 2196 |
</listitem> |
| 2197 |
</varlistentry> |
| 2198 |
|
| 2199 |
<varlistentry id="guc-subtransaction-buffers" xreflabel="subtransaction_buffers"> |
| 2200 |
<term><varname>subtransaction_buffers</varname> (<type>integer</type>) |
| 2201 |
<indexterm> |
| 2202 |
<primary><varname>subtransaction_buffers</varname> configuration parameter</primary> |
| 2203 |
</indexterm> |
| 2204 |
</term> |
| 2205 |
<listitem> |
| 2206 |
<para> |
| 2207 |
Specifies the amount of shared memory to use to cache the contents |
| 2208 |
of <literal>pg_subtrans</literal> (see |
| 2209 |
<xref linkend="pgdata-contents-table"/>). |
| 2210 |
If this value is specified without units, it is taken as blocks, |
| 2211 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2212 |
The default value is <literal>0</literal>, which requests |
| 2213 |
<varname>shared_buffers</varname>/512 up to 1024 blocks, |
| 2214 |
but not fewer than 16 blocks. |
| 2215 |
This parameter can only be set at server start. |
| 2216 |
</para> |
| 2217 |
</listitem> |
| 2218 |
</varlistentry> |
| 2219 |
|
| 2220 |
<varlistentry id="guc-transaction-buffers" xreflabel="transaction_buffers"> |
| 2221 |
<term><varname>transaction_buffers</varname> (<type>integer</type>) |
| 2222 |
<indexterm> |
| 2223 |
<primary><varname>transaction_buffers</varname> configuration parameter</primary> |
| 2224 |
</indexterm> |
| 2225 |
</term> |
| 2226 |
<listitem> |
| 2227 |
<para> |
| 2228 |
Specifies the amount of shared memory to use to cache the contents |
| 2229 |
of <literal>pg_xact</literal> (see |
| 2230 |
<xref linkend="pgdata-contents-table"/>). |
| 2231 |
If this value is specified without units, it is taken as blocks, |
| 2232 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2233 |
The default value is <literal>0</literal>, which requests |
| 2234 |
<varname>shared_buffers</varname>/512 up to 1024 blocks, |
| 2235 |
but not fewer than 16 blocks. |
| 2236 |
This parameter can only be set at server start. |
| 2237 |
</para> |
| 2238 |
</listitem> |
| 2239 |
</varlistentry> |
| 2240 |
|
| 2241 |
<varlistentry id="guc-max-stack-depth" xreflabel="max_stack_depth"> |
| 2242 |
<term><varname>max_stack_depth</varname> (<type>integer</type>) |
| 2243 |
<indexterm> |
| 2244 |
<primary><varname>max_stack_depth</varname> configuration parameter</primary> |
| 2245 |
</indexterm> |
| 2246 |
</term> |
| 2247 |
<listitem> |
| 2248 |
<para> |
| 2249 |
Specifies the maximum safe depth of the server's execution stack. |
| 2250 |
The ideal setting for this parameter is the actual stack size limit |
| 2251 |
enforced by the kernel (as set by <literal>ulimit -s</literal> or local |
| 2252 |
equivalent), less a safety margin of a megabyte or so. The safety |
| 2253 |
margin is needed because the stack depth is not checked in every |
| 2254 |
routine in the server, but only in key potentially-recursive routines. |
| 2255 |
If this value is specified without units, it is taken as kilobytes. |
| 2256 |
The default setting is two megabytes (<literal>2MB</literal>), which |
| 2257 |
is conservatively small and unlikely to risk crashes. However, |
| 2258 |
it might be too small to allow execution of complex functions. |
| 2259 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 2260 |
privilege can change this setting. |
| 2261 |
</para> |
| 2262 |
|
| 2263 |
<para> |
| 2264 |
Setting <varname>max_stack_depth</varname> higher than |
| 2265 |
the actual kernel limit will mean that a runaway recursive function |
| 2266 |
can crash an individual backend process. On platforms where |
| 2267 |
<productname>PostgreSQL</productname> can determine the kernel limit, |
| 2268 |
the server will not allow this variable to be set to an unsafe |
| 2269 |
value. However, not all platforms provide the information, |
| 2270 |
so caution is recommended in selecting a value. |
| 2271 |
</para> |
| 2272 |
</listitem> |
| 2273 |
</varlistentry> |
| 2274 |
|
| 2275 |
<varlistentry id="guc-shared-memory-type" xreflabel="shared_memory_type"> |
| 2276 |
<term><varname>shared_memory_type</varname> (<type>enum</type>) |
| 2277 |
<indexterm> |
| 2278 |
<primary><varname>shared_memory_type</varname> configuration parameter</primary> |
| 2279 |
</indexterm> |
| 2280 |
</term> |
| 2281 |
<listitem> |
| 2282 |
<para> |
| 2283 |
Specifies the shared memory implementation that the server |
| 2284 |
should use for the main shared memory region that holds |
| 2285 |
<productname>PostgreSQL</productname>'s shared buffers and other |
| 2286 |
shared data. Possible values are <literal>mmap</literal> (for |
| 2287 |
anonymous shared memory allocated using <function>mmap</function>), |
| 2288 |
<literal>sysv</literal> (for System V shared memory allocated via |
| 2289 |
<function>shmget</function>) and <literal>windows</literal> (for Windows |
| 2290 |
shared memory). Not all values are supported on all platforms; the |
| 2291 |
first supported option is the default for that platform. The use of |
| 2292 |
the <literal>sysv</literal> option, which is not the default on any |
| 2293 |
platform, is generally discouraged because it typically requires |
| 2294 |
non-default kernel settings to allow for large allocations (see <xref |
| 2295 |
linkend="sysvipc"/>). |
| 2296 |
This parameter can only be set at server start. |
| 2297 |
</para> |
| 2298 |
</listitem> |
| 2299 |
</varlistentry> |
| 2300 |
|
| 2301 |
<varlistentry id="guc-dynamic-shared-memory-type" xreflabel="dynamic_shared_memory_type"> |
| 2302 |
<term><varname>dynamic_shared_memory_type</varname> (<type>enum</type>) |
| 2303 |
<indexterm> |
| 2304 |
<primary><varname>dynamic_shared_memory_type</varname> configuration parameter</primary> |
| 2305 |
</indexterm> |
| 2306 |
</term> |
| 2307 |
<listitem> |
| 2308 |
<para> |
| 2309 |
Specifies the dynamic shared memory implementation that the server |
| 2310 |
should use. Possible values are <literal>posix</literal> (for POSIX shared |
| 2311 |
memory allocated using <literal>shm_open</literal>), <literal>sysv</literal> |
| 2312 |
(for System V shared memory allocated via <literal>shmget</literal>), |
| 2313 |
<literal>windows</literal> (for Windows shared memory), |
| 2314 |
and <literal>mmap</literal> (to simulate shared memory using |
| 2315 |
memory-mapped files stored in the data directory). |
| 2316 |
Not all values are supported on all platforms; the first supported |
| 2317 |
option is usually the default for that platform. The use of the |
| 2318 |
<literal>mmap</literal> option, which is not the default on any platform, |
| 2319 |
is generally discouraged because the operating system may write |
| 2320 |
modified pages back to disk repeatedly, increasing system I/O load; |
| 2321 |
however, it may be useful for debugging, when the |
| 2322 |
<literal>pg_dynshmem</literal> directory is stored on a RAM disk, or when |
| 2323 |
other shared memory facilities are not available. |
| 2324 |
This parameter can only be set at server start. |
| 2325 |
</para> |
| 2326 |
</listitem> |
| 2327 |
</varlistentry> |
| 2328 |
|
| 2329 |
<varlistentry id="guc-min-dynamic-shared-memory" xreflabel="min_dynamic_shared_memory"> |
| 2330 |
<term><varname>min_dynamic_shared_memory</varname> (<type>integer</type>) |
| 2331 |
<indexterm> |
| 2332 |
<primary><varname>min_dynamic_shared_memory</varname> configuration parameter</primary> |
| 2333 |
</indexterm> |
| 2334 |
</term> |
| 2335 |
<listitem> |
| 2336 |
<para> |
| 2337 |
Specifies the amount of memory that should be allocated at server |
| 2338 |
startup for use by parallel queries. When this memory region is |
| 2339 |
insufficient or exhausted by concurrent queries, new parallel queries |
| 2340 |
try to allocate extra shared memory temporarily from the operating |
| 2341 |
system using the method configured with |
| 2342 |
<varname>dynamic_shared_memory_type</varname>, which may be slower due |
| 2343 |
to memory management overheads. Memory that is allocated at startup |
| 2344 |
with <varname>min_dynamic_shared_memory</varname> is affected by |
| 2345 |
the <varname>huge_pages</varname> setting on operating systems where |
| 2346 |
that is supported, and may be more likely to benefit from larger pages |
| 2347 |
on operating systems where that is managed automatically. |
| 2348 |
The default value is <literal>0</literal> (none). This parameter can |
| 2349 |
only be set at server start. |
| 2350 |
</para> |
| 2351 |
</listitem> |
| 2352 |
</varlistentry> |
| 2353 |
|
| 2354 |
</variablelist> |
| 2355 |
</sect2> |
| 2356 |
|
| 2357 |
<sect2 id="runtime-config-resource-disk"> |
| 2358 |
<title>Disk</title> |
| 2359 |
|
| 2360 |
<variablelist> |
| 2361 |
<varlistentry id="guc-temp-file-limit" xreflabel="temp_file_limit"> |
| 2362 |
<term><varname>temp_file_limit</varname> (<type>integer</type>) |
| 2363 |
<indexterm> |
| 2364 |
<primary><varname>temp_file_limit</varname> configuration parameter</primary> |
| 2365 |
</indexterm> |
| 2366 |
</term> |
| 2367 |
<listitem> |
| 2368 |
<para> |
| 2369 |
Specifies the maximum amount of disk space that a process can use |
| 2370 |
for temporary files, such as sort and hash temporary files, or the |
| 2371 |
storage file for a held cursor. A transaction attempting to exceed |
| 2372 |
this limit will be canceled. |
| 2373 |
If this value is specified without units, it is taken as kilobytes. |
| 2374 |
<literal>-1</literal> (the default) means no limit. |
| 2375 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 2376 |
privilege can change this setting. |
| 2377 |
</para> |
| 2378 |
<para> |
| 2379 |
This setting constrains the total space used at any instant by all |
| 2380 |
temporary files used by a given <productname>PostgreSQL</productname> process. |
| 2381 |
It should be noted that disk space used for explicit temporary |
| 2382 |
tables, as opposed to temporary files used behind-the-scenes in query |
| 2383 |
execution, does <emphasis>not</emphasis> count against this limit. |
| 2384 |
</para> |
| 2385 |
</listitem> |
| 2386 |
</varlistentry> |
| 2387 |
|
| 2388 |
<varlistentry id="guc-file-copy-method" xreflabel="file_copy_method"> |
| 2389 |
<term><varname>file_copy_method</varname> (<type>enum</type>) |
| 2390 |
<indexterm> |
| 2391 |
<primary><varname>file_copy_method</varname> configuration parameter</primary> |
| 2392 |
</indexterm> |
| 2393 |
</term> |
| 2394 |
<listitem> |
| 2395 |
<para> |
| 2396 |
Specifies the method used to copy files. |
| 2397 |
Possible values are <literal>COPY</literal> (default) and |
| 2398 |
<literal>CLONE</literal> (if operating support is available). |
| 2399 |
</para> |
| 2400 |
|
| 2401 |
<para> |
| 2402 |
This parameter affects: |
| 2403 |
</para> |
| 2404 |
<itemizedlist> |
| 2405 |
<listitem> |
| 2406 |
<para> |
| 2407 |
<literal><command>CREATE DATABASE ... STRATEGY=FILE_COPY</command></literal> |
| 2408 |
</para> |
| 2409 |
</listitem> |
| 2410 |
<listitem> |
| 2411 |
<para> |
| 2412 |
<command>ALTER DATABASE ... SET TABLESPACE ...</command> |
| 2413 |
</para> |
| 2414 |
</listitem> |
| 2415 |
</itemizedlist> |
| 2416 |
|
| 2417 |
<para> |
| 2418 |
<literal>CLONE</literal> uses the <function>copy_file_range()</function> |
| 2419 |
(Linux, FreeBSD) or <function>copyfile</function> |
| 2420 |
(macOS) system calls, giving the kernel the opportunity to share disk |
| 2421 |
blocks or push work down to lower layers on some file systems. |
| 2422 |
</para> |
| 2423 |
</listitem> |
| 2424 |
</varlistentry> |
| 2425 |
|
| 2426 |
<varlistentry id="guc-file-extend-method" xreflabel="file_extend_method"> |
| 2427 |
<term><varname>file_extend_method</varname> (<type>enum</type>) |
| 2428 |
<indexterm> |
| 2429 |
<primary><varname>file_extend_method</varname> configuration parameter</primary> |
| 2430 |
</indexterm> |
| 2431 |
</term> |
| 2432 |
<listitem> |
| 2433 |
<para> |
| 2434 |
Specifies the method used to extend data files during bulk operations |
| 2435 |
such as <command>COPY</command>. The first available option is used as |
| 2436 |
the default, depending on the operating system: |
| 2437 |
<itemizedlist> |
| 2438 |
<listitem> |
| 2439 |
<para> |
| 2440 |
<literal>posix_fallocate</literal> (Unix) uses the standard POSIX |
| 2441 |
interface for allocating disk space, but is missing on some systems. |
| 2442 |
If it is present but the underlying file system doesn't support it, |
| 2443 |
this option silently falls back to <literal>write_zeros</literal>. |
| 2444 |
Current versions of BTRFS are known to disable compression when |
| 2445 |
this option is used. |
| 2446 |
This is the default on systems that have the function. |
| 2447 |
</para> |
| 2448 |
</listitem> |
| 2449 |
<listitem> |
| 2450 |
<para> |
| 2451 |
<literal>write_zeros</literal> extends files by writing out blocks |
| 2452 |
of zero bytes. This is the default on systems that don't have the |
| 2453 |
function <function>posix_fallocate</function>. |
| 2454 |
</para> |
| 2455 |
</listitem> |
| 2456 |
</itemizedlist> |
| 2457 |
The <literal>write_zeros</literal> method is always used when data |
| 2458 |
files are extended by 8 blocks or fewer. |
| 2459 |
</para> |
| 2460 |
</listitem> |
| 2461 |
</varlistentry> |
| 2462 |
|
| 2463 |
<varlistentry id="guc-max-notify-queue-pages" xreflabel="max_notify_queue_pages"> |
| 2464 |
<term><varname>max_notify_queue_pages</varname> (<type>integer</type>) |
| 2465 |
<indexterm> |
| 2466 |
<primary><varname>max_notify_queue_pages</varname> configuration parameter</primary> |
| 2467 |
</indexterm> |
| 2468 |
</term> |
| 2469 |
<listitem> |
| 2470 |
<para> |
| 2471 |
Specifies the maximum amount of allocated pages for |
| 2472 |
<xref linkend="sql-notify"/> / <xref linkend="sql-listen"/> queue. |
| 2473 |
The default value is 1048576. For 8 KB pages it allows to consume |
| 2474 |
up to 8 GB of disk space. |
| 2475 |
This parameter can only be set at server start. |
| 2476 |
</para> |
| 2477 |
</listitem> |
| 2478 |
</varlistentry> |
| 2479 |
|
| 2480 |
</variablelist> |
| 2481 |
</sect2> |
| 2482 |
|
| 2483 |
<sect2 id="runtime-config-resource-kernel"> |
| 2484 |
<title>Kernel Resource Usage</title> |
| 2485 |
|
| 2486 |
<variablelist> |
| 2487 |
<varlistentry id="guc-max-files-per-process" xreflabel="max_files_per_process"> |
| 2488 |
<term><varname>max_files_per_process</varname> (<type>integer</type>) |
| 2489 |
<indexterm> |
| 2490 |
<primary><varname>max_files_per_process</varname> configuration parameter</primary> |
| 2491 |
</indexterm> |
| 2492 |
</term> |
| 2493 |
<listitem> |
| 2494 |
<para> |
| 2495 |
Sets the maximum number of open files each server subprocess is |
| 2496 |
allowed to open simultaneously; files already opened in the |
| 2497 |
postmaster are not counted toward this limit. The default is one |
| 2498 |
thousand files. |
| 2499 |
</para> |
| 2500 |
<para> |
| 2501 |
If the kernel is enforcing |
| 2502 |
a safe per-process limit, you don't need to worry about this setting. |
| 2503 |
But on some platforms (notably, most BSD systems), the kernel will |
| 2504 |
allow individual processes to open many more files than the system |
| 2505 |
can actually support if many processes all try to open |
| 2506 |
that many files. If you find yourself seeing <quote>Too many open |
| 2507 |
files</quote> failures, try reducing this setting. |
| 2508 |
This parameter can only be set at server start. |
| 2509 |
</para> |
| 2510 |
</listitem> |
| 2511 |
</varlistentry> |
| 2512 |
</variablelist> |
| 2513 |
</sect2> |
| 2514 |
|
| 2515 |
|
| 2516 |
<sect2 id="runtime-config-resource-background-writer"> |
| 2517 |
<title>Background Writer</title> |
| 2518 |
|
| 2519 |
<para> |
| 2520 |
There is a separate server |
| 2521 |
process called the <firstterm>background writer</firstterm>, whose function |
| 2522 |
is to issue writes of <quote>dirty</quote> (new or modified) shared |
| 2523 |
buffers. When the number of clean shared buffers appears to be |
| 2524 |
insufficient, the background writer writes some dirty buffers to the |
| 2525 |
file system and marks them as clean. This reduces the likelihood |
| 2526 |
that server processes handling user queries will be unable to find |
| 2527 |
clean buffers and have to write dirty buffers themselves. |
| 2528 |
However, the background writer does cause a net overall |
| 2529 |
increase in I/O load, because while a repeatedly-dirtied page might |
| 2530 |
otherwise be written only once per checkpoint interval, the |
| 2531 |
background writer might write it several times as it is dirtied |
| 2532 |
in the same interval. The parameters discussed in this subsection |
| 2533 |
can be used to tune the behavior for local needs. |
| 2534 |
</para> |
| 2535 |
|
| 2536 |
<variablelist> |
| 2537 |
<varlistentry id="guc-bgwriter-delay" xreflabel="bgwriter_delay"> |
| 2538 |
<term><varname>bgwriter_delay</varname> (<type>integer</type>) |
| 2539 |
<indexterm> |
| 2540 |
<primary><varname>bgwriter_delay</varname> configuration parameter</primary> |
| 2541 |
</indexterm> |
| 2542 |
</term> |
| 2543 |
<listitem> |
| 2544 |
<para> |
| 2545 |
Specifies the delay between activity rounds for the |
| 2546 |
background writer. In each round the writer issues writes |
| 2547 |
for some number of dirty buffers (controllable by the |
| 2548 |
following parameters). It then sleeps for |
| 2549 |
the length of <varname>bgwriter_delay</varname>, and repeats. |
| 2550 |
When there are no dirty buffers in the |
| 2551 |
buffer pool, though, it goes into a longer sleep regardless of |
| 2552 |
<varname>bgwriter_delay</varname>. |
| 2553 |
If this value is specified without units, it is taken as milliseconds. |
| 2554 |
The default value is 200 |
| 2555 |
milliseconds (<literal>200ms</literal>). Note that on some systems, the |
| 2556 |
effective resolution of sleep delays is 10 milliseconds; setting |
| 2557 |
<varname>bgwriter_delay</varname> to a value that is not a multiple of 10 |
| 2558 |
might have the same results as setting it to the next higher multiple |
| 2559 |
of 10. This parameter can only be set in the |
| 2560 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 2561 |
</para> |
| 2562 |
</listitem> |
| 2563 |
</varlistentry> |
| 2564 |
|
| 2565 |
<varlistentry id="guc-bgwriter-lru-maxpages" xreflabel="bgwriter_lru_maxpages"> |
| 2566 |
<term><varname>bgwriter_lru_maxpages</varname> (<type>integer</type>) |
| 2567 |
<indexterm> |
| 2568 |
<primary><varname>bgwriter_lru_maxpages</varname> configuration parameter</primary> |
| 2569 |
</indexterm> |
| 2570 |
</term> |
| 2571 |
<listitem> |
| 2572 |
<para> |
| 2573 |
In each round, no more than this many buffers will be written |
| 2574 |
by the background writer. Setting this to zero disables |
| 2575 |
background writing. (Note that checkpoints, which are managed by |
| 2576 |
a separate, dedicated auxiliary process, are unaffected.) |
| 2577 |
The default value is 100 buffers. |
| 2578 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 2579 |
file or on the server command line. |
| 2580 |
</para> |
| 2581 |
</listitem> |
| 2582 |
</varlistentry> |
| 2583 |
|
| 2584 |
<varlistentry id="guc-bgwriter-lru-multiplier" xreflabel="bgwriter_lru_multiplier"> |
| 2585 |
<term><varname>bgwriter_lru_multiplier</varname> (<type>floating point</type>) |
| 2586 |
<indexterm> |
| 2587 |
<primary><varname>bgwriter_lru_multiplier</varname> configuration parameter</primary> |
| 2588 |
</indexterm> |
| 2589 |
</term> |
| 2590 |
<listitem> |
| 2591 |
<para> |
| 2592 |
The number of dirty buffers written in each round is based on the |
| 2593 |
number of new buffers that have been needed by server processes |
| 2594 |
during recent rounds. The average recent need is multiplied by |
| 2595 |
<varname>bgwriter_lru_multiplier</varname> to arrive at an estimate of the |
| 2596 |
number of buffers that will be needed during the next round. Dirty |
| 2597 |
buffers are written until there are that many clean, reusable buffers |
| 2598 |
available. (However, no more than <varname>bgwriter_lru_maxpages</varname> |
| 2599 |
buffers will be written per round.) |
| 2600 |
Thus, a setting of 1.0 represents a <quote>just in time</quote> policy |
| 2601 |
of writing exactly the number of buffers predicted to be needed. |
| 2602 |
Larger values provide some cushion against spikes in demand, |
| 2603 |
while smaller values intentionally leave writes to be done by |
| 2604 |
server processes. |
| 2605 |
The default is 2.0. |
| 2606 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 2607 |
file or on the server command line. |
| 2608 |
</para> |
| 2609 |
</listitem> |
| 2610 |
</varlistentry> |
| 2611 |
|
| 2612 |
<varlistentry id="guc-bgwriter-flush-after" xreflabel="bgwriter_flush_after"> |
| 2613 |
<term><varname>bgwriter_flush_after</varname> (<type>integer</type>) |
| 2614 |
<indexterm> |
| 2615 |
<primary><varname>bgwriter_flush_after</varname> configuration parameter</primary> |
| 2616 |
</indexterm> |
| 2617 |
</term> |
| 2618 |
<listitem> |
| 2619 |
<para> |
| 2620 |
Whenever more than this amount of data has |
| 2621 |
been written by the background writer, attempt to force the OS to issue these |
| 2622 |
writes to the underlying storage. Doing so will limit the amount of |
| 2623 |
dirty data in the kernel's page cache, reducing the likelihood of |
| 2624 |
stalls when an <function>fsync</function> is issued at the end of a checkpoint, or when |
| 2625 |
the OS writes data back in larger batches in the background. Often |
| 2626 |
that will result in greatly reduced transaction latency, but there |
| 2627 |
also are some cases, especially with workloads that are bigger than |
| 2628 |
<xref linkend="guc-shared-buffers"/>, but smaller than the OS's page |
| 2629 |
cache, where performance might degrade. This setting may have no |
| 2630 |
effect on some platforms. |
| 2631 |
If this value is specified without units, it is taken as blocks, |
| 2632 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2633 |
The valid range is between |
| 2634 |
<literal>0</literal>, which disables forced writeback, and |
| 2635 |
<literal>2MB</literal>. The default is <literal>512kB</literal> on Linux, |
| 2636 |
<literal>0</literal> elsewhere. (If <symbol>BLCKSZ</symbol> is not 8kB, |
| 2637 |
the default and maximum values scale proportionally to it.) |
| 2638 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 2639 |
file or on the server command line. |
| 2640 |
</para> |
| 2641 |
</listitem> |
| 2642 |
</varlistentry> |
| 2643 |
</variablelist> |
| 2644 |
|
| 2645 |
<para> |
| 2646 |
Smaller values of <varname>bgwriter_lru_maxpages</varname> and |
| 2647 |
<varname>bgwriter_lru_multiplier</varname> reduce the extra I/O load |
| 2648 |
caused by the background writer, but make it more likely that server |
| 2649 |
processes will have to issue writes for themselves, delaying interactive |
| 2650 |
queries. |
| 2651 |
</para> |
| 2652 |
</sect2> |
| 2653 |
|
| 2654 |
<sect2 id="runtime-config-resource-io"> |
| 2655 |
<title>I/O</title> |
| 2656 |
|
| 2657 |
<variablelist> |
| 2658 |
<varlistentry id="guc-backend-flush-after" xreflabel="backend_flush_after"> |
| 2659 |
<term><varname>backend_flush_after</varname> (<type>integer</type>) |
| 2660 |
<indexterm> |
| 2661 |
<primary><varname>backend_flush_after</varname> configuration parameter</primary> |
| 2662 |
</indexterm> |
| 2663 |
</term> |
| 2664 |
<listitem> |
| 2665 |
<para> |
| 2666 |
Whenever more than this amount of data has |
| 2667 |
been written by a single backend, attempt to force the OS to issue |
| 2668 |
these writes to the underlying storage. Doing so will limit the |
| 2669 |
amount of dirty data in the kernel's page cache, reducing the |
| 2670 |
likelihood of stalls when an <function>fsync</function> is issued at the end of a |
| 2671 |
checkpoint, or when the OS writes data back in larger batches in the |
| 2672 |
background. Often that will result in greatly reduced transaction |
| 2673 |
latency, but there also are some cases, especially with workloads |
| 2674 |
that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller |
| 2675 |
than the OS's page cache, where performance might degrade. This |
| 2676 |
setting may have no effect on some platforms. |
| 2677 |
If this value is specified without units, it is taken as blocks, |
| 2678 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2679 |
The valid range is |
| 2680 |
between <literal>0</literal>, which disables forced writeback, |
| 2681 |
and <literal>2MB</literal>. The default is <literal>0</literal>, i.e., no |
| 2682 |
forced writeback. (If <symbol>BLCKSZ</symbol> is not 8kB, |
| 2683 |
the maximum value scales proportionally to it.) |
| 2684 |
</para> |
| 2685 |
</listitem> |
| 2686 |
</varlistentry> |
| 2687 |
|
| 2688 |
<varlistentry id="guc-effective-io-concurrency" xreflabel="effective_io_concurrency"> |
| 2689 |
<term><varname>effective_io_concurrency</varname> (<type>integer</type>) |
| 2690 |
<indexterm> |
| 2691 |
<primary><varname>effective_io_concurrency</varname> configuration parameter</primary> |
| 2692 |
</indexterm> |
| 2693 |
</term> |
| 2694 |
<listitem> |
| 2695 |
<para> |
| 2696 |
Sets the number of concurrent storage I/O operations that |
| 2697 |
<productname>PostgreSQL</productname> expects can be executed |
| 2698 |
simultaneously. Raising this value will increase the number of I/O |
| 2699 |
operations that any individual <productname>PostgreSQL</productname> |
| 2700 |
session attempts to initiate in parallel. The allowed range is |
| 2701 |
<literal>1</literal> to <literal>1000</literal>, or |
| 2702 |
<literal>0</literal> to disable issuance of asynchronous I/O requests. |
| 2703 |
The default is <literal>16</literal>. |
| 2704 |
</para> |
| 2705 |
|
| 2706 |
<para> |
| 2707 |
Higher values will have the most impact on higher latency storage |
| 2708 |
where queries otherwise experience noticeable I/O stalls and on |
| 2709 |
devices with high IOPs. Unnecessarily high values may increase I/O |
| 2710 |
latency for all queries on the system. |
| 2711 |
</para> |
| 2712 |
|
| 2713 |
<para> |
| 2714 |
On systems with prefetch advice support, |
| 2715 |
<varname>effective_io_concurrency</varname> also controls the |
| 2716 |
prefetch distance. |
| 2717 |
</para> |
| 2718 |
|
| 2719 |
<para> |
| 2720 |
This value can be overridden for tables in a particular tablespace by |
| 2721 |
setting the tablespace parameter of the same name (see <xref |
| 2722 |
linkend="sql-altertablespace"/>). |
| 2723 |
</para> |
| 2724 |
</listitem> |
| 2725 |
</varlistentry> |
| 2726 |
|
| 2727 |
<varlistentry id="guc-maintenance-io-concurrency" xreflabel="maintenance_io_concurrency"> |
| 2728 |
<term><varname>maintenance_io_concurrency</varname> (<type>integer</type>) |
| 2729 |
<indexterm> |
| 2730 |
<primary><varname>maintenance_io_concurrency</varname> configuration parameter</primary> |
| 2731 |
</indexterm> |
| 2732 |
</term> |
| 2733 |
<listitem> |
| 2734 |
<para> |
| 2735 |
Similar to <varname>effective_io_concurrency</varname>, but used |
| 2736 |
for maintenance work that is done on behalf of many client sessions. |
| 2737 |
</para> |
| 2738 |
<para> |
| 2739 |
The default is <literal>16</literal>. This value can be overridden |
| 2740 |
for tables in a particular tablespace by setting the tablespace |
| 2741 |
parameter of the same name (see <xref |
| 2742 |
linkend="sql-altertablespace"/>). |
| 2743 |
</para> |
| 2744 |
</listitem> |
| 2745 |
</varlistentry> |
| 2746 |
|
| 2747 |
<varlistentry id="guc-io-max-combine-limit" xreflabel="io_max_combine_limit"> |
| 2748 |
<term><varname>io_max_combine_limit</varname> (<type>integer</type>) |
| 2749 |
<indexterm> |
| 2750 |
<primary><varname>io_max_combine_limit</varname> configuration parameter</primary> |
| 2751 |
</indexterm> |
| 2752 |
</term> |
| 2753 |
<listitem> |
| 2754 |
<para> |
| 2755 |
Controls the largest I/O size in operations that combine I/O, and silently |
| 2756 |
limits the user-settable parameter <varname>io_combine_limit</varname>. |
| 2757 |
This parameter can only be set at server start. |
| 2758 |
If this value is specified without units, it is taken as blocks, |
| 2759 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2760 |
The maximum possible size depends on the operating system and block |
| 2761 |
size, but is typically 1MB on Unix and 128kB on Windows. |
| 2762 |
The default is 128kB. |
| 2763 |
</para> |
| 2764 |
</listitem> |
| 2765 |
</varlistentry> |
| 2766 |
|
| 2767 |
<varlistentry id="guc-io-combine-limit" xreflabel="io_combine_limit"> |
| 2768 |
<term><varname>io_combine_limit</varname> (<type>integer</type>) |
| 2769 |
<indexterm> |
| 2770 |
<primary><varname>io_combine_limit</varname> configuration parameter</primary> |
| 2771 |
</indexterm> |
| 2772 |
</term> |
| 2773 |
<listitem> |
| 2774 |
<para> |
| 2775 |
Controls the largest I/O size in operations that combine I/O. If set |
| 2776 |
higher than the <varname>io_max_combine_limit</varname> parameter, the |
| 2777 |
lower value will silently be used instead, so both may need to be raised |
| 2778 |
to increase the I/O size. |
| 2779 |
If this value is specified without units, it is taken as blocks, |
| 2780 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 2781 |
The maximum possible size depends on the operating system and block |
| 2782 |
size, but is typically 1MB on Unix and 128kB on Windows. |
| 2783 |
The default is 128kB. |
| 2784 |
</para> |
| 2785 |
</listitem> |
| 2786 |
</varlistentry> |
| 2787 |
|
| 2788 |
<varlistentry id="guc-io-max-concurrency" xreflabel="io_max_concurrency"> |
| 2789 |
<term><varname>io_max_concurrency</varname> (<type>integer</type>) |
| 2790 |
<indexterm> |
| 2791 |
<primary><varname>io_max_concurrency</varname> configuration parameter</primary> |
| 2792 |
</indexterm> |
| 2793 |
</term> |
| 2794 |
<listitem> |
| 2795 |
<para> |
| 2796 |
Controls the maximum number of I/O operations that one process can |
| 2797 |
execute simultaneously. |
| 2798 |
</para> |
| 2799 |
<para> |
| 2800 |
The default setting of <literal>-1</literal> selects a number based |
| 2801 |
on <xref linkend="guc-shared-buffers"/> and the maximum number of |
| 2802 |
processes (<xref linkend="guc-max-connections"/>, <xref |
| 2803 |
linkend="guc-autovacuum-worker-slots"/>, <xref |
| 2804 |
linkend="guc-max-worker-processes"/> and <xref |
| 2805 |
linkend="guc-max-wal-senders"/>), but not more than |
| 2806 |
<literal>64</literal>. |
| 2807 |
</para> |
| 2808 |
<para> |
| 2809 |
This parameter can only be set at server start. |
| 2810 |
</para> |
| 2811 |
</listitem> |
| 2812 |
</varlistentry> |
| 2813 |
|
| 2814 |
<varlistentry id="guc-io-method" xreflabel="io_method"> |
| 2815 |
<term><varname>io_method</varname> (<type>enum</type>) |
| 2816 |
<indexterm> |
| 2817 |
<primary><varname>io_method</varname> configuration parameter</primary> |
| 2818 |
</indexterm> |
| 2819 |
</term> |
| 2820 |
<listitem> |
| 2821 |
<para> |
| 2822 |
Selects the method for executing asynchronous I/O. |
| 2823 |
Possible values are: |
| 2824 |
<itemizedlist> |
| 2825 |
<listitem> |
| 2826 |
<para> |
| 2827 |
<literal>worker</literal> (execute asynchronous I/O using worker processes) |
| 2828 |
</para> |
| 2829 |
</listitem> |
| 2830 |
<listitem> |
| 2831 |
<para> |
| 2832 |
<literal>io_uring</literal> (execute asynchronous I/O using |
| 2833 |
io_uring, requires a build with |
| 2834 |
<link linkend="configure-option-with-liburing"><option>--with-liburing</option></link> / |
| 2835 |
<link linkend="configure-with-liburing-meson"><option>-Dliburing</option></link>) |
| 2836 |
</para> |
| 2837 |
</listitem> |
| 2838 |
<listitem> |
| 2839 |
<para> |
| 2840 |
<literal>sync</literal> (execute asynchronous-eligible I/O synchronously) |
| 2841 |
</para> |
| 2842 |
</listitem> |
| 2843 |
</itemizedlist> |
| 2844 |
The default is <literal>worker</literal>. |
| 2845 |
</para> |
| 2846 |
<para> |
| 2847 |
This parameter can only be set at server start. |
| 2848 |
</para> |
| 2849 |
</listitem> |
| 2850 |
</varlistentry> |
| 2851 |
|
| 2852 |
<varlistentry id="guc-io-workers" xreflabel="io_workers"> |
| 2853 |
<term><varname>io_workers</varname> (<type>integer</type>) |
| 2854 |
<indexterm> |
| 2855 |
<primary><varname>io_workers</varname> configuration parameter</primary> |
| 2856 |
</indexterm> |
| 2857 |
</term> |
| 2858 |
<listitem> |
| 2859 |
<para> |
| 2860 |
Selects the number of I/O worker processes to use. The default is |
| 2861 |
3. This parameter can only be set in the |
| 2862 |
<filename>postgresql.conf</filename> file or on the server command |
| 2863 |
line. |
| 2864 |
</para> |
| 2865 |
<para> |
| 2866 |
Only has an effect if <xref linkend="guc-io-method"/> is set to |
| 2867 |
<literal>worker</literal>. |
| 2868 |
</para> |
| 2869 |
</listitem> |
| 2870 |
</varlistentry> |
| 2871 |
</variablelist> |
| 2872 |
</sect2> |
| 2873 |
|
| 2874 |
<sect2 id="runtime-config-resource-worker-processes"> |
| 2875 |
<title>Worker Processes</title> |
| 2876 |
|
| 2877 |
<variablelist> |
| 2878 |
<varlistentry id="guc-max-worker-processes" xreflabel="max_worker_processes"> |
| 2879 |
<term><varname>max_worker_processes</varname> (<type>integer</type>) |
| 2880 |
<indexterm> |
| 2881 |
<primary><varname>max_worker_processes</varname> configuration parameter</primary> |
| 2882 |
</indexterm> |
| 2883 |
</term> |
| 2884 |
<listitem> |
| 2885 |
<para> |
| 2886 |
Sets the maximum number of background processes that the cluster |
| 2887 |
can support. This parameter can only be set at server start. The |
| 2888 |
default is 8. |
| 2889 |
</para> |
| 2890 |
|
| 2891 |
<para> |
| 2892 |
When running a standby server, you must set this parameter to the |
| 2893 |
same or higher value than on the primary server. Otherwise, queries |
| 2894 |
will not be allowed in the standby server. |
| 2895 |
</para> |
| 2896 |
|
| 2897 |
<para> |
| 2898 |
When changing this value, consider also adjusting |
| 2899 |
<xref linkend="guc-max-parallel-workers"/>, |
| 2900 |
<xref linkend="guc-max-parallel-maintenance-workers"/>, and |
| 2901 |
<xref linkend="guc-max-parallel-workers-per-gather"/>. |
| 2902 |
</para> |
| 2903 |
</listitem> |
| 2904 |
</varlistentry> |
| 2905 |
|
| 2906 |
<varlistentry id="guc-max-parallel-workers-per-gather" xreflabel="max_parallel_workers_per_gather"> |
| 2907 |
<term><varname>max_parallel_workers_per_gather</varname> (<type>integer</type>) |
| 2908 |
<indexterm> |
| 2909 |
<primary><varname>max_parallel_workers_per_gather</varname> configuration parameter</primary> |
| 2910 |
</indexterm> |
| 2911 |
</term> |
| 2912 |
<listitem> |
| 2913 |
<para> |
| 2914 |
Sets the maximum number of workers that can be started by a single |
| 2915 |
<literal>Gather</literal> or <literal>Gather Merge</literal> node. |
| 2916 |
Parallel workers are taken from the pool of processes established by |
| 2917 |
<xref linkend="guc-max-worker-processes"/>, limited by |
| 2918 |
<xref linkend="guc-max-parallel-workers"/>. Note that the requested |
| 2919 |
number of workers may not actually be available at run time. If this |
| 2920 |
occurs, the plan will run with fewer workers than expected, which may |
| 2921 |
be inefficient. The default value is 2. Setting this value to 0 |
| 2922 |
disables parallel query execution. |
| 2923 |
</para> |
| 2924 |
|
| 2925 |
<para> |
| 2926 |
Note that parallel queries may consume very substantially more |
| 2927 |
resources than non-parallel queries, because each worker process is |
| 2928 |
a completely separate process which has roughly the same impact on the |
| 2929 |
system as an additional user session. This should be taken into |
| 2930 |
account when choosing a value for this setting, as well as when |
| 2931 |
configuring other settings that control resource utilization, such |
| 2932 |
as <xref linkend="guc-work-mem"/>. Resource limits such as |
| 2933 |
<varname>work_mem</varname> are applied individually to each worker, |
| 2934 |
which means the total utilization may be much higher across all |
| 2935 |
processes than it would normally be for any single process. |
| 2936 |
For example, a parallel query using 4 workers may use up to 5 times |
| 2937 |
as much CPU time, memory, I/O bandwidth, and so forth as a query which |
| 2938 |
uses no workers at all. |
| 2939 |
</para> |
| 2940 |
|
| 2941 |
<para> |
| 2942 |
For more information on parallel query, see |
| 2943 |
<xref linkend="parallel-query"/>. |
| 2944 |
</para> |
| 2945 |
</listitem> |
| 2946 |
</varlistentry> |
| 2947 |
|
| 2948 |
<varlistentry id="guc-max-parallel-maintenance-workers" xreflabel="max_parallel_maintenance_workers"> |
| 2949 |
<term><varname>max_parallel_maintenance_workers</varname> (<type>integer</type>) |
| 2950 |
<indexterm> |
| 2951 |
<primary><varname>max_parallel_maintenance_workers</varname> configuration parameter</primary> |
| 2952 |
</indexterm> |
| 2953 |
</term> |
| 2954 |
<listitem> |
| 2955 |
<para> |
| 2956 |
Sets the maximum number of parallel workers that can be |
| 2957 |
started by a single utility command. Currently, the parallel |
| 2958 |
utility commands that support the use of parallel workers are |
| 2959 |
<command>CREATE INDEX</command> when building a B-tree, |
| 2960 |
GIN, or BRIN index, |
| 2961 |
and <command>VACUUM</command> without <literal>FULL</literal> |
| 2962 |
option. Parallel workers are taken from the pool of processes |
| 2963 |
established by <xref linkend="guc-max-worker-processes"/>, limited |
| 2964 |
by <xref linkend="guc-max-parallel-workers"/>. Note that the requested |
| 2965 |
number of workers may not actually be available at run time. |
| 2966 |
If this occurs, the utility operation will run with fewer |
| 2967 |
workers than expected. The default value is 2. Setting this |
| 2968 |
value to 0 disables the use of parallel workers by utility |
| 2969 |
commands. |
| 2970 |
</para> |
| 2971 |
|
| 2972 |
<para> |
| 2973 |
Note that parallel utility commands should not consume |
| 2974 |
substantially more memory than equivalent non-parallel |
| 2975 |
operations. This strategy differs from that of parallel |
| 2976 |
query, where resource limits generally apply per worker |
| 2977 |
process. Parallel utility commands treat the resource limit |
| 2978 |
<varname>maintenance_work_mem</varname> as a limit to be applied to |
| 2979 |
the entire utility command, regardless of the number of |
| 2980 |
parallel worker processes. However, parallel utility |
| 2981 |
commands may still consume substantially more CPU resources |
| 2982 |
and I/O bandwidth. |
| 2983 |
</para> |
| 2984 |
</listitem> |
| 2985 |
</varlistentry> |
| 2986 |
|
| 2987 |
<varlistentry id="guc-max-parallel-workers" xreflabel="max_parallel_workers"> |
| 2988 |
<term><varname>max_parallel_workers</varname> (<type>integer</type>) |
| 2989 |
<indexterm> |
| 2990 |
<primary><varname>max_parallel_workers</varname> configuration parameter</primary> |
| 2991 |
</indexterm> |
| 2992 |
</term> |
| 2993 |
<listitem> |
| 2994 |
<para> |
| 2995 |
Sets the maximum number of workers that the cluster can support for |
| 2996 |
parallel operations. The default value is 8. When increasing or |
| 2997 |
decreasing this value, consider also adjusting |
| 2998 |
<xref linkend="guc-max-parallel-maintenance-workers"/> and |
| 2999 |
<xref linkend="guc-max-parallel-workers-per-gather"/>. |
| 3000 |
Also, note that a setting for this value which is higher than |
| 3001 |
<xref linkend="guc-max-worker-processes"/> will have no effect, |
| 3002 |
since parallel workers are taken from the pool of worker processes |
| 3003 |
established by that setting. |
| 3004 |
</para> |
| 3005 |
</listitem> |
| 3006 |
</varlistentry> |
| 3007 |
|
| 3008 |
<varlistentry id="guc-parallel-leader-participation" xreflabel="parallel_leader_participation"> |
| 3009 |
<term> |
| 3010 |
<varname>parallel_leader_participation</varname> (<type>boolean</type>) |
| 3011 |
<indexterm> |
| 3012 |
<primary><varname>parallel_leader_participation</varname> configuration parameter</primary> |
| 3013 |
</indexterm> |
| 3014 |
</term> |
| 3015 |
<listitem> |
| 3016 |
<para> |
| 3017 |
Allows the leader process to execute the query plan under |
| 3018 |
<literal>Gather</literal> and <literal>Gather Merge</literal> nodes |
| 3019 |
instead of waiting for worker processes. The default is |
| 3020 |
<literal>on</literal>. Setting this value to <literal>off</literal> |
| 3021 |
reduces the likelihood that workers will become blocked because the |
| 3022 |
leader is not reading tuples fast enough, but requires the leader |
| 3023 |
process to wait for worker processes to start up before the first |
| 3024 |
tuples can be produced. The degree to which the leader can help or |
| 3025 |
hinder performance depends on the plan type, number of workers and |
| 3026 |
query duration. |
| 3027 |
</para> |
| 3028 |
</listitem> |
| 3029 |
</varlistentry> |
| 3030 |
</variablelist> |
| 3031 |
</sect2> |
| 3032 |
</sect1> |
| 3033 |
|
| 3034 |
<sect1 id="runtime-config-wal"> |
| 3035 |
<title>Write Ahead Log</title> |
| 3036 |
|
| 3037 |
<para> |
| 3038 |
For additional information on tuning these settings, |
| 3039 |
see <xref linkend="wal-configuration"/>. |
| 3040 |
</para> |
| 3041 |
|
| 3042 |
<sect2 id="runtime-config-wal-settings"> |
| 3043 |
<title>Settings</title> |
| 3044 |
<variablelist> |
| 3045 |
|
| 3046 |
<varlistentry id="guc-wal-level" xreflabel="wal_level"> |
| 3047 |
<term><varname>wal_level</varname> (<type>enum</type>) |
| 3048 |
<indexterm> |
| 3049 |
<primary><varname>wal_level</varname> configuration parameter</primary> |
| 3050 |
</indexterm> |
| 3051 |
</term> |
| 3052 |
<listitem> |
| 3053 |
<para> |
| 3054 |
<varname>wal_level</varname> determines how much information is written to |
| 3055 |
the WAL. The default value is <literal>replica</literal>, which writes enough |
| 3056 |
data to support WAL archiving and replication, including running |
| 3057 |
read-only queries on a standby server. <literal>minimal</literal> removes all |
| 3058 |
logging except the information required to recover from a crash or |
| 3059 |
immediate shutdown. Finally, |
| 3060 |
<literal>logical</literal> adds information necessary to support logical |
| 3061 |
decoding. Each level includes the information logged at all lower |
| 3062 |
levels. This parameter can only be set at server start. |
| 3063 |
</para> |
| 3064 |
<para> |
| 3065 |
The <literal>minimal</literal> level generates the least WAL |
| 3066 |
volume. It logs no row information for permanent relations |
| 3067 |
in transactions that create or |
| 3068 |
rewrite them. This can make operations much faster (see |
| 3069 |
<xref linkend="populate-pitr"/>). Operations that initiate this |
| 3070 |
optimization include: |
| 3071 |
<simplelist> |
| 3072 |
<member><command>ALTER ... SET TABLESPACE</command></member> |
| 3073 |
<member><command>CLUSTER</command></member> |
| 3074 |
<member><command>CREATE TABLE</command></member> |
| 3075 |
<member><command>REFRESH MATERIALIZED VIEW</command> |
| 3076 |
(without <option>CONCURRENTLY</option>)</member> |
| 3077 |
<member><command>REINDEX</command></member> |
| 3078 |
<member><command>TRUNCATE</command></member> |
| 3079 |
</simplelist> |
| 3080 |
However, minimal WAL does not contain sufficient information for |
| 3081 |
point-in-time recovery, so <literal>replica</literal> or |
| 3082 |
higher must be used to enable continuous archiving |
| 3083 |
(<xref linkend="guc-archive-mode"/>) and streaming binary replication. |
| 3084 |
In fact, the server will not even start in this mode if |
| 3085 |
<varname>max_wal_senders</varname> is non-zero. |
| 3086 |
Note that changing <varname>wal_level</varname> to |
| 3087 |
<literal>minimal</literal> makes previous base backups unusable |
| 3088 |
for point-in-time recovery and standby servers. |
| 3089 |
</para> |
| 3090 |
<para> |
| 3091 |
In <literal>logical</literal> level, the same information is logged as |
| 3092 |
with <literal>replica</literal>, plus information needed to |
| 3093 |
extract logical change sets from the WAL. Using a level of |
| 3094 |
<literal>logical</literal> will increase the WAL volume, particularly if many |
| 3095 |
tables are configured for <literal>REPLICA IDENTITY FULL</literal> and |
| 3096 |
many <command>UPDATE</command> and <command>DELETE</command> statements are |
| 3097 |
executed. |
| 3098 |
</para> |
| 3099 |
<para> |
| 3100 |
In releases prior to 9.6, this parameter also allowed the |
| 3101 |
values <literal>archive</literal> and <literal>hot_standby</literal>. |
| 3102 |
These are still accepted but mapped to <literal>replica</literal>. |
| 3103 |
</para> |
| 3104 |
</listitem> |
| 3105 |
</varlistentry> |
| 3106 |
|
| 3107 |
<varlistentry id="guc-fsync" xreflabel="fsync"> |
| 3108 |
<term><varname>fsync</varname> (<type>boolean</type>) |
| 3109 |
<indexterm> |
| 3110 |
<primary><varname>fsync</varname> configuration parameter</primary> |
| 3111 |
</indexterm> |
| 3112 |
</term> |
| 3113 |
<listitem> |
| 3114 |
<para> |
| 3115 |
If this parameter is on, the <productname>PostgreSQL</productname> server |
| 3116 |
will try to make sure that updates are physically written to |
| 3117 |
disk, by issuing <function>fsync()</function> system calls or various |
| 3118 |
equivalent methods (see <xref linkend="guc-wal-sync-method"/>). |
| 3119 |
This ensures that the database cluster can recover to a |
| 3120 |
consistent state after an operating system or hardware crash. |
| 3121 |
</para> |
| 3122 |
|
| 3123 |
<para> |
| 3124 |
While turning off <varname>fsync</varname> is often a performance |
| 3125 |
benefit, this can result in unrecoverable data corruption in |
| 3126 |
the event of a power failure or system crash. Thus it |
| 3127 |
is only advisable to turn off <varname>fsync</varname> if |
| 3128 |
you can easily recreate your entire database from external |
| 3129 |
data. |
| 3130 |
</para> |
| 3131 |
|
| 3132 |
<para> |
| 3133 |
Examples of safe circumstances for turning off |
| 3134 |
<varname>fsync</varname> include the initial loading of a new |
| 3135 |
database cluster from a backup file, using a database cluster |
| 3136 |
for processing a batch of data after which the database |
| 3137 |
will be thrown away and recreated, |
| 3138 |
or for a read-only database clone which |
| 3139 |
gets recreated frequently and is not used for failover. High |
| 3140 |
quality hardware alone is not a sufficient justification for |
| 3141 |
turning off <varname>fsync</varname>. |
| 3142 |
</para> |
| 3143 |
|
| 3144 |
<para> |
| 3145 |
For reliable recovery when changing <varname>fsync</varname> |
| 3146 |
off to on, it is necessary to force all modified buffers in the |
| 3147 |
kernel to durable storage. This can be done while the cluster |
| 3148 |
is shutdown or while <varname>fsync</varname> is on by running <command>initdb |
| 3149 |
--sync-only</command>, running <command>sync</command>, unmounting the |
| 3150 |
file system, or rebooting the server. |
| 3151 |
</para> |
| 3152 |
|
| 3153 |
<para> |
| 3154 |
In many situations, turning off <xref linkend="guc-synchronous-commit"/> |
| 3155 |
for noncritical transactions can provide much of the potential |
| 3156 |
performance benefit of turning off <varname>fsync</varname>, without |
| 3157 |
the attendant risks of data corruption. |
| 3158 |
</para> |
| 3159 |
|
| 3160 |
<para> |
| 3161 |
<varname>fsync</varname> can only be set in the <filename>postgresql.conf</filename> |
| 3162 |
file or on the server command line. |
| 3163 |
If you turn this parameter off, also consider turning off |
| 3164 |
<xref linkend="guc-full-page-writes"/>. |
| 3165 |
</para> |
| 3166 |
</listitem> |
| 3167 |
</varlistentry> |
| 3168 |
|
| 3169 |
<varlistentry id="guc-synchronous-commit" xreflabel="synchronous_commit"> |
| 3170 |
<term><varname>synchronous_commit</varname> (<type>enum</type>) |
| 3171 |
<indexterm> |
| 3172 |
<primary><varname>synchronous_commit</varname> configuration parameter</primary> |
| 3173 |
</indexterm> |
| 3174 |
</term> |
| 3175 |
<listitem> |
| 3176 |
<para> |
| 3177 |
Specifies how much WAL processing must complete before |
| 3178 |
the database server returns a <quote>success</quote> |
| 3179 |
indication to the client. Valid values are |
| 3180 |
<literal>remote_apply</literal>, <literal>on</literal> |
| 3181 |
(the default), <literal>remote_write</literal>, |
| 3182 |
<literal>local</literal>, and <literal>off</literal>. |
| 3183 |
</para> |
| 3184 |
|
| 3185 |
<para> |
| 3186 |
If <varname>synchronous_standby_names</varname> is empty, |
| 3187 |
the only meaningful settings are <literal>on</literal> and |
| 3188 |
<literal>off</literal>; <literal>remote_apply</literal>, |
| 3189 |
<literal>remote_write</literal> and <literal>local</literal> |
| 3190 |
all provide the same local synchronization level |
| 3191 |
as <literal>on</literal>. The local behavior of all |
| 3192 |
non-<literal>off</literal> modes is to wait for local flush of WAL |
| 3193 |
to disk. In <literal>off</literal> mode, there is no waiting, |
| 3194 |
so there can be a delay between when success is reported to the |
| 3195 |
client and when the transaction is later guaranteed to be safe |
| 3196 |
against a server crash. (The maximum |
| 3197 |
delay is three times <xref linkend="guc-wal-writer-delay"/>.) Unlike |
| 3198 |
<xref linkend="guc-fsync"/>, setting this parameter to <literal>off</literal> |
| 3199 |
does not create any risk of database inconsistency: an operating |
| 3200 |
system or database crash might |
| 3201 |
result in some recent allegedly-committed transactions being lost, but |
| 3202 |
the database state will be just the same as if those transactions had |
| 3203 |
been aborted cleanly. So, turning <varname>synchronous_commit</varname> off |
| 3204 |
can be a useful alternative when performance is more important than |
| 3205 |
exact certainty about the durability of a transaction. For more |
| 3206 |
discussion see <xref linkend="wal-async-commit"/>. |
| 3207 |
</para> |
| 3208 |
|
| 3209 |
<para> |
| 3210 |
If <xref linkend="guc-synchronous-standby-names"/> is non-empty, |
| 3211 |
<varname>synchronous_commit</varname> also controls whether |
| 3212 |
transaction commits will wait for their WAL records to be |
| 3213 |
processed on the standby server(s). |
| 3214 |
</para> |
| 3215 |
|
| 3216 |
<para> |
| 3217 |
When set to <literal>remote_apply</literal>, commits will wait |
| 3218 |
until replies from the current synchronous standby(s) indicate they |
| 3219 |
have received the commit record of the transaction and applied |
| 3220 |
it, so that it has become visible to queries on the standby(s), |
| 3221 |
and also written to durable storage on the standbys. This will |
| 3222 |
cause much larger commit delays than previous settings since |
| 3223 |
it waits for WAL replay. When set to <literal>on</literal>, |
| 3224 |
commits wait until replies |
| 3225 |
from the current synchronous standby(s) indicate they have received |
| 3226 |
the commit record of the transaction and flushed it to durable storage. This |
| 3227 |
ensures the transaction will not be lost unless both the primary and |
| 3228 |
all synchronous standbys suffer corruption of their database storage. |
| 3229 |
When set to <literal>remote_write</literal>, commits will wait until replies |
| 3230 |
from the current synchronous standby(s) indicate they have |
| 3231 |
received the commit record of the transaction and written it to |
| 3232 |
their file systems. This setting ensures data preservation if a standby instance of |
| 3233 |
<productname>PostgreSQL</productname> crashes, but not if the standby |
| 3234 |
suffers an operating-system-level crash because the data has not |
| 3235 |
necessarily reached durable storage on the standby. |
| 3236 |
The setting <literal>local</literal> causes commits to wait for |
| 3237 |
local flush to disk, but not for replication. This is usually not |
| 3238 |
desirable when synchronous replication is in use, but is provided for |
| 3239 |
completeness. |
| 3240 |
</para> |
| 3241 |
|
| 3242 |
<para> |
| 3243 |
This parameter can be changed at any time; the behavior for any |
| 3244 |
one transaction is determined by the setting in effect when it |
| 3245 |
commits. It is therefore possible, and useful, to have some |
| 3246 |
transactions commit synchronously and others asynchronously. |
| 3247 |
For example, to make a single multistatement transaction commit |
| 3248 |
asynchronously when the default is the opposite, issue <command>SET |
| 3249 |
LOCAL synchronous_commit TO OFF</command> within the transaction. |
| 3250 |
</para> |
| 3251 |
|
| 3252 |
<para> |
| 3253 |
<xref linkend="synchronous-commit-matrix"/> summarizes the |
| 3254 |
capabilities of the <varname>synchronous_commit</varname> settings. |
| 3255 |
</para> |
| 3256 |
|
| 3257 |
<table id="synchronous-commit-matrix"> |
| 3258 |
<title>synchronous_commit Modes</title> |
| 3259 |
<tgroup cols="5"> |
| 3260 |
<colspec colname="col1" colwidth="1.5*"/> |
| 3261 |
<colspec colname="col2" colwidth="1*"/> |
| 3262 |
<colspec colname="col3" colwidth="1*"/> |
| 3263 |
<colspec colname="col4" colwidth="1*"/> |
| 3264 |
<colspec colname="col5" colwidth="1*"/> |
| 3265 |
<thead> |
| 3266 |
<row> |
| 3267 |
<entry>synchronous_commit setting</entry> |
| 3268 |
<entry>local durable commit</entry> |
| 3269 |
<entry>standby durable commit after PG crash</entry> |
| 3270 |
<entry>standby durable commit after OS crash</entry> |
| 3271 |
<entry>standby query consistency</entry> |
| 3272 |
</row> |
| 3273 |
</thead> |
| 3274 |
|
| 3275 |
<tbody> |
| 3276 |
|
| 3277 |
<row> |
| 3278 |
<entry>remote_apply</entry> |
| 3279 |
<entry align="center">•</entry> |
| 3280 |
<entry align="center">•</entry> |
| 3281 |
<entry align="center">•</entry> |
| 3282 |
<entry align="center">•</entry> |
| 3283 |
</row> |
| 3284 |
|
| 3285 |
<row> |
| 3286 |
<entry>on</entry> |
| 3287 |
<entry align="center">•</entry> |
| 3288 |
<entry align="center">•</entry> |
| 3289 |
<entry align="center">•</entry> |
| 3290 |
<entry align="center"></entry> |
| 3291 |
</row> |
| 3292 |
|
| 3293 |
<row> |
| 3294 |
<entry>remote_write</entry> |
| 3295 |
<entry align="center">•</entry> |
| 3296 |
<entry align="center">•</entry> |
| 3297 |
<entry align="center"></entry> |
| 3298 |
<entry align="center"></entry> |
| 3299 |
</row> |
| 3300 |
|
| 3301 |
<row> |
| 3302 |
<entry>local</entry> |
| 3303 |
<entry align="center">•</entry> |
| 3304 |
<entry align="center"></entry> |
| 3305 |
<entry align="center"></entry> |
| 3306 |
<entry align="center"></entry> |
| 3307 |
</row> |
| 3308 |
|
| 3309 |
<row> |
| 3310 |
<entry>off</entry> |
| 3311 |
<entry align="center"></entry> |
| 3312 |
<entry align="center"></entry> |
| 3313 |
<entry align="center"></entry> |
| 3314 |
<entry align="center"></entry> |
| 3315 |
</row> |
| 3316 |
|
| 3317 |
</tbody> |
| 3318 |
</tgroup> |
| 3319 |
</table> |
| 3320 |
|
| 3321 |
</listitem> |
| 3322 |
</varlistentry> |
| 3323 |
|
| 3324 |
<varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method"> |
| 3325 |
<term><varname>wal_sync_method</varname> (<type>enum</type>) |
| 3326 |
<indexterm> |
| 3327 |
<primary><varname>wal_sync_method</varname> configuration parameter</primary> |
| 3328 |
</indexterm> |
| 3329 |
</term> |
| 3330 |
<listitem> |
| 3331 |
<para> |
| 3332 |
Method used for forcing WAL updates out to disk. |
| 3333 |
If <varname>fsync</varname> is off then this setting is irrelevant, |
| 3334 |
since WAL file updates will not be forced out at all. |
| 3335 |
Possible values are: |
| 3336 |
</para> |
| 3337 |
<itemizedlist> |
| 3338 |
<listitem> |
| 3339 |
<para> |
| 3340 |
<literal>open_datasync</literal> (write WAL files with <function>open()</function> option <symbol>O_DSYNC</symbol>) |
| 3341 |
</para> |
| 3342 |
</listitem> |
| 3343 |
<listitem> |
| 3344 |
<para> |
| 3345 |
<literal>fdatasync</literal> (call <function>fdatasync()</function> at each commit) |
| 3346 |
</para> |
| 3347 |
</listitem> |
| 3348 |
<listitem> |
| 3349 |
<para> |
| 3350 |
<literal>fsync</literal> (call <function>fsync()</function> at each commit) |
| 3351 |
</para> |
| 3352 |
</listitem> |
| 3353 |
<listitem> |
| 3354 |
<para> |
| 3355 |
<literal>fsync_writethrough</literal> (call <function>fsync()</function> at each commit, forcing write-through of any disk write cache) |
| 3356 |
</para> |
| 3357 |
</listitem> |
| 3358 |
<listitem> |
| 3359 |
<para> |
| 3360 |
<literal>open_sync</literal> (write WAL files with <function>open()</function> option <symbol>O_SYNC</symbol>) |
| 3361 |
</para> |
| 3362 |
</listitem> |
| 3363 |
</itemizedlist> |
| 3364 |
<para> |
| 3365 |
Not all of these choices are available on all platforms. |
| 3366 |
The default is the first method in the above list that is supported |
| 3367 |
by the platform, except that <literal>fdatasync</literal> is the default on |
| 3368 |
Linux and FreeBSD. The default is not necessarily ideal; it might be |
| 3369 |
necessary to change this setting or other aspects of your system |
| 3370 |
configuration in order to create a crash-safe configuration or |
| 3371 |
achieve optimal performance. |
| 3372 |
These aspects are discussed in <xref linkend="wal-reliability"/>. |
| 3373 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3374 |
file or on the server command line. |
| 3375 |
</para> |
| 3376 |
</listitem> |
| 3377 |
</varlistentry> |
| 3378 |
|
| 3379 |
<varlistentry id="guc-full-page-writes" xreflabel="full_page_writes"> |
| 3380 |
<term><varname>full_page_writes</varname> (<type>boolean</type>) |
| 3381 |
<indexterm> |
| 3382 |
<primary><varname>full_page_writes</varname> configuration parameter</primary> |
| 3383 |
</indexterm> |
| 3384 |
</term> |
| 3385 |
<listitem> |
| 3386 |
<para> |
| 3387 |
When this parameter is on, the <productname>PostgreSQL</productname> server |
| 3388 |
writes the entire content of each disk page to WAL during the |
| 3389 |
first modification of that page after a checkpoint. |
| 3390 |
This is needed because |
| 3391 |
a page write that is in process during an operating system crash might |
| 3392 |
be only partially completed, leading to an on-disk page |
| 3393 |
that contains a mix of old and new data. The row-level change data |
| 3394 |
normally stored in WAL will not be enough to completely restore |
| 3395 |
such a page during post-crash recovery. Storing the full page image |
| 3396 |
guarantees that the page can be correctly restored, but at the price |
| 3397 |
of increasing the amount of data that must be written to WAL. |
| 3398 |
(Because WAL replay always starts from a checkpoint, it is sufficient |
| 3399 |
to do this during the first change of each page after a checkpoint. |
| 3400 |
Therefore, one way to reduce the cost of full-page writes is to |
| 3401 |
increase the checkpoint interval parameters.) |
| 3402 |
</para> |
| 3403 |
|
| 3404 |
<para> |
| 3405 |
Turning this parameter off speeds normal operation, but |
| 3406 |
might lead to either unrecoverable data corruption, or silent |
| 3407 |
data corruption, after a system failure. The risks are similar to turning off |
| 3408 |
<varname>fsync</varname>, though smaller, and it should be turned off |
| 3409 |
only based on the same circumstances recommended for that parameter. |
| 3410 |
</para> |
| 3411 |
|
| 3412 |
<para> |
| 3413 |
Turning off this parameter does not affect use of |
| 3414 |
WAL archiving for point-in-time recovery (PITR) |
| 3415 |
(see <xref linkend="continuous-archiving"/>). |
| 3416 |
</para> |
| 3417 |
|
| 3418 |
<para> |
| 3419 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3420 |
file or on the server command line. |
| 3421 |
The default is <literal>on</literal>. |
| 3422 |
</para> |
| 3423 |
</listitem> |
| 3424 |
</varlistentry> |
| 3425 |
|
| 3426 |
<varlistentry id="guc-wal-log-hints" xreflabel="wal_log_hints"> |
| 3427 |
<term><varname>wal_log_hints</varname> (<type>boolean</type>) |
| 3428 |
<indexterm> |
| 3429 |
<primary><varname>wal_log_hints</varname> configuration parameter</primary> |
| 3430 |
</indexterm> |
| 3431 |
</term> |
| 3432 |
<listitem> |
| 3433 |
<para> |
| 3434 |
When this parameter is <literal>on</literal>, the <productname>PostgreSQL</productname> |
| 3435 |
server writes the entire content of each disk page to WAL during the |
| 3436 |
first modification of that page after a checkpoint, even for |
| 3437 |
non-critical modifications of so-called hint bits. |
| 3438 |
</para> |
| 3439 |
|
| 3440 |
<para> |
| 3441 |
If data checksums are enabled, hint bit updates are always WAL-logged |
| 3442 |
and this setting is ignored. You can use this setting to test how much |
| 3443 |
extra WAL-logging would occur if your database had data checksums |
| 3444 |
enabled. |
| 3445 |
</para> |
| 3446 |
|
| 3447 |
<para> |
| 3448 |
This parameter can only be set at server start. The default value is <literal>off</literal>. |
| 3449 |
</para> |
| 3450 |
</listitem> |
| 3451 |
</varlistentry> |
| 3452 |
|
| 3453 |
<varlistentry id="guc-wal-compression" xreflabel="wal_compression"> |
| 3454 |
<term><varname>wal_compression</varname> (<type>enum</type>) |
| 3455 |
<indexterm> |
| 3456 |
<primary><varname>wal_compression</varname> configuration parameter</primary> |
| 3457 |
</indexterm> |
| 3458 |
</term> |
| 3459 |
<listitem> |
| 3460 |
<para> |
| 3461 |
This parameter enables compression of WAL using the specified |
| 3462 |
compression method. |
| 3463 |
When enabled, the <productname>PostgreSQL</productname> |
| 3464 |
server compresses full page images written to WAL (e.g. when |
| 3465 |
<xref linkend="guc-full-page-writes"/> is on, during a base backup, |
| 3466 |
etc.). |
| 3467 |
A compressed page image will be decompressed during WAL replay. |
| 3468 |
The supported methods are <literal>pglz</literal>, |
| 3469 |
<literal>lz4</literal> (if <productname>PostgreSQL</productname> |
| 3470 |
was compiled with <option>--with-lz4</option>) and |
| 3471 |
<literal>zstd</literal> (if <productname>PostgreSQL</productname> |
| 3472 |
was compiled with <option>--with-zstd</option>). |
| 3473 |
The value <literal>on</literal> is a historical spelling of <literal>pglz</literal>. |
| 3474 |
The default value is <literal>off</literal>. |
| 3475 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 3476 |
privilege can change this setting. |
| 3477 |
</para> |
| 3478 |
|
| 3479 |
<para> |
| 3480 |
Enabling compression can reduce the WAL volume without |
| 3481 |
increasing the risk of unrecoverable data corruption, |
| 3482 |
but at the cost of some extra CPU spent on the compression during |
| 3483 |
WAL logging and on the decompression during WAL replay. |
| 3484 |
</para> |
| 3485 |
</listitem> |
| 3486 |
</varlistentry> |
| 3487 |
|
| 3488 |
<varlistentry id="guc-wal-init-zero" xreflabel="wal_init_zero"> |
| 3489 |
<term><varname>wal_init_zero</varname> (<type>boolean</type>) |
| 3490 |
<indexterm> |
| 3491 |
<primary><varname>wal_init_zero</varname> configuration parameter</primary> |
| 3492 |
</indexterm> |
| 3493 |
</term> |
| 3494 |
<listitem> |
| 3495 |
<para> |
| 3496 |
If set to <literal>on</literal> (the default), this option causes new |
| 3497 |
WAL files to be filled with zeroes. On some file systems, this ensures |
| 3498 |
that space is allocated before we need to write WAL records. However, |
| 3499 |
<firstterm>Copy-On-Write</firstterm> (COW) file systems may not benefit |
| 3500 |
from this technique, so the option is given to skip the unnecessary |
| 3501 |
work. If set to <literal>off</literal>, only the final byte is written |
| 3502 |
when the file is created so that it has the expected size. |
| 3503 |
</para> |
| 3504 |
</listitem> |
| 3505 |
</varlistentry> |
| 3506 |
|
| 3507 |
<varlistentry id="guc-wal-recycle" xreflabel="wal_recycle"> |
| 3508 |
<term><varname>wal_recycle</varname> (<type>boolean</type>) |
| 3509 |
<indexterm> |
| 3510 |
<primary><varname>wal_recycle</varname> configuration parameter</primary> |
| 3511 |
</indexterm> |
| 3512 |
</term> |
| 3513 |
<listitem> |
| 3514 |
<para> |
| 3515 |
If set to <literal>on</literal> (the default), this option causes WAL |
| 3516 |
files to be recycled by renaming them, avoiding the need to create new |
| 3517 |
ones. On COW file systems, it may be faster to create new ones, so the |
| 3518 |
option is given to disable this behavior. |
| 3519 |
</para> |
| 3520 |
</listitem> |
| 3521 |
</varlistentry> |
| 3522 |
|
| 3523 |
<varlistentry id="guc-wal-buffers" xreflabel="wal_buffers"> |
| 3524 |
<term><varname>wal_buffers</varname> (<type>integer</type>) |
| 3525 |
<indexterm> |
| 3526 |
<primary><varname>wal_buffers</varname> configuration parameter</primary> |
| 3527 |
</indexterm> |
| 3528 |
</term> |
| 3529 |
<listitem> |
| 3530 |
<para> |
| 3531 |
The amount of shared memory used for WAL data that has not yet been |
| 3532 |
written to disk. The default setting of -1 selects a size equal to |
| 3533 |
1/32nd (about 3%) of <xref linkend="guc-shared-buffers"/>, but not less |
| 3534 |
than <literal>64kB</literal> nor more than the size of one WAL |
| 3535 |
segment, typically <literal>16MB</literal>. This value can be set |
| 3536 |
manually if the automatic choice is too large or too small, |
| 3537 |
but any positive value less than <literal>32kB</literal> will be |
| 3538 |
treated as <literal>32kB</literal>. |
| 3539 |
If this value is specified without units, it is taken as WAL blocks, |
| 3540 |
that is <symbol>XLOG_BLCKSZ</symbol> bytes, typically 8kB. |
| 3541 |
This parameter can only be set at server start. |
| 3542 |
</para> |
| 3543 |
|
| 3544 |
<para> |
| 3545 |
The contents of the WAL buffers are written out to disk at every |
| 3546 |
transaction commit, so extremely large values are unlikely to |
| 3547 |
provide a significant benefit. However, setting this value to at |
| 3548 |
least a few megabytes can improve write performance on a busy |
| 3549 |
server where many clients are committing at once. The auto-tuning |
| 3550 |
selected by the default setting of -1 should give reasonable |
| 3551 |
results in most cases. |
| 3552 |
</para> |
| 3553 |
|
| 3554 |
</listitem> |
| 3555 |
</varlistentry> |
| 3556 |
|
| 3557 |
<varlistentry id="guc-wal-writer-delay" xreflabel="wal_writer_delay"> |
| 3558 |
<term><varname>wal_writer_delay</varname> (<type>integer</type>) |
| 3559 |
<indexterm> |
| 3560 |
<primary><varname>wal_writer_delay</varname> configuration parameter</primary> |
| 3561 |
</indexterm> |
| 3562 |
</term> |
| 3563 |
<listitem> |
| 3564 |
<para> |
| 3565 |
Specifies how often the WAL writer flushes WAL, in time terms. |
| 3566 |
After flushing WAL the writer sleeps for the length of time given |
| 3567 |
by <varname>wal_writer_delay</varname>, unless woken up sooner |
| 3568 |
by an asynchronously committing transaction. If the last flush |
| 3569 |
happened less than <varname>wal_writer_delay</varname> ago and less |
| 3570 |
than <varname>wal_writer_flush_after</varname> worth of WAL has been |
| 3571 |
produced since, then WAL is only written to the operating system, not |
| 3572 |
flushed to disk. |
| 3573 |
If this value is specified without units, it is taken as milliseconds. |
| 3574 |
The default value is 200 milliseconds (<literal>200ms</literal>). Note that |
| 3575 |
on some systems, the effective resolution of sleep delays is 10 |
| 3576 |
milliseconds; setting <varname>wal_writer_delay</varname> to a value that is |
| 3577 |
not a multiple of 10 might have the same results as setting it to the |
| 3578 |
next higher multiple of 10. This parameter can only be set in the |
| 3579 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 3580 |
</para> |
| 3581 |
</listitem> |
| 3582 |
</varlistentry> |
| 3583 |
|
| 3584 |
<varlistentry id="guc-wal-writer-flush-after" xreflabel="wal_writer_flush_after"> |
| 3585 |
<term><varname>wal_writer_flush_after</varname> (<type>integer</type>) |
| 3586 |
<indexterm> |
| 3587 |
<primary><varname>wal_writer_flush_after</varname> configuration parameter</primary> |
| 3588 |
</indexterm> |
| 3589 |
</term> |
| 3590 |
<listitem> |
| 3591 |
<para> |
| 3592 |
Specifies how often the WAL writer flushes WAL, in volume terms. |
| 3593 |
If the last flush happened less |
| 3594 |
than <varname>wal_writer_delay</varname> ago and less |
| 3595 |
than <varname>wal_writer_flush_after</varname> worth of WAL has been |
| 3596 |
produced since, then WAL is only written to the operating system, not |
| 3597 |
flushed to disk. If <varname>wal_writer_flush_after</varname> is set |
| 3598 |
to <literal>0</literal> then WAL data is always flushed immediately. |
| 3599 |
If this value is specified without units, it is taken as WAL blocks, |
| 3600 |
that is <symbol>XLOG_BLCKSZ</symbol> bytes, typically 8kB. |
| 3601 |
The default is <literal>1MB</literal>. |
| 3602 |
This parameter can only be set in the |
| 3603 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 3604 |
</para> |
| 3605 |
</listitem> |
| 3606 |
</varlistentry> |
| 3607 |
|
| 3608 |
<varlistentry id="guc-wal-skip-threshold" xreflabel="wal_skip_threshold"> |
| 3609 |
<term><varname>wal_skip_threshold</varname> (<type>integer</type>) |
| 3610 |
<indexterm> |
| 3611 |
<primary><varname>wal_skip_threshold</varname> configuration parameter</primary> |
| 3612 |
</indexterm> |
| 3613 |
</term> |
| 3614 |
<listitem> |
| 3615 |
<para> |
| 3616 |
When <varname>wal_level</varname> is <literal>minimal</literal> and a |
| 3617 |
transaction commits after creating or rewriting a permanent relation, |
| 3618 |
this setting determines how to persist the new data. If the data is |
| 3619 |
smaller than this setting, write it to the WAL log; otherwise, use an |
| 3620 |
fsync of affected files. Depending on the properties of your storage, |
| 3621 |
raising or lowering this value might help if such commits are slowing |
| 3622 |
concurrent transactions. If this value is specified without units, it |
| 3623 |
is taken as kilobytes. The default is two megabytes |
| 3624 |
(<literal>2MB</literal>). |
| 3625 |
</para> |
| 3626 |
</listitem> |
| 3627 |
</varlistentry> |
| 3628 |
|
| 3629 |
<varlistentry id="guc-commit-delay" xreflabel="commit_delay"> |
| 3630 |
<term><varname>commit_delay</varname> (<type>integer</type>) |
| 3631 |
<indexterm> |
| 3632 |
<primary><varname>commit_delay</varname> configuration parameter</primary> |
| 3633 |
</indexterm> |
| 3634 |
</term> |
| 3635 |
<listitem> |
| 3636 |
<para> |
| 3637 |
Setting <varname>commit_delay</varname> adds a time delay |
| 3638 |
before a WAL flush is initiated. This can improve |
| 3639 |
group commit throughput by allowing a larger number of transactions |
| 3640 |
to commit via a single WAL flush, if system load is high enough |
| 3641 |
that additional transactions become ready to commit within the |
| 3642 |
given interval. However, it also increases latency by up to the |
| 3643 |
<varname>commit_delay</varname> for each WAL |
| 3644 |
flush. Because the delay is just wasted if no other transactions |
| 3645 |
become ready to commit, a delay is only performed if at least |
| 3646 |
<varname>commit_siblings</varname> other transactions are active |
| 3647 |
when a flush is about to be initiated. Also, no delays are |
| 3648 |
performed if <varname>fsync</varname> is disabled. |
| 3649 |
If this value is specified without units, it is taken as microseconds. |
| 3650 |
The default <varname>commit_delay</varname> is zero (no delay). |
| 3651 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 3652 |
privilege can change this setting. |
| 3653 |
</para> |
| 3654 |
<para> |
| 3655 |
In <productname>PostgreSQL</productname> releases prior to 9.3, |
| 3656 |
<varname>commit_delay</varname> behaved differently and was much |
| 3657 |
less effective: it affected only commits, rather than all WAL flushes, |
| 3658 |
and waited for the entire configured delay even if the WAL flush |
| 3659 |
was completed sooner. Beginning in <productname>PostgreSQL</productname> 9.3, |
| 3660 |
the first process that becomes ready to flush waits for the configured |
| 3661 |
interval, while subsequent processes wait only until the leader |
| 3662 |
completes the flush operation. |
| 3663 |
</para> |
| 3664 |
</listitem> |
| 3665 |
</varlistentry> |
| 3666 |
|
| 3667 |
<varlistentry id="guc-commit-siblings" xreflabel="commit_siblings"> |
| 3668 |
<term><varname>commit_siblings</varname> (<type>integer</type>) |
| 3669 |
<indexterm> |
| 3670 |
<primary><varname>commit_siblings</varname> configuration parameter</primary> |
| 3671 |
</indexterm> |
| 3672 |
</term> |
| 3673 |
<listitem> |
| 3674 |
<para> |
| 3675 |
Minimum number of concurrent open transactions to require |
| 3676 |
before performing the <varname>commit_delay</varname> delay. A larger |
| 3677 |
value makes it more probable that at least one other |
| 3678 |
transaction will become ready to commit during the delay |
| 3679 |
interval. The default is five transactions. |
| 3680 |
</para> |
| 3681 |
</listitem> |
| 3682 |
</varlistentry> |
| 3683 |
|
| 3684 |
</variablelist> |
| 3685 |
</sect2> |
| 3686 |
<sect2 id="runtime-config-wal-checkpoints"> |
| 3687 |
<title>Checkpoints</title> |
| 3688 |
|
| 3689 |
<variablelist> |
| 3690 |
<varlistentry id="guc-checkpoint-timeout" xreflabel="checkpoint_timeout"> |
| 3691 |
<term><varname>checkpoint_timeout</varname> (<type>integer</type>) |
| 3692 |
<indexterm> |
| 3693 |
<primary><varname>checkpoint_timeout</varname> configuration parameter</primary> |
| 3694 |
</indexterm> |
| 3695 |
</term> |
| 3696 |
<listitem> |
| 3697 |
<para> |
| 3698 |
Maximum time between automatic WAL checkpoints. |
| 3699 |
If this value is specified without units, it is taken as seconds. |
| 3700 |
The valid range is between 30 seconds and one day. |
| 3701 |
The default is five minutes (<literal>5min</literal>). |
| 3702 |
Increasing this parameter can increase the amount of time needed |
| 3703 |
for crash recovery. |
| 3704 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3705 |
file or on the server command line. |
| 3706 |
</para> |
| 3707 |
</listitem> |
| 3708 |
</varlistentry> |
| 3709 |
|
| 3710 |
<varlistentry id="guc-checkpoint-completion-target" xreflabel="checkpoint_completion_target"> |
| 3711 |
<term><varname>checkpoint_completion_target</varname> (<type>floating point</type>) |
| 3712 |
<indexterm> |
| 3713 |
<primary><varname>checkpoint_completion_target</varname> configuration parameter</primary> |
| 3714 |
</indexterm> |
| 3715 |
</term> |
| 3716 |
<listitem> |
| 3717 |
<para> |
| 3718 |
Specifies the target of checkpoint completion, as a fraction of |
| 3719 |
total time between checkpoints. The default is 0.9, which spreads the |
| 3720 |
checkpoint across almost all of the available interval, providing fairly |
| 3721 |
consistent I/O load while also leaving some time for checkpoint |
| 3722 |
completion overhead. Reducing this parameter is not recommended because |
| 3723 |
it causes the checkpoint to complete faster. This results in a higher |
| 3724 |
rate of I/O during the checkpoint followed by a period of less I/O between |
| 3725 |
the checkpoint completion and the next scheduled checkpoint. This |
| 3726 |
parameter can only be set in the <filename>postgresql.conf</filename> file |
| 3727 |
or on the server command line. |
| 3728 |
</para> |
| 3729 |
</listitem> |
| 3730 |
</varlistentry> |
| 3731 |
|
| 3732 |
<varlistentry id="guc-checkpoint-flush-after" xreflabel="checkpoint_flush_after"> |
| 3733 |
<term><varname>checkpoint_flush_after</varname> (<type>integer</type>) |
| 3734 |
<indexterm> |
| 3735 |
<primary><varname>checkpoint_flush_after</varname> configuration parameter</primary> |
| 3736 |
</indexterm> |
| 3737 |
</term> |
| 3738 |
<listitem> |
| 3739 |
<para> |
| 3740 |
Whenever more than this amount of data has been |
| 3741 |
written while performing a checkpoint, attempt to force the |
| 3742 |
OS to issue these writes to the underlying storage. Doing so will |
| 3743 |
limit the amount of dirty data in the kernel's page cache, reducing |
| 3744 |
the likelihood of stalls when an <function>fsync</function> is issued at the end of the |
| 3745 |
checkpoint, or when the OS writes data back in larger batches in the |
| 3746 |
background. Often that will result in greatly reduced transaction |
| 3747 |
latency, but there also are some cases, especially with workloads |
| 3748 |
that are bigger than <xref linkend="guc-shared-buffers"/>, but smaller |
| 3749 |
than the OS's page cache, where performance might degrade. This |
| 3750 |
setting may have no effect on some platforms. |
| 3751 |
If this value is specified without units, it is taken as blocks, |
| 3752 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 3753 |
The valid range is |
| 3754 |
between <literal>0</literal>, which disables forced writeback, |
| 3755 |
and <literal>2MB</literal>. The default is <literal>256kB</literal> on |
| 3756 |
Linux, <literal>0</literal> elsewhere. (If <symbol>BLCKSZ</symbol> is not |
| 3757 |
8kB, the default and maximum values scale proportionally to it.) |
| 3758 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3759 |
file or on the server command line. |
| 3760 |
</para> |
| 3761 |
</listitem> |
| 3762 |
</varlistentry> |
| 3763 |
|
| 3764 |
<varlistentry id="guc-checkpoint-warning" xreflabel="checkpoint_warning"> |
| 3765 |
<term><varname>checkpoint_warning</varname> (<type>integer</type>) |
| 3766 |
<indexterm> |
| 3767 |
<primary><varname>checkpoint_warning</varname> configuration parameter</primary> |
| 3768 |
</indexterm> |
| 3769 |
</term> |
| 3770 |
<listitem> |
| 3771 |
<para> |
| 3772 |
Write a message to the server log if checkpoints caused by |
| 3773 |
the filling of WAL segment files happen closer together |
| 3774 |
than this amount of time (which suggests that |
| 3775 |
<varname>max_wal_size</varname> ought to be raised). |
| 3776 |
If this value is specified without units, it is taken as seconds. |
| 3777 |
The default is 30 seconds (<literal>30s</literal>). |
| 3778 |
Zero disables the warning. |
| 3779 |
No warnings will be generated if <varname>checkpoint_timeout</varname> |
| 3780 |
is less than <varname>checkpoint_warning</varname>. |
| 3781 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3782 |
file or on the server command line. |
| 3783 |
</para> |
| 3784 |
</listitem> |
| 3785 |
</varlistentry> |
| 3786 |
|
| 3787 |
<varlistentry id="guc-max-wal-size" xreflabel="max_wal_size"> |
| 3788 |
<term><varname>max_wal_size</varname> (<type>integer</type>) |
| 3789 |
<indexterm> |
| 3790 |
<primary><varname>max_wal_size</varname> configuration parameter</primary> |
| 3791 |
</indexterm> |
| 3792 |
</term> |
| 3793 |
<listitem> |
| 3794 |
<para> |
| 3795 |
Maximum size to let the WAL grow during automatic |
| 3796 |
checkpoints. This is a soft limit; WAL size can exceed |
| 3797 |
<varname>max_wal_size</varname> under special circumstances, such as |
| 3798 |
heavy load, a failing <varname>archive_command</varname> or <varname>archive_library</varname>, or a high |
| 3799 |
<varname>wal_keep_size</varname> setting. |
| 3800 |
If this value is specified without units, it is taken as megabytes. |
| 3801 |
The default is 1 GB. |
| 3802 |
Increasing this parameter can increase the amount of time needed for |
| 3803 |
crash recovery. |
| 3804 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3805 |
file or on the server command line. |
| 3806 |
</para> |
| 3807 |
</listitem> |
| 3808 |
</varlistentry> |
| 3809 |
|
| 3810 |
<varlistentry id="guc-min-wal-size" xreflabel="min_wal_size"> |
| 3811 |
<term><varname>min_wal_size</varname> (<type>integer</type>) |
| 3812 |
<indexterm> |
| 3813 |
<primary><varname>min_wal_size</varname> configuration parameter</primary> |
| 3814 |
</indexterm> |
| 3815 |
</term> |
| 3816 |
<listitem> |
| 3817 |
<para> |
| 3818 |
As long as WAL disk usage stays below this setting, old WAL files are |
| 3819 |
always recycled for future use at a checkpoint, rather than removed. |
| 3820 |
This can be used to ensure that enough WAL space is reserved to |
| 3821 |
handle spikes in WAL usage, for example when running large batch |
| 3822 |
jobs. |
| 3823 |
If this value is specified without units, it is taken as megabytes. |
| 3824 |
The default is 80 MB. |
| 3825 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3826 |
file or on the server command line. |
| 3827 |
</para> |
| 3828 |
</listitem> |
| 3829 |
</varlistentry> |
| 3830 |
|
| 3831 |
</variablelist> |
| 3832 |
</sect2> |
| 3833 |
<sect2 id="runtime-config-wal-archiving"> |
| 3834 |
<title>Archiving</title> |
| 3835 |
|
| 3836 |
<variablelist> |
| 3837 |
<varlistentry id="guc-archive-mode" xreflabel="archive_mode"> |
| 3838 |
<term><varname>archive_mode</varname> (<type>enum</type>) |
| 3839 |
<indexterm> |
| 3840 |
<primary><varname>archive_mode</varname> configuration parameter</primary> |
| 3841 |
</indexterm> |
| 3842 |
</term> |
| 3843 |
<listitem> |
| 3844 |
<para> |
| 3845 |
When <varname>archive_mode</varname> is enabled, completed WAL segments |
| 3846 |
are sent to archive storage by setting |
| 3847 |
<xref linkend="guc-archive-command"/> or |
| 3848 |
<xref linkend="guc-archive-library"/>. In addition to <literal>off</literal>, |
| 3849 |
to disable, there are two modes: <literal>on</literal>, and |
| 3850 |
<literal>always</literal>. During normal operation, there is no |
| 3851 |
difference between the two modes, but when set to <literal>always</literal> |
| 3852 |
the WAL archiver is enabled also during archive recovery or standby |
| 3853 |
mode. In <literal>always</literal> mode, all files restored from the archive |
| 3854 |
or streamed with streaming replication will be archived (again). See |
| 3855 |
<xref linkend="continuous-archiving-in-standby"/> for details. |
| 3856 |
</para> |
| 3857 |
<para> |
| 3858 |
<varname>archive_mode</varname> is a separate setting from |
| 3859 |
<varname>archive_command</varname> and |
| 3860 |
<varname>archive_library</varname> so that |
| 3861 |
<varname>archive_command</varname> and |
| 3862 |
<varname>archive_library</varname> can be changed without leaving |
| 3863 |
archiving mode. |
| 3864 |
This parameter can only be set at server start. |
| 3865 |
<varname>archive_mode</varname> cannot be enabled when |
| 3866 |
<varname>wal_level</varname> is set to <literal>minimal</literal>. |
| 3867 |
</para> |
| 3868 |
</listitem> |
| 3869 |
</varlistentry> |
| 3870 |
|
| 3871 |
<varlistentry id="guc-archive-command" xreflabel="archive_command"> |
| 3872 |
<term><varname>archive_command</varname> (<type>string</type>) |
| 3873 |
<indexterm> |
| 3874 |
<primary><varname>archive_command</varname> configuration parameter</primary> |
| 3875 |
</indexterm> |
| 3876 |
</term> |
| 3877 |
<listitem> |
| 3878 |
<para> |
| 3879 |
The local shell command to execute to archive a completed WAL file |
| 3880 |
segment. Any <literal>%p</literal> in the string is |
| 3881 |
replaced by the path name of the file to archive, and any |
| 3882 |
<literal>%f</literal> is replaced by only the file name. |
| 3883 |
(The path name is relative to the working directory of the server, |
| 3884 |
i.e., the cluster's data directory.) |
| 3885 |
Use <literal>%%</literal> to embed an actual <literal>%</literal> character in the |
| 3886 |
command. It is important for the command to return a zero |
| 3887 |
exit status only if it succeeds. For more information see |
| 3888 |
<xref linkend="backup-archiving-wal"/>. |
| 3889 |
</para> |
| 3890 |
<para> |
| 3891 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 3892 |
file or on the server command line. It is only used if |
| 3893 |
<varname>archive_mode</varname> was enabled at server start and |
| 3894 |
<varname>archive_library</varname> is set to an empty string. If both |
| 3895 |
<varname>archive_command</varname> and <varname>archive_library</varname> |
| 3896 |
are set, an error will be raised. |
| 3897 |
If <varname>archive_command</varname> is an empty string (the default) while |
| 3898 |
<varname>archive_mode</varname> is enabled (and <varname>archive_library</varname> |
| 3899 |
is set to an empty string), WAL archiving is temporarily |
| 3900 |
disabled, but the server continues to accumulate WAL segment files in |
| 3901 |
the expectation that a command will soon be provided. Setting |
| 3902 |
<varname>archive_command</varname> to a command that does nothing but |
| 3903 |
return true, e.g., <literal>/bin/true</literal> (<literal>REM</literal> on |
| 3904 |
Windows), effectively disables |
| 3905 |
archiving, but also breaks the chain of WAL files needed for |
| 3906 |
archive recovery, so it should only be used in unusual circumstances. |
| 3907 |
</para> |
| 3908 |
</listitem> |
| 3909 |
</varlistentry> |
| 3910 |
|
| 3911 |
<varlistentry id="guc-archive-library" xreflabel="archive_library"> |
| 3912 |
<term><varname>archive_library</varname> (<type>string</type>) |
| 3913 |
<indexterm> |
| 3914 |
<primary><varname>archive_library</varname> configuration parameter</primary> |
| 3915 |
</indexterm> |
| 3916 |
</term> |
| 3917 |
<listitem> |
| 3918 |
<para> |
| 3919 |
The library to use for archiving completed WAL file segments. If set to |
| 3920 |
an empty string (the default), archiving via shell is enabled, and |
| 3921 |
<xref linkend="guc-archive-command"/> is used. If both |
| 3922 |
<varname>archive_command</varname> and <varname>archive_library</varname> |
| 3923 |
are set, an error will be raised. Otherwise, the specified |
| 3924 |
shared library is used for archiving. The WAL archiver process is |
| 3925 |
restarted by the postmaster when this parameter changes. For more |
| 3926 |
information, see <xref linkend="backup-archiving-wal"/> and |
| 3927 |
<xref linkend="archive-modules"/>. |
| 3928 |
</para> |
| 3929 |
<para> |
| 3930 |
This parameter can only be set in the |
| 3931 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 3932 |
</para> |
| 3933 |
</listitem> |
| 3934 |
</varlistentry> |
| 3935 |
|
| 3936 |
<varlistentry id="guc-archive-timeout" xreflabel="archive_timeout"> |
| 3937 |
<term><varname>archive_timeout</varname> (<type>integer</type>) |
| 3938 |
<indexterm> |
| 3939 |
<primary><varname>archive_timeout</varname> configuration parameter</primary> |
| 3940 |
</indexterm> |
| 3941 |
</term> |
| 3942 |
<listitem> |
| 3943 |
<para> |
| 3944 |
The <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/> is only invoked for |
| 3945 |
completed WAL segments. Hence, if your server generates little WAL |
| 3946 |
traffic (or has slack periods where it does so), there could be a |
| 3947 |
long delay between the completion of a transaction and its safe |
| 3948 |
recording in archive storage. To limit how old unarchived |
| 3949 |
data can be, you can set <varname>archive_timeout</varname> to force the |
| 3950 |
server to switch to a new WAL segment file periodically. When this |
| 3951 |
parameter is greater than zero, the server will switch to a new |
| 3952 |
segment file whenever this amount of time has elapsed since the last |
| 3953 |
segment file switch, and there has been any database activity, |
| 3954 |
including a single checkpoint (checkpoints are skipped if there is |
| 3955 |
no database activity). Note that archived files that are closed |
| 3956 |
early due to a forced switch are still the same length as completely |
| 3957 |
full files. Therefore, it is unwise to use a very short |
| 3958 |
<varname>archive_timeout</varname> — it will bloat your archive |
| 3959 |
storage. <varname>archive_timeout</varname> settings of a minute or so are |
| 3960 |
usually reasonable. You should consider using streaming replication, |
| 3961 |
instead of archiving, if you want data to be copied off the primary |
| 3962 |
server more quickly than that. |
| 3963 |
If this value is specified without units, it is taken as seconds. |
| 3964 |
This parameter can only be set in the |
| 3965 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 3966 |
</para> |
| 3967 |
</listitem> |
| 3968 |
</varlistentry> |
| 3969 |
|
| 3970 |
</variablelist> |
| 3971 |
</sect2> |
| 3972 |
|
| 3973 |
<sect2 id="runtime-config-wal-recovery"> |
| 3974 |
|
| 3975 |
<title>Recovery</title> |
| 3976 |
|
| 3977 |
<indexterm> |
| 3978 |
<primary>configuration</primary> |
| 3979 |
<secondary>of recovery</secondary> |
| 3980 |
<tertiary>general settings</tertiary> |
| 3981 |
</indexterm> |
| 3982 |
|
| 3983 |
<para> |
| 3984 |
This section describes the settings that apply to recovery in general, |
| 3985 |
affecting crash recovery, streaming replication and archive-based |
| 3986 |
replication. |
| 3987 |
</para> |
| 3988 |
|
| 3989 |
|
| 3990 |
<variablelist> |
| 3991 |
<varlistentry id="guc-recovery-prefetch" xreflabel="recovery_prefetch"> |
| 3992 |
<term><varname>recovery_prefetch</varname> (<type>enum</type>) |
| 3993 |
<indexterm> |
| 3994 |
<primary><varname>recovery_prefetch</varname> configuration parameter</primary> |
| 3995 |
</indexterm> |
| 3996 |
</term> |
| 3997 |
<listitem> |
| 3998 |
<para> |
| 3999 |
Whether to try to prefetch blocks that are referenced in the WAL that |
| 4000 |
are not yet in the buffer pool, during recovery. Valid values are |
| 4001 |
<literal>off</literal>, <literal>on</literal> and |
| 4002 |
<literal>try</literal> (the default). The setting |
| 4003 |
<literal>try</literal> enables |
| 4004 |
prefetching only if the operating system provides support for issuing |
| 4005 |
read-ahead advice. |
| 4006 |
</para> |
| 4007 |
<para> |
| 4008 |
Prefetching blocks that will soon be needed can reduce I/O wait times |
| 4009 |
during recovery with some workloads. |
| 4010 |
See also the <xref linkend="guc-wal-decode-buffer-size"/> and |
| 4011 |
<xref linkend="guc-maintenance-io-concurrency"/> settings, which limit |
| 4012 |
prefetching activity. |
| 4013 |
</para> |
| 4014 |
</listitem> |
| 4015 |
</varlistentry> |
| 4016 |
|
| 4017 |
<varlistentry id="guc-wal-decode-buffer-size" xreflabel="wal_decode_buffer_size"> |
| 4018 |
<term><varname>wal_decode_buffer_size</varname> (<type>integer</type>) |
| 4019 |
<indexterm> |
| 4020 |
<primary><varname>wal_decode_buffer_size</varname> configuration parameter</primary> |
| 4021 |
</indexterm> |
| 4022 |
</term> |
| 4023 |
<listitem> |
| 4024 |
<para> |
| 4025 |
A limit on how far ahead the server can look in the WAL, to find |
| 4026 |
blocks to prefetch. If this value is specified without units, it is |
| 4027 |
taken as bytes. |
| 4028 |
The default is 512kB. |
| 4029 |
This parameter can only be set at server start. |
| 4030 |
</para> |
| 4031 |
</listitem> |
| 4032 |
</varlistentry> |
| 4033 |
|
| 4034 |
</variablelist> |
| 4035 |
</sect2> |
| 4036 |
|
| 4037 |
<sect2 id="runtime-config-wal-archive-recovery"> |
| 4038 |
|
| 4039 |
<title>Archive Recovery</title> |
| 4040 |
|
| 4041 |
<indexterm> |
| 4042 |
<primary>configuration</primary> |
| 4043 |
<secondary>of recovery</secondary> |
| 4044 |
<tertiary>of a standby server</tertiary> |
| 4045 |
</indexterm> |
| 4046 |
|
| 4047 |
<para> |
| 4048 |
This section describes the settings that apply only for the duration of |
| 4049 |
the recovery. They must be reset for any subsequent recovery you wish to |
| 4050 |
perform. |
| 4051 |
</para> |
| 4052 |
|
| 4053 |
<para> |
| 4054 |
<quote>Recovery</quote> covers using the server as a standby or for |
| 4055 |
executing a targeted recovery. Typically, standby mode would be used to |
| 4056 |
provide high availability and/or read scalability, whereas a targeted |
| 4057 |
recovery is used to recover from data loss. |
| 4058 |
</para> |
| 4059 |
|
| 4060 |
<para> |
| 4061 |
To start the server in standby mode, create a file called |
| 4062 |
<filename>standby.signal</filename><indexterm><primary>standby.signal</primary></indexterm> |
| 4063 |
in the data directory. The server will enter recovery and will not stop |
| 4064 |
recovery when the end of archived WAL is reached, but will keep trying to |
| 4065 |
continue recovery by connecting to the sending server as specified by the |
| 4066 |
<varname>primary_conninfo</varname> setting and/or by fetching new WAL |
| 4067 |
segments using <varname>restore_command</varname>. For this mode, the |
| 4068 |
parameters from this section and <xref |
| 4069 |
linkend="runtime-config-replication-standby"/> are of interest. |
| 4070 |
Parameters from <xref linkend="runtime-config-wal-recovery-target"/> will |
| 4071 |
also be applied but are typically not useful in this mode. |
| 4072 |
</para> |
| 4073 |
|
| 4074 |
<para> |
| 4075 |
To start the server in targeted recovery mode, create a file called |
| 4076 |
<filename>recovery.signal</filename><indexterm><primary>recovery.signal</primary></indexterm> |
| 4077 |
in the data directory. If both <filename>standby.signal</filename> and |
| 4078 |
<filename>recovery.signal</filename> files are created, standby mode |
| 4079 |
takes precedence. Targeted recovery mode ends when the archived WAL is |
| 4080 |
fully replayed, or when <varname>recovery_target</varname> is reached. |
| 4081 |
In this mode, the parameters from both this section and <xref |
| 4082 |
linkend="runtime-config-wal-recovery-target"/> will be used. |
| 4083 |
</para> |
| 4084 |
|
| 4085 |
<variablelist> |
| 4086 |
<varlistentry id="guc-restore-command" xreflabel="restore_command"> |
| 4087 |
<term><varname>restore_command</varname> (<type>string</type>) |
| 4088 |
<indexterm> |
| 4089 |
<primary><varname>restore_command</varname> configuration parameter</primary> |
| 4090 |
</indexterm> |
| 4091 |
</term> |
| 4092 |
<listitem> |
| 4093 |
<para> |
| 4094 |
The local shell command to execute to retrieve an archived segment of |
| 4095 |
the WAL file series. This parameter is required for archive recovery, |
| 4096 |
but optional for streaming replication. |
| 4097 |
Any <literal>%f</literal> in the string is |
| 4098 |
replaced by the name of the file to retrieve from the archive, |
| 4099 |
and any <literal>%p</literal> is replaced by the copy destination path name |
| 4100 |
on the server. |
| 4101 |
(The path name is relative to the current working directory, |
| 4102 |
i.e., the cluster's data directory.) |
| 4103 |
Any <literal>%r</literal> is replaced by the name of the file containing the |
| 4104 |
last valid restart point. That is the earliest file that must be kept |
| 4105 |
to allow a restore to be restartable, so this information can be used |
| 4106 |
to truncate the archive to just the minimum required to support |
| 4107 |
restarting from the current restore. <literal>%r</literal> is typically only |
| 4108 |
used by warm-standby configurations |
| 4109 |
(see <xref linkend="warm-standby"/>). |
| 4110 |
Write <literal>%%</literal> to embed an actual <literal>%</literal> character. |
| 4111 |
</para> |
| 4112 |
|
| 4113 |
<para> |
| 4114 |
It is important for the command to return a zero exit status |
| 4115 |
only if it succeeds. The command <emphasis>will</emphasis> be asked for file |
| 4116 |
names that are not present in the archive; it must return nonzero |
| 4117 |
when so asked. Examples: |
| 4118 |
<programlisting> |
| 4119 |
restore_command = 'cp /mnt/server/archivedir/%f "%p"' |
| 4120 |
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows |
| 4121 |
</programlisting> |
| 4122 |
An exception is that if the command was terminated by a signal (other |
| 4123 |
than <systemitem>SIGTERM</systemitem>, which is used as part of a |
| 4124 |
database server shutdown) or an error by the shell (such as command |
| 4125 |
not found), then recovery will abort and the server will not start up. |
| 4126 |
</para> |
| 4127 |
|
| 4128 |
<para> |
| 4129 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 4130 |
file or on the server command line. |
| 4131 |
</para> |
| 4132 |
</listitem> |
| 4133 |
</varlistentry> |
| 4134 |
|
| 4135 |
<varlistentry id="guc-archive-cleanup-command" xreflabel="archive_cleanup_command"> |
| 4136 |
<term><varname>archive_cleanup_command</varname> (<type>string</type>) |
| 4137 |
<indexterm> |
| 4138 |
<primary><varname>archive_cleanup_command</varname> configuration parameter</primary> |
| 4139 |
</indexterm> |
| 4140 |
</term> |
| 4141 |
<listitem> |
| 4142 |
<para> |
| 4143 |
This optional parameter specifies a shell command that will be executed |
| 4144 |
at every restartpoint. The purpose of |
| 4145 |
<varname>archive_cleanup_command</varname> is to provide a mechanism for |
| 4146 |
cleaning up old archived WAL files that are no longer needed by the |
| 4147 |
standby server. |
| 4148 |
Any <literal>%r</literal> is replaced by the name of the file containing the |
| 4149 |
last valid restart point. |
| 4150 |
That is the earliest file that must be <emphasis>kept</emphasis> to allow a |
| 4151 |
restore to be restartable, and so all files earlier than <literal>%r</literal> |
| 4152 |
may be safely removed. |
| 4153 |
This information can be used to truncate the archive to just the |
| 4154 |
minimum required to support restart from the current restore. |
| 4155 |
The <xref linkend="pgarchivecleanup"/> module |
| 4156 |
is often used in <varname>archive_cleanup_command</varname> for |
| 4157 |
single-standby configurations, for example: |
| 4158 |
<programlisting>archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'</programlisting> |
| 4159 |
Note however that if multiple standby servers are restoring from the |
| 4160 |
same archive directory, you will need to ensure that you do not delete |
| 4161 |
WAL files until they are no longer needed by any of the servers. |
| 4162 |
<varname>archive_cleanup_command</varname> would typically be used in a |
| 4163 |
warm-standby configuration (see <xref linkend="warm-standby"/>). |
| 4164 |
Write <literal>%%</literal> to embed an actual <literal>%</literal> character in the |
| 4165 |
command. |
| 4166 |
</para> |
| 4167 |
<para> |
| 4168 |
If the command returns a nonzero exit status then a warning log |
| 4169 |
message will be written. An exception is that if the command was |
| 4170 |
terminated by a signal or an error by the shell (such as command not |
| 4171 |
found), a fatal error will be raised. |
| 4172 |
</para> |
| 4173 |
<para> |
| 4174 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 4175 |
file or on the server command line. |
| 4176 |
</para> |
| 4177 |
</listitem> |
| 4178 |
</varlistentry> |
| 4179 |
|
| 4180 |
<varlistentry id="guc-recovery-end-command" xreflabel="recovery_end_command"> |
| 4181 |
<term><varname>recovery_end_command</varname> (<type>string</type>) |
| 4182 |
<indexterm> |
| 4183 |
<primary><varname>recovery_end_command</varname> configuration parameter</primary> |
| 4184 |
</indexterm> |
| 4185 |
</term> |
| 4186 |
<listitem> |
| 4187 |
<para> |
| 4188 |
This parameter specifies a shell command that will be executed once only |
| 4189 |
at the end of recovery. This parameter is optional. The purpose of the |
| 4190 |
<varname>recovery_end_command</varname> is to provide a mechanism for cleanup |
| 4191 |
following replication or recovery. |
| 4192 |
Any <literal>%r</literal> is replaced by the name of the file containing the |
| 4193 |
last valid restart point, like in <xref linkend="guc-archive-cleanup-command"/>. |
| 4194 |
</para> |
| 4195 |
<para> |
| 4196 |
If the command returns a nonzero exit status then a warning log |
| 4197 |
message will be written and the database will proceed to start up |
| 4198 |
anyway. An exception is that if the command was terminated by a |
| 4199 |
signal or an error by the shell (such as command not found), the |
| 4200 |
database will not proceed with startup. |
| 4201 |
</para> |
| 4202 |
<para> |
| 4203 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 4204 |
file or on the server command line. |
| 4205 |
</para> |
| 4206 |
</listitem> |
| 4207 |
</varlistentry> |
| 4208 |
|
| 4209 |
</variablelist> |
| 4210 |
|
| 4211 |
</sect2> |
| 4212 |
|
| 4213 |
<sect2 id="runtime-config-wal-recovery-target"> |
| 4214 |
|
| 4215 |
<title>Recovery Target</title> |
| 4216 |
|
| 4217 |
<para> |
| 4218 |
By default, recovery will recover to the end of the WAL log. The |
| 4219 |
following parameters can be used to specify an earlier stopping point. |
| 4220 |
At most one of <varname>recovery_target</varname>, |
| 4221 |
<varname>recovery_target_lsn</varname>, <varname>recovery_target_name</varname>, |
| 4222 |
<varname>recovery_target_time</varname>, or <varname>recovery_target_xid</varname> |
| 4223 |
can be used; if more than one of these is specified in the configuration |
| 4224 |
file, an error will be raised. |
| 4225 |
These parameters can only be set at server start. |
| 4226 |
</para> |
| 4227 |
|
| 4228 |
<variablelist> |
| 4229 |
<varlistentry id="guc-recovery-target" xreflabel="recovery_target"> |
| 4230 |
<term><varname>recovery_target</varname><literal> = 'immediate'</literal> |
| 4231 |
<indexterm> |
| 4232 |
<primary><varname>recovery_target</varname> configuration parameter</primary> |
| 4233 |
</indexterm> |
| 4234 |
</term> |
| 4235 |
<listitem> |
| 4236 |
<para> |
| 4237 |
This parameter specifies that recovery should end as soon as a |
| 4238 |
consistent state is reached, i.e., as early as possible. When restoring |
| 4239 |
from an online backup, this means the point where taking the backup |
| 4240 |
ended. |
| 4241 |
</para> |
| 4242 |
<para> |
| 4243 |
Technically, this is a string parameter, but <literal>'immediate'</literal> |
| 4244 |
is currently the only allowed value. |
| 4245 |
</para> |
| 4246 |
</listitem> |
| 4247 |
</varlistentry> |
| 4248 |
|
| 4249 |
<varlistentry id="guc-recovery-target-name" xreflabel="recovery_target_name"> |
| 4250 |
<term><varname>recovery_target_name</varname> (<type>string</type>) |
| 4251 |
<indexterm> |
| 4252 |
<primary><varname>recovery_target_name</varname> configuration parameter</primary> |
| 4253 |
</indexterm> |
| 4254 |
</term> |
| 4255 |
<listitem> |
| 4256 |
<para> |
| 4257 |
This parameter specifies the named restore point (created with |
| 4258 |
<function>pg_create_restore_point()</function>) to which recovery will proceed. |
| 4259 |
</para> |
| 4260 |
</listitem> |
| 4261 |
</varlistentry> |
| 4262 |
|
| 4263 |
<varlistentry id="guc-recovery-target-time" xreflabel="recovery_target_time"> |
| 4264 |
<term><varname>recovery_target_time</varname> (<type>timestamp</type>) |
| 4265 |
<indexterm> |
| 4266 |
<primary><varname>recovery_target_time</varname> configuration parameter</primary> |
| 4267 |
</indexterm> |
| 4268 |
</term> |
| 4269 |
<listitem> |
| 4270 |
<para> |
| 4271 |
This parameter specifies the time stamp up to which recovery |
| 4272 |
will proceed. |
| 4273 |
The precise stopping point is also influenced by |
| 4274 |
<xref linkend="guc-recovery-target-inclusive"/>. |
| 4275 |
</para> |
| 4276 |
|
| 4277 |
<para> |
| 4278 |
The value of this parameter is a time stamp in the same format |
| 4279 |
accepted by the <type>timestamp with time zone</type> data type, |
| 4280 |
except that you cannot use a time zone abbreviation (unless the |
| 4281 |
<xref linkend="guc-timezone-abbreviations"/> variable has been set |
| 4282 |
earlier in the configuration file). Preferred style is to use a |
| 4283 |
numeric offset from UTC, or you can write a full time zone name, |
| 4284 |
e.g., <literal>Europe/Helsinki</literal> not <literal>EEST</literal>. |
| 4285 |
</para> |
| 4286 |
</listitem> |
| 4287 |
</varlistentry> |
| 4288 |
|
| 4289 |
<varlistentry id="guc-recovery-target-xid" xreflabel="recovery_target_xid"> |
| 4290 |
<term><varname>recovery_target_xid</varname> (<type>string</type>) |
| 4291 |
<indexterm> |
| 4292 |
<primary><varname>recovery_target_xid</varname> configuration parameter</primary> |
| 4293 |
</indexterm> |
| 4294 |
</term> |
| 4295 |
<listitem> |
| 4296 |
<para> |
| 4297 |
This parameter specifies the transaction ID up to which recovery |
| 4298 |
will proceed. Keep in mind |
| 4299 |
that while transaction IDs are assigned sequentially at transaction |
| 4300 |
start, transactions can complete in a different numeric order. |
| 4301 |
The transactions that will be recovered are those that committed |
| 4302 |
before (and optionally including) the specified one. |
| 4303 |
The precise stopping point is also influenced by |
| 4304 |
<xref linkend="guc-recovery-target-inclusive"/>. |
| 4305 |
</para> |
| 4306 |
</listitem> |
| 4307 |
</varlistentry> |
| 4308 |
|
| 4309 |
<varlistentry id="guc-recovery-target-lsn" xreflabel="recovery_target_lsn"> |
| 4310 |
<term><varname>recovery_target_lsn</varname> (<type>pg_lsn</type>) |
| 4311 |
<indexterm> |
| 4312 |
<primary><varname>recovery_target_lsn</varname> configuration parameter</primary> |
| 4313 |
</indexterm> |
| 4314 |
</term> |
| 4315 |
<listitem> |
| 4316 |
<para> |
| 4317 |
This parameter specifies the LSN of the write-ahead log location up |
| 4318 |
to which recovery will proceed. The precise stopping point is also |
| 4319 |
influenced by <xref linkend="guc-recovery-target-inclusive"/>. This |
| 4320 |
parameter is parsed using the system data type |
| 4321 |
<link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>. |
| 4322 |
</para> |
| 4323 |
</listitem> |
| 4324 |
</varlistentry> |
| 4325 |
</variablelist> |
| 4326 |
|
| 4327 |
<para> |
| 4328 |
The following options further specify the recovery target, and affect |
| 4329 |
what happens when the target is reached: |
| 4330 |
</para> |
| 4331 |
|
| 4332 |
<variablelist> |
| 4333 |
<varlistentry id="guc-recovery-target-inclusive" |
| 4334 |
xreflabel="recovery_target_inclusive"> |
| 4335 |
<term><varname>recovery_target_inclusive</varname> (<type>boolean</type>) |
| 4336 |
<indexterm> |
| 4337 |
<primary><varname>recovery_target_inclusive</varname> configuration parameter</primary> |
| 4338 |
</indexterm> |
| 4339 |
</term> |
| 4340 |
<listitem> |
| 4341 |
<para> |
| 4342 |
Specifies whether to stop just after the specified recovery target |
| 4343 |
(<literal>on</literal>), or just before the recovery target |
| 4344 |
(<literal>off</literal>). |
| 4345 |
Applies when <xref linkend="guc-recovery-target-lsn"/>, |
| 4346 |
<xref linkend="guc-recovery-target-time"/>, or |
| 4347 |
<xref linkend="guc-recovery-target-xid"/> is specified. |
| 4348 |
This setting controls whether transactions |
| 4349 |
having exactly the target WAL location (LSN), commit time, or transaction ID, respectively, will |
| 4350 |
be included in the recovery. Default is <literal>on</literal>. |
| 4351 |
</para> |
| 4352 |
</listitem> |
| 4353 |
</varlistentry> |
| 4354 |
|
| 4355 |
<varlistentry id="guc-recovery-target-timeline" |
| 4356 |
xreflabel="recovery_target_timeline"> |
| 4357 |
<term><varname>recovery_target_timeline</varname> (<type>string</type>) |
| 4358 |
<indexterm> |
| 4359 |
<primary><varname>recovery_target_timeline</varname> configuration parameter</primary> |
| 4360 |
</indexterm> |
| 4361 |
</term> |
| 4362 |
<listitem> |
| 4363 |
<para> |
| 4364 |
Specifies recovering into a particular timeline. The value can be a |
| 4365 |
numeric timeline ID or a special value. The value |
| 4366 |
<literal>current</literal> recovers along the same timeline that was |
| 4367 |
current when the base backup was taken. The |
| 4368 |
value <literal>latest</literal> recovers |
| 4369 |
to the latest timeline found in the archive, which is useful in |
| 4370 |
a standby server. <literal>latest</literal> is the default. |
| 4371 |
</para> |
| 4372 |
|
| 4373 |
<para> |
| 4374 |
To specify a timeline ID in hexadecimal (for example, if extracted |
| 4375 |
from a WAL file name or history file), prefix it with a |
| 4376 |
<literal>0x</literal>. For instance, if the WAL file name is |
| 4377 |
<filename>00000011000000A10000004F</filename>, then the timeline ID is |
| 4378 |
<literal>0x11</literal> (or 17 decimal). |
| 4379 |
</para> |
| 4380 |
|
| 4381 |
<para> |
| 4382 |
You usually only need to set this parameter |
| 4383 |
in complex re-recovery situations, where you need to return to |
| 4384 |
a state that itself was reached after a point-in-time recovery. |
| 4385 |
See <xref linkend="backup-timelines"/> for discussion. |
| 4386 |
</para> |
| 4387 |
</listitem> |
| 4388 |
</varlistentry> |
| 4389 |
|
| 4390 |
<varlistentry id="guc-recovery-target-action" |
| 4391 |
xreflabel="recovery_target_action"> |
| 4392 |
<term><varname>recovery_target_action</varname> (<type>enum</type>) |
| 4393 |
<indexterm> |
| 4394 |
<primary><varname>recovery_target_action</varname> configuration parameter</primary> |
| 4395 |
</indexterm> |
| 4396 |
</term> |
| 4397 |
<listitem> |
| 4398 |
<para> |
| 4399 |
Specifies what action the server should take once the recovery target is |
| 4400 |
reached. The default is <literal>pause</literal>, which means recovery will |
| 4401 |
be paused. <literal>promote</literal> means the recovery process will finish |
| 4402 |
and the server will start to accept connections. |
| 4403 |
Finally <literal>shutdown</literal> will stop the server after reaching the |
| 4404 |
recovery target. |
| 4405 |
</para> |
| 4406 |
<para> |
| 4407 |
The intended use of the <literal>pause</literal> setting is to allow queries |
| 4408 |
to be executed against the database to check if this recovery target |
| 4409 |
is the most desirable point for recovery. |
| 4410 |
The paused state can be resumed by |
| 4411 |
using <function>pg_wal_replay_resume()</function> (see |
| 4412 |
<xref linkend="functions-recovery-control-table"/>), which then |
| 4413 |
causes recovery to end. If this recovery target is not the |
| 4414 |
desired stopping point, then shut down the server, change the |
| 4415 |
recovery target settings to a later target and restart to |
| 4416 |
continue recovery. |
| 4417 |
</para> |
| 4418 |
<para> |
| 4419 |
The <literal>shutdown</literal> setting is useful to have the instance ready |
| 4420 |
at the exact replay point desired. The instance will still be able to |
| 4421 |
replay more WAL records (and in fact will have to replay WAL records |
| 4422 |
since the last checkpoint next time it is started). |
| 4423 |
</para> |
| 4424 |
<para> |
| 4425 |
Note that because <filename>recovery.signal</filename> will not be |
| 4426 |
removed when <varname>recovery_target_action</varname> is set to <literal>shutdown</literal>, |
| 4427 |
any subsequent start will end with immediate shutdown unless the |
| 4428 |
configuration is changed or the <filename>recovery.signal</filename> |
| 4429 |
file is removed manually. |
| 4430 |
</para> |
| 4431 |
<para> |
| 4432 |
This setting has no effect if no recovery target is set. |
| 4433 |
If <xref linkend="guc-hot-standby"/> is not enabled, a setting of |
| 4434 |
<literal>pause</literal> will act the same as <literal>shutdown</literal>. |
| 4435 |
If the recovery target is reached while a promotion is ongoing, |
| 4436 |
a setting of <literal>pause</literal> will act the same as |
| 4437 |
<literal>promote</literal>. |
| 4438 |
</para> |
| 4439 |
<para> |
| 4440 |
In any case, if a recovery target is configured but the archive |
| 4441 |
recovery ends before the target is reached, the server will shut down |
| 4442 |
with a fatal error. |
| 4443 |
</para> |
| 4444 |
</listitem> |
| 4445 |
</varlistentry> |
| 4446 |
|
| 4447 |
</variablelist> |
| 4448 |
</sect2> |
| 4449 |
|
| 4450 |
<sect2 id="runtime-config-wal-summarization"> |
| 4451 |
<title>WAL Summarization</title> |
| 4452 |
|
| 4453 |
<para> |
| 4454 |
These settings control WAL summarization, a feature which must be |
| 4455 |
enabled in order to perform an |
| 4456 |
<link linkend="backup-incremental-backup">incremental backup</link>. |
| 4457 |
</para> |
| 4458 |
|
| 4459 |
<variablelist> |
| 4460 |
<varlistentry id="guc-summarize-wal" xreflabel="summarize_wal"> |
| 4461 |
<term><varname>summarize_wal</varname> (<type>boolean</type>) |
| 4462 |
<indexterm> |
| 4463 |
<primary><varname>summarize_wal</varname> configuration parameter</primary> |
| 4464 |
</indexterm> |
| 4465 |
</term> |
| 4466 |
<listitem> |
| 4467 |
<para> |
| 4468 |
Enables the WAL summarizer process. Note that WAL summarization can |
| 4469 |
be enabled either on a primary or on a standby. This parameter can only |
| 4470 |
be set in the <filename>postgresql.conf</filename> file or on the server |
| 4471 |
command line. The default is <literal>off</literal>. |
| 4472 |
</para> |
| 4473 |
<para> |
| 4474 |
The server cannot be started with <literal>summarize_wal=on</literal> |
| 4475 |
if <literal>wal_level</literal> is set to <literal>minimal</literal>. If |
| 4476 |
<literal>summarize_wal=on</literal> is configured after server startup |
| 4477 |
while <literal>wal_level=minimal</literal>, the summarizer will run |
| 4478 |
but refuse to generate summary files for any WAL generated with |
| 4479 |
<literal>wal_level=minimal</literal>. |
| 4480 |
</para> |
| 4481 |
</listitem> |
| 4482 |
</varlistentry> |
| 4483 |
|
| 4484 |
<varlistentry id="guc-wal-summary-keep-time" xreflabel="wal_summary_keep_time"> |
| 4485 |
<term><varname>wal_summary_keep_time</varname> (<type>integer</type>) |
| 4486 |
<indexterm> |
| 4487 |
<primary><varname>wal_summary_keep_time</varname> configuration parameter</primary> |
| 4488 |
</indexterm> |
| 4489 |
</term> |
| 4490 |
<listitem> |
| 4491 |
<para> |
| 4492 |
Configures the amount of time after which the WAL summarizer |
| 4493 |
automatically removes old WAL summaries. The file timestamp is used to |
| 4494 |
determine which files are old enough to remove. Typically, you should set |
| 4495 |
this comfortably higher than the time that could pass between a backup |
| 4496 |
and a later incremental backup that depends on it. WAL summaries must |
| 4497 |
be available for the entire range of WAL records between the preceding |
| 4498 |
backup and the new one being taken; if not, the incremental backup will |
| 4499 |
fail. If this parameter is set to zero, WAL summaries will not be |
| 4500 |
automatically deleted, but it is safe to manually remove files that you |
| 4501 |
know will not be required for future incremental backups. |
| 4502 |
This parameter can only be set in the |
| 4503 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 4504 |
If this value is specified without units, it is taken as minutes. |
| 4505 |
The default is 10 days. If <literal>summarize_wal = off</literal>, |
| 4506 |
existing WAL summaries will not be removed regardless of the value of |
| 4507 |
this parameter, because the WAL summarizer will not run. |
| 4508 |
</para> |
| 4509 |
</listitem> |
| 4510 |
</varlistentry> |
| 4511 |
|
| 4512 |
</variablelist> |
| 4513 |
|
| 4514 |
</sect2> |
| 4515 |
|
| 4516 |
</sect1> |
| 4517 |
|
| 4518 |
<sect1 id="runtime-config-replication"> |
| 4519 |
<title>Replication</title> |
| 4520 |
|
| 4521 |
<para> |
| 4522 |
These settings control the behavior of the built-in |
| 4523 |
<firstterm>streaming replication</firstterm> feature (see |
| 4524 |
<xref linkend="streaming-replication"/>), and the built-in |
| 4525 |
<firstterm>logical replication</firstterm> feature (see |
| 4526 |
<xref linkend="logical-replication"/>). |
| 4527 |
</para> |
| 4528 |
|
| 4529 |
<para> |
| 4530 |
For <emphasis>streaming replication</emphasis>, servers will be either a |
| 4531 |
primary or a standby server. Primaries can send data, while standbys |
| 4532 |
are always receivers of replicated data. When cascading replication |
| 4533 |
(see <xref linkend="cascading-replication"/>) is used, standby servers |
| 4534 |
can also be senders, as well as receivers. |
| 4535 |
Parameters are mainly for sending and standby servers, though some |
| 4536 |
parameters have meaning only on the primary server. Settings may vary |
| 4537 |
across the cluster without problems if that is required. |
| 4538 |
</para> |
| 4539 |
|
| 4540 |
<para> |
| 4541 |
For <emphasis>logical replication</emphasis>, <firstterm>publishers</firstterm> |
| 4542 |
(servers that do <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>) |
| 4543 |
replicate data to <firstterm>subscribers</firstterm> |
| 4544 |
(servers that do <link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>). |
| 4545 |
Servers can also be publishers and subscribers at the same time. Note, |
| 4546 |
the following sections refer to publishers as "senders". For more details |
| 4547 |
about logical replication configuration settings refer to |
| 4548 |
<xref linkend="logical-replication-config"/>. |
| 4549 |
</para> |
| 4550 |
|
| 4551 |
<sect2 id="runtime-config-replication-sender"> |
| 4552 |
<title>Sending Servers</title> |
| 4553 |
|
| 4554 |
<para> |
| 4555 |
These parameters can be set on any server that is |
| 4556 |
to send replication data to one or more standby servers. |
| 4557 |
The primary is always a sending server, so these parameters must |
| 4558 |
always be set on the primary. |
| 4559 |
The role and meaning of these parameters does not change after a |
| 4560 |
standby becomes the primary. |
| 4561 |
</para> |
| 4562 |
|
| 4563 |
<variablelist> |
| 4564 |
<varlistentry id="guc-max-wal-senders" xreflabel="max_wal_senders"> |
| 4565 |
<term><varname>max_wal_senders</varname> (<type>integer</type>) |
| 4566 |
<indexterm> |
| 4567 |
<primary><varname>max_wal_senders</varname> configuration parameter</primary> |
| 4568 |
</indexterm> |
| 4569 |
</term> |
| 4570 |
<listitem> |
| 4571 |
<para> |
| 4572 |
Specifies the maximum number of concurrent connections from standby |
| 4573 |
servers or streaming base backup clients (i.e., the maximum number of |
| 4574 |
simultaneously running WAL sender processes). The default is |
| 4575 |
<literal>10</literal>. The value <literal>0</literal> means |
| 4576 |
replication is disabled. Abrupt disconnection of a streaming client might |
| 4577 |
leave an orphaned connection slot behind until a timeout is reached, |
| 4578 |
so this parameter should be set slightly higher than the maximum |
| 4579 |
number of expected clients so disconnected clients can immediately |
| 4580 |
reconnect. This parameter can only be set at server start. Also, |
| 4581 |
<varname>wal_level</varname> must be set to |
| 4582 |
<literal>replica</literal> or higher to allow connections from standby |
| 4583 |
servers. |
| 4584 |
</para> |
| 4585 |
|
| 4586 |
<para> |
| 4587 |
When running a standby server, you must set this parameter to the |
| 4588 |
same or higher value than on the primary server. Otherwise, queries |
| 4589 |
will not be allowed in the standby server. |
| 4590 |
</para> |
| 4591 |
</listitem> |
| 4592 |
</varlistentry> |
| 4593 |
|
| 4594 |
<varlistentry id="guc-max-replication-slots" xreflabel="max_replication_slots"> |
| 4595 |
<term><varname>max_replication_slots</varname> (<type>integer</type>) |
| 4596 |
<indexterm> |
| 4597 |
<primary><varname>max_replication_slots</varname> configuration parameter</primary> |
| 4598 |
</indexterm> |
| 4599 |
</term> |
| 4600 |
<listitem> |
| 4601 |
<para> |
| 4602 |
Specifies the maximum number of replication slots |
| 4603 |
(see <xref linkend="streaming-replication-slots"/>) that the server |
| 4604 |
can support. The default is 10. This parameter can only be set at |
| 4605 |
server start. |
| 4606 |
Setting it to a lower value than the number of currently |
| 4607 |
existing replication slots will prevent the server from starting. |
| 4608 |
Also, <varname>wal_level</varname> must be set |
| 4609 |
to <literal>replica</literal> or higher to allow replication slots to |
| 4610 |
be used. |
| 4611 |
</para> |
| 4612 |
</listitem> |
| 4613 |
</varlistentry> |
| 4614 |
|
| 4615 |
<varlistentry id="guc-output-plugin-libraries" xreflabel="output_plugin_libraries"> |
| 4616 |
<term><varname>output_plugin_libraries</varname> (<type>string</type>) |
| 4617 |
<indexterm> |
| 4618 |
<primary><varname>output_plugin_libraries</varname> configuration parameter</primary> |
| 4619 |
</indexterm> |
| 4620 |
</term> |
| 4621 |
<listitem> |
| 4622 |
<para> |
| 4623 |
Lists the libraries installed in <xref linkend="guc-dynamic-library-path"/> |
| 4624 |
that are also trusted for use as logical output plugins by replication |
| 4625 |
clients. Any <link linkend="logicaldecoding-example">logical decoding</link> |
| 4626 |
or <link linkend="protocol-replication">replication</link> requests for |
| 4627 |
other libraries will be refused. All users are subject to this |
| 4628 |
restriction. The default is <literal>'pgoutput, test_decoding'</literal>, |
| 4629 |
which are the two logical output plugins included in the standard |
| 4630 |
<productname>PostgreSQL</productname> distribution. |
| 4631 |
</para> |
| 4632 |
<para> |
| 4633 |
The format is a comma-separated list of library names, where each name |
| 4634 |
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> |
| 4635 |
command (but logical decoding clients must specify a plugin name that |
| 4636 |
<emphasis>exactly</emphasis> matches an entry in the list, without |
| 4637 |
variations in case or path structure). Whitespace between entries is |
| 4638 |
ignored; surround a library name with double quotes if you need to |
| 4639 |
include whitespace or commas in the name. |
| 4640 |
</para> |
| 4641 |
<para> |
| 4642 |
It is the responsibility of the server administrator to ensure that |
| 4643 |
libraries added to this list do not unintentionally give additional |
| 4644 |
privileges to non-superusers when they are loaded into the server. |
| 4645 |
</para> |
| 4646 |
<note> |
| 4647 |
<para> |
| 4648 |
When updating the server from a version that does not have the |
| 4649 |
<literal>output_plugin_libraries</literal> parameter, the following |
| 4650 |
query can help construct the list of plugins that are required by all |
| 4651 |
persistent logical replication slots: |
| 4652 |
<programlisting> |
| 4653 |
SELECT DISTINCT plugin FROM pg_replication_slots WHERE plugin IS NOT NULL; |
| 4654 |
</programlisting> |
| 4655 |
Review the list carefully for safety before adjusting |
| 4656 |
<literal>output_plugin_libraries</literal>. |
| 4657 |
</para> |
| 4658 |
<para> |
| 4659 |
The above query can only display plugins which were successfully |
| 4660 |
added to replication slots at some point in the past. Newly refused |
| 4661 |
requests will appear in the logs with a message similar to |
| 4662 |
<programlisting> |
| 4663 |
ERROR: library "..." may not be used as an output plugin |
| 4664 |
DETAIL: The configuration parameter "output_plugin_libraries" (currently 'pgoutput, test_decoding') does not name this library as a trusted output plugin. |
| 4665 |
HINT: If it is safe for all REPLICATION users to use this library as an output plugin, add it to "output_plugin_libraries" and reload the server configuration. |
| 4666 |
</programlisting> |
| 4667 |
</para> |
| 4668 |
</note> |
| 4669 |
</listitem> |
| 4670 |
</varlistentry> |
| 4671 |
|
| 4672 |
<varlistentry id="guc-wal-keep-size" xreflabel="wal_keep_size"> |
| 4673 |
<term><varname>wal_keep_size</varname> (<type>integer</type>) |
| 4674 |
<indexterm> |
| 4675 |
<primary><varname>wal_keep_size</varname> configuration parameter</primary> |
| 4676 |
</indexterm> |
| 4677 |
</term> |
| 4678 |
<listitem> |
| 4679 |
<para> |
| 4680 |
Specifies the minimum size of past WAL files kept in the |
| 4681 |
<filename>pg_wal</filename> |
| 4682 |
directory, in case a standby server needs to fetch them for streaming |
| 4683 |
replication. If a standby |
| 4684 |
server connected to the sending server falls behind by more than |
| 4685 |
<varname>wal_keep_size</varname> megabytes, the sending server might |
| 4686 |
remove a WAL segment still needed by the standby, in which case the |
| 4687 |
replication connection will be terminated. Downstream connections |
| 4688 |
will also eventually fail as a result. (However, the standby |
| 4689 |
server can recover by fetching the segment from archive, if WAL |
| 4690 |
archiving is in use.) |
| 4691 |
</para> |
| 4692 |
|
| 4693 |
<para> |
| 4694 |
This sets only the minimum size of segments retained in |
| 4695 |
<filename>pg_wal</filename>; the system might need to retain more segments |
| 4696 |
for WAL archival or to recover from a checkpoint. If |
| 4697 |
<varname>wal_keep_size</varname> is zero (the default), the system |
| 4698 |
doesn't keep any extra segments for standby purposes, so the number |
| 4699 |
of old WAL segments available to standby servers is a function of |
| 4700 |
the location of the previous checkpoint and status of WAL |
| 4701 |
archiving. |
| 4702 |
If this value is specified without units, it is taken as megabytes. |
| 4703 |
This parameter can only be set in the |
| 4704 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 4705 |
</para> |
| 4706 |
</listitem> |
| 4707 |
</varlistentry> |
| 4708 |
|
| 4709 |
<varlistentry id="guc-max-slot-wal-keep-size" xreflabel="max_slot_wal_keep_size"> |
| 4710 |
<term><varname>max_slot_wal_keep_size</varname> (<type>integer</type>) |
| 4711 |
<indexterm> |
| 4712 |
<primary><varname>max_slot_wal_keep_size</varname> configuration parameter</primary> |
| 4713 |
</indexterm> |
| 4714 |
</term> |
| 4715 |
<listitem> |
| 4716 |
<para> |
| 4717 |
Specify the maximum size of WAL files |
| 4718 |
that <link linkend="streaming-replication-slots">replication |
| 4719 |
slots</link> are allowed to retain in the <filename>pg_wal</filename> |
| 4720 |
directory at checkpoint time. |
| 4721 |
If <varname>max_slot_wal_keep_size</varname> is -1 (the default), |
| 4722 |
replication slots may retain an unlimited amount of WAL files. Otherwise, if |
| 4723 |
restart_lsn of a replication slot falls behind the current LSN by more |
| 4724 |
than the given size, the standby using the slot may no longer be able |
| 4725 |
to continue replication due to removal of required WAL files. You |
| 4726 |
can see the WAL availability of replication slots |
| 4727 |
in <link linkend="view-pg-replication-slots">pg_replication_slots</link>. |
| 4728 |
If this value is specified without units, it is taken as megabytes. |
| 4729 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 4730 |
file or on the server command line. |
| 4731 |
</para> |
| 4732 |
</listitem> |
| 4733 |
</varlistentry> |
| 4734 |
|
| 4735 |
<varlistentry id="guc-idle-replication-slot-timeout" xreflabel="idle_replication_slot_timeout"> |
| 4736 |
<term><varname>idle_replication_slot_timeout</varname> (<type>integer</type>) |
| 4737 |
<indexterm> |
| 4738 |
<primary><varname>idle_replication_slot_timeout</varname> configuration parameter</primary> |
| 4739 |
</indexterm> |
| 4740 |
</term> |
| 4741 |
<listitem> |
| 4742 |
<para> |
| 4743 |
Invalidate replication slots that have remained inactive (not used by |
| 4744 |
a <link linkend="protocol-replication">replication connection</link>) |
| 4745 |
for longer than this duration. |
| 4746 |
If this value is specified without units, it is taken as seconds. |
| 4747 |
A value of zero (the default) disables the idle timeout |
| 4748 |
invalidation mechanism. This parameter can only be set in the |
| 4749 |
<filename>postgresql.conf</filename> file or on the server command |
| 4750 |
line. |
| 4751 |
</para> |
| 4752 |
|
| 4753 |
<para> |
| 4754 |
Slot invalidation due to idle timeout occurs during checkpoint. |
| 4755 |
Because checkpoints happen at <varname>checkpoint_timeout</varname> |
| 4756 |
intervals, there can be some lag between when the |
| 4757 |
<varname>idle_replication_slot_timeout</varname> was exceeded and when |
| 4758 |
the slot invalidation is triggered at the next checkpoint. |
| 4759 |
To avoid such lags, users can force a checkpoint to promptly invalidate |
| 4760 |
inactive slots. The duration of slot inactivity is calculated using the |
| 4761 |
slot's <link linkend="view-pg-replication-slots">pg_replication_slots</link>.<structfield>inactive_since</structfield> |
| 4762 |
value. |
| 4763 |
</para> |
| 4764 |
|
| 4765 |
<para> |
| 4766 |
Note that the idle timeout invalidation mechanism is not applicable |
| 4767 |
for slots that do not reserve WAL or for slots on the standby server |
| 4768 |
that are being synced from the primary server (i.e., standby slots |
| 4769 |
having <link linkend="view-pg-replication-slots">pg_replication_slots</link>.<structfield>synced</structfield> |
| 4770 |
value <literal>true</literal>). Synced slots are always considered to |
| 4771 |
be inactive because they don't perform logical decoding to produce |
| 4772 |
changes. |
| 4773 |
</para> |
| 4774 |
</listitem> |
| 4775 |
</varlistentry> |
| 4776 |
|
| 4777 |
<varlistentry id="guc-wal-sender-timeout" xreflabel="wal_sender_timeout"> |
| 4778 |
<term><varname>wal_sender_timeout</varname> (<type>integer</type>) |
| 4779 |
<indexterm> |
| 4780 |
<primary><varname>wal_sender_timeout</varname> configuration parameter</primary> |
| 4781 |
</indexterm> |
| 4782 |
</term> |
| 4783 |
<listitem> |
| 4784 |
<para> |
| 4785 |
Terminate replication connections that are inactive for longer |
| 4786 |
than this amount of time. This is useful for |
| 4787 |
the sending server to detect a standby crash or network outage. |
| 4788 |
If this value is specified without units, it is taken as milliseconds. |
| 4789 |
The default value is 60 seconds. |
| 4790 |
A value of zero disables the timeout mechanism. |
| 4791 |
</para> |
| 4792 |
<para> |
| 4793 |
With a cluster distributed across multiple geographic |
| 4794 |
locations, using different values per location brings more flexibility |
| 4795 |
in the cluster management. A smaller value is useful for faster |
| 4796 |
failure detection with a standby having a low-latency network |
| 4797 |
connection, and a larger value helps in judging better the health |
| 4798 |
of a standby if located on a remote location, with a high-latency |
| 4799 |
network connection. |
| 4800 |
</para> |
| 4801 |
</listitem> |
| 4802 |
</varlistentry> |
| 4803 |
|
| 4804 |
<varlistentry id="guc-track-commit-timestamp" xreflabel="track_commit_timestamp"> |
| 4805 |
<term><varname>track_commit_timestamp</varname> (<type>boolean</type>) |
| 4806 |
<indexterm> |
| 4807 |
<primary><varname>track_commit_timestamp</varname> configuration parameter</primary> |
| 4808 |
</indexterm> |
| 4809 |
</term> |
| 4810 |
<listitem> |
| 4811 |
<para> |
| 4812 |
Record commit time of transactions. |
| 4813 |
This parameter can only be set at server start. |
| 4814 |
The default value is <literal>off</literal>. |
| 4815 |
</para> |
| 4816 |
</listitem> |
| 4817 |
</varlistentry> |
| 4818 |
|
| 4819 |
</variablelist> |
| 4820 |
</sect2> |
| 4821 |
|
| 4822 |
<sect2 id="runtime-config-replication-primary"> |
| 4823 |
<title>Primary Server</title> |
| 4824 |
|
| 4825 |
<para> |
| 4826 |
These parameters can be set on the primary server that is |
| 4827 |
to send replication data to one or more standby servers. |
| 4828 |
Note that in addition to these parameters, |
| 4829 |
<xref linkend="guc-wal-level"/> must be set appropriately on the primary |
| 4830 |
server, and optionally WAL archiving can be enabled as |
| 4831 |
well (see <xref linkend="runtime-config-wal-archiving"/>). |
| 4832 |
The values of these parameters on standby servers are irrelevant, |
| 4833 |
although you may wish to set them there in preparation for the |
| 4834 |
possibility of a standby becoming the primary. |
| 4835 |
</para> |
| 4836 |
|
| 4837 |
<variablelist> |
| 4838 |
|
| 4839 |
<varlistentry id="guc-synchronous-standby-names" xreflabel="synchronous_standby_names"> |
| 4840 |
<term><varname>synchronous_standby_names</varname> (<type>string</type>) |
| 4841 |
<indexterm> |
| 4842 |
<primary><varname>synchronous_standby_names</varname> configuration parameter</primary> |
| 4843 |
</indexterm> |
| 4844 |
</term> |
| 4845 |
<listitem> |
| 4846 |
<para> |
| 4847 |
Specifies a list of standby servers that can support |
| 4848 |
<firstterm>synchronous replication</firstterm>, as described in |
| 4849 |
<xref linkend="synchronous-replication"/>. |
| 4850 |
There will be one or more active synchronous standbys; |
| 4851 |
transactions waiting for commit will be allowed to proceed after |
| 4852 |
these standby servers confirm receipt of their data. |
| 4853 |
The synchronous standbys will be those whose names appear |
| 4854 |
in this list, and |
| 4855 |
that are both currently connected and streaming data in real-time |
| 4856 |
(as shown by a state of <literal>streaming</literal> in the |
| 4857 |
<link linkend="monitoring-pg-stat-replication-view"> |
| 4858 |
<structname>pg_stat_replication</structname></link> view). |
| 4859 |
Specifying more than one synchronous standby can allow for very high |
| 4860 |
availability and protection against data loss. |
| 4861 |
</para> |
| 4862 |
<para> |
| 4863 |
The name of a standby server for this purpose is the |
| 4864 |
<varname>application_name</varname> setting of the standby, as set in the |
| 4865 |
standby's connection information. In case of a physical replication |
| 4866 |
standby, this should be set in the <varname>primary_conninfo</varname> |
| 4867 |
setting; the default is the setting of <xref linkend="guc-cluster-name"/> |
| 4868 |
if set, else <literal>walreceiver</literal>. |
| 4869 |
For logical replication, this can be set in the connection |
| 4870 |
information of the subscription, and it defaults to the |
| 4871 |
subscription name. For other replication stream consumers, |
| 4872 |
consult their documentation. |
| 4873 |
</para> |
| 4874 |
<para> |
| 4875 |
This parameter specifies a list of standby servers using |
| 4876 |
either of the following syntaxes: |
| 4877 |
<synopsis> |
| 4878 |
[FIRST] <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] ) |
| 4879 |
ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="parameter">standby_name</replaceable> [, ...] ) |
| 4880 |
<replaceable class="parameter">standby_name</replaceable> [, ...] |
| 4881 |
</synopsis> |
| 4882 |
where <replaceable class="parameter">num_sync</replaceable> is |
| 4883 |
the number of synchronous standbys that transactions need to |
| 4884 |
wait for replies from, |
| 4885 |
and <replaceable class="parameter">standby_name</replaceable> |
| 4886 |
is the name of a standby server. |
| 4887 |
<replaceable class="parameter">num_sync</replaceable> |
| 4888 |
must be an integer value greater than zero. |
| 4889 |
<literal>FIRST</literal> and <literal>ANY</literal> specify the method to choose |
| 4890 |
synchronous standbys from the listed servers. |
| 4891 |
</para> |
| 4892 |
<para> |
| 4893 |
The keyword <literal>FIRST</literal>, coupled with |
| 4894 |
<replaceable class="parameter">num_sync</replaceable>, specifies a |
| 4895 |
priority-based synchronous replication and makes transaction commits |
| 4896 |
wait until their WAL records are replicated to |
| 4897 |
<replaceable class="parameter">num_sync</replaceable> synchronous |
| 4898 |
standbys chosen based on their priorities. For example, a setting of |
| 4899 |
<literal>FIRST 3 (s1, s2, s3, s4)</literal> will cause each commit to wait for |
| 4900 |
replies from three higher-priority standbys chosen from standby servers |
| 4901 |
<literal>s1</literal>, <literal>s2</literal>, <literal>s3</literal> and <literal>s4</literal>. |
| 4902 |
The standbys whose names appear earlier in the list are given higher |
| 4903 |
priority and will be considered as synchronous. Other standby servers |
| 4904 |
appearing later in this list represent potential synchronous standbys. |
| 4905 |
If any of the current synchronous standbys disconnects for whatever |
| 4906 |
reason, it will be replaced immediately with the next-highest-priority |
| 4907 |
standby. The keyword <literal>FIRST</literal> is optional. |
| 4908 |
</para> |
| 4909 |
<para> |
| 4910 |
The keyword <literal>ANY</literal>, coupled with |
| 4911 |
<replaceable class="parameter">num_sync</replaceable>, specifies a |
| 4912 |
quorum-based synchronous replication and makes transaction commits |
| 4913 |
wait until their WAL records are replicated to <emphasis>at least</emphasis> |
| 4914 |
<replaceable class="parameter">num_sync</replaceable> listed standbys. |
| 4915 |
For example, a setting of <literal>ANY 3 (s1, s2, s3, s4)</literal> will cause |
| 4916 |
each commit to proceed as soon as at least any three standbys of |
| 4917 |
<literal>s1</literal>, <literal>s2</literal>, <literal>s3</literal> and <literal>s4</literal> |
| 4918 |
reply. |
| 4919 |
</para> |
| 4920 |
<para> |
| 4921 |
<literal>FIRST</literal> and <literal>ANY</literal> are case-insensitive. If these |
| 4922 |
keywords are used as the name of a standby server, |
| 4923 |
its <replaceable class="parameter">standby_name</replaceable> must |
| 4924 |
be double-quoted. |
| 4925 |
</para> |
| 4926 |
<para> |
| 4927 |
The third syntax was used before <productname>PostgreSQL</productname> |
| 4928 |
version 9.6 and is still supported. It's the same as the first syntax |
| 4929 |
with <literal>FIRST</literal> and |
| 4930 |
<replaceable class="parameter">num_sync</replaceable> equal to 1. |
| 4931 |
For example, <literal>FIRST 1 (s1, s2)</literal> and <literal>s1, s2</literal> have |
| 4932 |
the same meaning: either <literal>s1</literal> or <literal>s2</literal> is chosen |
| 4933 |
as a synchronous standby. |
| 4934 |
</para> |
| 4935 |
<para> |
| 4936 |
The special entry <literal>*</literal> matches any standby name. |
| 4937 |
</para> |
| 4938 |
<para> |
| 4939 |
There is no mechanism to enforce uniqueness of standby names. In case |
| 4940 |
of duplicates one of the matching standbys will be considered as |
| 4941 |
higher priority, though exactly which one is indeterminate. |
| 4942 |
</para> |
| 4943 |
<note> |
| 4944 |
<para> |
| 4945 |
Each <replaceable class="parameter">standby_name</replaceable> |
| 4946 |
should have the form of a valid SQL identifier, unless it |
| 4947 |
is <literal>*</literal>. You can use double-quoting if necessary. But note |
| 4948 |
that <replaceable class="parameter">standby_name</replaceable>s are |
| 4949 |
compared to standby application names case-insensitively, whether |
| 4950 |
double-quoted or not. |
| 4951 |
</para> |
| 4952 |
</note> |
| 4953 |
<para> |
| 4954 |
If no synchronous standby names are specified here, then synchronous |
| 4955 |
replication is not enabled and transaction commits will not wait for |
| 4956 |
replication. This is the default configuration. Even when |
| 4957 |
synchronous replication is enabled, individual transactions can be |
| 4958 |
configured not to wait for replication by setting the |
| 4959 |
<xref linkend="guc-synchronous-commit"/> parameter to |
| 4960 |
<literal>local</literal> or <literal>off</literal>. |
| 4961 |
</para> |
| 4962 |
<para> |
| 4963 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 4964 |
file or on the server command line. |
| 4965 |
</para> |
| 4966 |
</listitem> |
| 4967 |
|
| 4968 |
</varlistentry> |
| 4969 |
<varlistentry id="guc-synchronized-standby-slots" xreflabel="synchronized_standby_slots"> |
| 4970 |
<term><varname>synchronized_standby_slots</varname> (<type>string</type>) |
| 4971 |
<indexterm> |
| 4972 |
<primary><varname>synchronized_standby_slots</varname> configuration parameter</primary> |
| 4973 |
</indexterm> |
| 4974 |
</term> |
| 4975 |
<listitem> |
| 4976 |
<para> |
| 4977 |
A comma-separated list of streaming replication standby server slot names |
| 4978 |
that logical WAL sender processes will wait for. Logical WAL sender processes |
| 4979 |
will send decoded changes to plugins only after the specified replication |
| 4980 |
slots confirm receiving WAL. This guarantees that logical replication |
| 4981 |
failover slots do not consume changes until those changes are received |
| 4982 |
and flushed to corresponding physical standbys. If a |
| 4983 |
logical replication connection is meant to switch to a physical standby |
| 4984 |
after the standby is promoted, the physical replication slot for the |
| 4985 |
standby should be listed here. Note that logical replication will not |
| 4986 |
proceed if the slots specified in the |
| 4987 |
<varname>synchronized_standby_slots</varname> do not exist or are invalidated. |
| 4988 |
Additionally, the replication management functions |
| 4989 |
<link linkend="pg-replication-slot-advance"> |
| 4990 |
<function>pg_replication_slot_advance</function></link>, |
| 4991 |
<link linkend="pg-logical-slot-get-changes"> |
| 4992 |
<function>pg_logical_slot_get_changes</function></link>, and |
| 4993 |
<link linkend="pg-logical-slot-peek-changes"> |
| 4994 |
<function>pg_logical_slot_peek_changes</function></link>, |
| 4995 |
when used with logical failover slots, will block until all |
| 4996 |
physical slots specified in <varname>synchronized_standby_slots</varname> have |
| 4997 |
confirmed WAL receipt. |
| 4998 |
</para> |
| 4999 |
<para> |
| 5000 |
The standbys corresponding to the physical replication slots in |
| 5001 |
<varname>synchronized_standby_slots</varname> must configure |
| 5002 |
<literal>sync_replication_slots = true</literal> so they can receive |
| 5003 |
logical failover slot changes from the primary. |
| 5004 |
</para> |
| 5005 |
</listitem> |
| 5006 |
</varlistentry> |
| 5007 |
|
| 5008 |
</variablelist> |
| 5009 |
</sect2> |
| 5010 |
|
| 5011 |
<sect2 id="runtime-config-replication-standby"> |
| 5012 |
<title>Standby Servers</title> |
| 5013 |
|
| 5014 |
<para> |
| 5015 |
These settings control the behavior of a |
| 5016 |
<link linkend="standby-server-operation">standby server</link> |
| 5017 |
that is |
| 5018 |
to receive replication data. Their values on the primary server |
| 5019 |
are irrelevant. |
| 5020 |
</para> |
| 5021 |
|
| 5022 |
<variablelist> |
| 5023 |
|
| 5024 |
<varlistentry id="guc-primary-conninfo" xreflabel="primary_conninfo"> |
| 5025 |
<term><varname>primary_conninfo</varname> (<type>string</type>) |
| 5026 |
<indexterm> |
| 5027 |
<primary><varname>primary_conninfo</varname> configuration parameter</primary> |
| 5028 |
</indexterm> |
| 5029 |
</term> |
| 5030 |
<listitem> |
| 5031 |
<para> |
| 5032 |
Specifies a connection string to be used for the standby server |
| 5033 |
to connect with a sending server. This string is in the format |
| 5034 |
described in <xref linkend="libpq-connstring"/>. If any option is |
| 5035 |
unspecified in this string, then the corresponding environment |
| 5036 |
variable (see <xref linkend="libpq-envars"/>) is checked. If the |
| 5037 |
environment variable is not set either, then |
| 5038 |
defaults are used. |
| 5039 |
</para> |
| 5040 |
<para> |
| 5041 |
The connection string should specify the host name (or address) |
| 5042 |
of the sending server, as well as the port number if it is not |
| 5043 |
the same as the standby server's default. |
| 5044 |
Also specify a user name corresponding to a suitably-privileged role |
| 5045 |
on the sending server (see |
| 5046 |
<xref linkend="streaming-replication-authentication"/>). |
| 5047 |
A password needs to be provided too, if the sender demands password |
| 5048 |
authentication. It can be provided in the |
| 5049 |
<varname>primary_conninfo</varname> string, or in a separate |
| 5050 |
<filename>~/.pgpass</filename> file on the standby server (use |
| 5051 |
<literal>replication</literal> as the database name). |
| 5052 |
</para> |
| 5053 |
<para> |
| 5054 |
For replication slot synchronization (see |
| 5055 |
<xref linkend="logicaldecoding-replication-slots-synchronization"/>), |
| 5056 |
it is also necessary to specify a valid <literal>dbname</literal> |
| 5057 |
in the <varname>primary_conninfo</varname> string. This will only be |
| 5058 |
used for slot synchronization. It is ignored for streaming. |
| 5059 |
</para> |
| 5060 |
<para> |
| 5061 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 5062 |
file or on the server command line. |
| 5063 |
If this parameter is changed while the WAL receiver process is |
| 5064 |
running, that process is signaled to shut down and expected to |
| 5065 |
restart with the new setting (except if <varname>primary_conninfo</varname> |
| 5066 |
is an empty string). |
| 5067 |
This setting has no effect if the server is not in standby mode. |
| 5068 |
</para> |
| 5069 |
</listitem> |
| 5070 |
</varlistentry> |
| 5071 |
<varlistentry id="guc-primary-slot-name" xreflabel="primary_slot_name"> |
| 5072 |
<term><varname>primary_slot_name</varname> (<type>string</type>) |
| 5073 |
<indexterm> |
| 5074 |
<primary><varname>primary_slot_name</varname> configuration parameter</primary> |
| 5075 |
</indexterm> |
| 5076 |
</term> |
| 5077 |
<listitem> |
| 5078 |
<para> |
| 5079 |
Optionally specifies an existing replication slot to be used when |
| 5080 |
connecting to the sending server via streaming replication to control |
| 5081 |
resource removal on the upstream node |
| 5082 |
(see <xref linkend="streaming-replication-slots"/>). |
| 5083 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 5084 |
file or on the server command line. |
| 5085 |
If this parameter is changed while the WAL receiver process is running, |
| 5086 |
that process is signaled to shut down and expected to restart with the |
| 5087 |
new setting. |
| 5088 |
This setting has no effect if <varname>primary_conninfo</varname> is not |
| 5089 |
set or the server is not in standby mode. |
| 5090 |
</para> |
| 5091 |
</listitem> |
| 5092 |
</varlistentry> |
| 5093 |
|
| 5094 |
<varlistentry id="guc-hot-standby" xreflabel="hot_standby"> |
| 5095 |
<term><varname>hot_standby</varname> (<type>boolean</type>) |
| 5096 |
<indexterm> |
| 5097 |
<primary><varname>hot_standby</varname> configuration parameter</primary> |
| 5098 |
</indexterm> |
| 5099 |
</term> |
| 5100 |
<listitem> |
| 5101 |
<para> |
| 5102 |
Specifies whether or not you can connect and run queries during |
| 5103 |
recovery, as described in <xref linkend="hot-standby"/>. |
| 5104 |
The default value is <literal>on</literal>. |
| 5105 |
This parameter can only be set at server start. It only has effect |
| 5106 |
during archive recovery or in standby mode. |
| 5107 |
</para> |
| 5108 |
</listitem> |
| 5109 |
</varlistentry> |
| 5110 |
|
| 5111 |
<varlistentry id="guc-max-standby-archive-delay" xreflabel="max_standby_archive_delay"> |
| 5112 |
<term><varname>max_standby_archive_delay</varname> (<type>integer</type>) |
| 5113 |
<indexterm> |
| 5114 |
<primary><varname>max_standby_archive_delay</varname> configuration parameter</primary> |
| 5115 |
</indexterm> |
| 5116 |
</term> |
| 5117 |
<listitem> |
| 5118 |
<para> |
| 5119 |
When hot standby is active, this parameter determines how long the |
| 5120 |
standby server should wait before canceling standby queries that |
| 5121 |
conflict with about-to-be-applied WAL entries, as described in |
| 5122 |
<xref linkend="hot-standby-conflict"/>. |
| 5123 |
<varname>max_standby_archive_delay</varname> applies when WAL data is |
| 5124 |
being read from WAL archive (and is therefore not current). |
| 5125 |
If this value is specified without units, it is taken as milliseconds. |
| 5126 |
The default is 30 seconds. |
| 5127 |
A value of -1 allows the standby to wait forever for conflicting |
| 5128 |
queries to complete. |
| 5129 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 5130 |
file or on the server command line. |
| 5131 |
</para> |
| 5132 |
<para> |
| 5133 |
Note that <varname>max_standby_archive_delay</varname> is not the same as the |
| 5134 |
maximum length of time a query can run before cancellation; rather it |
| 5135 |
is the maximum total time allowed to apply any one WAL segment's data. |
| 5136 |
Thus, if one query has resulted in significant delay earlier in the |
| 5137 |
WAL segment, subsequent conflicting queries will have much less grace |
| 5138 |
time. |
| 5139 |
</para> |
| 5140 |
</listitem> |
| 5141 |
</varlistentry> |
| 5142 |
|
| 5143 |
<varlistentry id="guc-max-standby-streaming-delay" xreflabel="max_standby_streaming_delay"> |
| 5144 |
<term><varname>max_standby_streaming_delay</varname> (<type>integer</type>) |
| 5145 |
<indexterm> |
| 5146 |
<primary><varname>max_standby_streaming_delay</varname> configuration parameter</primary> |
| 5147 |
</indexterm> |
| 5148 |
</term> |
| 5149 |
<listitem> |
| 5150 |
<para> |
| 5151 |
When hot standby is active, this parameter determines how long the |
| 5152 |
standby server should wait before canceling standby queries that |
| 5153 |
conflict with about-to-be-applied WAL entries, as described in |
| 5154 |
<xref linkend="hot-standby-conflict"/>. |
| 5155 |
<varname>max_standby_streaming_delay</varname> applies when WAL data is |
| 5156 |
being received via streaming replication. |
| 5157 |
If this value is specified without units, it is taken as milliseconds. |
| 5158 |
The default is 30 seconds. |
| 5159 |
A value of -1 allows the standby to wait forever for conflicting |
| 5160 |
queries to complete. |
| 5161 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 5162 |
file or on the server command line. |
| 5163 |
</para> |
| 5164 |
<para> |
| 5165 |
Note that <varname>max_standby_streaming_delay</varname> is not the same as |
| 5166 |
the maximum length of time a query can run before cancellation; rather |
| 5167 |
it is the maximum total time allowed to apply WAL data once it has |
| 5168 |
been received from the primary server. Thus, if one query has |
| 5169 |
resulted in significant delay, subsequent conflicting queries will |
| 5170 |
have much less grace time until the standby server has caught up |
| 5171 |
again. |
| 5172 |
</para> |
| 5173 |
</listitem> |
| 5174 |
</varlistentry> |
| 5175 |
|
| 5176 |
<varlistentry id="guc-wal-receiver-create-temp-slot" xreflabel="wal_receiver_create_temp_slot"> |
| 5177 |
<term><varname>wal_receiver_create_temp_slot</varname> (<type>boolean</type>) |
| 5178 |
<indexterm> |
| 5179 |
<primary><varname>wal_receiver_create_temp_slot</varname> configuration parameter</primary> |
| 5180 |
</indexterm> |
| 5181 |
</term> |
| 5182 |
<listitem> |
| 5183 |
<para> |
| 5184 |
Specifies whether the WAL receiver process should create a temporary replication |
| 5185 |
slot on the remote instance when no permanent replication slot to use |
| 5186 |
has been configured (using <xref linkend="guc-primary-slot-name"/>). |
| 5187 |
The default is off. This parameter can only be set in the |
| 5188 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 5189 |
If this parameter is changed while the WAL receiver process is running, |
| 5190 |
that process is signaled to shut down and expected to restart with |
| 5191 |
the new setting. |
| 5192 |
</para> |
| 5193 |
</listitem> |
| 5194 |
</varlistentry> |
| 5195 |
|
| 5196 |
<varlistentry id="guc-wal-receiver-status-interval" xreflabel="wal_receiver_status_interval"> |
| 5197 |
<term><varname>wal_receiver_status_interval</varname> (<type>integer</type>) |
| 5198 |
<indexterm> |
| 5199 |
<primary><varname>wal_receiver_status_interval</varname> configuration parameter</primary> |
| 5200 |
</indexterm> |
| 5201 |
</term> |
| 5202 |
<listitem> |
| 5203 |
<para> |
| 5204 |
Specifies the minimum frequency for the WAL receiver |
| 5205 |
process on the standby to send information about replication progress |
| 5206 |
to the primary or upstream standby, where it can be seen using the |
| 5207 |
<link linkend="monitoring-pg-stat-replication-view"> |
| 5208 |
<structname>pg_stat_replication</structname></link> |
| 5209 |
view. The standby will report |
| 5210 |
the last write-ahead log location it has written, the last position it |
| 5211 |
has flushed to disk, and the last position it has applied. |
| 5212 |
This parameter's value is the maximum amount of time between reports. |
| 5213 |
Updates are sent each time the write or flush positions change, or as |
| 5214 |
often as specified by this parameter if set to a non-zero value. |
| 5215 |
There are additional cases where updates are sent while ignoring this |
| 5216 |
parameter; for example, when processing of the existing WAL completes |
| 5217 |
or when <varname>synchronous_commit</varname> is set to |
| 5218 |
<literal>remote_apply</literal>. |
| 5219 |
Thus, the apply position may lag slightly behind the true position. |
| 5220 |
If this value is specified without units, it is taken as seconds. |
| 5221 |
The default value is 10 seconds. This parameter can only be set in |
| 5222 |
the <filename>postgresql.conf</filename> file or on the server |
| 5223 |
command line. |
| 5224 |
</para> |
| 5225 |
</listitem> |
| 5226 |
</varlistentry> |
| 5227 |
|
| 5228 |
<varlistentry id="guc-hot-standby-feedback" xreflabel="hot_standby_feedback"> |
| 5229 |
<term><varname>hot_standby_feedback</varname> (<type>boolean</type>) |
| 5230 |
<indexterm> |
| 5231 |
<primary><varname>hot_standby_feedback</varname> configuration parameter</primary> |
| 5232 |
</indexterm> |
| 5233 |
</term> |
| 5234 |
<listitem> |
| 5235 |
<para> |
| 5236 |
Specifies whether or not a hot standby will send feedback to the primary |
| 5237 |
or upstream standby |
| 5238 |
about queries currently executing on the standby. This parameter can |
| 5239 |
be used to eliminate query cancels caused by cleanup records, but |
| 5240 |
can cause database bloat on the primary for some workloads. |
| 5241 |
Feedback messages will not be sent more frequently than once per |
| 5242 |
<varname>wal_receiver_status_interval</varname>. The default value is |
| 5243 |
<literal>off</literal>. This parameter can only be set in the |
| 5244 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 5245 |
</para> |
| 5246 |
<para> |
| 5247 |
If cascaded replication is in use the feedback is passed upstream |
| 5248 |
until it eventually reaches the primary. Standbys make no other use |
| 5249 |
of feedback they receive other than to pass upstream. |
| 5250 |
</para> |
| 5251 |
<para> |
| 5252 |
Note that if the clock on standby is moved ahead or backward, the |
| 5253 |
feedback message might not be sent at the required interval. In |
| 5254 |
extreme cases, this can lead to a prolonged risk of not removing dead |
| 5255 |
rows on the primary for extended periods, as the feedback mechanism is |
| 5256 |
based on timestamps. |
| 5257 |
</para> |
| 5258 |
</listitem> |
| 5259 |
</varlistentry> |
| 5260 |
|
| 5261 |
<varlistentry id="guc-wal-receiver-timeout" xreflabel="wal_receiver_timeout"> |
| 5262 |
<term><varname>wal_receiver_timeout</varname> (<type>integer</type>) |
| 5263 |
<indexterm> |
| 5264 |
<primary><varname>wal_receiver_timeout</varname> configuration parameter</primary> |
| 5265 |
</indexterm> |
| 5266 |
</term> |
| 5267 |
<listitem> |
| 5268 |
<para> |
| 5269 |
Terminate replication connections that are inactive for longer |
| 5270 |
than this amount of time. This is useful for |
| 5271 |
the receiving standby server to detect a primary node crash or network |
| 5272 |
outage. |
| 5273 |
If this value is specified without units, it is taken as milliseconds. |
| 5274 |
The default value is 60 seconds. |
| 5275 |
A value of zero disables the timeout mechanism. |
| 5276 |
This parameter can only be set in |
| 5277 |
the <filename>postgresql.conf</filename> file or on the server |
| 5278 |
command line. |
| 5279 |
</para> |
| 5280 |
</listitem> |
| 5281 |
</varlistentry> |
| 5282 |
|
| 5283 |
<varlistentry id="guc-wal-retrieve-retry-interval" xreflabel="wal_retrieve_retry_interval"> |
| 5284 |
<term><varname>wal_retrieve_retry_interval</varname> (<type>integer</type>) |
| 5285 |
<indexterm> |
| 5286 |
<primary><varname>wal_retrieve_retry_interval</varname> configuration parameter</primary> |
| 5287 |
</indexterm> |
| 5288 |
</term> |
| 5289 |
<listitem> |
| 5290 |
<para> |
| 5291 |
Specifies how long the standby server should wait when WAL data is not |
| 5292 |
available from any sources (streaming replication, |
| 5293 |
local <filename>pg_wal</filename> or WAL archive) before trying |
| 5294 |
again to retrieve WAL data. |
| 5295 |
If this value is specified without units, it is taken as milliseconds. |
| 5296 |
The default value is 5 seconds. |
| 5297 |
This parameter can only be set in |
| 5298 |
the <filename>postgresql.conf</filename> file or on the server |
| 5299 |
command line. |
| 5300 |
</para> |
| 5301 |
<para> |
| 5302 |
This parameter is useful in configurations where a node in recovery |
| 5303 |
needs to control the amount of time to wait for new WAL data to be |
| 5304 |
available. For example, in archive recovery, it is possible to |
| 5305 |
make the recovery more responsive in the detection of a new WAL |
| 5306 |
file by reducing the value of this parameter. On a system with |
| 5307 |
low WAL activity, increasing it reduces the amount of requests necessary |
| 5308 |
to access WAL archives, something useful for example in cloud |
| 5309 |
environments where the number of times an infrastructure is accessed |
| 5310 |
is taken into account. |
| 5311 |
</para> |
| 5312 |
<para> |
| 5313 |
In logical replication, this parameter also limits how often a failing |
| 5314 |
replication apply worker or table synchronization worker will be |
| 5315 |
respawned. |
| 5316 |
</para> |
| 5317 |
</listitem> |
| 5318 |
</varlistentry> |
| 5319 |
|
| 5320 |
<varlistentry id="guc-recovery-min-apply-delay" xreflabel="recovery_min_apply_delay"> |
| 5321 |
<term><varname>recovery_min_apply_delay</varname> (<type>integer</type>) |
| 5322 |
<indexterm> |
| 5323 |
<primary><varname>recovery_min_apply_delay</varname> configuration parameter</primary> |
| 5324 |
</indexterm> |
| 5325 |
</term> |
| 5326 |
<listitem> |
| 5327 |
<para> |
| 5328 |
By default, a standby server restores WAL records from the |
| 5329 |
sending server as soon as possible. It may be useful to have a time-delayed |
| 5330 |
copy of the data, offering opportunities to correct data loss errors. |
| 5331 |
This parameter allows you to delay recovery by a specified amount |
| 5332 |
of time. For example, if |
| 5333 |
you set this parameter to <literal>5min</literal>, the standby will |
| 5334 |
replay each transaction commit only when the system time on the standby |
| 5335 |
is at least five minutes past the commit time reported by the primary. |
| 5336 |
If this value is specified without units, it is taken as milliseconds. |
| 5337 |
The default is zero, adding no delay. |
| 5338 |
</para> |
| 5339 |
<para> |
| 5340 |
It is possible that the replication delay between servers exceeds the |
| 5341 |
value of this parameter, in which case no delay is added. |
| 5342 |
Note that the delay is calculated between the WAL time stamp as written |
| 5343 |
on primary and the current time on the standby. Delays in transfer |
| 5344 |
because of network lag or cascading replication configurations |
| 5345 |
may reduce the actual wait time significantly. If the system |
| 5346 |
clocks on primary and standby are not synchronized, this may lead to |
| 5347 |
recovery applying records earlier than expected; but that is not a |
| 5348 |
major issue because useful settings of this parameter are much larger |
| 5349 |
than typical time deviations between servers. |
| 5350 |
</para> |
| 5351 |
<para> |
| 5352 |
The delay occurs only on WAL records for transaction commits. |
| 5353 |
Other records are replayed as quickly as possible, which |
| 5354 |
is not a problem because MVCC visibility rules ensure their effects |
| 5355 |
are not visible until the corresponding commit record is applied. |
| 5356 |
</para> |
| 5357 |
<para> |
| 5358 |
The delay occurs once the database in recovery has reached a consistent |
| 5359 |
state, until the standby is promoted or triggered. After that the standby |
| 5360 |
will end recovery without further waiting. |
| 5361 |
</para> |
| 5362 |
<para> |
| 5363 |
WAL records must be kept on the standby until they are ready to be |
| 5364 |
applied. Therefore, longer delays will result in a greater accumulation |
| 5365 |
of WAL files, increasing disk space requirements for the standby's |
| 5366 |
<filename>pg_wal</filename> directory. |
| 5367 |
</para> |
| 5368 |
<para> |
| 5369 |
This parameter is intended for use with streaming replication deployments; |
| 5370 |
however, if the parameter is specified it will be honored in all cases |
| 5371 |
except crash recovery. |
| 5372 |
|
| 5373 |
<varname>hot_standby_feedback</varname> will be delayed by use of this feature |
| 5374 |
which could lead to bloat on the primary; use both together with care. |
| 5375 |
|
| 5376 |
<warning> |
| 5377 |
<para> |
| 5378 |
Synchronous replication is affected by this setting when <varname>synchronous_commit</varname> |
| 5379 |
is set to <literal>remote_apply</literal>; every <literal>COMMIT</literal> |
| 5380 |
will need to wait to be applied. |
| 5381 |
</para> |
| 5382 |
</warning> |
| 5383 |
</para> |
| 5384 |
<para> |
| 5385 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 5386 |
file or on the server command line. |
| 5387 |
</para> |
| 5388 |
</listitem> |
| 5389 |
</varlistentry> |
| 5390 |
|
| 5391 |
<varlistentry id="guc-sync-replication-slots" xreflabel="sync_replication_slots"> |
| 5392 |
<term><varname>sync_replication_slots</varname> (<type>boolean</type>) |
| 5393 |
<indexterm> |
| 5394 |
<primary><varname>sync_replication_slots</varname> configuration parameter</primary> |
| 5395 |
</indexterm> |
| 5396 |
</term> |
| 5397 |
<listitem> |
| 5398 |
<para> |
| 5399 |
It enables a physical standby to synchronize logical failover slots |
| 5400 |
from the primary server so that logical subscribers can resume |
| 5401 |
replication from the new primary server after failover. |
| 5402 |
</para> |
| 5403 |
<para> |
| 5404 |
It is disabled by default. This parameter can only be set in the |
| 5405 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 5406 |
</para> |
| 5407 |
</listitem> |
| 5408 |
</varlistentry> |
| 5409 |
</variablelist> |
| 5410 |
</sect2> |
| 5411 |
|
| 5412 |
<sect2 id="runtime-config-replication-subscriber"> |
| 5413 |
<title>Subscribers</title> |
| 5414 |
|
| 5415 |
<para> |
| 5416 |
These settings control the behavior of a logical replication subscriber. |
| 5417 |
Their values on the publisher are irrelevant. |
| 5418 |
See <xref linkend="logical-replication-config"/> for more details. |
| 5419 |
</para> |
| 5420 |
|
| 5421 |
<variablelist> |
| 5422 |
|
| 5423 |
<varlistentry id="guc-max-active-replication-origins" xreflabel="max_active_replication_origins"> |
| 5424 |
<term><varname>max_active_replication_origins</varname> (<type>integer</type>) |
| 5425 |
<indexterm> |
| 5426 |
<primary><varname>max_active_replication_origins</varname> configuration parameter</primary> |
| 5427 |
</indexterm> |
| 5428 |
</term> |
| 5429 |
<listitem> |
| 5430 |
<para> |
| 5431 |
Specifies how many replication origins (see |
| 5432 |
<xref linkend="replication-origins"/>) can be tracked simultaneously, |
| 5433 |
effectively limiting how many logical replication subscriptions can |
| 5434 |
be created on the server. Setting it to a lower value than the current |
| 5435 |
number of tracked replication origins (reflected in |
| 5436 |
<link linkend="view-pg-replication-origin-status">pg_replication_origin_status</link>) |
| 5437 |
will prevent the server from starting. It defaults to 10. This parameter |
| 5438 |
can only be set at server start. |
| 5439 |
|
| 5440 |
<literal>max_active_replication_origins</literal> must be set to at least the |
| 5441 |
number of subscriptions that will be added to the subscriber, plus some |
| 5442 |
reserve for table synchronization. |
| 5443 |
</para> |
| 5444 |
</listitem> |
| 5445 |
</varlistentry> |
| 5446 |
|
| 5447 |
<varlistentry id="guc-max-logical-replication-workers" xreflabel="max_logical_replication_workers"> |
| 5448 |
<term><varname>max_logical_replication_workers</varname> (<type>integer</type>) |
| 5449 |
<indexterm> |
| 5450 |
<primary><varname>max_logical_replication_workers</varname> configuration parameter</primary> |
| 5451 |
</indexterm> |
| 5452 |
</term> |
| 5453 |
<listitem> |
| 5454 |
<para> |
| 5455 |
Specifies maximum number of logical replication workers. This includes |
| 5456 |
leader apply workers, parallel apply workers, and table synchronization |
| 5457 |
workers. |
| 5458 |
</para> |
| 5459 |
<para> |
| 5460 |
Logical replication workers are taken from the pool defined by |
| 5461 |
<varname>max_worker_processes</varname>. |
| 5462 |
</para> |
| 5463 |
<para> |
| 5464 |
The default value is 4. This parameter can only be set at server |
| 5465 |
start. |
| 5466 |
</para> |
| 5467 |
</listitem> |
| 5468 |
</varlistentry> |
| 5469 |
|
| 5470 |
<varlistentry id="guc-max-sync-workers-per-subscription" xreflabel="max_sync_workers_per_subscription"> |
| 5471 |
<term><varname>max_sync_workers_per_subscription</varname> (<type>integer</type>) |
| 5472 |
<indexterm> |
| 5473 |
<primary><varname>max_sync_workers_per_subscription</varname> configuration parameter</primary> |
| 5474 |
</indexterm> |
| 5475 |
</term> |
| 5476 |
<listitem> |
| 5477 |
<para> |
| 5478 |
Maximum number of synchronization workers per subscription. This |
| 5479 |
parameter controls the amount of parallelism of the initial data copy |
| 5480 |
during the subscription initialization or when new tables are added. |
| 5481 |
</para> |
| 5482 |
<para> |
| 5483 |
Currently, there can be only one synchronization worker per table. |
| 5484 |
</para> |
| 5485 |
<para> |
| 5486 |
The synchronization workers are taken from the pool defined by |
| 5487 |
<varname>max_logical_replication_workers</varname>. |
| 5488 |
</para> |
| 5489 |
<para> |
| 5490 |
The default value is 2. This parameter can only be set in the |
| 5491 |
<filename>postgresql.conf</filename> file or on the server command |
| 5492 |
line. |
| 5493 |
</para> |
| 5494 |
</listitem> |
| 5495 |
</varlistentry> |
| 5496 |
|
| 5497 |
<varlistentry id="guc-max-parallel-apply-workers-per-subscription" xreflabel="max_parallel_apply_workers_per_subscription"> |
| 5498 |
<term><varname>max_parallel_apply_workers_per_subscription</varname> (<type>integer</type>) |
| 5499 |
<indexterm> |
| 5500 |
<primary><varname>max_parallel_apply_workers_per_subscription</varname> configuration parameter</primary> |
| 5501 |
</indexterm> |
| 5502 |
</term> |
| 5503 |
<listitem> |
| 5504 |
<para> |
| 5505 |
Maximum number of parallel apply workers per subscription. This |
| 5506 |
parameter controls the amount of parallelism for streaming of |
| 5507 |
in-progress transactions with subscription parameter |
| 5508 |
<literal>streaming = parallel</literal>. |
| 5509 |
</para> |
| 5510 |
<para> |
| 5511 |
The parallel apply workers are taken from the pool defined by |
| 5512 |
<varname>max_logical_replication_workers</varname>. |
| 5513 |
</para> |
| 5514 |
<para> |
| 5515 |
The default value is 2. This parameter can only be set in the |
| 5516 |
<filename>postgresql.conf</filename> file or on the server command |
| 5517 |
line. |
| 5518 |
</para> |
| 5519 |
</listitem> |
| 5520 |
</varlistentry> |
| 5521 |
|
| 5522 |
</variablelist> |
| 5523 |
</sect2> |
| 5524 |
|
| 5525 |
</sect1> |
| 5526 |
|
| 5527 |
<sect1 id="runtime-config-query"> |
| 5528 |
<title>Query Planning</title> |
| 5529 |
|
| 5530 |
<sect2 id="runtime-config-query-enable"> |
| 5531 |
<title>Planner Method Configuration</title> |
| 5532 |
|
| 5533 |
<para> |
| 5534 |
These configuration parameters provide a crude method of |
| 5535 |
influencing the query plans chosen by the query optimizer. If |
| 5536 |
the default plan chosen by the optimizer for a particular query |
| 5537 |
is not optimal, a <emphasis>temporary</emphasis> solution is to use one |
| 5538 |
of these configuration parameters to force the optimizer to |
| 5539 |
choose a different plan. |
| 5540 |
Better ways to improve the quality of the |
| 5541 |
plans chosen by the optimizer include adjusting the planner cost |
| 5542 |
constants (see <xref linkend="runtime-config-query-constants"/>), |
| 5543 |
running <link linkend="sql-analyze"><command>ANALYZE</command></link> manually, increasing |
| 5544 |
the value of the <xref |
| 5545 |
linkend="guc-default-statistics-target"/> configuration parameter, |
| 5546 |
and increasing the amount of statistics collected for |
| 5547 |
specific columns using <command>ALTER TABLE SET |
| 5548 |
STATISTICS</command>. |
| 5549 |
</para> |
| 5550 |
|
| 5551 |
<variablelist> |
| 5552 |
<varlistentry id="guc-enable-async-append" xreflabel="enable_async_append"> |
| 5553 |
<term><varname>enable_async_append</varname> (<type>boolean</type>) |
| 5554 |
<indexterm> |
| 5555 |
<primary><varname>enable_async_append</varname> configuration parameter</primary> |
| 5556 |
</indexterm> |
| 5557 |
</term> |
| 5558 |
<listitem> |
| 5559 |
<para> |
| 5560 |
Enables or disables the query planner's use of async-aware |
| 5561 |
append plan types. The default is <literal>on</literal>. |
| 5562 |
</para> |
| 5563 |
</listitem> |
| 5564 |
</varlistentry> |
| 5565 |
|
| 5566 |
<varlistentry id="guc-enable-bitmapscan" xreflabel="enable_bitmapscan"> |
| 5567 |
<term><varname>enable_bitmapscan</varname> (<type>boolean</type>) |
| 5568 |
<indexterm> |
| 5569 |
<primary>bitmap scan</primary> |
| 5570 |
</indexterm> |
| 5571 |
<indexterm> |
| 5572 |
<primary><varname>enable_bitmapscan</varname> configuration parameter</primary> |
| 5573 |
</indexterm> |
| 5574 |
</term> |
| 5575 |
<listitem> |
| 5576 |
<para> |
| 5577 |
Enables or disables the query planner's use of bitmap-scan plan |
| 5578 |
types. The default is <literal>on</literal>. |
| 5579 |
</para> |
| 5580 |
</listitem> |
| 5581 |
</varlistentry> |
| 5582 |
|
| 5583 |
<varlistentry id="guc-enable-distinct-reordering" xreflabel="enable_distinct_reordering"> |
| 5584 |
<term><varname>enable_distinct_reordering</varname> (<type>boolean</type>) |
| 5585 |
<indexterm> |
| 5586 |
<primary><varname>enable_distinct_reordering</varname> configuration parameter</primary> |
| 5587 |
</indexterm> |
| 5588 |
</term> |
| 5589 |
<listitem> |
| 5590 |
<para> |
| 5591 |
Enables or disables the query planner's ability to reorder DISTINCT |
| 5592 |
keys to match the input path's pathkeys. The default is <literal>on</literal>. |
| 5593 |
</para> |
| 5594 |
</listitem> |
| 5595 |
</varlistentry> |
| 5596 |
|
| 5597 |
<varlistentry id="guc-enable-gathermerge" xreflabel="enable_gathermerge"> |
| 5598 |
<term><varname>enable_gathermerge</varname> (<type>boolean</type>) |
| 5599 |
<indexterm> |
| 5600 |
<primary><varname>enable_gathermerge</varname> configuration parameter</primary> |
| 5601 |
</indexterm> |
| 5602 |
</term> |
| 5603 |
<listitem> |
| 5604 |
<para> |
| 5605 |
Enables or disables the query planner's use of gather |
| 5606 |
merge plan types. The default is <literal>on</literal>. |
| 5607 |
</para> |
| 5608 |
</listitem> |
| 5609 |
</varlistentry> |
| 5610 |
|
| 5611 |
<varlistentry id="guc-enable-groupby-reordering" xreflabel="enable_group_by_reordering"> |
| 5612 |
<term><varname>enable_group_by_reordering</varname> (<type>boolean</type>) |
| 5613 |
<indexterm> |
| 5614 |
<primary><varname>enable_group_by_reordering</varname> configuration parameter</primary> |
| 5615 |
</indexterm> |
| 5616 |
</term> |
| 5617 |
<listitem> |
| 5618 |
<para> |
| 5619 |
Controls if the query planner will produce a plan which will provide |
| 5620 |
<literal>GROUP BY</literal> keys sorted in the order of keys of |
| 5621 |
a child node of the plan, such as an index scan. When disabled, the |
| 5622 |
query planner will produce a plan with <literal>GROUP BY</literal> |
| 5623 |
keys only sorted to match the <literal>ORDER BY</literal> clause, |
| 5624 |
if any. When enabled, the planner will try to produce a more |
| 5625 |
efficient plan. The default value is <literal>on</literal>. |
| 5626 |
</para> |
| 5627 |
</listitem> |
| 5628 |
</varlistentry> |
| 5629 |
|
| 5630 |
<varlistentry id="guc-enable-hashagg" xreflabel="enable_hashagg"> |
| 5631 |
<term><varname>enable_hashagg</varname> (<type>boolean</type>) |
| 5632 |
<indexterm> |
| 5633 |
<primary><varname>enable_hashagg</varname> configuration parameter</primary> |
| 5634 |
</indexterm> |
| 5635 |
</term> |
| 5636 |
<listitem> |
| 5637 |
<para> |
| 5638 |
Enables or disables the query planner's use of hashed |
| 5639 |
aggregation plan types. The default is <literal>on</literal>. |
| 5640 |
</para> |
| 5641 |
</listitem> |
| 5642 |
</varlistentry> |
| 5643 |
|
| 5644 |
<varlistentry id="guc-enable-hashjoin" xreflabel="enable_hashjoin"> |
| 5645 |
<term><varname>enable_hashjoin</varname> (<type>boolean</type>) |
| 5646 |
<indexterm> |
| 5647 |
<primary><varname>enable_hashjoin</varname> configuration parameter</primary> |
| 5648 |
</indexterm> |
| 5649 |
</term> |
| 5650 |
<listitem> |
| 5651 |
<para> |
| 5652 |
Enables or disables the query planner's use of hash-join plan |
| 5653 |
types. The default is <literal>on</literal>. |
| 5654 |
</para> |
| 5655 |
</listitem> |
| 5656 |
</varlistentry> |
| 5657 |
|
| 5658 |
<varlistentry id="guc-enable-incremental-sort" xreflabel="enable_incremental_sort"> |
| 5659 |
<term><varname>enable_incremental_sort</varname> (<type>boolean</type>) |
| 5660 |
<indexterm> |
| 5661 |
<primary><varname>enable_incremental_sort</varname> configuration parameter</primary> |
| 5662 |
</indexterm> |
| 5663 |
</term> |
| 5664 |
<listitem> |
| 5665 |
<para> |
| 5666 |
Enables or disables the query planner's use of incremental sort steps. |
| 5667 |
The default is <literal>on</literal>. |
| 5668 |
</para> |
| 5669 |
</listitem> |
| 5670 |
</varlistentry> |
| 5671 |
|
| 5672 |
<varlistentry id="guc-enable-indexscan" xreflabel="enable_indexscan"> |
| 5673 |
<term><varname>enable_indexscan</varname> (<type>boolean</type>) |
| 5674 |
<indexterm> |
| 5675 |
<primary>index scan</primary> |
| 5676 |
</indexterm> |
| 5677 |
<indexterm> |
| 5678 |
<primary><varname>enable_indexscan</varname> configuration parameter</primary> |
| 5679 |
</indexterm> |
| 5680 |
</term> |
| 5681 |
<listitem> |
| 5682 |
<para> |
| 5683 |
Enables or disables the query planner's use of index-scan and |
| 5684 |
index-only-scan plan types. The default is <literal>on</literal>. |
| 5685 |
Also see <xref linkend="guc-enable-indexonlyscan"/>. |
| 5686 |
</para> |
| 5687 |
</listitem> |
| 5688 |
</varlistentry> |
| 5689 |
|
| 5690 |
<varlistentry id="guc-enable-indexonlyscan" xreflabel="enable_indexonlyscan"> |
| 5691 |
<term><varname>enable_indexonlyscan</varname> (<type>boolean</type>) |
| 5692 |
<indexterm> |
| 5693 |
<primary><varname>enable_indexonlyscan</varname> configuration parameter</primary> |
| 5694 |
</indexterm> |
| 5695 |
</term> |
| 5696 |
<listitem> |
| 5697 |
<para> |
| 5698 |
Enables or disables the query planner's use of index-only-scan plan |
| 5699 |
types (see <xref linkend="indexes-index-only-scans"/>). |
| 5700 |
The default is <literal>on</literal>. The |
| 5701 |
<xref linkend="guc-enable-indexscan"/> setting must also be |
| 5702 |
enabled to have the query planner consider index-only-scans. |
| 5703 |
</para> |
| 5704 |
</listitem> |
| 5705 |
</varlistentry> |
| 5706 |
|
| 5707 |
<varlistentry id="guc-enable-material" xreflabel="enable_material"> |
| 5708 |
<term><varname>enable_material</varname> (<type>boolean</type>) |
| 5709 |
<indexterm> |
| 5710 |
<primary><varname>enable_material</varname> configuration parameter</primary> |
| 5711 |
</indexterm> |
| 5712 |
</term> |
| 5713 |
<listitem> |
| 5714 |
<para> |
| 5715 |
Enables or disables the query planner's use of materialization. |
| 5716 |
It is impossible to suppress materialization entirely, |
| 5717 |
but turning this variable off prevents the planner from inserting |
| 5718 |
materialize nodes except in cases where it is required for correctness. |
| 5719 |
The default is <literal>on</literal>. |
| 5720 |
</para> |
| 5721 |
</listitem> |
| 5722 |
</varlistentry> |
| 5723 |
|
| 5724 |
<varlistentry id="guc-enable-memoize" xreflabel="enable_memoize"> |
| 5725 |
<term><varname>enable_memoize</varname> (<type>boolean</type>) |
| 5726 |
<indexterm> |
| 5727 |
<primary><varname>enable_memoize</varname> configuration parameter</primary> |
| 5728 |
</indexterm> |
| 5729 |
</term> |
| 5730 |
<listitem> |
| 5731 |
<para> |
| 5732 |
Enables or disables the query planner's use of memoize plans for |
| 5733 |
caching results from parameterized scans inside nested-loop joins. |
| 5734 |
This plan type allows scans to the underlying plans to be skipped when |
| 5735 |
the results for the current parameters are already in the cache. Less |
| 5736 |
commonly looked up results may be evicted from the cache when more |
| 5737 |
space is required for new entries. The default is |
| 5738 |
<literal>on</literal>. |
| 5739 |
</para> |
| 5740 |
</listitem> |
| 5741 |
</varlistentry> |
| 5742 |
|
| 5743 |
<varlistentry id="guc-enable-mergejoin" xreflabel="enable_mergejoin"> |
| 5744 |
<term><varname>enable_mergejoin</varname> (<type>boolean</type>) |
| 5745 |
<indexterm> |
| 5746 |
<primary><varname>enable_mergejoin</varname> configuration parameter</primary> |
| 5747 |
</indexterm> |
| 5748 |
</term> |
| 5749 |
<listitem> |
| 5750 |
<para> |
| 5751 |
Enables or disables the query planner's use of merge-join plan |
| 5752 |
types. The default is <literal>on</literal>. |
| 5753 |
</para> |
| 5754 |
</listitem> |
| 5755 |
</varlistentry> |
| 5756 |
|
| 5757 |
<varlistentry id="guc-enable-nestloop" xreflabel="enable_nestloop"> |
| 5758 |
<term><varname>enable_nestloop</varname> (<type>boolean</type>) |
| 5759 |
<indexterm> |
| 5760 |
<primary><varname>enable_nestloop</varname> configuration parameter</primary> |
| 5761 |
</indexterm> |
| 5762 |
</term> |
| 5763 |
<listitem> |
| 5764 |
<para> |
| 5765 |
Enables or disables the query planner's use of nested-loop join |
| 5766 |
plans. It is impossible to suppress nested-loop joins entirely, |
| 5767 |
but turning this variable off discourages the planner from using |
| 5768 |
one if there are other methods available. The default is |
| 5769 |
<literal>on</literal>. |
| 5770 |
</para> |
| 5771 |
</listitem> |
| 5772 |
</varlistentry> |
| 5773 |
|
| 5774 |
<varlistentry id="guc-enable-parallel-append" xreflabel="enable_parallel_append"> |
| 5775 |
<term><varname>enable_parallel_append</varname> (<type>boolean</type>) |
| 5776 |
<indexterm> |
| 5777 |
<primary><varname>enable_parallel_append</varname> configuration parameter</primary> |
| 5778 |
</indexterm> |
| 5779 |
</term> |
| 5780 |
<listitem> |
| 5781 |
<para> |
| 5782 |
Enables or disables the query planner's use of parallel-aware |
| 5783 |
append plan types. The default is <literal>on</literal>. |
| 5784 |
</para> |
| 5785 |
</listitem> |
| 5786 |
</varlistentry> |
| 5787 |
|
| 5788 |
<varlistentry id="guc-enable-parallel-hash" xreflabel="enable_parallel_hash"> |
| 5789 |
<term><varname>enable_parallel_hash</varname> (<type>boolean</type>) |
| 5790 |
<indexterm> |
| 5791 |
<primary><varname>enable_parallel_hash</varname> configuration parameter</primary> |
| 5792 |
</indexterm> |
| 5793 |
</term> |
| 5794 |
<listitem> |
| 5795 |
<para> |
| 5796 |
Enables or disables the query planner's use of hash-join plan |
| 5797 |
types with parallel hash. Has no effect if hash-join plans are not |
| 5798 |
also enabled. The default is <literal>on</literal>. |
| 5799 |
</para> |
| 5800 |
</listitem> |
| 5801 |
</varlistentry> |
| 5802 |
|
| 5803 |
<varlistentry id="guc-enable-partition-pruning" xreflabel="enable_partition_pruning"> |
| 5804 |
<term><varname>enable_partition_pruning</varname> (<type>boolean</type>) |
| 5805 |
<indexterm> |
| 5806 |
<primary><varname>enable_partition_pruning</varname> configuration parameter</primary> |
| 5807 |
</indexterm> |
| 5808 |
</term> |
| 5809 |
<listitem> |
| 5810 |
<para> |
| 5811 |
Enables or disables the query planner's ability to eliminate a |
| 5812 |
partitioned table's partitions from query plans. This also controls |
| 5813 |
the planner's ability to generate query plans which allow the query |
| 5814 |
executor to remove (ignore) partitions during query execution. The |
| 5815 |
default is <literal>on</literal>. |
| 5816 |
See <xref linkend="ddl-partition-pruning"/> for details. |
| 5817 |
</para> |
| 5818 |
</listitem> |
| 5819 |
</varlistentry> |
| 5820 |
|
| 5821 |
<varlistentry id="guc-enable-partitionwise-join" xreflabel="enable_partitionwise_join"> |
| 5822 |
<term><varname>enable_partitionwise_join</varname> (<type>boolean</type>) |
| 5823 |
<indexterm> |
| 5824 |
<primary><varname>enable_partitionwise_join</varname> configuration parameter</primary> |
| 5825 |
</indexterm> |
| 5826 |
</term> |
| 5827 |
<listitem> |
| 5828 |
<para> |
| 5829 |
Enables or disables the query planner's use of partitionwise join, |
| 5830 |
which allows a join between partitioned tables to be performed by |
| 5831 |
joining the matching partitions. Partitionwise join currently applies |
| 5832 |
only when the join conditions include all the partition keys, which |
| 5833 |
must be of the same data type and have one-to-one matching sets of |
| 5834 |
child partitions. With this setting enabled, the number of nodes |
| 5835 |
whose memory usage is restricted by <varname>work_mem</varname> |
| 5836 |
appearing in the final plan can increase linearly according to the |
| 5837 |
number of partitions being scanned. This can result in a large |
| 5838 |
increase in overall memory consumption during the execution of the |
| 5839 |
query. Query planning also becomes significantly more expensive in |
| 5840 |
terms of memory and CPU. The default value is <literal>off</literal>. |
| 5841 |
</para> |
| 5842 |
</listitem> |
| 5843 |
</varlistentry> |
| 5844 |
|
| 5845 |
<varlistentry id="guc-enable-partitionwise-aggregate" xreflabel="enable_partitionwise_aggregate"> |
| 5846 |
<term><varname>enable_partitionwise_aggregate</varname> (<type>boolean</type>) |
| 5847 |
<indexterm> |
| 5848 |
<primary><varname>enable_partitionwise_aggregate</varname> configuration parameter</primary> |
| 5849 |
</indexterm> |
| 5850 |
</term> |
| 5851 |
<listitem> |
| 5852 |
<para> |
| 5853 |
Enables or disables the query planner's use of partitionwise grouping |
| 5854 |
or aggregation, which allows grouping or aggregation on partitioned |
| 5855 |
tables to be performed separately for each partition. If the |
| 5856 |
<literal>GROUP BY</literal> clause does not include the partition |
| 5857 |
keys, only partial aggregation can be performed on a per-partition |
| 5858 |
basis, and finalization must be performed later. With this setting |
| 5859 |
enabled, the number of nodes whose memory usage is restricted by |
| 5860 |
<varname>work_mem</varname> appearing in the final plan can increase |
| 5861 |
linearly according to the number of partitions being scanned. This |
| 5862 |
can result in a large increase in overall memory consumption during |
| 5863 |
the execution of the query. Query planning also becomes significantly |
| 5864 |
more expensive in terms of memory and CPU. The default value is |
| 5865 |
<literal>off</literal>. |
| 5866 |
</para> |
| 5867 |
</listitem> |
| 5868 |
</varlistentry> |
| 5869 |
|
| 5870 |
<varlistentry id="guc-enable-presorted-aggregate" xreflabel="enable_presorted_aggregate"> |
| 5871 |
<term><varname>enable_presorted_aggregate</varname> (<type>boolean</type>) |
| 5872 |
<indexterm> |
| 5873 |
<primary><varname>enable_presorted_aggregate</varname> configuration parameter</primary> |
| 5874 |
</indexterm> |
| 5875 |
</term> |
| 5876 |
<listitem> |
| 5877 |
<para> |
| 5878 |
Controls if the query planner will produce a plan which will provide |
| 5879 |
rows which are presorted in the order required for the query's |
| 5880 |
<literal>ORDER BY</literal> / <literal>DISTINCT</literal> aggregate |
| 5881 |
functions. When disabled, the query planner will produce a plan which |
| 5882 |
will always require the executor to perform a sort before performing |
| 5883 |
aggregation of each aggregate function containing an |
| 5884 |
<literal>ORDER BY</literal> or <literal>DISTINCT</literal> clause. |
| 5885 |
When enabled, the planner will try to produce a more efficient plan |
| 5886 |
which provides input to the aggregate functions which is presorted in |
| 5887 |
the order they require for aggregation. The default value is |
| 5888 |
<literal>on</literal>. |
| 5889 |
</para> |
| 5890 |
</listitem> |
| 5891 |
</varlistentry> |
| 5892 |
|
| 5893 |
<varlistentry id="guc-enable-self-join-elimination" xreflabel="enable_self_join_elimination"> |
| 5894 |
<term><varname>enable_self_join_elimination</varname> (<type>boolean</type>) |
| 5895 |
<indexterm> |
| 5896 |
<primary><varname>enable_self_join_elimination</varname> configuration parameter</primary> |
| 5897 |
</indexterm> |
| 5898 |
</term> |
| 5899 |
<listitem> |
| 5900 |
<para> |
| 5901 |
Enables or disables the query planner's optimization which analyses |
| 5902 |
the query tree and replaces self joins with semantically equivalent |
| 5903 |
single scans. Takes into consideration only plain tables. |
| 5904 |
The default is <literal>on</literal>. |
| 5905 |
</para> |
| 5906 |
</listitem> |
| 5907 |
</varlistentry> |
| 5908 |
|
| 5909 |
<varlistentry id="guc-enable-seqscan" xreflabel="enable_seqscan"> |
| 5910 |
<term><varname>enable_seqscan</varname> (<type>boolean</type>) |
| 5911 |
<indexterm> |
| 5912 |
<primary>sequential scan</primary> |
| 5913 |
</indexterm> |
| 5914 |
<indexterm> |
| 5915 |
<primary><varname>enable_seqscan</varname> configuration parameter</primary> |
| 5916 |
</indexterm> |
| 5917 |
</term> |
| 5918 |
<listitem> |
| 5919 |
<para> |
| 5920 |
Enables or disables the query planner's use of sequential scan |
| 5921 |
plan types. It is impossible to suppress sequential scans |
| 5922 |
entirely, but turning this variable off discourages the planner |
| 5923 |
from using one if there are other methods available. The |
| 5924 |
default is <literal>on</literal>. |
| 5925 |
</para> |
| 5926 |
</listitem> |
| 5927 |
</varlistentry> |
| 5928 |
|
| 5929 |
<varlistentry id="guc-enable-sort" xreflabel="enable_sort"> |
| 5930 |
<term><varname>enable_sort</varname> (<type>boolean</type>) |
| 5931 |
<indexterm> |
| 5932 |
<primary><varname>enable_sort</varname> configuration parameter</primary> |
| 5933 |
</indexterm> |
| 5934 |
</term> |
| 5935 |
<listitem> |
| 5936 |
<para> |
| 5937 |
Enables or disables the query planner's use of explicit sort |
| 5938 |
steps. It is impossible to suppress explicit sorts entirely, |
| 5939 |
but turning this variable off discourages the planner from |
| 5940 |
using one if there are other methods available. The default |
| 5941 |
is <literal>on</literal>. |
| 5942 |
</para> |
| 5943 |
</listitem> |
| 5944 |
</varlistentry> |
| 5945 |
|
| 5946 |
<varlistentry id="guc-enable-tidscan" xreflabel="enable_tidscan"> |
| 5947 |
<term><varname>enable_tidscan</varname> (<type>boolean</type>) |
| 5948 |
<indexterm> |
| 5949 |
<primary><varname>enable_tidscan</varname> configuration parameter</primary> |
| 5950 |
</indexterm> |
| 5951 |
</term> |
| 5952 |
<listitem> |
| 5953 |
<para> |
| 5954 |
Enables or disables the query planner's use of <acronym>TID</acronym> |
| 5955 |
scan plan types. The default is <literal>on</literal>. |
| 5956 |
</para> |
| 5957 |
</listitem> |
| 5958 |
</varlistentry> |
| 5959 |
|
| 5960 |
</variablelist> |
| 5961 |
</sect2> |
| 5962 |
<sect2 id="runtime-config-query-constants"> |
| 5963 |
<title>Planner Cost Constants</title> |
| 5964 |
|
| 5965 |
<para> |
| 5966 |
The <firstterm>cost</firstterm> variables described in this section are measured |
| 5967 |
on an arbitrary scale. Only their relative values matter, hence |
| 5968 |
scaling them all up or down by the same factor will result in no change |
| 5969 |
in the planner's choices. By default, these cost variables are based on |
| 5970 |
the cost of sequential page fetches; that is, |
| 5971 |
<varname>seq_page_cost</varname> is conventionally set to <literal>1.0</literal> |
| 5972 |
and the other cost variables are set with reference to that. But |
| 5973 |
you can use a different scale if you prefer, such as actual execution |
| 5974 |
times in milliseconds on a particular machine. |
| 5975 |
</para> |
| 5976 |
|
| 5977 |
<note> |
| 5978 |
<para> |
| 5979 |
Unfortunately, there is no well-defined method for determining ideal |
| 5980 |
values for the cost variables. They are best treated as averages over |
| 5981 |
the entire mix of queries that a particular installation will receive. This |
| 5982 |
means that changing them on the basis of just a few experiments is very |
| 5983 |
risky. |
| 5984 |
</para> |
| 5985 |
</note> |
| 5986 |
|
| 5987 |
<variablelist> |
| 5988 |
|
| 5989 |
<varlistentry id="guc-seq-page-cost" xreflabel="seq_page_cost"> |
| 5990 |
<term><varname>seq_page_cost</varname> (<type>floating point</type>) |
| 5991 |
<indexterm> |
| 5992 |
<primary><varname>seq_page_cost</varname> configuration parameter</primary> |
| 5993 |
</indexterm> |
| 5994 |
</term> |
| 5995 |
<listitem> |
| 5996 |
<para> |
| 5997 |
Sets the planner's estimate of the cost of a disk page fetch |
| 5998 |
that is part of a series of sequential fetches. The default is 1.0. |
| 5999 |
This value can be overridden for tables and indexes in a particular |
| 6000 |
tablespace by setting the tablespace parameter of the same name |
| 6001 |
(see <xref linkend="sql-altertablespace"/>). |
| 6002 |
</para> |
| 6003 |
</listitem> |
| 6004 |
</varlistentry> |
| 6005 |
|
| 6006 |
<varlistentry id="guc-random-page-cost" xreflabel="random_page_cost"> |
| 6007 |
<term><varname>random_page_cost</varname> (<type>floating point</type>) |
| 6008 |
<indexterm> |
| 6009 |
<primary><varname>random_page_cost</varname> configuration parameter</primary> |
| 6010 |
</indexterm> |
| 6011 |
</term> |
| 6012 |
<listitem> |
| 6013 |
<para> |
| 6014 |
Sets the planner's estimate of the cost of a |
| 6015 |
non-sequentially-fetched disk page. The default is 4.0. |
| 6016 |
This value can be overridden for tables and indexes in a particular |
| 6017 |
tablespace by setting the tablespace parameter of the same name |
| 6018 |
(see <xref linkend="sql-altertablespace"/>). |
| 6019 |
</para> |
| 6020 |
|
| 6021 |
<para> |
| 6022 |
Reducing this value relative to <varname>seq_page_cost</varname> |
| 6023 |
will cause the system to prefer index scans; raising it will |
| 6024 |
make index scans look relatively more expensive. You can raise |
| 6025 |
or lower both values together to change the importance of disk I/O |
| 6026 |
costs relative to CPU costs, which are described by the following |
| 6027 |
parameters. |
| 6028 |
</para> |
| 6029 |
|
| 6030 |
<para> |
| 6031 |
Random access to durable storage is normally much more expensive |
| 6032 |
than four times sequential access. However, a lower default is |
| 6033 |
used (4.0) because the majority of random accesses to storage, |
| 6034 |
such as indexed reads, are assumed to be in cache. Also, the |
| 6035 |
latency of network-attached storage tends to reduce the relative |
| 6036 |
overhead of random access. |
| 6037 |
</para> |
| 6038 |
|
| 6039 |
<para> |
| 6040 |
If you believe caching is less frequent than the default |
| 6041 |
value reflects, and network latency is minimal, you can increase |
| 6042 |
random_page_cost to better reflect the true cost of random storage |
| 6043 |
reads. Storage that has a higher random read cost relative to |
| 6044 |
sequential, like magnetic disks, might also be better modeled with |
| 6045 |
a higher value for random_page_cost. Correspondingly, if your data |
| 6046 |
is likely to be completely in cache, such as when the database |
| 6047 |
is smaller than the total server memory, or network latency is |
| 6048 |
high, decreasing random_page_cost might be appropriate. |
| 6049 |
</para> |
| 6050 |
|
| 6051 |
<tip> |
| 6052 |
<para> |
| 6053 |
Although the system will let you set <varname>random_page_cost</varname> to |
| 6054 |
less than <varname>seq_page_cost</varname>, it is not physically sensible |
| 6055 |
to do so. However, setting them equal makes sense if the database |
| 6056 |
is entirely cached in RAM, since in that case there is no penalty |
| 6057 |
for touching pages out of sequence. Also, in a heavily-cached |
| 6058 |
database you should lower both values relative to the CPU parameters, |
| 6059 |
since the cost of fetching a page already in RAM is much smaller |
| 6060 |
than it would normally be. |
| 6061 |
</para> |
| 6062 |
</tip> |
| 6063 |
</listitem> |
| 6064 |
</varlistentry> |
| 6065 |
|
| 6066 |
<varlistentry id="guc-cpu-tuple-cost" xreflabel="cpu_tuple_cost"> |
| 6067 |
<term><varname>cpu_tuple_cost</varname> (<type>floating point</type>) |
| 6068 |
<indexterm> |
| 6069 |
<primary><varname>cpu_tuple_cost</varname> configuration parameter</primary> |
| 6070 |
</indexterm> |
| 6071 |
</term> |
| 6072 |
<listitem> |
| 6073 |
<para> |
| 6074 |
Sets the planner's estimate of the cost of processing |
| 6075 |
each row during a query. |
| 6076 |
The default is 0.01. |
| 6077 |
</para> |
| 6078 |
</listitem> |
| 6079 |
</varlistentry> |
| 6080 |
|
| 6081 |
<varlistentry id="guc-cpu-index-tuple-cost" xreflabel="cpu_index_tuple_cost"> |
| 6082 |
<term><varname>cpu_index_tuple_cost</varname> (<type>floating point</type>) |
| 6083 |
<indexterm> |
| 6084 |
<primary><varname>cpu_index_tuple_cost</varname> configuration parameter</primary> |
| 6085 |
</indexterm> |
| 6086 |
</term> |
| 6087 |
<listitem> |
| 6088 |
<para> |
| 6089 |
Sets the planner's estimate of the cost of processing |
| 6090 |
each index entry during an index scan. |
| 6091 |
The default is 0.005. |
| 6092 |
</para> |
| 6093 |
</listitem> |
| 6094 |
</varlistentry> |
| 6095 |
|
| 6096 |
<varlistentry id="guc-cpu-operator-cost" xreflabel="cpu_operator_cost"> |
| 6097 |
<term><varname>cpu_operator_cost</varname> (<type>floating point</type>) |
| 6098 |
<indexterm> |
| 6099 |
<primary><varname>cpu_operator_cost</varname> configuration parameter</primary> |
| 6100 |
</indexterm> |
| 6101 |
</term> |
| 6102 |
<listitem> |
| 6103 |
<para> |
| 6104 |
Sets the planner's estimate of the cost of processing each |
| 6105 |
operator or function executed during a query. |
| 6106 |
The default is 0.0025. |
| 6107 |
</para> |
| 6108 |
</listitem> |
| 6109 |
</varlistentry> |
| 6110 |
|
| 6111 |
<varlistentry id="guc-parallel-setup-cost" xreflabel="parallel_setup_cost"> |
| 6112 |
<term><varname>parallel_setup_cost</varname> (<type>floating point</type>) |
| 6113 |
<indexterm> |
| 6114 |
<primary><varname>parallel_setup_cost</varname> configuration parameter</primary> |
| 6115 |
</indexterm> |
| 6116 |
</term> |
| 6117 |
<listitem> |
| 6118 |
<para> |
| 6119 |
Sets the planner's estimate of the cost of launching parallel worker |
| 6120 |
processes. |
| 6121 |
The default is 1000. |
| 6122 |
</para> |
| 6123 |
</listitem> |
| 6124 |
</varlistentry> |
| 6125 |
|
| 6126 |
<varlistentry id="guc-parallel-tuple-cost" xreflabel="parallel_tuple_cost"> |
| 6127 |
<term><varname>parallel_tuple_cost</varname> (<type>floating point</type>) |
| 6128 |
<indexterm> |
| 6129 |
<primary><varname>parallel_tuple_cost</varname> configuration parameter</primary> |
| 6130 |
</indexterm> |
| 6131 |
</term> |
| 6132 |
<listitem> |
| 6133 |
<para> |
| 6134 |
Sets the planner's estimate of the cost of transferring one tuple |
| 6135 |
from a parallel worker process to another process. |
| 6136 |
The default is 0.1. |
| 6137 |
</para> |
| 6138 |
</listitem> |
| 6139 |
</varlistentry> |
| 6140 |
|
| 6141 |
<varlistentry id="guc-min-parallel-table-scan-size" xreflabel="min_parallel_table_scan_size"> |
| 6142 |
<term><varname>min_parallel_table_scan_size</varname> (<type>integer</type>) |
| 6143 |
<indexterm> |
| 6144 |
<primary><varname>min_parallel_table_scan_size</varname> configuration parameter</primary> |
| 6145 |
</indexterm> |
| 6146 |
</term> |
| 6147 |
<listitem> |
| 6148 |
<para> |
| 6149 |
Sets the minimum amount of table data that must be scanned in order |
| 6150 |
for a parallel scan to be considered. For a parallel sequential scan, |
| 6151 |
the amount of table data scanned is always equal to the size of the |
| 6152 |
table, but when indexes are used the amount of table data |
| 6153 |
scanned will normally be less. |
| 6154 |
If this value is specified without units, it is taken as blocks, |
| 6155 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 6156 |
The default is 8 megabytes (<literal>8MB</literal>). |
| 6157 |
</para> |
| 6158 |
</listitem> |
| 6159 |
</varlistentry> |
| 6160 |
|
| 6161 |
<varlistentry id="guc-min-parallel-index-scan-size" xreflabel="min_parallel_index_scan_size"> |
| 6162 |
<term><varname>min_parallel_index_scan_size</varname> (<type>integer</type>) |
| 6163 |
<indexterm> |
| 6164 |
<primary><varname>min_parallel_index_scan_size</varname> configuration parameter</primary> |
| 6165 |
</indexterm> |
| 6166 |
</term> |
| 6167 |
<listitem> |
| 6168 |
<para> |
| 6169 |
Sets the minimum amount of index data that must be scanned in order |
| 6170 |
for a parallel scan to be considered. Note that a parallel index scan |
| 6171 |
typically won't touch the entire index; it is the number of pages |
| 6172 |
which the planner believes will actually be touched by the scan which |
| 6173 |
is relevant. This parameter is also used to decide whether a |
| 6174 |
particular index can participate in a parallel vacuum. See |
| 6175 |
<xref linkend="sql-vacuum"/>. |
| 6176 |
If this value is specified without units, it is taken as blocks, |
| 6177 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 6178 |
The default is 512 kilobytes (<literal>512kB</literal>). |
| 6179 |
</para> |
| 6180 |
</listitem> |
| 6181 |
</varlistentry> |
| 6182 |
|
| 6183 |
<varlistentry id="guc-effective-cache-size" xreflabel="effective_cache_size"> |
| 6184 |
<term><varname>effective_cache_size</varname> (<type>integer</type>) |
| 6185 |
<indexterm> |
| 6186 |
<primary><varname>effective_cache_size</varname> configuration parameter</primary> |
| 6187 |
</indexterm> |
| 6188 |
</term> |
| 6189 |
<listitem> |
| 6190 |
<para> |
| 6191 |
Sets the planner's assumption about the effective size of the |
| 6192 |
disk cache that is available to a single query. This is |
| 6193 |
factored into estimates of the cost of using an index; a |
| 6194 |
higher value makes it more likely index scans will be used, a |
| 6195 |
lower value makes it more likely sequential scans will be |
| 6196 |
used. When setting this parameter you should consider both |
| 6197 |
<productname>PostgreSQL</productname>'s shared buffers and the |
| 6198 |
portion of the kernel's disk cache that will be used for |
| 6199 |
<productname>PostgreSQL</productname> data files, though some |
| 6200 |
data might exist in both places. Also, take |
| 6201 |
into account the expected number of concurrent queries on different |
| 6202 |
tables, since they will have to share the available |
| 6203 |
space. This parameter has no effect on the size of shared |
| 6204 |
memory allocated by <productname>PostgreSQL</productname>, nor |
| 6205 |
does it reserve kernel disk cache; it is used only for estimation |
| 6206 |
purposes. The system also does not assume data remains in |
| 6207 |
the disk cache between queries. |
| 6208 |
If this value is specified without units, it is taken as blocks, |
| 6209 |
that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. |
| 6210 |
The default is 4 gigabytes (<literal>4GB</literal>). |
| 6211 |
(If <symbol>BLCKSZ</symbol> is not 8kB, the default value scales |
| 6212 |
proportionally to it.) |
| 6213 |
</para> |
| 6214 |
</listitem> |
| 6215 |
</varlistentry> |
| 6216 |
|
| 6217 |
<varlistentry id="guc-jit-above-cost" xreflabel="jit_above_cost"> |
| 6218 |
<term><varname>jit_above_cost</varname> (<type>floating point</type>) |
| 6219 |
<indexterm> |
| 6220 |
<primary><varname>jit_above_cost</varname> configuration parameter</primary> |
| 6221 |
</indexterm> |
| 6222 |
</term> |
| 6223 |
<listitem> |
| 6224 |
<para> |
| 6225 |
Sets the query cost above which JIT compilation is activated, if |
| 6226 |
enabled (see <xref linkend="jit"/>). |
| 6227 |
Performing <acronym>JIT</acronym> costs planning time but can |
| 6228 |
accelerate query execution. |
| 6229 |
Setting this to <literal>-1</literal> disables JIT compilation. |
| 6230 |
The default is <literal>100000</literal>. |
| 6231 |
</para> |
| 6232 |
</listitem> |
| 6233 |
</varlistentry> |
| 6234 |
|
| 6235 |
<varlistentry id="guc-jit-inline-above-cost" xreflabel="jit_inline_above_cost"> |
| 6236 |
<term><varname>jit_inline_above_cost</varname> (<type>floating point</type>) |
| 6237 |
<indexterm> |
| 6238 |
<primary><varname>jit_inline_above_cost</varname> configuration parameter</primary> |
| 6239 |
</indexterm> |
| 6240 |
</term> |
| 6241 |
<listitem> |
| 6242 |
<para> |
| 6243 |
Sets the query cost above which JIT compilation attempts to inline |
| 6244 |
functions and operators. Inlining adds planning time, but can |
| 6245 |
improve execution speed. It is not meaningful to set this to less |
| 6246 |
than <varname>jit_above_cost</varname>. |
| 6247 |
Setting this to <literal>-1</literal> disables inlining. |
| 6248 |
The default is <literal>500000</literal>. |
| 6249 |
</para> |
| 6250 |
</listitem> |
| 6251 |
</varlistentry> |
| 6252 |
|
| 6253 |
<varlistentry id="guc-jit-optimize-above-cost" xreflabel="jit_optimize_above_cost"> |
| 6254 |
<term><varname>jit_optimize_above_cost</varname> (<type>floating point</type>) |
| 6255 |
<indexterm> |
| 6256 |
<primary><varname>jit_optimize_above_cost</varname> configuration parameter</primary> |
| 6257 |
</indexterm> |
| 6258 |
</term> |
| 6259 |
<listitem> |
| 6260 |
<para> |
| 6261 |
Sets the query cost above which JIT compilation applies expensive |
| 6262 |
optimizations. Such optimization adds planning time, but can improve |
| 6263 |
execution speed. It is not meaningful to set this to less |
| 6264 |
than <varname>jit_above_cost</varname>, and it is unlikely to be |
| 6265 |
beneficial to set it to more |
| 6266 |
than <varname>jit_inline_above_cost</varname>. |
| 6267 |
Setting this to <literal>-1</literal> disables expensive optimizations. |
| 6268 |
The default is <literal>500000</literal>. |
| 6269 |
</para> |
| 6270 |
</listitem> |
| 6271 |
</varlistentry> |
| 6272 |
|
| 6273 |
</variablelist> |
| 6274 |
|
| 6275 |
</sect2> |
| 6276 |
<sect2 id="runtime-config-query-geqo"> |
| 6277 |
<title>Genetic Query Optimizer</title> |
| 6278 |
|
| 6279 |
<para> |
| 6280 |
The genetic query optimizer (GEQO) is an algorithm that does query |
| 6281 |
planning using heuristic searching. This reduces planning time for |
| 6282 |
complex queries (those joining many relations), at the cost of producing |
| 6283 |
plans that are sometimes inferior to those found by the normal |
| 6284 |
exhaustive-search algorithm. |
| 6285 |
For more information see <xref linkend="geqo"/>. |
| 6286 |
</para> |
| 6287 |
|
| 6288 |
<variablelist> |
| 6289 |
|
| 6290 |
<varlistentry id="guc-geqo" xreflabel="geqo"> |
| 6291 |
<term><varname>geqo</varname> (<type>boolean</type>) |
| 6292 |
<indexterm> |
| 6293 |
<primary>genetic query optimization</primary> |
| 6294 |
</indexterm> |
| 6295 |
<indexterm> |
| 6296 |
<primary>GEQO</primary> |
| 6297 |
<see>genetic query optimization</see> |
| 6298 |
</indexterm> |
| 6299 |
<indexterm> |
| 6300 |
<primary><varname>geqo</varname> configuration parameter</primary> |
| 6301 |
</indexterm> |
| 6302 |
</term> |
| 6303 |
<listitem> |
| 6304 |
<para> |
| 6305 |
Enables or disables genetic query optimization. |
| 6306 |
This is on by default. It is usually best not to turn it off in |
| 6307 |
production; the <varname>geqo_threshold</varname> variable provides |
| 6308 |
more granular control of GEQO. |
| 6309 |
</para> |
| 6310 |
</listitem> |
| 6311 |
</varlistentry> |
| 6312 |
|
| 6313 |
<varlistentry id="guc-geqo-threshold" xreflabel="geqo_threshold"> |
| 6314 |
<term><varname>geqo_threshold</varname> (<type>integer</type>) |
| 6315 |
<indexterm> |
| 6316 |
<primary><varname>geqo_threshold</varname> configuration parameter</primary> |
| 6317 |
</indexterm> |
| 6318 |
</term> |
| 6319 |
<listitem> |
| 6320 |
<para> |
| 6321 |
Use genetic query optimization to plan queries with at least |
| 6322 |
this many <literal>FROM</literal> items involved. (Note that a |
| 6323 |
<literal>FULL OUTER JOIN</literal> construct counts as only one <literal>FROM</literal> |
| 6324 |
item.) The default is 12. For simpler queries it is usually best |
| 6325 |
to use the regular, exhaustive-search planner, but for queries with |
| 6326 |
many tables the exhaustive search takes too long, often |
| 6327 |
longer than the penalty of executing a suboptimal plan. Thus, |
| 6328 |
a threshold on the size of the query is a convenient way to manage |
| 6329 |
use of GEQO. |
| 6330 |
</para> |
| 6331 |
</listitem> |
| 6332 |
</varlistentry> |
| 6333 |
|
| 6334 |
<varlistentry id="guc-geqo-effort" xreflabel="geqo_effort"> |
| 6335 |
<term><varname>geqo_effort</varname> (<type>integer</type>) |
| 6336 |
<indexterm> |
| 6337 |
<primary><varname>geqo_effort</varname> configuration parameter</primary> |
| 6338 |
</indexterm> |
| 6339 |
</term> |
| 6340 |
<listitem> |
| 6341 |
<para> |
| 6342 |
Controls the trade-off between planning time and query plan |
| 6343 |
quality in GEQO. This variable must be an integer in the |
| 6344 |
range from 1 to 10. The default value is five. Larger values |
| 6345 |
increase the time spent doing query planning, but also |
| 6346 |
increase the likelihood that an efficient query plan will be |
| 6347 |
chosen. |
| 6348 |
</para> |
| 6349 |
|
| 6350 |
<para> |
| 6351 |
<varname>geqo_effort</varname> doesn't actually do anything |
| 6352 |
directly; it is only used to compute the default values for |
| 6353 |
the other variables that influence GEQO behavior (described |
| 6354 |
below). If you prefer, you can set the other parameters by |
| 6355 |
hand instead. |
| 6356 |
</para> |
| 6357 |
</listitem> |
| 6358 |
</varlistentry> |
| 6359 |
|
| 6360 |
<varlistentry id="guc-geqo-pool-size" xreflabel="geqo_pool_size"> |
| 6361 |
<term><varname>geqo_pool_size</varname> (<type>integer</type>) |
| 6362 |
<indexterm> |
| 6363 |
<primary><varname>geqo_pool_size</varname> configuration parameter</primary> |
| 6364 |
</indexterm> |
| 6365 |
</term> |
| 6366 |
<listitem> |
| 6367 |
<para> |
| 6368 |
Controls the pool size used by GEQO, that is the |
| 6369 |
number of individuals in the genetic population. It must be |
| 6370 |
at least two, and useful values are typically 100 to 1000. If |
| 6371 |
it is set to zero (the default setting) then a suitable |
| 6372 |
value is chosen based on <varname>geqo_effort</varname> and |
| 6373 |
the number of tables in the query. |
| 6374 |
</para> |
| 6375 |
</listitem> |
| 6376 |
</varlistentry> |
| 6377 |
|
| 6378 |
<varlistentry id="guc-geqo-generations" xreflabel="geqo_generations"> |
| 6379 |
<term><varname>geqo_generations</varname> (<type>integer</type>) |
| 6380 |
<indexterm> |
| 6381 |
<primary><varname>geqo_generations</varname> configuration parameter</primary> |
| 6382 |
</indexterm> |
| 6383 |
</term> |
| 6384 |
<listitem> |
| 6385 |
<para> |
| 6386 |
Controls the number of generations used by GEQO, that is |
| 6387 |
the number of iterations of the algorithm. It must |
| 6388 |
be at least one, and useful values are in the same range as |
| 6389 |
the pool size. If it is set to zero (the default setting) |
| 6390 |
then a suitable value is chosen based on |
| 6391 |
<varname>geqo_pool_size</varname>. |
| 6392 |
</para> |
| 6393 |
</listitem> |
| 6394 |
</varlistentry> |
| 6395 |
|
| 6396 |
<varlistentry id="guc-geqo-selection-bias" xreflabel="geqo_selection_bias"> |
| 6397 |
<term><varname>geqo_selection_bias</varname> (<type>floating point</type>) |
| 6398 |
<indexterm> |
| 6399 |
<primary><varname>geqo_selection_bias</varname> configuration parameter</primary> |
| 6400 |
</indexterm> |
| 6401 |
</term> |
| 6402 |
<listitem> |
| 6403 |
<para> |
| 6404 |
Controls the selection bias used by GEQO. The selection bias |
| 6405 |
is the selective pressure within the population. Values can be |
| 6406 |
from 1.50 to 2.00; the latter is the default. |
| 6407 |
</para> |
| 6408 |
</listitem> |
| 6409 |
</varlistentry> |
| 6410 |
|
| 6411 |
<varlistentry id="guc-geqo-seed" xreflabel="geqo_seed"> |
| 6412 |
<term><varname>geqo_seed</varname> (<type>floating point</type>) |
| 6413 |
<indexterm> |
| 6414 |
<primary><varname>geqo_seed</varname> configuration parameter</primary> |
| 6415 |
</indexterm> |
| 6416 |
</term> |
| 6417 |
<listitem> |
| 6418 |
<para> |
| 6419 |
Controls the initial value of the random number generator used |
| 6420 |
by GEQO to select random paths through the join order search space. |
| 6421 |
The value can range from zero (the default) to one. Varying the |
| 6422 |
value changes the set of join paths explored, and may result in a |
| 6423 |
better or worse best path being found. |
| 6424 |
</para> |
| 6425 |
</listitem> |
| 6426 |
</varlistentry> |
| 6427 |
|
| 6428 |
</variablelist> |
| 6429 |
</sect2> |
| 6430 |
<sect2 id="runtime-config-query-other"> |
| 6431 |
<title>Other Planner Options</title> |
| 6432 |
|
| 6433 |
<variablelist> |
| 6434 |
|
| 6435 |
<varlistentry id="guc-default-statistics-target" xreflabel="default_statistics_target"> |
| 6436 |
<term><varname>default_statistics_target</varname> (<type>integer</type>) |
| 6437 |
<indexterm> |
| 6438 |
<primary><varname>default_statistics_target</varname> configuration parameter</primary> |
| 6439 |
</indexterm> |
| 6440 |
</term> |
| 6441 |
<listitem> |
| 6442 |
<para> |
| 6443 |
Sets the default statistics target for table columns without |
| 6444 |
a column-specific target set via <command>ALTER TABLE |
| 6445 |
SET STATISTICS</command>. Larger values increase the time needed to |
| 6446 |
do <command>ANALYZE</command>, but might improve the quality of the |
| 6447 |
planner's estimates. The default is 100. For more information |
| 6448 |
on the use of statistics by the <productname>PostgreSQL</productname> |
| 6449 |
query planner, refer to <xref linkend="planner-stats"/>. |
| 6450 |
</para> |
| 6451 |
</listitem> |
| 6452 |
</varlistentry> |
| 6453 |
|
| 6454 |
<varlistentry id="guc-constraint-exclusion" xreflabel="constraint_exclusion"> |
| 6455 |
<term><varname>constraint_exclusion</varname> (<type>enum</type>) |
| 6456 |
<indexterm> |
| 6457 |
<primary>constraint exclusion</primary> |
| 6458 |
</indexterm> |
| 6459 |
<indexterm> |
| 6460 |
<primary><varname>constraint_exclusion</varname> configuration parameter</primary> |
| 6461 |
</indexterm> |
| 6462 |
</term> |
| 6463 |
<listitem> |
| 6464 |
<para> |
| 6465 |
Controls the query planner's use of table constraints to |
| 6466 |
optimize queries. |
| 6467 |
The allowed values of <varname>constraint_exclusion</varname> are |
| 6468 |
<literal>on</literal> (examine constraints for all tables), |
| 6469 |
<literal>off</literal> (never examine constraints), and |
| 6470 |
<literal>partition</literal> (examine constraints only for inheritance |
| 6471 |
child tables and <literal>UNION ALL</literal> subqueries). |
| 6472 |
<literal>partition</literal> is the default setting. |
| 6473 |
It is often used with traditional inheritance trees to improve |
| 6474 |
performance. |
| 6475 |
</para> |
| 6476 |
|
| 6477 |
<para> |
| 6478 |
When this parameter allows it for a particular table, the planner |
| 6479 |
compares query conditions with the table's <literal>CHECK</literal> |
| 6480 |
constraints, and omits scanning tables for which the conditions |
| 6481 |
contradict the constraints. For example: |
| 6482 |
|
| 6483 |
<programlisting> |
| 6484 |
CREATE TABLE parent(key integer, ...); |
| 6485 |
CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent); |
| 6486 |
CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent); |
| 6487 |
... |
| 6488 |
SELECT * FROM parent WHERE key = 2400; |
| 6489 |
</programlisting> |
| 6490 |
|
| 6491 |
With constraint exclusion enabled, this <command>SELECT</command> |
| 6492 |
will not scan <structname>child1000</structname> at all, improving performance. |
| 6493 |
</para> |
| 6494 |
|
| 6495 |
<para> |
| 6496 |
Currently, constraint exclusion is enabled by default |
| 6497 |
only for cases that are often used to implement table partitioning via |
| 6498 |
inheritance trees. Turning it on for all tables imposes extra |
| 6499 |
planning overhead that is quite noticeable on simple queries, and most |
| 6500 |
often will yield no benefit for simple queries. If you have no |
| 6501 |
tables that are partitioned using traditional inheritance, you might |
| 6502 |
prefer to turn it off entirely. (Note that the equivalent feature for |
| 6503 |
partitioned tables is controlled by a separate parameter, |
| 6504 |
<xref linkend="guc-enable-partition-pruning"/>.) |
| 6505 |
</para> |
| 6506 |
|
| 6507 |
<para> |
| 6508 |
Refer to <xref linkend="ddl-partitioning-constraint-exclusion"/> for |
| 6509 |
more information on using constraint exclusion to implement |
| 6510 |
partitioning. |
| 6511 |
</para> |
| 6512 |
</listitem> |
| 6513 |
</varlistentry> |
| 6514 |
|
| 6515 |
<varlistentry id="guc-cursor-tuple-fraction" xreflabel="cursor_tuple_fraction"> |
| 6516 |
<term><varname>cursor_tuple_fraction</varname> (<type>floating point</type>) |
| 6517 |
<indexterm> |
| 6518 |
<primary><varname>cursor_tuple_fraction</varname> configuration parameter</primary> |
| 6519 |
</indexterm> |
| 6520 |
</term> |
| 6521 |
<listitem> |
| 6522 |
<para> |
| 6523 |
Sets the planner's estimate of the fraction of a cursor's rows that |
| 6524 |
will be retrieved. The default is 0.1. Smaller values of this |
| 6525 |
setting bias the planner towards using <quote>fast start</quote> plans |
| 6526 |
for cursors, which will retrieve the first few rows quickly while |
| 6527 |
perhaps taking a long time to fetch all rows. Larger values |
| 6528 |
put more emphasis on the total estimated time. At the maximum |
| 6529 |
setting of 1.0, cursors are planned exactly like regular queries, |
| 6530 |
considering only the total estimated time and not how soon the |
| 6531 |
first rows might be delivered. |
| 6532 |
</para> |
| 6533 |
</listitem> |
| 6534 |
</varlistentry> |
| 6535 |
|
| 6536 |
<varlistentry id="guc-from-collapse-limit" xreflabel="from_collapse_limit"> |
| 6537 |
<term><varname>from_collapse_limit</varname> (<type>integer</type>) |
| 6538 |
<indexterm> |
| 6539 |
<primary><varname>from_collapse_limit</varname> configuration parameter</primary> |
| 6540 |
</indexterm> |
| 6541 |
</term> |
| 6542 |
<listitem> |
| 6543 |
<para> |
| 6544 |
The planner will merge sub-queries into upper queries if the |
| 6545 |
resulting <literal>FROM</literal> list would have no more than |
| 6546 |
this many items. Smaller values reduce planning time but might |
| 6547 |
yield inferior query plans. The default is eight. |
| 6548 |
For more information see <xref linkend="explicit-joins"/>. |
| 6549 |
</para> |
| 6550 |
|
| 6551 |
<para> |
| 6552 |
Setting this value to <xref linkend="guc-geqo-threshold"/> or more |
| 6553 |
may trigger use of the GEQO planner, resulting in non-optimal |
| 6554 |
plans. See <xref linkend="runtime-config-query-geqo"/>. |
| 6555 |
</para> |
| 6556 |
</listitem> |
| 6557 |
</varlistentry> |
| 6558 |
|
| 6559 |
<varlistentry id="guc-jit" xreflabel="jit"> |
| 6560 |
<term><varname>jit</varname> (<type>boolean</type>) |
| 6561 |
<indexterm> |
| 6562 |
<primary><varname>jit</varname> configuration parameter</primary> |
| 6563 |
</indexterm> |
| 6564 |
</term> |
| 6565 |
<listitem> |
| 6566 |
<para> |
| 6567 |
Determines whether <acronym>JIT</acronym> compilation may be used by |
| 6568 |
<productname>PostgreSQL</productname>, if available (see <xref |
| 6569 |
linkend="jit"/>). |
| 6570 |
The default is <literal>on</literal>. |
| 6571 |
</para> |
| 6572 |
</listitem> |
| 6573 |
</varlistentry> |
| 6574 |
|
| 6575 |
<varlistentry id="guc-join-collapse-limit" xreflabel="join_collapse_limit"> |
| 6576 |
<term><varname>join_collapse_limit</varname> (<type>integer</type>) |
| 6577 |
<indexterm> |
| 6578 |
<primary><varname>join_collapse_limit</varname> configuration parameter</primary> |
| 6579 |
</indexterm> |
| 6580 |
</term> |
| 6581 |
<listitem> |
| 6582 |
<para> |
| 6583 |
The planner will rewrite explicit <literal>JOIN</literal> |
| 6584 |
constructs (except <literal>FULL JOIN</literal>s) into lists of |
| 6585 |
<literal>FROM</literal> items whenever a list of no more than this many items |
| 6586 |
would result. Smaller values reduce planning time but might |
| 6587 |
yield inferior query plans. |
| 6588 |
</para> |
| 6589 |
|
| 6590 |
<para> |
| 6591 |
By default, this variable is set the same as |
| 6592 |
<varname>from_collapse_limit</varname>, which is appropriate |
| 6593 |
for most uses. Setting it to 1 prevents any reordering of |
| 6594 |
explicit <literal>JOIN</literal>s. Thus, the explicit join order |
| 6595 |
specified in the query will be the actual order in which the |
| 6596 |
relations are joined. Because the query planner does not always choose |
| 6597 |
the optimal join order, advanced users can elect to |
| 6598 |
temporarily set this variable to 1, and then specify the join |
| 6599 |
order they desire explicitly. |
| 6600 |
For more information see <xref linkend="explicit-joins"/>. |
| 6601 |
</para> |
| 6602 |
|
| 6603 |
<para> |
| 6604 |
Setting this value to <xref linkend="guc-geqo-threshold"/> or more |
| 6605 |
may trigger use of the GEQO planner, resulting in non-optimal |
| 6606 |
plans. See <xref linkend="runtime-config-query-geqo"/>. |
| 6607 |
</para> |
| 6608 |
</listitem> |
| 6609 |
</varlistentry> |
| 6610 |
|
| 6611 |
<varlistentry id="guc-plan-cache-mode" xreflabel="plan_cache_mode"> |
| 6612 |
<term><varname>plan_cache_mode</varname> (<type>enum</type>) |
| 6613 |
<indexterm> |
| 6614 |
<primary><varname>plan_cache_mode</varname> configuration parameter</primary> |
| 6615 |
</indexterm> |
| 6616 |
</term> |
| 6617 |
<listitem> |
| 6618 |
<para> |
| 6619 |
Prepared statements (either explicitly prepared or implicitly |
| 6620 |
generated, for example by PL/pgSQL) can be executed using custom or |
| 6621 |
generic plans. Custom plans are made afresh for each execution |
| 6622 |
using its specific set of parameter values, while generic plans do |
| 6623 |
not rely on the parameter values and can be re-used across |
| 6624 |
executions. Thus, use of a generic plan saves planning time, but if |
| 6625 |
the ideal plan depends strongly on the parameter values then a |
| 6626 |
generic plan may be inefficient. The choice between these options |
| 6627 |
is normally made automatically, but it can be overridden |
| 6628 |
with <varname>plan_cache_mode</varname>. |
| 6629 |
The allowed values are <literal>auto</literal> (the default), |
| 6630 |
<literal>force_custom_plan</literal> and |
| 6631 |
<literal>force_generic_plan</literal>. |
| 6632 |
This setting is considered when a cached plan is to be executed, |
| 6633 |
not when it is prepared. |
| 6634 |
For more information see <xref linkend="sql-prepare"/>. |
| 6635 |
</para> |
| 6636 |
</listitem> |
| 6637 |
</varlistentry> |
| 6638 |
|
| 6639 |
<varlistentry id="guc-recursive-worktable-factor" xreflabel="recursive_worktable_factor"> |
| 6640 |
<term><varname>recursive_worktable_factor</varname> (<type>floating point</type>) |
| 6641 |
<indexterm> |
| 6642 |
<primary><varname>recursive_worktable_factor</varname> configuration parameter</primary> |
| 6643 |
</indexterm> |
| 6644 |
</term> |
| 6645 |
<listitem> |
| 6646 |
<para> |
| 6647 |
Sets the planner's estimate of the average size of the working |
| 6648 |
table of a <link linkend="queries-with-recursive">recursive |
| 6649 |
query</link>, as a multiple of the estimated size of the initial |
| 6650 |
non-recursive term of the query. This helps the planner choose |
| 6651 |
the most appropriate method for joining the working table to the |
| 6652 |
query's other tables. |
| 6653 |
The default value is <literal>10.0</literal>. A smaller value |
| 6654 |
such as <literal>1.0</literal> can be helpful when the recursion |
| 6655 |
has low <quote>fan-out</quote> from one step to the next, as for |
| 6656 |
example in shortest-path queries. Graph analytics queries may |
| 6657 |
benefit from larger-than-default values. |
| 6658 |
</para> |
| 6659 |
</listitem> |
| 6660 |
</varlistentry> |
| 6661 |
|
| 6662 |
</variablelist> |
| 6663 |
</sect2> |
| 6664 |
</sect1> |
| 6665 |
|
| 6666 |
<sect1 id="runtime-config-logging"> |
| 6667 |
<title>Error Reporting and Logging</title> |
| 6668 |
|
| 6669 |
<indexterm zone="runtime-config-logging"> |
| 6670 |
<primary>server log</primary> |
| 6671 |
</indexterm> |
| 6672 |
|
| 6673 |
<sect2 id="runtime-config-logging-where"> |
| 6674 |
<title>Where to Log</title> |
| 6675 |
|
| 6676 |
<indexterm zone="runtime-config-logging-where"> |
| 6677 |
<primary>where to log</primary> |
| 6678 |
</indexterm> |
| 6679 |
|
| 6680 |
<indexterm> |
| 6681 |
<primary>current_logfiles</primary> |
| 6682 |
<secondary>and the log_destination configuration parameter</secondary> |
| 6683 |
</indexterm> |
| 6684 |
|
| 6685 |
<variablelist> |
| 6686 |
|
| 6687 |
<varlistentry id="guc-log-destination" xreflabel="log_destination"> |
| 6688 |
<term><varname>log_destination</varname> (<type>string</type>) |
| 6689 |
<indexterm> |
| 6690 |
<primary><varname>log_destination</varname> configuration parameter</primary> |
| 6691 |
</indexterm> |
| 6692 |
</term> |
| 6693 |
<listitem> |
| 6694 |
<para> |
| 6695 |
<productname>PostgreSQL</productname> supports several methods |
| 6696 |
for logging server messages, including |
| 6697 |
<systemitem>stderr</systemitem>, <systemitem>csvlog</systemitem>, |
| 6698 |
<systemitem>jsonlog</systemitem>, and |
| 6699 |
<systemitem>syslog</systemitem>. On Windows, |
| 6700 |
<systemitem>eventlog</systemitem> is also supported. Set this |
| 6701 |
parameter to a list of desired log destinations separated by |
| 6702 |
commas. The default is to log to <systemitem>stderr</systemitem> |
| 6703 |
only. |
| 6704 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6705 |
file or on the server command line. |
| 6706 |
</para> |
| 6707 |
<para> |
| 6708 |
If <systemitem>csvlog</systemitem> is included in <varname>log_destination</varname>, |
| 6709 |
log entries are output in <quote>comma-separated |
| 6710 |
value</quote> (<acronym>CSV</acronym>) format, which is convenient for |
| 6711 |
loading logs into programs. |
| 6712 |
See <xref linkend="runtime-config-logging-csvlog"/> for details. |
| 6713 |
<xref linkend="guc-logging-collector"/> must be enabled to generate |
| 6714 |
CSV-format log output. |
| 6715 |
</para> |
| 6716 |
<para> |
| 6717 |
If <systemitem>jsonlog</systemitem> is included in |
| 6718 |
<varname>log_destination</varname>, log entries are output in |
| 6719 |
<acronym>JSON</acronym> format, which is convenient for loading logs |
| 6720 |
into programs. |
| 6721 |
See <xref linkend="runtime-config-logging-jsonlog"/> for details. |
| 6722 |
<xref linkend="guc-logging-collector"/> must be enabled to generate |
| 6723 |
JSON-format log output. |
| 6724 |
</para> |
| 6725 |
<para> |
| 6726 |
When either <systemitem>stderr</systemitem>, |
| 6727 |
<systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are |
| 6728 |
included, the file <filename>current_logfiles</filename> is created to |
| 6729 |
record the location of the log file(s) currently in use by the logging |
| 6730 |
collector and the associated logging destination. This provides a |
| 6731 |
convenient way to find the logs currently in use by the instance. Here |
| 6732 |
is an example of this file's content: |
| 6733 |
<programlisting> |
| 6734 |
stderr log/postgresql.log |
| 6735 |
csvlog log/postgresql.csv |
| 6736 |
jsonlog log/postgresql.json |
| 6737 |
</programlisting> |
| 6738 |
|
| 6739 |
<filename>current_logfiles</filename> is recreated when a new log file |
| 6740 |
is created as an effect of rotation, and |
| 6741 |
when <varname>log_destination</varname> is reloaded. It is removed when |
| 6742 |
none of <systemitem>stderr</systemitem>, |
| 6743 |
<systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are |
| 6744 |
included in <varname>log_destination</varname>, and when the logging |
| 6745 |
collector is disabled. |
| 6746 |
</para> |
| 6747 |
|
| 6748 |
<note> |
| 6749 |
<para> |
| 6750 |
On most Unix systems, you will need to alter the configuration of |
| 6751 |
your system's <application>syslog</application> daemon in order |
| 6752 |
to make use of the <systemitem>syslog</systemitem> option for |
| 6753 |
<varname>log_destination</varname>. <productname>PostgreSQL</productname> |
| 6754 |
can log to <application>syslog</application> facilities |
| 6755 |
<literal>LOCAL0</literal> through <literal>LOCAL7</literal> (see <xref |
| 6756 |
linkend="guc-syslog-facility"/>), but the default |
| 6757 |
<application>syslog</application> configuration on most platforms |
| 6758 |
will discard all such messages. You will need to add something like: |
| 6759 |
<programlisting> |
| 6760 |
local0.* /var/log/postgresql |
| 6761 |
</programlisting> |
| 6762 |
to the <application>syslog</application> daemon's configuration file |
| 6763 |
to make it work. |
| 6764 |
</para> |
| 6765 |
<para> |
| 6766 |
On Windows, when you use the <literal>eventlog</literal> |
| 6767 |
option for <varname>log_destination</varname>, you should |
| 6768 |
register an event source and its library with the operating |
| 6769 |
system so that the Windows Event Viewer can display event |
| 6770 |
log messages cleanly. |
| 6771 |
See <xref linkend="event-log-registration"/> for details. |
| 6772 |
</para> |
| 6773 |
</note> |
| 6774 |
</listitem> |
| 6775 |
</varlistentry> |
| 6776 |
|
| 6777 |
<varlistentry id="guc-logging-collector" xreflabel="logging_collector"> |
| 6778 |
<term><varname>logging_collector</varname> (<type>boolean</type>) |
| 6779 |
<indexterm> |
| 6780 |
<primary><varname>logging_collector</varname> configuration parameter</primary> |
| 6781 |
</indexterm> |
| 6782 |
</term> |
| 6783 |
<listitem> |
| 6784 |
<para> |
| 6785 |
This parameter enables the <firstterm>logging collector</firstterm>, which |
| 6786 |
is a background process that captures log messages |
| 6787 |
sent to <systemitem>stderr</systemitem> and redirects them into log files. |
| 6788 |
This approach is often more useful than |
| 6789 |
logging to <application>syslog</application>, since some types of messages |
| 6790 |
might not appear in <application>syslog</application> output. (One common |
| 6791 |
example is dynamic-linker failure messages; another is error messages |
| 6792 |
produced by scripts such as <varname>archive_command</varname>.) |
| 6793 |
This parameter can only be set at server start. |
| 6794 |
</para> |
| 6795 |
|
| 6796 |
<note> |
| 6797 |
<para> |
| 6798 |
It is possible to log to <systemitem>stderr</systemitem> without using the |
| 6799 |
logging collector; the log messages will just go to wherever the |
| 6800 |
server's <systemitem>stderr</systemitem> is directed. However, that method is |
| 6801 |
only suitable for low log volumes, since it provides no convenient |
| 6802 |
way to rotate log files. Also, on some platforms not using the |
| 6803 |
logging collector can result in lost or garbled log output, because |
| 6804 |
multiple processes writing concurrently to the same log file can |
| 6805 |
overwrite each other's output. |
| 6806 |
</para> |
| 6807 |
</note> |
| 6808 |
|
| 6809 |
<note> |
| 6810 |
<para> |
| 6811 |
The logging collector is designed to never lose messages. This means |
| 6812 |
that in case of extremely high load, server processes could be |
| 6813 |
blocked while trying to send additional log messages when the |
| 6814 |
collector has fallen behind. In contrast, <application>syslog</application> |
| 6815 |
prefers to drop messages if it cannot write them, which means it |
| 6816 |
may fail to log some messages in such cases but it will not block |
| 6817 |
the rest of the system. |
| 6818 |
</para> |
| 6819 |
</note> |
| 6820 |
|
| 6821 |
</listitem> |
| 6822 |
</varlistentry> |
| 6823 |
|
| 6824 |
<varlistentry id="guc-log-directory" xreflabel="log_directory"> |
| 6825 |
<term><varname>log_directory</varname> (<type>string</type>) |
| 6826 |
<indexterm> |
| 6827 |
<primary><varname>log_directory</varname> configuration parameter</primary> |
| 6828 |
</indexterm> |
| 6829 |
</term> |
| 6830 |
<listitem> |
| 6831 |
<para> |
| 6832 |
When <varname>logging_collector</varname> is enabled, |
| 6833 |
this parameter determines the directory in which log files will be created. |
| 6834 |
It can be specified as an absolute path, or relative to the |
| 6835 |
cluster data directory. |
| 6836 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6837 |
file or on the server command line. |
| 6838 |
The default is <literal>log</literal>. |
| 6839 |
</para> |
| 6840 |
</listitem> |
| 6841 |
</varlistentry> |
| 6842 |
|
| 6843 |
<varlistentry id="guc-log-filename" xreflabel="log_filename"> |
| 6844 |
<term><varname>log_filename</varname> (<type>string</type>) |
| 6845 |
<indexterm> |
| 6846 |
<primary><varname>log_filename</varname> configuration parameter</primary> |
| 6847 |
</indexterm> |
| 6848 |
</term> |
| 6849 |
<listitem> |
| 6850 |
<para> |
| 6851 |
When <varname>logging_collector</varname> is enabled, |
| 6852 |
this parameter sets the file names of the created log files. The value |
| 6853 |
is treated as a <function>strftime</function> pattern, |
| 6854 |
so <literal>%</literal>-escapes can be used to specify time-varying |
| 6855 |
file names. (Note that if there are |
| 6856 |
any time-zone-dependent <literal>%</literal>-escapes, the computation |
| 6857 |
is done in the zone specified |
| 6858 |
by <xref linkend="guc-log-timezone"/>.) |
| 6859 |
The supported <literal>%</literal>-escapes are similar to those |
| 6860 |
listed in the Open Group's <ulink |
| 6861 |
url="https://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html">strftime |
| 6862 |
</ulink> specification. |
| 6863 |
Note that the system's <function>strftime</function> is not used |
| 6864 |
directly, so platform-specific (nonstandard) extensions do not work. |
| 6865 |
The default is <literal>postgresql-%Y-%m-%d_%H%M%S.log</literal>. |
| 6866 |
</para> |
| 6867 |
<para> |
| 6868 |
If you specify a file name without escapes, you should plan to |
| 6869 |
use a log rotation utility to avoid eventually filling the |
| 6870 |
entire disk. In releases prior to 8.4, if |
| 6871 |
no <literal>%</literal> escapes were |
| 6872 |
present, <productname>PostgreSQL</productname> would append |
| 6873 |
the epoch of the new log file's creation time, but this is no |
| 6874 |
longer the case. |
| 6875 |
</para> |
| 6876 |
<para> |
| 6877 |
If CSV-format output is enabled in <varname>log_destination</varname>, |
| 6878 |
<literal>.csv</literal> will be appended to the timestamped |
| 6879 |
log file name to create the file name for CSV-format output. |
| 6880 |
(If <varname>log_filename</varname> ends in <literal>.log</literal>, the suffix is |
| 6881 |
replaced instead.) |
| 6882 |
</para> |
| 6883 |
<para> |
| 6884 |
If JSON-format output is enabled in <varname>log_destination</varname>, |
| 6885 |
<literal>.json</literal> will be appended to the timestamped |
| 6886 |
log file name to create the file name for JSON-format output. |
| 6887 |
(If <varname>log_filename</varname> ends in <literal>.log</literal>, the suffix is |
| 6888 |
replaced instead.) |
| 6889 |
</para> |
| 6890 |
<para> |
| 6891 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6892 |
file or on the server command line. |
| 6893 |
</para> |
| 6894 |
</listitem> |
| 6895 |
</varlistentry> |
| 6896 |
|
| 6897 |
<varlistentry id="guc-log-file-mode" xreflabel="log_file_mode"> |
| 6898 |
<term><varname>log_file_mode</varname> (<type>integer</type>) |
| 6899 |
<indexterm> |
| 6900 |
<primary><varname>log_file_mode</varname> configuration parameter</primary> |
| 6901 |
</indexterm> |
| 6902 |
</term> |
| 6903 |
<listitem> |
| 6904 |
<para> |
| 6905 |
On Unix systems this parameter sets the permissions for log files |
| 6906 |
when <varname>logging_collector</varname> is enabled. (On Microsoft |
| 6907 |
Windows this parameter is ignored.) |
| 6908 |
The parameter value is expected to be a numeric mode |
| 6909 |
specified in the format accepted by the |
| 6910 |
<function>chmod</function> and <function>umask</function> |
| 6911 |
system calls. (To use the customary octal format the number |
| 6912 |
must start with a <literal>0</literal> (zero).) |
| 6913 |
</para> |
| 6914 |
<para> |
| 6915 |
The default permissions are <literal>0600</literal>, meaning only the |
| 6916 |
server owner can read or write the log files. The other commonly |
| 6917 |
useful setting is <literal>0640</literal>, allowing members of the owner's |
| 6918 |
group to read the files. Note however that to make use of such a |
| 6919 |
setting, you'll need to alter <xref linkend="guc-log-directory"/> to |
| 6920 |
store the files somewhere outside the cluster data directory. In |
| 6921 |
any case, it's unwise to make the log files world-readable, since |
| 6922 |
they might contain sensitive data. |
| 6923 |
</para> |
| 6924 |
<para> |
| 6925 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6926 |
file or on the server command line. |
| 6927 |
</para> |
| 6928 |
</listitem> |
| 6929 |
</varlistentry> |
| 6930 |
|
| 6931 |
<varlistentry id="guc-log-rotation-age" xreflabel="log_rotation_age"> |
| 6932 |
<term><varname>log_rotation_age</varname> (<type>integer</type>) |
| 6933 |
<indexterm> |
| 6934 |
<primary><varname>log_rotation_age</varname> configuration parameter</primary> |
| 6935 |
</indexterm> |
| 6936 |
</term> |
| 6937 |
<listitem> |
| 6938 |
<para> |
| 6939 |
When <varname>logging_collector</varname> is enabled, |
| 6940 |
this parameter determines the maximum amount of time to use an |
| 6941 |
individual log file, after which a new log file will be created. |
| 6942 |
If this value is specified without units, it is taken as minutes. |
| 6943 |
The default is 24 hours. |
| 6944 |
Set to zero to disable time-based creation of new log files. |
| 6945 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6946 |
file or on the server command line. |
| 6947 |
</para> |
| 6948 |
</listitem> |
| 6949 |
</varlistentry> |
| 6950 |
|
| 6951 |
<varlistentry id="guc-log-rotation-size" xreflabel="log_rotation_size"> |
| 6952 |
<term><varname>log_rotation_size</varname> (<type>integer</type>) |
| 6953 |
<indexterm> |
| 6954 |
<primary><varname>log_rotation_size</varname> configuration parameter</primary> |
| 6955 |
</indexterm> |
| 6956 |
</term> |
| 6957 |
<listitem> |
| 6958 |
<para> |
| 6959 |
When <varname>logging_collector</varname> is enabled, |
| 6960 |
this parameter determines the maximum size of an individual log file. |
| 6961 |
After this amount of data has been emitted into a log file, |
| 6962 |
a new log file will be created. |
| 6963 |
If this value is specified without units, it is taken as kilobytes. |
| 6964 |
The default is 10 megabytes. |
| 6965 |
Set to zero to disable size-based creation of new log files. |
| 6966 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6967 |
file or on the server command line. |
| 6968 |
</para> |
| 6969 |
</listitem> |
| 6970 |
</varlistentry> |
| 6971 |
|
| 6972 |
<varlistentry id="guc-log-truncate-on-rotation" xreflabel="log_truncate_on_rotation"> |
| 6973 |
<term><varname>log_truncate_on_rotation</varname> (<type>boolean</type>) |
| 6974 |
<indexterm> |
| 6975 |
<primary><varname>log_truncate_on_rotation</varname> configuration parameter</primary> |
| 6976 |
</indexterm> |
| 6977 |
</term> |
| 6978 |
<listitem> |
| 6979 |
<para> |
| 6980 |
When <varname>logging_collector</varname> is enabled, |
| 6981 |
this parameter will cause <productname>PostgreSQL</productname> to truncate (overwrite), |
| 6982 |
rather than append to, any existing log file of the same name. |
| 6983 |
However, truncation will occur only when a new file is being opened |
| 6984 |
due to time-based rotation, not during server startup or size-based |
| 6985 |
rotation. When off, pre-existing files will be appended to in |
| 6986 |
all cases. For example, using this setting in combination with |
| 6987 |
a <varname>log_filename</varname> like <literal>postgresql-%H.log</literal> |
| 6988 |
would result in generating twenty-four hourly log files and then |
| 6989 |
cyclically overwriting them. |
| 6990 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 6991 |
file or on the server command line. |
| 6992 |
</para> |
| 6993 |
<para> |
| 6994 |
Example: To keep 7 days of logs, one log file per day named |
| 6995 |
<literal>server_log.Mon</literal>, <literal>server_log.Tue</literal>, |
| 6996 |
etc., and automatically overwrite last week's log with this week's log, |
| 6997 |
set <varname>log_filename</varname> to <literal>server_log.%a</literal>, |
| 6998 |
<varname>log_truncate_on_rotation</varname> to <literal>on</literal>, and |
| 6999 |
<varname>log_rotation_age</varname> to <literal>1440</literal>. |
| 7000 |
</para> |
| 7001 |
<para> |
| 7002 |
Example: To keep 24 hours of logs, one log file per hour, but |
| 7003 |
also rotate sooner if the log file size exceeds 1GB, set |
| 7004 |
<varname>log_filename</varname> to <literal>server_log.%H%M</literal>, |
| 7005 |
<varname>log_truncate_on_rotation</varname> to <literal>on</literal>, |
| 7006 |
<varname>log_rotation_age</varname> to <literal>60</literal>, and |
| 7007 |
<varname>log_rotation_size</varname> to <literal>1000000</literal>. |
| 7008 |
Including <literal>%M</literal> in <varname>log_filename</varname> allows |
| 7009 |
any size-driven rotations that might occur to select a file name |
| 7010 |
different from the hour's initial file name. |
| 7011 |
</para> |
| 7012 |
</listitem> |
| 7013 |
</varlistentry> |
| 7014 |
|
| 7015 |
<varlistentry id="guc-syslog-facility" xreflabel="syslog_facility"> |
| 7016 |
<term><varname>syslog_facility</varname> (<type>enum</type>) |
| 7017 |
<indexterm> |
| 7018 |
<primary><varname>syslog_facility</varname> configuration parameter</primary> |
| 7019 |
</indexterm> |
| 7020 |
</term> |
| 7021 |
<listitem> |
| 7022 |
<para> |
| 7023 |
When logging to <application>syslog</application> is enabled, this parameter |
| 7024 |
determines the <application>syslog</application> |
| 7025 |
<quote>facility</quote> to be used. You can choose |
| 7026 |
from <literal>LOCAL0</literal>, <literal>LOCAL1</literal>, |
| 7027 |
<literal>LOCAL2</literal>, <literal>LOCAL3</literal>, <literal>LOCAL4</literal>, |
| 7028 |
<literal>LOCAL5</literal>, <literal>LOCAL6</literal>, <literal>LOCAL7</literal>; |
| 7029 |
the default is <literal>LOCAL0</literal>. See also the |
| 7030 |
documentation of your system's |
| 7031 |
<application>syslog</application> daemon. |
| 7032 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7033 |
file or on the server command line. |
| 7034 |
</para> |
| 7035 |
</listitem> |
| 7036 |
</varlistentry> |
| 7037 |
|
| 7038 |
<varlistentry id="guc-syslog-ident" xreflabel="syslog_ident"> |
| 7039 |
<term><varname>syslog_ident</varname> (<type>string</type>) |
| 7040 |
<indexterm> |
| 7041 |
<primary><varname>syslog_ident</varname> configuration parameter</primary> |
| 7042 |
</indexterm> |
| 7043 |
</term> |
| 7044 |
<listitem> |
| 7045 |
<para> |
| 7046 |
When logging to <application>syslog</application> is enabled, this parameter |
| 7047 |
determines the program name used to identify |
| 7048 |
<productname>PostgreSQL</productname> messages in |
| 7049 |
<application>syslog</application> logs. The default is |
| 7050 |
<literal>postgres</literal>. |
| 7051 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7052 |
file or on the server command line. |
| 7053 |
</para> |
| 7054 |
</listitem> |
| 7055 |
</varlistentry> |
| 7056 |
|
| 7057 |
<varlistentry id="guc-syslog-sequence-numbers" xreflabel="syslog_sequence_numbers"> |
| 7058 |
<term><varname>syslog_sequence_numbers</varname> (<type>boolean</type>) |
| 7059 |
<indexterm> |
| 7060 |
<primary><varname>syslog_sequence_numbers</varname> configuration parameter</primary> |
| 7061 |
</indexterm> |
| 7062 |
</term> |
| 7063 |
|
| 7064 |
<listitem> |
| 7065 |
<para> |
| 7066 |
When logging to <application>syslog</application> and this is on (the |
| 7067 |
default), then each message will be prefixed by an increasing |
| 7068 |
sequence number (such as <literal>[2]</literal>). This circumvents |
| 7069 |
the <quote>--- last message repeated N times ---</quote> suppression |
| 7070 |
that many syslog implementations perform by default. In more modern |
| 7071 |
syslog implementations, repeated message suppression can be configured |
| 7072 |
(for example, <literal>$RepeatedMsgReduction</literal> |
| 7073 |
in <productname>rsyslog</productname>), so this might not be |
| 7074 |
necessary. Also, you could turn this off if you actually want to |
| 7075 |
suppress repeated messages. |
| 7076 |
</para> |
| 7077 |
|
| 7078 |
<para> |
| 7079 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7080 |
file or on the server command line. |
| 7081 |
</para> |
| 7082 |
</listitem> |
| 7083 |
</varlistentry> |
| 7084 |
|
| 7085 |
<varlistentry id="guc-syslog-split-messages" xreflabel="syslog_split_messages"> |
| 7086 |
<term><varname>syslog_split_messages</varname> (<type>boolean</type>) |
| 7087 |
<indexterm> |
| 7088 |
<primary><varname>syslog_split_messages</varname> configuration parameter</primary> |
| 7089 |
</indexterm> |
| 7090 |
</term> |
| 7091 |
<listitem> |
| 7092 |
<para> |
| 7093 |
When logging to <application>syslog</application> is enabled, this parameter |
| 7094 |
determines how messages are delivered to syslog. When on (the |
| 7095 |
default), messages are split by lines, and long lines are split so |
| 7096 |
that they will fit into 1024 bytes, which is a typical size limit for |
| 7097 |
traditional syslog implementations. When off, PostgreSQL server log |
| 7098 |
messages are delivered to the syslog service as is, and it is up to |
| 7099 |
the syslog service to cope with the potentially bulky messages. |
| 7100 |
</para> |
| 7101 |
|
| 7102 |
<para> |
| 7103 |
If syslog is ultimately logging to a text file, then the effect will |
| 7104 |
be the same either way, and it is best to leave the setting on, since |
| 7105 |
most syslog implementations either cannot handle large messages or |
| 7106 |
would need to be specially configured to handle them. But if syslog |
| 7107 |
is ultimately writing into some other medium, it might be necessary or |
| 7108 |
more useful to keep messages logically together. |
| 7109 |
</para> |
| 7110 |
|
| 7111 |
<para> |
| 7112 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7113 |
file or on the server command line. |
| 7114 |
</para> |
| 7115 |
</listitem> |
| 7116 |
</varlistentry> |
| 7117 |
|
| 7118 |
<varlistentry id="guc-event-source" xreflabel="event_source"> |
| 7119 |
<term><varname>event_source</varname> (<type>string</type>) |
| 7120 |
<indexterm> |
| 7121 |
<primary><varname>event_source</varname> configuration parameter</primary> |
| 7122 |
</indexterm> |
| 7123 |
</term> |
| 7124 |
<listitem> |
| 7125 |
<para> |
| 7126 |
When logging to <application>event log</application> is enabled, this parameter |
| 7127 |
determines the program name used to identify |
| 7128 |
<productname>PostgreSQL</productname> messages in |
| 7129 |
the log. The default is <literal>PostgreSQL</literal>. |
| 7130 |
This parameter can only be set at server start. |
| 7131 |
</para> |
| 7132 |
</listitem> |
| 7133 |
</varlistentry> |
| 7134 |
|
| 7135 |
</variablelist> |
| 7136 |
</sect2> |
| 7137 |
<sect2 id="runtime-config-logging-when"> |
| 7138 |
<title>When to Log</title> |
| 7139 |
|
| 7140 |
<variablelist> |
| 7141 |
|
| 7142 |
<varlistentry id="guc-log-min-messages" xreflabel="log_min_messages"> |
| 7143 |
<term><varname>log_min_messages</varname> (<type>enum</type>) |
| 7144 |
<indexterm> |
| 7145 |
<primary><varname>log_min_messages</varname> configuration parameter</primary> |
| 7146 |
</indexterm> |
| 7147 |
</term> |
| 7148 |
<listitem> |
| 7149 |
<para> |
| 7150 |
Controls which <link linkend="runtime-config-severity-levels">message |
| 7151 |
levels</link> are written to the server log. |
| 7152 |
Valid values are <literal>DEBUG5</literal>, <literal>DEBUG4</literal>, |
| 7153 |
<literal>DEBUG3</literal>, <literal>DEBUG2</literal>, <literal>DEBUG1</literal>, |
| 7154 |
<literal>INFO</literal>, <literal>NOTICE</literal>, <literal>WARNING</literal>, |
| 7155 |
<literal>ERROR</literal>, <literal>LOG</literal>, <literal>FATAL</literal>, and |
| 7156 |
<literal>PANIC</literal>. Each level includes all the levels that |
| 7157 |
follow it. The later the level, the fewer messages are sent |
| 7158 |
to the log. The default is <literal>WARNING</literal>. Note that |
| 7159 |
<literal>LOG</literal> has a different rank here than in |
| 7160 |
<xref linkend="guc-client-min-messages"/>. |
| 7161 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7162 |
privilege can change this setting. |
| 7163 |
</para> |
| 7164 |
</listitem> |
| 7165 |
</varlistentry> |
| 7166 |
|
| 7167 |
<varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement"> |
| 7168 |
<term><varname>log_min_error_statement</varname> (<type>enum</type>) |
| 7169 |
<indexterm> |
| 7170 |
<primary><varname>log_min_error_statement</varname> configuration parameter</primary> |
| 7171 |
</indexterm> |
| 7172 |
</term> |
| 7173 |
<listitem> |
| 7174 |
<para> |
| 7175 |
Controls which SQL statements that cause an error |
| 7176 |
condition are recorded in the server log. The current |
| 7177 |
SQL statement is included in the log entry for any message of |
| 7178 |
the specified |
| 7179 |
<link linkend="runtime-config-severity-levels">severity</link> |
| 7180 |
or higher. |
| 7181 |
Valid values are <literal>DEBUG5</literal>, |
| 7182 |
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>, |
| 7183 |
<literal>DEBUG2</literal>, <literal>DEBUG1</literal>, |
| 7184 |
<literal>INFO</literal>, <literal>NOTICE</literal>, |
| 7185 |
<literal>WARNING</literal>, <literal>ERROR</literal>, |
| 7186 |
<literal>LOG</literal>, |
| 7187 |
<literal>FATAL</literal>, and <literal>PANIC</literal>. |
| 7188 |
The default is <literal>ERROR</literal>, which means statements |
| 7189 |
causing errors, log messages, fatal errors, or panics will be logged. |
| 7190 |
To effectively turn off logging of failing statements, |
| 7191 |
set this parameter to <literal>PANIC</literal>. |
| 7192 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7193 |
privilege can change this setting. |
| 7194 |
</para> |
| 7195 |
</listitem> |
| 7196 |
</varlistentry> |
| 7197 |
|
| 7198 |
<varlistentry id="guc-log-min-duration-statement" xreflabel="log_min_duration_statement"> |
| 7199 |
<term><varname>log_min_duration_statement</varname> (<type>integer</type>) |
| 7200 |
<indexterm> |
| 7201 |
<primary><varname>log_min_duration_statement</varname> configuration parameter</primary> |
| 7202 |
</indexterm> |
| 7203 |
</term> |
| 7204 |
<listitem> |
| 7205 |
<para> |
| 7206 |
Causes the duration of each completed statement to be logged |
| 7207 |
if the statement ran for at least the specified amount of time. |
| 7208 |
For example, if you set it to <literal>250ms</literal> |
| 7209 |
then all SQL statements that run 250ms or longer will be |
| 7210 |
logged. Enabling this parameter can be helpful in tracking down |
| 7211 |
unoptimized queries in your applications. |
| 7212 |
If this value is specified without units, it is taken as milliseconds. |
| 7213 |
Setting this to zero prints all statement durations. |
| 7214 |
<literal>-1</literal> (the default) disables logging statement |
| 7215 |
durations. |
| 7216 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7217 |
privilege can change this setting. |
| 7218 |
</para> |
| 7219 |
|
| 7220 |
<para> |
| 7221 |
This overrides <xref linkend="guc-log-min-duration-sample"/>, |
| 7222 |
meaning that queries with duration exceeding this setting are not |
| 7223 |
subject to sampling and are always logged. |
| 7224 |
</para> |
| 7225 |
|
| 7226 |
<para> |
| 7227 |
For clients using extended query protocol, durations of the Parse, |
| 7228 |
Bind, and Execute steps are logged independently. |
| 7229 |
</para> |
| 7230 |
|
| 7231 |
<note> |
| 7232 |
<para> |
| 7233 |
When using this option together with |
| 7234 |
<xref linkend="guc-log-statement"/>, |
| 7235 |
the text of statements that are logged because of |
| 7236 |
<varname>log_statement</varname> will not be repeated in the |
| 7237 |
duration log message. |
| 7238 |
If you are not using <application>syslog</application>, it is recommended |
| 7239 |
that you log the PID or session ID using |
| 7240 |
<xref linkend="guc-log-line-prefix"/> |
| 7241 |
so that you can link the statement message to the later |
| 7242 |
duration message using the process ID or session ID. |
| 7243 |
</para> |
| 7244 |
</note> |
| 7245 |
</listitem> |
| 7246 |
</varlistentry> |
| 7247 |
|
| 7248 |
<varlistentry id="guc-log-min-duration-sample" xreflabel="log_min_duration_sample"> |
| 7249 |
<term><varname>log_min_duration_sample</varname> (<type>integer</type>) |
| 7250 |
<indexterm> |
| 7251 |
<primary><varname>log_min_duration_sample</varname> configuration parameter</primary> |
| 7252 |
</indexterm> |
| 7253 |
</term> |
| 7254 |
<listitem> |
| 7255 |
<para> |
| 7256 |
Allows sampling the duration of completed statements that ran for |
| 7257 |
at least the specified amount of time. This produces the same |
| 7258 |
kind of log entries as |
| 7259 |
<xref linkend="guc-log-min-duration-statement"/>, but only for a |
| 7260 |
subset of the executed statements, with sample rate controlled by |
| 7261 |
<xref linkend="guc-log-statement-sample-rate"/>. |
| 7262 |
For example, if you set it to <literal>100ms</literal> then all |
| 7263 |
SQL statements that run 100ms or longer will be considered for |
| 7264 |
sampling. Enabling this parameter can be helpful when the |
| 7265 |
traffic is too high to log all queries. |
| 7266 |
If this value is specified without units, it is taken as milliseconds. |
| 7267 |
Setting this to zero samples all statement durations. |
| 7268 |
<literal>-1</literal> (the default) disables sampling statement |
| 7269 |
durations. |
| 7270 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7271 |
privilege can change this setting. |
| 7272 |
</para> |
| 7273 |
|
| 7274 |
<para> |
| 7275 |
This setting has lower priority |
| 7276 |
than <varname>log_min_duration_statement</varname>, meaning that |
| 7277 |
statements with durations |
| 7278 |
exceeding <varname>log_min_duration_statement</varname> are not |
| 7279 |
subject to sampling and are always logged. |
| 7280 |
</para> |
| 7281 |
|
| 7282 |
<para> |
| 7283 |
Other notes for <varname>log_min_duration_statement</varname> |
| 7284 |
apply also to this setting. |
| 7285 |
</para> |
| 7286 |
</listitem> |
| 7287 |
</varlistentry> |
| 7288 |
|
| 7289 |
<varlistentry id="guc-log-statement-sample-rate" xreflabel="log_statement_sample_rate"> |
| 7290 |
<term><varname>log_statement_sample_rate</varname> (<type>floating point</type>) |
| 7291 |
<indexterm> |
| 7292 |
<primary><varname>log_statement_sample_rate</varname> configuration parameter</primary> |
| 7293 |
</indexterm> |
| 7294 |
</term> |
| 7295 |
<listitem> |
| 7296 |
<para> |
| 7297 |
Determines the fraction of statements with duration exceeding |
| 7298 |
<xref linkend="guc-log-min-duration-sample"/> that will be logged. |
| 7299 |
Sampling is stochastic, for example <literal>0.5</literal> means |
| 7300 |
there is statistically one chance in two that any given statement |
| 7301 |
will be logged. |
| 7302 |
The default is <literal>1.0</literal>, meaning to log all sampled |
| 7303 |
statements. |
| 7304 |
Setting this to zero disables sampled statement-duration logging, |
| 7305 |
the same as setting |
| 7306 |
<varname>log_min_duration_sample</varname> to |
| 7307 |
<literal>-1</literal>. |
| 7308 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7309 |
privilege can change this setting. |
| 7310 |
</para> |
| 7311 |
</listitem> |
| 7312 |
</varlistentry> |
| 7313 |
|
| 7314 |
<varlistentry id="guc-log-transaction-sample-rate" xreflabel="log_transaction_sample_rate"> |
| 7315 |
<term><varname>log_transaction_sample_rate</varname> (<type>floating point</type>) |
| 7316 |
<indexterm> |
| 7317 |
<primary><varname>log_transaction_sample_rate</varname> configuration parameter</primary> |
| 7318 |
</indexterm> |
| 7319 |
</term> |
| 7320 |
<listitem> |
| 7321 |
<para> |
| 7322 |
Sets the fraction of transactions whose statements are all logged, |
| 7323 |
in addition to statements logged for other reasons. It applies to |
| 7324 |
each new transaction regardless of its statements' durations. |
| 7325 |
Sampling is stochastic, for example <literal>0.1</literal> means |
| 7326 |
there is statistically one chance in ten that any given transaction |
| 7327 |
will be logged. |
| 7328 |
<varname>log_transaction_sample_rate</varname> can be helpful to |
| 7329 |
construct a sample of transactions. |
| 7330 |
The default is <literal>0</literal>, meaning not to log |
| 7331 |
statements from any additional transactions. Setting this |
| 7332 |
to <literal>1</literal> logs all statements of all transactions. |
| 7333 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7334 |
privilege can change this setting. |
| 7335 |
</para> |
| 7336 |
<note> |
| 7337 |
<para> |
| 7338 |
Like all statement-logging options, this option can add significant |
| 7339 |
overhead. |
| 7340 |
</para> |
| 7341 |
</note> |
| 7342 |
</listitem> |
| 7343 |
</varlistentry> |
| 7344 |
|
| 7345 |
<varlistentry id="guc-log-startup-progress-interval" xreflabel="log_startup_progress_interval"> |
| 7346 |
<term><varname>log_startup_progress_interval</varname> (<type>integer</type>) |
| 7347 |
<indexterm> |
| 7348 |
<primary><varname>log_startup_progress_interval</varname> configuration parameter</primary> |
| 7349 |
</indexterm> |
| 7350 |
</term> |
| 7351 |
<listitem> |
| 7352 |
<para> |
| 7353 |
Sets the amount of time after which the startup process will log |
| 7354 |
a message about a long-running operation that is still in progress, |
| 7355 |
as well as the interval between further progress messages for that |
| 7356 |
operation. The default is 10 seconds. A setting of <literal>0</literal> |
| 7357 |
disables the feature. If this value is specified without units, |
| 7358 |
it is taken as milliseconds. This setting is applied separately to |
| 7359 |
each operation. |
| 7360 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7361 |
file or on the server command line. |
| 7362 |
</para> |
| 7363 |
|
| 7364 |
<para> |
| 7365 |
For example, if syncing the data directory takes 25 seconds and |
| 7366 |
thereafter resetting unlogged relations takes 8 seconds, and if this |
| 7367 |
setting has the default value of 10 seconds, then a messages will be |
| 7368 |
logged for syncing the data directory after it has been in progress |
| 7369 |
for 10 seconds and again after it has been in progress for 20 seconds, |
| 7370 |
but nothing will be logged for resetting unlogged relations. |
| 7371 |
</para> |
| 7372 |
</listitem> |
| 7373 |
</varlistentry> |
| 7374 |
|
| 7375 |
</variablelist> |
| 7376 |
|
| 7377 |
<para> |
| 7378 |
<xref linkend="runtime-config-severity-levels"/> explains the message |
| 7379 |
severity levels used by <productname>PostgreSQL</productname>. If logging output |
| 7380 |
is sent to <systemitem>syslog</systemitem> or Windows' |
| 7381 |
<systemitem>eventlog</systemitem>, the severity levels are translated |
| 7382 |
as shown in the table. |
| 7383 |
</para> |
| 7384 |
|
| 7385 |
<table id="runtime-config-severity-levels"> |
| 7386 |
<title>Message Severity Levels</title> |
| 7387 |
<tgroup cols="4"> |
| 7388 |
<colspec colname="col1" colwidth="1*"/> |
| 7389 |
<colspec colname="col2" colwidth="2*"/> |
| 7390 |
<colspec colname="col3" colwidth="1*"/> |
| 7391 |
<colspec colname="col4" colwidth="1*"/> |
| 7392 |
<thead> |
| 7393 |
<row> |
| 7394 |
<entry>Severity</entry> |
| 7395 |
<entry>Usage</entry> |
| 7396 |
<entry><systemitem>syslog</systemitem></entry> |
| 7397 |
<entry><systemitem>eventlog</systemitem></entry> |
| 7398 |
</row> |
| 7399 |
</thead> |
| 7400 |
|
| 7401 |
<tbody> |
| 7402 |
<row> |
| 7403 |
<entry><literal>DEBUG1 .. DEBUG5</literal></entry> |
| 7404 |
<entry>Provides successively-more-detailed information for use by |
| 7405 |
developers.</entry> |
| 7406 |
<entry><literal>DEBUG</literal></entry> |
| 7407 |
<entry><literal>INFORMATION</literal></entry> |
| 7408 |
</row> |
| 7409 |
|
| 7410 |
<row> |
| 7411 |
<entry><literal>INFO</literal></entry> |
| 7412 |
<entry>Provides information implicitly requested by the user, |
| 7413 |
e.g., output from <command>VACUUM VERBOSE</command>.</entry> |
| 7414 |
<entry><literal>INFO</literal></entry> |
| 7415 |
<entry><literal>INFORMATION</literal></entry> |
| 7416 |
</row> |
| 7417 |
|
| 7418 |
<row> |
| 7419 |
<entry><literal>NOTICE</literal></entry> |
| 7420 |
<entry>Provides information that might be helpful to users, e.g., |
| 7421 |
notice of truncation of long identifiers.</entry> |
| 7422 |
<entry><literal>NOTICE</literal></entry> |
| 7423 |
<entry><literal>INFORMATION</literal></entry> |
| 7424 |
</row> |
| 7425 |
|
| 7426 |
<row> |
| 7427 |
<entry><literal>WARNING</literal></entry> |
| 7428 |
<entry>Provides warnings of likely problems, e.g., <command>COMMIT</command> |
| 7429 |
outside a transaction block.</entry> |
| 7430 |
<entry><literal>NOTICE</literal></entry> |
| 7431 |
<entry><literal>WARNING</literal></entry> |
| 7432 |
</row> |
| 7433 |
|
| 7434 |
<row> |
| 7435 |
<entry><literal>ERROR</literal></entry> |
| 7436 |
<entry>Reports an error that caused the current command to |
| 7437 |
abort.</entry> |
| 7438 |
<entry><literal>WARNING</literal></entry> |
| 7439 |
<entry><literal>ERROR</literal></entry> |
| 7440 |
</row> |
| 7441 |
|
| 7442 |
<row> |
| 7443 |
<entry><literal>LOG</literal></entry> |
| 7444 |
<entry>Reports information of interest to administrators, e.g., |
| 7445 |
checkpoint activity.</entry> |
| 7446 |
<entry><literal>INFO</literal></entry> |
| 7447 |
<entry><literal>INFORMATION</literal></entry> |
| 7448 |
</row> |
| 7449 |
|
| 7450 |
<row> |
| 7451 |
<entry><literal>FATAL</literal></entry> |
| 7452 |
<entry>Reports an error that caused the current session to |
| 7453 |
abort.</entry> |
| 7454 |
<entry><literal>ERR</literal></entry> |
| 7455 |
<entry><literal>ERROR</literal></entry> |
| 7456 |
</row> |
| 7457 |
|
| 7458 |
<row> |
| 7459 |
<entry><literal>PANIC</literal></entry> |
| 7460 |
<entry>Reports an error that caused all database sessions to abort.</entry> |
| 7461 |
<entry><literal>CRIT</literal></entry> |
| 7462 |
<entry><literal>ERROR</literal></entry> |
| 7463 |
</row> |
| 7464 |
</tbody> |
| 7465 |
</tgroup> |
| 7466 |
</table> |
| 7467 |
|
| 7468 |
</sect2> |
| 7469 |
<sect2 id="runtime-config-logging-what"> |
| 7470 |
<title>What to Log</title> |
| 7471 |
|
| 7472 |
<note> |
| 7473 |
<para> |
| 7474 |
What you choose to log can have security implications; see |
| 7475 |
<xref linkend="logfile-maintenance"/>. |
| 7476 |
</para> |
| 7477 |
</note> |
| 7478 |
|
| 7479 |
<variablelist> |
| 7480 |
|
| 7481 |
<varlistentry id="guc-application-name" xreflabel="application_name"> |
| 7482 |
<term><varname>application_name</varname> (<type>string</type>) |
| 7483 |
<indexterm> |
| 7484 |
<primary><varname>application_name</varname> configuration parameter</primary> |
| 7485 |
</indexterm> |
| 7486 |
</term> |
| 7487 |
<listitem> |
| 7488 |
<para> |
| 7489 |
The <varname>application_name</varname> can be any string of less than |
| 7490 |
<symbol>NAMEDATALEN</symbol> characters (64 characters in a standard build). |
| 7491 |
It is typically set by an application upon connection to the server. |
| 7492 |
The name will be displayed in the <structname>pg_stat_activity</structname> view |
| 7493 |
and included in CSV log entries. It can also be included in regular |
| 7494 |
log entries via the <xref linkend="guc-log-line-prefix"/> parameter. |
| 7495 |
Only printable ASCII characters may be used in the |
| 7496 |
<varname>application_name</varname> value. |
| 7497 |
Other characters are replaced with <link |
| 7498 |
linkend="sql-syntax-strings-escape">C-style hexadecimal escapes</link>. |
| 7499 |
</para> |
| 7500 |
</listitem> |
| 7501 |
</varlistentry> |
| 7502 |
|
| 7503 |
<varlistentry id="guc-debug-print-parse"> |
| 7504 |
<term><varname>debug_print_parse</varname> (<type>boolean</type>) |
| 7505 |
<indexterm> |
| 7506 |
<primary><varname>debug_print_parse</varname> configuration parameter</primary> |
| 7507 |
</indexterm> |
| 7508 |
</term> |
| 7509 |
<term><varname>debug_print_rewritten</varname> (<type>boolean</type>) |
| 7510 |
<indexterm> |
| 7511 |
<primary><varname>debug_print_rewritten</varname> configuration parameter</primary> |
| 7512 |
</indexterm> |
| 7513 |
</term> |
| 7514 |
<term><varname>debug_print_plan</varname> (<type>boolean</type>) |
| 7515 |
<indexterm> |
| 7516 |
<primary><varname>debug_print_plan</varname> configuration parameter</primary> |
| 7517 |
</indexterm> |
| 7518 |
</term> |
| 7519 |
<listitem> |
| 7520 |
<para> |
| 7521 |
These parameters enable various debugging output to be emitted. |
| 7522 |
When set, they print the resulting parse tree, the query rewriter |
| 7523 |
output, or the execution plan for each executed query. |
| 7524 |
These messages are emitted at <literal>LOG</literal> message level, so by |
| 7525 |
default they will appear in the server log but will not be sent to the |
| 7526 |
client. You can change that by adjusting |
| 7527 |
<xref linkend="guc-client-min-messages"/> and/or |
| 7528 |
<xref linkend="guc-log-min-messages"/>. |
| 7529 |
These parameters are off by default. |
| 7530 |
</para> |
| 7531 |
</listitem> |
| 7532 |
</varlistentry> |
| 7533 |
|
| 7534 |
<varlistentry id="guc-debug-pretty-print"> |
| 7535 |
<term><varname>debug_pretty_print</varname> (<type>boolean</type>) |
| 7536 |
<indexterm> |
| 7537 |
<primary><varname>debug_pretty_print</varname> configuration parameter</primary> |
| 7538 |
</indexterm> |
| 7539 |
</term> |
| 7540 |
<listitem> |
| 7541 |
<para> |
| 7542 |
When set, <varname>debug_pretty_print</varname> indents the messages |
| 7543 |
produced by <varname>debug_print_parse</varname>, |
| 7544 |
<varname>debug_print_rewritten</varname>, or |
| 7545 |
<varname>debug_print_plan</varname>. This results in more readable |
| 7546 |
but much longer output than the <quote>compact</quote> format used when |
| 7547 |
it is off. It is on by default. |
| 7548 |
</para> |
| 7549 |
</listitem> |
| 7550 |
</varlistentry> |
| 7551 |
|
| 7552 |
<varlistentry id="guc-log-autovacuum-min-duration" xreflabel="log_autovacuum_min_duration"> |
| 7553 |
<term><varname>log_autovacuum_min_duration</varname> (<type>integer</type>) |
| 7554 |
<indexterm> |
| 7555 |
<primary><varname>log_autovacuum_min_duration</varname></primary> |
| 7556 |
<secondary>configuration parameter</secondary> |
| 7557 |
</indexterm> |
| 7558 |
</term> |
| 7559 |
<listitem> |
| 7560 |
<para> |
| 7561 |
Causes each action executed by autovacuum to be logged if it ran for at |
| 7562 |
least the specified amount of time. Setting this to zero logs |
| 7563 |
all autovacuum actions. <literal>-1</literal> disables logging autovacuum |
| 7564 |
actions. If this value is specified without units, it is taken as milliseconds. |
| 7565 |
For example, if you set this to |
| 7566 |
<literal>250ms</literal> then all automatic vacuums and analyzes that run |
| 7567 |
250ms or longer will be logged. In addition, when this parameter is |
| 7568 |
set to any value other than <literal>-1</literal>, a message will be |
| 7569 |
logged if an autovacuum action is skipped due to a conflicting lock or a |
| 7570 |
concurrently dropped relation. The default is <literal>10min</literal>. |
| 7571 |
Enabling this parameter can be helpful in tracking autovacuum activity. |
| 7572 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7573 |
file or on the server command line; but the setting can be overridden for |
| 7574 |
individual tables by changing table storage parameters. |
| 7575 |
</para> |
| 7576 |
</listitem> |
| 7577 |
</varlistentry> |
| 7578 |
|
| 7579 |
<varlistentry id="guc-log-checkpoints" xreflabel="log_checkpoints"> |
| 7580 |
<term><varname>log_checkpoints</varname> (<type>boolean</type>) |
| 7581 |
<indexterm> |
| 7582 |
<primary><varname>log_checkpoints</varname> configuration parameter</primary> |
| 7583 |
</indexterm> |
| 7584 |
</term> |
| 7585 |
<listitem> |
| 7586 |
<para> |
| 7587 |
Causes checkpoints and restartpoints to be logged in the server log. |
| 7588 |
Some statistics are included in the log messages, including the number |
| 7589 |
of buffers written and the time spent writing them. |
| 7590 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7591 |
file or on the server command line. The default is on. |
| 7592 |
</para> |
| 7593 |
</listitem> |
| 7594 |
</varlistentry> |
| 7595 |
|
| 7596 |
<varlistentry id="guc-log-connections" xreflabel="log_connections"> |
| 7597 |
<term><varname>log_connections</varname> (<type>string</type>) |
| 7598 |
<indexterm> |
| 7599 |
<primary><varname>log_connections</varname> configuration parameter</primary> |
| 7600 |
</indexterm> |
| 7601 |
</term> |
| 7602 |
<listitem> |
| 7603 |
<para> |
| 7604 |
Causes aspects of each connection to the server to be logged. |
| 7605 |
The default is the empty string, <literal>''</literal>, which |
| 7606 |
disables all connection logging. The following options may be |
| 7607 |
specified alone or in a comma-separated list: |
| 7608 |
</para> |
| 7609 |
|
| 7610 |
<table id="log-connections-options"> |
| 7611 |
<title>Log Connection Options</title> |
| 7612 |
<tgroup cols="2"> |
| 7613 |
<colspec colname="col1" colwidth="1*"/> |
| 7614 |
<colspec colname="col2" colwidth="2*"/> |
| 7615 |
<thead> |
| 7616 |
<row> |
| 7617 |
<entry>Name</entry> |
| 7618 |
<entry>Description</entry> |
| 7619 |
</row> |
| 7620 |
</thead> |
| 7621 |
<tbody> |
| 7622 |
<row> |
| 7623 |
<entry><literal>receipt</literal></entry> |
| 7624 |
<entry>Logs receipt of a connection.</entry> |
| 7625 |
</row> |
| 7626 |
|
| 7627 |
<row> |
| 7628 |
<entry><literal>authentication</literal></entry> |
| 7629 |
<entry> |
| 7630 |
Logs the original identity used by an authentication method |
| 7631 |
to identify a user. In most cases, the identity string |
| 7632 |
matches the <productname>PostgreSQL</productname> username, |
| 7633 |
but some third-party authentication methods may alter the |
| 7634 |
original user identifier before the server stores it. Failed |
| 7635 |
authentication is always logged regardless of the value of |
| 7636 |
this setting. |
| 7637 |
</entry> |
| 7638 |
</row> |
| 7639 |
|
| 7640 |
<row> |
| 7641 |
<entry><literal>authorization</literal></entry> |
| 7642 |
<entry> |
| 7643 |
Logs successful completion of authorization. At this point |
| 7644 |
the connection has been established but the backend is not |
| 7645 |
yet fully set up. The log message includes the authorized |
| 7646 |
username as well as the database name and application name, |
| 7647 |
if applicable. |
| 7648 |
</entry> |
| 7649 |
</row> |
| 7650 |
|
| 7651 |
<row> |
| 7652 |
<entry><literal>setup_durations</literal></entry> |
| 7653 |
<entry> |
| 7654 |
Logs the time spent establishing the connection and setting up the |
| 7655 |
backend until the connection is ready to execute its first |
| 7656 |
query. The log message includes three durations: the total |
| 7657 |
setup duration (starting from the postmaster accepting the |
| 7658 |
incoming connection and ending when the connection is ready |
| 7659 |
for query), the time it took to fork the new backend, and |
| 7660 |
the time it took to authenticate the user. |
| 7661 |
</entry> |
| 7662 |
</row> |
| 7663 |
|
| 7664 |
<row> |
| 7665 |
<entry><literal>all</literal></entry> |
| 7666 |
<entry> |
| 7667 |
A convenience alias equivalent to specifying all options. If |
| 7668 |
<literal>all</literal> is specified in a list of other |
| 7669 |
options, all connection aspects will be logged. |
| 7670 |
</entry> |
| 7671 |
</row> |
| 7672 |
|
| 7673 |
</tbody> |
| 7674 |
</tgroup> |
| 7675 |
</table> |
| 7676 |
|
| 7677 |
<para> |
| 7678 |
Disconnection logging is separately controlled by <xref |
| 7679 |
linkend="guc-log-disconnections"/>. |
| 7680 |
</para> |
| 7681 |
|
| 7682 |
<para> |
| 7683 |
For the purposes of backwards compatibility, <literal>on</literal>, |
| 7684 |
<literal>off</literal>, <literal>true</literal>, |
| 7685 |
<literal>false</literal>, <literal>yes</literal>, |
| 7686 |
<literal>no</literal>, <literal>1</literal>, and <literal>0</literal> |
| 7687 |
are still supported. The positive values are equivalent to specifying |
| 7688 |
the <literal>receipt</literal>, <literal>authentication</literal>, and |
| 7689 |
<literal>authorization</literal> options. |
| 7690 |
</para> |
| 7691 |
|
| 7692 |
<para> |
| 7693 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7694 |
privilege can change this parameter at session start, |
| 7695 |
and it cannot be changed at all within a session. |
| 7696 |
</para> |
| 7697 |
|
| 7698 |
<note> |
| 7699 |
<para> |
| 7700 |
Some client programs, like <application>psql</application>, attempt |
| 7701 |
to connect twice while determining if a password is required, so |
| 7702 |
duplicate <quote>connection received</quote> messages do not |
| 7703 |
necessarily indicate a problem. |
| 7704 |
</para> |
| 7705 |
</note> |
| 7706 |
</listitem> |
| 7707 |
</varlistentry> |
| 7708 |
|
| 7709 |
<varlistentry id="guc-log-disconnections" xreflabel="log_disconnections"> |
| 7710 |
<term><varname>log_disconnections</varname> (<type>boolean</type>) |
| 7711 |
<indexterm> |
| 7712 |
<primary><varname>log_disconnections</varname> configuration parameter</primary> |
| 7713 |
</indexterm> |
| 7714 |
</term> |
| 7715 |
<listitem> |
| 7716 |
<para> |
| 7717 |
Causes session terminations to be logged. The log output |
| 7718 |
provides information similar to <varname>log_connections</varname>, |
| 7719 |
plus the duration of the session. |
| 7720 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7721 |
privilege can change this parameter at session start, |
| 7722 |
and it cannot be changed at all within a session. |
| 7723 |
The default is <literal>off</literal>. |
| 7724 |
</para> |
| 7725 |
</listitem> |
| 7726 |
</varlistentry> |
| 7727 |
|
| 7728 |
|
| 7729 |
<varlistentry id="guc-log-duration" xreflabel="log_duration"> |
| 7730 |
<term><varname>log_duration</varname> (<type>boolean</type>) |
| 7731 |
<indexterm> |
| 7732 |
<primary><varname>log_duration</varname> configuration parameter</primary> |
| 7733 |
</indexterm> |
| 7734 |
</term> |
| 7735 |
<listitem> |
| 7736 |
<para> |
| 7737 |
Causes the duration of every completed statement to be logged. |
| 7738 |
The default is <literal>off</literal>. |
| 7739 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7740 |
privilege can change this setting. |
| 7741 |
</para> |
| 7742 |
|
| 7743 |
<para> |
| 7744 |
For clients using extended query protocol, durations of the Parse, |
| 7745 |
Bind, and Execute steps are logged independently. |
| 7746 |
</para> |
| 7747 |
|
| 7748 |
<note> |
| 7749 |
<para> |
| 7750 |
The difference between enabling <varname>log_duration</varname> and setting |
| 7751 |
<xref linkend="guc-log-min-duration-statement"/> to zero is that |
| 7752 |
exceeding <varname>log_min_duration_statement</varname> forces the text of |
| 7753 |
the query to be logged, but this option doesn't. Thus, if |
| 7754 |
<varname>log_duration</varname> is <literal>on</literal> and |
| 7755 |
<varname>log_min_duration_statement</varname> has a positive value, all |
| 7756 |
durations are logged but the query text is included only for |
| 7757 |
statements exceeding the threshold. This behavior can be useful for |
| 7758 |
gathering statistics in high-load installations. |
| 7759 |
</para> |
| 7760 |
</note> |
| 7761 |
</listitem> |
| 7762 |
</varlistentry> |
| 7763 |
|
| 7764 |
<varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity"> |
| 7765 |
<term><varname>log_error_verbosity</varname> (<type>enum</type>) |
| 7766 |
<indexterm> |
| 7767 |
<primary><varname>log_error_verbosity</varname> configuration parameter</primary> |
| 7768 |
</indexterm> |
| 7769 |
</term> |
| 7770 |
<listitem> |
| 7771 |
<para> |
| 7772 |
Controls the amount of detail written in the server log for each |
| 7773 |
message that is logged. Valid values are <literal>TERSE</literal>, |
| 7774 |
<literal>DEFAULT</literal>, and <literal>VERBOSE</literal>, each adding more |
| 7775 |
fields to displayed messages. <literal>TERSE</literal> excludes |
| 7776 |
the logging of <literal>DETAIL</literal>, <literal>HINT</literal>, |
| 7777 |
<literal>QUERY</literal>, and <literal>CONTEXT</literal> error information. |
| 7778 |
<literal>VERBOSE</literal> output includes the <symbol>SQLSTATE</symbol> error |
| 7779 |
code (see also <xref linkend="errcodes-appendix"/>) and the source code file name, function name, |
| 7780 |
and line number that generated the error. |
| 7781 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 7782 |
privilege can change this setting. |
| 7783 |
</para> |
| 7784 |
</listitem> |
| 7785 |
</varlistentry> |
| 7786 |
|
| 7787 |
<varlistentry id="guc-log-hostname" xreflabel="log_hostname"> |
| 7788 |
<term><varname>log_hostname</varname> (<type>boolean</type>) |
| 7789 |
<indexterm> |
| 7790 |
<primary><varname>log_hostname</varname> configuration parameter</primary> |
| 7791 |
</indexterm> |
| 7792 |
</term> |
| 7793 |
<listitem> |
| 7794 |
<para> |
| 7795 |
By default, connection log messages only show the IP address of the |
| 7796 |
connecting host. Turning this parameter on causes logging of the |
| 7797 |
host name as well. Note that depending on your host name resolution |
| 7798 |
setup this might impose a non-negligible performance penalty. |
| 7799 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7800 |
file or on the server command line. |
| 7801 |
</para> |
| 7802 |
</listitem> |
| 7803 |
</varlistentry> |
| 7804 |
|
| 7805 |
<varlistentry id="guc-log-line-prefix" xreflabel="log_line_prefix"> |
| 7806 |
<term><varname>log_line_prefix</varname> (<type>string</type>) |
| 7807 |
<indexterm> |
| 7808 |
<primary><varname>log_line_prefix</varname> configuration parameter</primary> |
| 7809 |
</indexterm> |
| 7810 |
</term> |
| 7811 |
<listitem> |
| 7812 |
<para> |
| 7813 |
This is a <function>printf</function>-style string that is output at the |
| 7814 |
beginning of each log line. |
| 7815 |
<literal>%</literal> characters begin <quote>escape sequences</quote> |
| 7816 |
that are replaced with status information as outlined below. |
| 7817 |
Unrecognized escapes are ignored. Other |
| 7818 |
characters are copied straight to the log line. Some escapes are |
| 7819 |
only recognized by session processes, and will be treated as empty by |
| 7820 |
background processes such as the main server process. Status |
| 7821 |
information may be aligned either left or right by specifying a |
| 7822 |
numeric literal after the % and before the option. A negative |
| 7823 |
value will cause the status information to be padded on the |
| 7824 |
right with spaces to give it a minimum width, whereas a positive |
| 7825 |
value will pad on the left. Padding can be useful to aid human |
| 7826 |
readability in log files. |
| 7827 |
</para> |
| 7828 |
|
| 7829 |
<para> |
| 7830 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 7831 |
file or on the server command line. The default is |
| 7832 |
<literal>'%m [%p] '</literal> which logs a time stamp and the process ID. |
| 7833 |
</para> |
| 7834 |
|
| 7835 |
<informaltable> |
| 7836 |
<tgroup cols="3"> |
| 7837 |
<thead> |
| 7838 |
<row> |
| 7839 |
<entry>Escape</entry> |
| 7840 |
<entry>Effect</entry> |
| 7841 |
<entry>Session only</entry> |
| 7842 |
</row> |
| 7843 |
</thead> |
| 7844 |
<tbody> |
| 7845 |
<row> |
| 7846 |
<entry><literal>%a</literal></entry> |
| 7847 |
<entry>Application name</entry> |
| 7848 |
<entry>yes</entry> |
| 7849 |
</row> |
| 7850 |
<row> |
| 7851 |
<entry><literal>%u</literal></entry> |
| 7852 |
<entry>User name</entry> |
| 7853 |
<entry>yes</entry> |
| 7854 |
</row> |
| 7855 |
<row> |
| 7856 |
<entry><literal>%d</literal></entry> |
| 7857 |
<entry>Database name</entry> |
| 7858 |
<entry>yes</entry> |
| 7859 |
</row> |
| 7860 |
<row> |
| 7861 |
<entry><literal>%r</literal></entry> |
| 7862 |
<entry>Remote host name or IP address, and remote port</entry> |
| 7863 |
<entry>yes</entry> |
| 7864 |
</row> |
| 7865 |
<row> |
| 7866 |
<entry><literal>%h</literal></entry> |
| 7867 |
<entry>Remote host name or IP address</entry> |
| 7868 |
<entry>yes</entry> |
| 7869 |
</row> |
| 7870 |
<row> |
| 7871 |
<entry><literal>%L</literal></entry> |
| 7872 |
<entry>Local address (the IP address on the server that the |
| 7873 |
client connected to)</entry> |
| 7874 |
<entry>yes</entry> |
| 7875 |
</row> |
| 7876 |
<row> |
| 7877 |
<entry><literal>%b</literal></entry> |
| 7878 |
<entry>Backend type</entry> |
| 7879 |
<entry>no</entry> |
| 7880 |
</row> |
| 7881 |
<row> |
| 7882 |
<entry><literal>%p</literal></entry> |
| 7883 |
<entry>Process ID</entry> |
| 7884 |
<entry>no</entry> |
| 7885 |
</row> |
| 7886 |
<row> |
| 7887 |
<entry><literal>%P</literal></entry> |
| 7888 |
<entry>Process ID of the parallel group leader, if this process |
| 7889 |
is a parallel query worker</entry> |
| 7890 |
<entry>no</entry> |
| 7891 |
</row> |
| 7892 |
<row> |
| 7893 |
<entry><literal>%t</literal></entry> |
| 7894 |
<entry>Time stamp without milliseconds</entry> |
| 7895 |
<entry>no</entry> |
| 7896 |
</row> |
| 7897 |
<row> |
| 7898 |
<entry><literal>%m</literal></entry> |
| 7899 |
<entry>Time stamp with milliseconds</entry> |
| 7900 |
<entry>no</entry> |
| 7901 |
</row> |
| 7902 |
<row> |
| 7903 |
<entry><literal>%n</literal></entry> |
| 7904 |
<entry>Time stamp with milliseconds (as a Unix epoch)</entry> |
| 7905 |
<entry>no</entry> |
| 7906 |
</row> |
| 7907 |
<row> |
| 7908 |
<entry><literal>%i</literal></entry> |
| 7909 |
<entry>Command tag: type of session's current command</entry> |
| 7910 |
<entry>yes</entry> |
| 7911 |
</row> |
| 7912 |
<row> |
| 7913 |
<entry><literal>%e</literal></entry> |
| 7914 |
<entry>SQLSTATE error code</entry> |
| 7915 |
<entry>no</entry> |
| 7916 |
</row> |
| 7917 |
<row> |
| 7918 |
<entry><literal>%c</literal></entry> |
| 7919 |
<entry>Session ID: see below</entry> |
| 7920 |
<entry>no</entry> |
| 7921 |
</row> |
| 7922 |
<row> |
| 7923 |
<entry><literal>%l</literal></entry> |
| 7924 |
<entry>Number of the log line for each session or process, starting at 1</entry> |
| 7925 |
<entry>no</entry> |
| 7926 |
</row> |
| 7927 |
<row> |
| 7928 |
<entry><literal>%s</literal></entry> |
| 7929 |
<entry>Process start time stamp</entry> |
| 7930 |
<entry>no</entry> |
| 7931 |
</row> |
| 7932 |
<row> |
| 7933 |
<entry><literal>%v</literal></entry> |
| 7934 |
<entry>Virtual transaction ID (procNumber/localXID); see |
| 7935 |
<xref linkend="transaction-id"/></entry> |
| 7936 |
<entry>no</entry> |
| 7937 |
</row> |
| 7938 |
<row> |
| 7939 |
<entry><literal>%x</literal></entry> |
| 7940 |
<entry>Transaction ID (0 if none is assigned); see |
| 7941 |
<xref linkend="transaction-id"/></entry> |
| 7942 |
<entry>no</entry> |
| 7943 |
</row> |
| 7944 |
<row> |
| 7945 |
<entry><literal>%q</literal></entry> |
| 7946 |
<entry>Produces no output, but tells non-session |
| 7947 |
processes to stop at this point in the string; ignored by |
| 7948 |
session processes</entry> |
| 7949 |
<entry>no</entry> |
| 7950 |
</row> |
| 7951 |
<row> |
| 7952 |
<entry><literal>%Q</literal></entry> |
| 7953 |
<entry>Query identifier of the current query. Query |
| 7954 |
identifiers are not computed by default, so this field |
| 7955 |
will be zero unless <xref linkend="guc-compute-query-id"/> |
| 7956 |
parameter is enabled or a third-party module that computes |
| 7957 |
query identifiers is configured.</entry> |
| 7958 |
<entry>yes</entry> |
| 7959 |
</row> |
| 7960 |
<row> |
| 7961 |
<entry><literal>%%</literal></entry> |
| 7962 |
<entry>Literal <literal>%</literal></entry> |
| 7963 |
<entry>no</entry> |
| 7964 |
</row> |
| 7965 |
</tbody> |
| 7966 |
</tgroup> |
| 7967 |
</informaltable> |
| 7968 |
|
| 7969 |
<para> |
| 7970 |
The backend type corresponds to the column |
| 7971 |
<structfield>backend_type</structfield> in the view |
| 7972 |
<link linkend="monitoring-pg-stat-activity-view"> |
| 7973 |
<structname>pg_stat_activity</structname></link>, |
| 7974 |
but additional types can appear |
| 7975 |
in the log that don't show in that view. |
| 7976 |
</para> |
| 7977 |
|
| 7978 |
<para> |
| 7979 |
The <literal>%c</literal> escape prints a quasi-unique session identifier, |
| 7980 |
consisting of two 4-byte hexadecimal numbers (without leading zeros) |
| 7981 |
separated by a dot. The numbers are the process start time and the |
| 7982 |
process ID, so <literal>%c</literal> can also be used as a space saving way |
| 7983 |
of printing those items. For example, to generate the session |
| 7984 |
identifier from <literal>pg_stat_activity</literal>, use this query: |
| 7985 |
<programlisting> |
| 7986 |
SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || |
| 7987 |
to_hex(pid) |
| 7988 |
FROM pg_stat_activity; |
| 7989 |
</programlisting> |
| 7990 |
|
| 7991 |
</para> |
| 7992 |
|
| 7993 |
<tip> |
| 7994 |
<para> |
| 7995 |
If you set a nonempty value for <varname>log_line_prefix</varname>, |
| 7996 |
you should usually make its last character be a space, to provide |
| 7997 |
visual separation from the rest of the log line. A punctuation |
| 7998 |
character can be used too. |
| 7999 |
</para> |
| 8000 |
</tip> |
| 8001 |
|
| 8002 |
<tip> |
| 8003 |
<para> |
| 8004 |
<application>Syslog</application> produces its own |
| 8005 |
time stamp and process ID information, so you probably do not want to |
| 8006 |
include those escapes if you are logging to <application>syslog</application>. |
| 8007 |
</para> |
| 8008 |
</tip> |
| 8009 |
|
| 8010 |
<tip> |
| 8011 |
<para> |
| 8012 |
The <literal>%q</literal> escape is useful when including information that is |
| 8013 |
only available in session (backend) context like user or database |
| 8014 |
name. For example: |
| 8015 |
<programlisting> |
| 8016 |
log_line_prefix = '%m [%p] %q%u@%d/%a ' |
| 8017 |
</programlisting> |
| 8018 |
</para> |
| 8019 |
</tip> |
| 8020 |
|
| 8021 |
<note> |
| 8022 |
<para> |
| 8023 |
The <literal>%Q</literal> escape always reports a zero identifier |
| 8024 |
for lines output by <xref linkend="guc-log-statement"/> because |
| 8025 |
<varname>log_statement</varname> generates output before an |
| 8026 |
identifier can be calculated, including invalid statements for |
| 8027 |
which an identifier cannot be calculated. |
| 8028 |
</para> |
| 8029 |
</note> |
| 8030 |
</listitem> |
| 8031 |
</varlistentry> |
| 8032 |
|
| 8033 |
<varlistentry id="guc-log-lock-waits" xreflabel="log_lock_waits"> |
| 8034 |
<term><varname>log_lock_waits</varname> (<type>boolean</type>) |
| 8035 |
<indexterm> |
| 8036 |
<primary><varname>log_lock_waits</varname> configuration parameter</primary> |
| 8037 |
</indexterm> |
| 8038 |
</term> |
| 8039 |
<listitem> |
| 8040 |
<para> |
| 8041 |
Controls whether a log message is produced when a session waits |
| 8042 |
longer than <xref linkend="guc-deadlock-timeout"/> to acquire a |
| 8043 |
lock. This is useful in determining if lock waits are causing |
| 8044 |
poor performance. The default is <literal>off</literal>. |
| 8045 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8046 |
privilege can change this setting. |
| 8047 |
</para> |
| 8048 |
</listitem> |
| 8049 |
</varlistentry> |
| 8050 |
|
| 8051 |
<varlistentry id="guc-log-lock-failures" xreflabel="log_lock_failures"> |
| 8052 |
<term><varname>log_lock_failures</varname> (<type>boolean</type>) |
| 8053 |
<indexterm> |
| 8054 |
<primary><varname>log_lock_failures</varname> configuration parameter</primary> |
| 8055 |
</indexterm> |
| 8056 |
</term> |
| 8057 |
<listitem> |
| 8058 |
<para> |
| 8059 |
Controls whether a detailed log message is produced |
| 8060 |
when a lock acquisition fails. This is useful for analyzing |
| 8061 |
the causes of lock failures. Currently, only lock failures |
| 8062 |
due to <literal>SELECT NOWAIT</literal> is supported. |
| 8063 |
The default is <literal>off</literal>. Only superusers and |
| 8064 |
users with the appropriate <literal>SET</literal> privilege |
| 8065 |
can change this setting. |
| 8066 |
</para> |
| 8067 |
</listitem> |
| 8068 |
</varlistentry> |
| 8069 |
|
| 8070 |
|
| 8071 |
<varlistentry id="guc-log-recovery-conflict-waits" xreflabel="log_recovery_conflict_waits"> |
| 8072 |
<term><varname>log_recovery_conflict_waits</varname> (<type>boolean</type>) |
| 8073 |
<indexterm> |
| 8074 |
<primary><varname>log_recovery_conflict_waits</varname> configuration parameter</primary> |
| 8075 |
</indexterm> |
| 8076 |
</term> |
| 8077 |
<listitem> |
| 8078 |
<para> |
| 8079 |
Controls whether a log message is produced when the startup process |
| 8080 |
waits longer than <varname>deadlock_timeout</varname> |
| 8081 |
for recovery conflicts. This is useful in determining if recovery |
| 8082 |
conflicts prevent the recovery from applying WAL. |
| 8083 |
</para> |
| 8084 |
|
| 8085 |
<para> |
| 8086 |
The default is <literal>off</literal>. This parameter can only be set |
| 8087 |
in the <filename>postgresql.conf</filename> file or on the server |
| 8088 |
command line. |
| 8089 |
</para> |
| 8090 |
</listitem> |
| 8091 |
</varlistentry> |
| 8092 |
|
| 8093 |
<varlistentry id="guc-log-parameter-max-length" xreflabel="log_parameter_max_length"> |
| 8094 |
<term><varname>log_parameter_max_length</varname> (<type>integer</type>) |
| 8095 |
<indexterm> |
| 8096 |
<primary><varname>log_parameter_max_length</varname> configuration parameter</primary> |
| 8097 |
</indexterm> |
| 8098 |
</term> |
| 8099 |
<listitem> |
| 8100 |
<para> |
| 8101 |
If greater than zero, each bind parameter value logged with a |
| 8102 |
non-error statement-logging message is trimmed to this many bytes. |
| 8103 |
Zero disables logging of bind parameters for non-error statement logs. |
| 8104 |
<literal>-1</literal> (the default) allows bind parameters to be |
| 8105 |
logged in full. |
| 8106 |
If this value is specified without units, it is taken as bytes. |
| 8107 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8108 |
privilege can change this setting. |
| 8109 |
</para> |
| 8110 |
|
| 8111 |
<para> |
| 8112 |
This setting only affects log messages printed as a result of |
| 8113 |
<xref linkend="guc-log-statement"/>, |
| 8114 |
<xref linkend="guc-log-min-duration-statement"/>, and related settings. |
| 8115 |
Non-zero values of this setting add some overhead, particularly |
| 8116 |
if parameters are sent in binary form, since then conversion to |
| 8117 |
text is required. |
| 8118 |
</para> |
| 8119 |
</listitem> |
| 8120 |
</varlistentry> |
| 8121 |
|
| 8122 |
<varlistentry id="guc-log-parameter-max-length-on-error" xreflabel="log_parameter_max_length_on_error"> |
| 8123 |
<term><varname>log_parameter_max_length_on_error</varname> (<type>integer</type>) |
| 8124 |
<indexterm> |
| 8125 |
<primary><varname>log_parameter_max_length_on_error</varname> configuration parameter</primary> |
| 8126 |
</indexterm> |
| 8127 |
</term> |
| 8128 |
<listitem> |
| 8129 |
<para> |
| 8130 |
If greater than zero, each bind parameter value reported in error |
| 8131 |
messages is trimmed to this many bytes. |
| 8132 |
Zero (the default) disables including bind parameters in error |
| 8133 |
messages. |
| 8134 |
<literal>-1</literal> allows bind parameters to be printed in full. |
| 8135 |
If this value is specified without units, it is taken as bytes. |
| 8136 |
</para> |
| 8137 |
|
| 8138 |
<para> |
| 8139 |
Non-zero values of this setting add overhead, as |
| 8140 |
<productname>PostgreSQL</productname> will need to store textual |
| 8141 |
representations of parameter values in memory at the start of each |
| 8142 |
statement, whether or not an error eventually occurs. The overhead |
| 8143 |
is greater when bind parameters are sent in binary form than when |
| 8144 |
they are sent as text, since the former case requires data |
| 8145 |
conversion while the latter only requires copying the string. |
| 8146 |
</para> |
| 8147 |
</listitem> |
| 8148 |
</varlistentry> |
| 8149 |
|
| 8150 |
<varlistentry id="guc-log-statement" xreflabel="log_statement"> |
| 8151 |
<term><varname>log_statement</varname> (<type>enum</type>) |
| 8152 |
<indexterm> |
| 8153 |
<primary><varname>log_statement</varname> configuration parameter</primary> |
| 8154 |
</indexterm> |
| 8155 |
</term> |
| 8156 |
<listitem> |
| 8157 |
<para> |
| 8158 |
Controls which SQL statements are logged. Valid values are |
| 8159 |
<literal>none</literal> (off), <literal>ddl</literal>, <literal>mod</literal>, and |
| 8160 |
<literal>all</literal> (all statements). <literal>ddl</literal> logs all data definition |
| 8161 |
statements, such as <command>CREATE</command>, <command>ALTER</command>, and |
| 8162 |
<command>DROP</command> statements. <literal>mod</literal> logs all |
| 8163 |
<literal>ddl</literal> statements, plus data-modifying statements |
| 8164 |
such as <command>INSERT</command>, |
| 8165 |
<command>UPDATE</command>, <command>DELETE</command>, <command>TRUNCATE</command>, |
| 8166 |
and <command>COPY FROM</command>. |
| 8167 |
<command>PREPARE</command>, <command>EXECUTE</command>, and |
| 8168 |
<command>EXPLAIN ANALYZE</command> statements are also logged if their |
| 8169 |
contained command is of an appropriate type. For clients using |
| 8170 |
extended query protocol, logging occurs when an Execute message |
| 8171 |
is received, and values of the Bind parameters are included |
| 8172 |
(with any embedded single-quote marks doubled). |
| 8173 |
</para> |
| 8174 |
|
| 8175 |
<para> |
| 8176 |
The default is <literal>none</literal>. |
| 8177 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8178 |
privilege can change this setting. |
| 8179 |
</para> |
| 8180 |
|
| 8181 |
<note> |
| 8182 |
<para> |
| 8183 |
Statements that contain simple syntax errors are not logged |
| 8184 |
even by the <varname>log_statement</varname> = <literal>all</literal> setting, |
| 8185 |
because the log message is emitted only after basic parsing has |
| 8186 |
been done to determine the statement type. In the case of extended |
| 8187 |
query protocol, this setting likewise does not log statements that |
| 8188 |
fail before the Execute phase (i.e., during parse analysis or |
| 8189 |
planning). Set <varname>log_min_error_statement</varname> to |
| 8190 |
<literal>ERROR</literal> (or lower) to log such statements. |
| 8191 |
</para> |
| 8192 |
<para> |
| 8193 |
Logged statements might reveal sensitive data and even contain |
| 8194 |
plaintext passwords. |
| 8195 |
</para> |
| 8196 |
</note> |
| 8197 |
</listitem> |
| 8198 |
</varlistentry> |
| 8199 |
|
| 8200 |
<varlistentry id="guc-log-replication-commands" xreflabel="log_replication_commands"> |
| 8201 |
<term><varname>log_replication_commands</varname> (<type>boolean</type>) |
| 8202 |
<indexterm> |
| 8203 |
<primary><varname>log_replication_commands</varname> configuration parameter</primary> |
| 8204 |
</indexterm> |
| 8205 |
</term> |
| 8206 |
<listitem> |
| 8207 |
<para> |
| 8208 |
Causes each replication command and <literal>walsender</literal> |
| 8209 |
process's replication slot acquisition/release to be logged in the |
| 8210 |
server log. See <xref linkend="protocol-replication"/> for more |
| 8211 |
information about replication command. The default value is |
| 8212 |
<literal>off</literal>. Only superusers and users with the appropriate |
| 8213 |
<literal>SET</literal> privilege can change this setting. |
| 8214 |
</para> |
| 8215 |
</listitem> |
| 8216 |
</varlistentry> |
| 8217 |
|
| 8218 |
<varlistentry id="guc-log-temp-files" xreflabel="log_temp_files"> |
| 8219 |
<term><varname>log_temp_files</varname> (<type>integer</type>) |
| 8220 |
<indexterm> |
| 8221 |
<primary><varname>log_temp_files</varname> configuration parameter</primary> |
| 8222 |
</indexterm> |
| 8223 |
</term> |
| 8224 |
<listitem> |
| 8225 |
<para> |
| 8226 |
Controls logging of temporary file names and sizes. |
| 8227 |
Temporary files can be |
| 8228 |
created for sorts, hashes, and temporary query results. |
| 8229 |
If enabled by this setting, a log entry is emitted for each |
| 8230 |
temporary file, with the file size specified in bytes, when it is deleted. |
| 8231 |
A value of zero logs all temporary file information, while positive |
| 8232 |
values log only files whose size is greater than or equal to |
| 8233 |
the specified amount of data. |
| 8234 |
If this value is specified without units, it is taken as kilobytes. |
| 8235 |
The default setting is -1, which disables such logging. |
| 8236 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8237 |
privilege can change this setting. |
| 8238 |
</para> |
| 8239 |
</listitem> |
| 8240 |
</varlistentry> |
| 8241 |
|
| 8242 |
<varlistentry id="guc-log-timezone" xreflabel="log_timezone"> |
| 8243 |
<term><varname>log_timezone</varname> (<type>string</type>) |
| 8244 |
<indexterm> |
| 8245 |
<primary><varname>log_timezone</varname> configuration parameter</primary> |
| 8246 |
</indexterm> |
| 8247 |
</term> |
| 8248 |
<listitem> |
| 8249 |
<para> |
| 8250 |
Sets the time zone used for timestamps written in the server log. |
| 8251 |
Unlike <xref linkend="guc-timezone"/>, this value is cluster-wide, |
| 8252 |
so that all sessions will report timestamps consistently. |
| 8253 |
The built-in default is <literal>GMT</literal>, but that is typically |
| 8254 |
overridden in <filename>postgresql.conf</filename>; <application>initdb</application> |
| 8255 |
will install a setting there corresponding to its system environment. |
| 8256 |
See <xref linkend="datatype-timezones"/> for more information. |
| 8257 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 8258 |
file or on the server command line. |
| 8259 |
</para> |
| 8260 |
</listitem> |
| 8261 |
</varlistentry> |
| 8262 |
|
| 8263 |
</variablelist> |
| 8264 |
</sect2> |
| 8265 |
<sect2 id="runtime-config-logging-csvlog"> |
| 8266 |
<title>Using CSV-Format Log Output</title> |
| 8267 |
|
| 8268 |
<para> |
| 8269 |
Including <literal>csvlog</literal> in the <varname>log_destination</varname> list |
| 8270 |
provides a convenient way to import log files into a database table. |
| 8271 |
This option emits log lines in comma-separated-values |
| 8272 |
(<acronym>CSV</acronym>) format, |
| 8273 |
with these columns: |
| 8274 |
time stamp with milliseconds, |
| 8275 |
user name, |
| 8276 |
database name, |
| 8277 |
process ID, |
| 8278 |
client host:port number, |
| 8279 |
session ID, |
| 8280 |
per-session line number, |
| 8281 |
command tag, |
| 8282 |
session start time, |
| 8283 |
virtual transaction ID, |
| 8284 |
regular transaction ID, |
| 8285 |
error severity, |
| 8286 |
SQLSTATE code, |
| 8287 |
error message, |
| 8288 |
error message detail, |
| 8289 |
hint, |
| 8290 |
internal query that led to the error (if any), |
| 8291 |
character count of the error position therein, |
| 8292 |
error context, |
| 8293 |
user query that led to the error (if any and enabled by |
| 8294 |
<varname>log_min_error_statement</varname>), |
| 8295 |
character count of the error position therein, |
| 8296 |
location of the error in the PostgreSQL source code |
| 8297 |
(if <varname>log_error_verbosity</varname> is set to <literal>verbose</literal>), |
| 8298 |
application name, backend type, process ID of parallel group leader, |
| 8299 |
and query id. |
| 8300 |
Here is a sample table definition for storing CSV-format log output: |
| 8301 |
|
| 8302 |
<programlisting> |
| 8303 |
CREATE TABLE postgres_log |
| 8304 |
( |
| 8305 |
log_time timestamp(3) with time zone, |
| 8306 |
user_name text, |
| 8307 |
database_name text, |
| 8308 |
process_id integer, |
| 8309 |
connection_from text, |
| 8310 |
session_id text, |
| 8311 |
session_line_num bigint, |
| 8312 |
command_tag text, |
| 8313 |
session_start_time timestamp with time zone, |
| 8314 |
virtual_transaction_id text, |
| 8315 |
transaction_id bigint, |
| 8316 |
error_severity text, |
| 8317 |
sql_state_code text, |
| 8318 |
message text, |
| 8319 |
detail text, |
| 8320 |
hint text, |
| 8321 |
internal_query text, |
| 8322 |
internal_query_pos integer, |
| 8323 |
context text, |
| 8324 |
query text, |
| 8325 |
query_pos integer, |
| 8326 |
location text, |
| 8327 |
application_name text, |
| 8328 |
backend_type text, |
| 8329 |
leader_pid integer, |
| 8330 |
query_id bigint, |
| 8331 |
PRIMARY KEY (session_id, session_line_num) |
| 8332 |
); |
| 8333 |
</programlisting> |
| 8334 |
</para> |
| 8335 |
|
| 8336 |
<para> |
| 8337 |
To import a log file into this table, use the <command>COPY FROM</command> |
| 8338 |
command: |
| 8339 |
|
| 8340 |
<programlisting> |
| 8341 |
COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; |
| 8342 |
</programlisting> |
| 8343 |
It is also possible to access the file as a foreign table, using |
| 8344 |
the supplied <xref linkend="file-fdw"/> module. |
| 8345 |
</para> |
| 8346 |
|
| 8347 |
<para> |
| 8348 |
There are a few things you need to do to simplify importing CSV log |
| 8349 |
files: |
| 8350 |
|
| 8351 |
<orderedlist> |
| 8352 |
<listitem> |
| 8353 |
<para> |
| 8354 |
Set <varname>log_filename</varname> and |
| 8355 |
<varname>log_rotation_age</varname> to provide a consistent, |
| 8356 |
predictable naming scheme for your log files. This lets you |
| 8357 |
predict what the file name will be and know when an individual log |
| 8358 |
file is complete and therefore ready to be imported. |
| 8359 |
</para> |
| 8360 |
</listitem> |
| 8361 |
|
| 8362 |
<listitem> |
| 8363 |
<para> |
| 8364 |
Set <varname>log_rotation_size</varname> to 0 to disable |
| 8365 |
size-based log rotation, as it makes the log file name difficult |
| 8366 |
to predict. |
| 8367 |
</para> |
| 8368 |
</listitem> |
| 8369 |
|
| 8370 |
<listitem> |
| 8371 |
<para> |
| 8372 |
Set <varname>log_truncate_on_rotation</varname> to <literal>on</literal> so |
| 8373 |
that old log data isn't mixed with the new in the same file. |
| 8374 |
</para> |
| 8375 |
</listitem> |
| 8376 |
|
| 8377 |
<listitem> |
| 8378 |
<para> |
| 8379 |
The table definition above includes a primary key specification. |
| 8380 |
This is useful to protect against accidentally importing the same |
| 8381 |
information twice. The <command>COPY</command> command commits all of the |
| 8382 |
data it imports at one time, so any error will cause the entire |
| 8383 |
import to fail. If you import a partial log file and later import |
| 8384 |
the file again when it is complete, the primary key violation will |
| 8385 |
cause the import to fail. Wait until the log is complete and |
| 8386 |
closed before importing. This procedure will also protect against |
| 8387 |
accidentally importing a partial line that hasn't been completely |
| 8388 |
written, which would also cause <command>COPY</command> to fail. |
| 8389 |
</para> |
| 8390 |
</listitem> |
| 8391 |
</orderedlist> |
| 8392 |
</para> |
| 8393 |
</sect2> |
| 8394 |
<sect2 id="runtime-config-logging-jsonlog"> |
| 8395 |
<title>Using JSON-Format Log Output</title> |
| 8396 |
|
| 8397 |
<para> |
| 8398 |
Including <literal>jsonlog</literal> in the |
| 8399 |
<varname>log_destination</varname> list provides a convenient way to |
| 8400 |
import log files into many different programs. This option emits log |
| 8401 |
lines in <acronym>JSON</acronym> format. |
| 8402 |
</para> |
| 8403 |
|
| 8404 |
<para> |
| 8405 |
String fields with null values are excluded from output. |
| 8406 |
Additional fields may be added in the future. User applications that |
| 8407 |
process <literal>jsonlog</literal> output should ignore unknown fields. |
| 8408 |
</para> |
| 8409 |
|
| 8410 |
<para> |
| 8411 |
Each log line is serialized as a JSON object with the set of keys and |
| 8412 |
their associated values shown in <xref |
| 8413 |
linkend="runtime-config-logging-jsonlog-keys-values"/>. |
| 8414 |
</para> |
| 8415 |
|
| 8416 |
<table id="runtime-config-logging-jsonlog-keys-values"> |
| 8417 |
<title>Keys and Values of JSON Log Entries</title> |
| 8418 |
<tgroup cols="3"> |
| 8419 |
<thead> |
| 8420 |
<row> |
| 8421 |
<entry>Key name</entry> |
| 8422 |
<entry>Type</entry> |
| 8423 |
<entry>Description</entry> |
| 8424 |
</row> |
| 8425 |
</thead> |
| 8426 |
<tbody> |
| 8427 |
<row> |
| 8428 |
<entry><literal>timestamp</literal></entry> |
| 8429 |
<entry>string</entry> |
| 8430 |
<entry>Time stamp with milliseconds</entry> |
| 8431 |
</row> |
| 8432 |
<row> |
| 8433 |
<entry><literal>user</literal></entry> |
| 8434 |
<entry>string</entry> |
| 8435 |
<entry>User name</entry> |
| 8436 |
</row> |
| 8437 |
<row> |
| 8438 |
<entry><literal>dbname</literal></entry> |
| 8439 |
<entry>string</entry> |
| 8440 |
<entry>Database name</entry> |
| 8441 |
</row> |
| 8442 |
<row> |
| 8443 |
<entry><literal>pid</literal></entry> |
| 8444 |
<entry>number</entry> |
| 8445 |
<entry>Process ID</entry> |
| 8446 |
</row> |
| 8447 |
<row> |
| 8448 |
<entry><literal>remote_host</literal></entry> |
| 8449 |
<entry>string</entry> |
| 8450 |
<entry>Client host</entry> |
| 8451 |
</row> |
| 8452 |
<row> |
| 8453 |
<entry><literal>remote_port</literal></entry> |
| 8454 |
<entry>number</entry> |
| 8455 |
<entry>Client port</entry> |
| 8456 |
</row> |
| 8457 |
<row> |
| 8458 |
<entry><literal>session_id</literal></entry> |
| 8459 |
<entry>string</entry> |
| 8460 |
<entry>Session ID</entry> |
| 8461 |
</row> |
| 8462 |
<row> |
| 8463 |
<entry><literal>line_num</literal></entry> |
| 8464 |
<entry>number</entry> |
| 8465 |
<entry>Per-session line number</entry> |
| 8466 |
</row> |
| 8467 |
<row> |
| 8468 |
<entry><literal>ps</literal></entry> |
| 8469 |
<entry>string</entry> |
| 8470 |
<entry>Current ps display</entry> |
| 8471 |
</row> |
| 8472 |
<row> |
| 8473 |
<entry><literal>session_start</literal></entry> |
| 8474 |
<entry>string</entry> |
| 8475 |
<entry>Session start time</entry> |
| 8476 |
</row> |
| 8477 |
<row> |
| 8478 |
<entry><literal>vxid</literal></entry> |
| 8479 |
<entry>string</entry> |
| 8480 |
<entry>Virtual transaction ID</entry> |
| 8481 |
</row> |
| 8482 |
<row> |
| 8483 |
<entry><literal>txid</literal></entry> |
| 8484 |
<entry>string</entry> |
| 8485 |
<entry>Regular transaction ID</entry> |
| 8486 |
</row> |
| 8487 |
<row> |
| 8488 |
<entry><literal>error_severity</literal></entry> |
| 8489 |
<entry>string</entry> |
| 8490 |
<entry>Error severity</entry> |
| 8491 |
</row> |
| 8492 |
<row> |
| 8493 |
<entry><literal>state_code</literal></entry> |
| 8494 |
<entry>string</entry> |
| 8495 |
<entry>SQLSTATE code</entry> |
| 8496 |
</row> |
| 8497 |
<row> |
| 8498 |
<entry><literal>message</literal></entry> |
| 8499 |
<entry>string</entry> |
| 8500 |
<entry>Error message</entry> |
| 8501 |
</row> |
| 8502 |
<row> |
| 8503 |
<entry><literal>detail</literal></entry> |
| 8504 |
<entry>string</entry> |
| 8505 |
<entry>Error message detail</entry> |
| 8506 |
</row> |
| 8507 |
<row> |
| 8508 |
<entry><literal>hint</literal></entry> |
| 8509 |
<entry>string</entry> |
| 8510 |
<entry>Error message hint</entry> |
| 8511 |
</row> |
| 8512 |
<row> |
| 8513 |
<entry><literal>internal_query</literal></entry> |
| 8514 |
<entry>string</entry> |
| 8515 |
<entry>Internal query that led to the error</entry> |
| 8516 |
</row> |
| 8517 |
<row> |
| 8518 |
<entry><literal>internal_position</literal></entry> |
| 8519 |
<entry>number</entry> |
| 8520 |
<entry>Cursor index into internal query</entry> |
| 8521 |
</row> |
| 8522 |
<row> |
| 8523 |
<entry><literal>context</literal></entry> |
| 8524 |
<entry>string</entry> |
| 8525 |
<entry>Error context</entry> |
| 8526 |
</row> |
| 8527 |
<row> |
| 8528 |
<entry><literal>statement</literal></entry> |
| 8529 |
<entry>string</entry> |
| 8530 |
<entry>Client-supplied query string</entry> |
| 8531 |
</row> |
| 8532 |
<row> |
| 8533 |
<entry><literal>cursor_position</literal></entry> |
| 8534 |
<entry>number</entry> |
| 8535 |
<entry>Cursor index into query string</entry> |
| 8536 |
</row> |
| 8537 |
<row> |
| 8538 |
<entry><literal>func_name</literal></entry> |
| 8539 |
<entry>string</entry> |
| 8540 |
<entry>Error location function name</entry> |
| 8541 |
</row> |
| 8542 |
<row> |
| 8543 |
<entry><literal>file_name</literal></entry> |
| 8544 |
<entry>string</entry> |
| 8545 |
<entry>File name of error location</entry> |
| 8546 |
</row> |
| 8547 |
<row> |
| 8548 |
<entry><literal>file_line_num</literal></entry> |
| 8549 |
<entry>number</entry> |
| 8550 |
<entry>File line number of the error location</entry> |
| 8551 |
</row> |
| 8552 |
<row> |
| 8553 |
<entry><literal>application_name</literal></entry> |
| 8554 |
<entry>string</entry> |
| 8555 |
<entry>Client application name</entry> |
| 8556 |
</row> |
| 8557 |
<row> |
| 8558 |
<entry><literal>backend_type</literal></entry> |
| 8559 |
<entry>string</entry> |
| 8560 |
<entry>Type of backend</entry> |
| 8561 |
</row> |
| 8562 |
<row> |
| 8563 |
<entry><literal>leader_pid</literal></entry> |
| 8564 |
<entry>number</entry> |
| 8565 |
<entry>Process ID of leader for active parallel workers</entry> |
| 8566 |
</row> |
| 8567 |
<row> |
| 8568 |
<entry><literal>query_id</literal></entry> |
| 8569 |
<entry>number</entry> |
| 8570 |
<entry>Query ID</entry> |
| 8571 |
</row> |
| 8572 |
</tbody> |
| 8573 |
</tgroup> |
| 8574 |
</table> |
| 8575 |
</sect2> |
| 8576 |
|
| 8577 |
<sect2 id="runtime-config-logging-proc-title"> |
| 8578 |
<title>Process Title</title> |
| 8579 |
|
| 8580 |
<para> |
| 8581 |
These settings control how process titles of server processes are |
| 8582 |
modified. Process titles are typically viewed using programs like |
| 8583 |
<application>ps</application> or, on Windows, <application>Process Explorer</application>. |
| 8584 |
See <xref linkend="monitoring-ps"/> for details. |
| 8585 |
</para> |
| 8586 |
|
| 8587 |
<variablelist> |
| 8588 |
<varlistentry id="guc-cluster-name" xreflabel="cluster_name"> |
| 8589 |
<term><varname>cluster_name</varname> (<type>string</type>) |
| 8590 |
<indexterm> |
| 8591 |
<primary><varname>cluster_name</varname> configuration parameter</primary> |
| 8592 |
</indexterm> |
| 8593 |
</term> |
| 8594 |
<listitem> |
| 8595 |
<para> |
| 8596 |
Sets a name that identifies this database cluster (instance) for |
| 8597 |
various purposes. The cluster name appears in the process title for |
| 8598 |
all server processes in this cluster. Moreover, it is the default |
| 8599 |
application name for a standby connection (see <xref |
| 8600 |
linkend="guc-synchronous-standby-names"/>). |
| 8601 |
</para> |
| 8602 |
|
| 8603 |
<para> |
| 8604 |
The name can be any string of less |
| 8605 |
than <symbol>NAMEDATALEN</symbol> characters (64 characters in a standard |
| 8606 |
build). Only printable ASCII characters may be used in the |
| 8607 |
<varname>cluster_name</varname> value. |
| 8608 |
Other characters are replaced with <link |
| 8609 |
linkend="sql-syntax-strings-escape">C-style hexadecimal escapes</link>. |
| 8610 |
No name is shown if this parameter is set to the empty string |
| 8611 |
<literal>''</literal> (which is the default). |
| 8612 |
This parameter can only be set at server start. |
| 8613 |
</para> |
| 8614 |
</listitem> |
| 8615 |
</varlistentry> |
| 8616 |
|
| 8617 |
<varlistentry id="guc-update-process-title" xreflabel="update_process_title"> |
| 8618 |
<term><varname>update_process_title</varname> (<type>boolean</type>) |
| 8619 |
<indexterm> |
| 8620 |
<primary><varname>update_process_title</varname> configuration parameter</primary> |
| 8621 |
</indexterm> |
| 8622 |
</term> |
| 8623 |
<listitem> |
| 8624 |
<para> |
| 8625 |
Enables updating of the process title every time a new SQL command |
| 8626 |
is received by the server. |
| 8627 |
This setting defaults to <literal>on</literal> on most platforms, but it |
| 8628 |
defaults to <literal>off</literal> on Windows due to that platform's larger |
| 8629 |
overhead for updating the process title. |
| 8630 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8631 |
privilege can change this setting. |
| 8632 |
</para> |
| 8633 |
</listitem> |
| 8634 |
</varlistentry> |
| 8635 |
</variablelist> |
| 8636 |
</sect2> |
| 8637 |
</sect1> |
| 8638 |
|
| 8639 |
<sect1 id="runtime-config-statistics"> |
| 8640 |
<title>Run-time Statistics</title> |
| 8641 |
|
| 8642 |
<sect2 id="runtime-config-cumulative-statistics"> |
| 8643 |
<title>Cumulative Query and Index Statistics</title> |
| 8644 |
|
| 8645 |
<para> |
| 8646 |
These parameters control the server-wide cumulative statistics system. |
| 8647 |
When enabled, the data that is collected can be accessed via the |
| 8648 |
<structname>pg_stat</structname> and <structname>pg_statio</structname> |
| 8649 |
family of system views. Refer to <xref linkend="monitoring"/> for more |
| 8650 |
information. |
| 8651 |
</para> |
| 8652 |
|
| 8653 |
<variablelist> |
| 8654 |
|
| 8655 |
<varlistentry id="guc-track-activities" xreflabel="track_activities"> |
| 8656 |
<term><varname>track_activities</varname> (<type>boolean</type>) |
| 8657 |
<indexterm> |
| 8658 |
<primary><varname>track_activities</varname> configuration parameter</primary> |
| 8659 |
</indexterm> |
| 8660 |
</term> |
| 8661 |
<listitem> |
| 8662 |
<para> |
| 8663 |
Enables the collection of information on the currently |
| 8664 |
executing command of each session, along with its identifier and the |
| 8665 |
time when that command began execution. This parameter is on by |
| 8666 |
default. Note that even when enabled, this information is only |
| 8667 |
visible to superusers, roles with privileges of the |
| 8668 |
<literal>pg_read_all_stats</literal> role and the user owning the |
| 8669 |
sessions being reported on (including sessions belonging to a role they |
| 8670 |
have the privileges of), so it should not represent a security risk. |
| 8671 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8672 |
privilege can change this setting. |
| 8673 |
</para> |
| 8674 |
</listitem> |
| 8675 |
</varlistentry> |
| 8676 |
|
| 8677 |
<varlistentry id="guc-track-activity-query-size" xreflabel="track_activity_query_size"> |
| 8678 |
<term><varname>track_activity_query_size</varname> (<type>integer</type>) |
| 8679 |
<indexterm> |
| 8680 |
<primary><varname>track_activity_query_size</varname> configuration parameter</primary> |
| 8681 |
</indexterm> |
| 8682 |
</term> |
| 8683 |
<listitem> |
| 8684 |
<para> |
| 8685 |
Specifies the amount of memory reserved to store the text of the |
| 8686 |
currently executing command for each active session, for the |
| 8687 |
<structname>pg_stat_activity</structname>.<structfield>query</structfield> field. |
| 8688 |
If this value is specified without units, it is taken as bytes. |
| 8689 |
The default value is 1024 bytes. |
| 8690 |
This parameter can only be set at server start. |
| 8691 |
</para> |
| 8692 |
</listitem> |
| 8693 |
</varlistentry> |
| 8694 |
|
| 8695 |
<varlistentry id="guc-track-counts" xreflabel="track_counts"> |
| 8696 |
<term><varname>track_counts</varname> (<type>boolean</type>) |
| 8697 |
<indexterm> |
| 8698 |
<primary><varname>track_counts</varname> configuration parameter</primary> |
| 8699 |
</indexterm> |
| 8700 |
</term> |
| 8701 |
<listitem> |
| 8702 |
<para> |
| 8703 |
Enables collection of statistics on database activity. |
| 8704 |
This parameter is on by default, because the autovacuum |
| 8705 |
daemon needs the collected information. |
| 8706 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8707 |
privilege can change this setting. |
| 8708 |
</para> |
| 8709 |
</listitem> |
| 8710 |
</varlistentry> |
| 8711 |
|
| 8712 |
<varlistentry id="guc-track-cost-delay-timing" xreflabel="track_cost_delay_timing"> |
| 8713 |
<term><varname>track_cost_delay_timing</varname> (<type>boolean</type>) |
| 8714 |
<indexterm> |
| 8715 |
<primary><varname>track_cost_delay_timing</varname> configuration parameter</primary> |
| 8716 |
</indexterm> |
| 8717 |
</term> |
| 8718 |
<listitem> |
| 8719 |
<para> |
| 8720 |
Enables timing of cost-based vacuum delay (see |
| 8721 |
<xref linkend="runtime-config-resource-vacuum-cost"/>). This parameter |
| 8722 |
is off by default, as it will repeatedly query the operating system for |
| 8723 |
the current time, which may cause significant overhead on some |
| 8724 |
platforms. You can use the <xref linkend="pgtesttiming"/> tool to |
| 8725 |
measure the overhead of timing on your system. Cost-based vacuum delay |
| 8726 |
timing information is displayed in |
| 8727 |
<link linkend="vacuum-progress-reporting"><structname>pg_stat_progress_vacuum</structname></link>, |
| 8728 |
<link linkend="analyze-progress-reporting"><structname>pg_stat_progress_analyze</structname></link>, |
| 8729 |
in the output of <xref linkend="sql-vacuum"/> and |
| 8730 |
<xref linkend="sql-analyze"/> when the |
| 8731 |
<literal>VERBOSE</literal> option is used, and by autovacuum for |
| 8732 |
auto-vacuums and auto-analyzes when |
| 8733 |
<xref linkend="guc-log-autovacuum-min-duration"/> is set. |
| 8734 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8735 |
privilege can change this setting. |
| 8736 |
</para> |
| 8737 |
</listitem> |
| 8738 |
</varlistentry> |
| 8739 |
|
| 8740 |
<varlistentry id="guc-track-io-timing" xreflabel="track_io_timing"> |
| 8741 |
<term><varname>track_io_timing</varname> (<type>boolean</type>) |
| 8742 |
<indexterm> |
| 8743 |
<primary><varname>track_io_timing</varname> configuration parameter</primary> |
| 8744 |
</indexterm> |
| 8745 |
</term> |
| 8746 |
<listitem> |
| 8747 |
<para> |
| 8748 |
Enables timing of database I/O waits. This parameter is off by |
| 8749 |
default, as it will repeatedly query the operating system for |
| 8750 |
the current time, which may cause significant overhead on some |
| 8751 |
platforms. You can use the <xref linkend="pgtesttiming"/> tool to |
| 8752 |
measure the overhead of timing on your system. |
| 8753 |
I/O timing information is |
| 8754 |
displayed in <link linkend="monitoring-pg-stat-database-view"> |
| 8755 |
<structname>pg_stat_database</structname></link>, |
| 8756 |
<link linkend="monitoring-pg-stat-io-view"> |
| 8757 |
<structname>pg_stat_io</structname></link> (if <varname>object</varname> |
| 8758 |
is not <literal>wal</literal>), in the output of the |
| 8759 |
<link linkend="pg-stat-get-backend-io"> |
| 8760 |
<function>pg_stat_get_backend_io()</function></link> function (if |
| 8761 |
<varname>object</varname> is not <literal>wal</literal>), in the |
| 8762 |
output of <xref linkend="sql-explain"/> when the <literal>BUFFERS</literal> |
| 8763 |
option is used, in the output of <xref linkend="sql-vacuum"/> when |
| 8764 |
the <literal>VERBOSE</literal> option is used, by autovacuum |
| 8765 |
for auto-vacuums and auto-analyzes, when <xref |
| 8766 |
linkend="guc-log-autovacuum-min-duration"/> is set and by |
| 8767 |
<xref linkend="pgstatstatements"/>. |
| 8768 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8769 |
privilege can change this setting. |
| 8770 |
</para> |
| 8771 |
</listitem> |
| 8772 |
</varlistentry> |
| 8773 |
|
| 8774 |
<varlistentry id="guc-track-wal-io-timing" xreflabel="track_wal_io_timing"> |
| 8775 |
<term><varname>track_wal_io_timing</varname> (<type>boolean</type>) |
| 8776 |
<indexterm> |
| 8777 |
<primary><varname>track_wal_io_timing</varname> configuration parameter</primary> |
| 8778 |
</indexterm> |
| 8779 |
</term> |
| 8780 |
<listitem> |
| 8781 |
<para> |
| 8782 |
Enables timing of WAL I/O waits. This parameter is off by default, |
| 8783 |
as it will repeatedly query the operating system for the current time, |
| 8784 |
which may cause significant overhead on some platforms. |
| 8785 |
You can use the <application>pg_test_timing</application> tool to |
| 8786 |
measure the overhead of timing on your system. |
| 8787 |
I/O timing information is displayed in |
| 8788 |
<link linkend="monitoring-pg-stat-io-view"> |
| 8789 |
<structname>pg_stat_io</structname></link> for the |
| 8790 |
<varname>object</varname> <literal>wal</literal> and in the output of |
| 8791 |
the <link linkend="pg-stat-get-backend-io"> |
| 8792 |
<function>pg_stat_get_backend_io()</function></link> function for the |
| 8793 |
<varname>object</varname> <literal>wal</literal>. |
| 8794 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8795 |
privilege can change this setting. |
| 8796 |
</para> |
| 8797 |
</listitem> |
| 8798 |
</varlistentry> |
| 8799 |
|
| 8800 |
<varlistentry id="guc-track-functions" xreflabel="track_functions"> |
| 8801 |
<term><varname>track_functions</varname> (<type>enum</type>) |
| 8802 |
<indexterm> |
| 8803 |
<primary><varname>track_functions</varname> configuration parameter</primary> |
| 8804 |
</indexterm> |
| 8805 |
</term> |
| 8806 |
<listitem> |
| 8807 |
<para> |
| 8808 |
Enables tracking of function call counts and time used. Specify |
| 8809 |
<literal>pl</literal> to track only procedural-language functions, |
| 8810 |
<literal>all</literal> to also track SQL and C language functions. |
| 8811 |
The default is <literal>none</literal>, which disables function |
| 8812 |
statistics tracking. |
| 8813 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8814 |
privilege can change this setting. |
| 8815 |
</para> |
| 8816 |
|
| 8817 |
<note> |
| 8818 |
<para> |
| 8819 |
SQL-language functions that are simple enough to be <quote>inlined</quote> |
| 8820 |
into the calling query will not be tracked, regardless of this |
| 8821 |
setting. |
| 8822 |
</para> |
| 8823 |
</note> |
| 8824 |
</listitem> |
| 8825 |
</varlistentry> |
| 8826 |
|
| 8827 |
<varlistentry id="guc-stats-fetch-consistency" xreflabel="stats_fetch_consistency"> |
| 8828 |
<term><varname>stats_fetch_consistency</varname> (<type>enum</type>) |
| 8829 |
<indexterm> |
| 8830 |
<primary><varname>stats_fetch_consistency</varname> configuration parameter</primary> |
| 8831 |
</indexterm> |
| 8832 |
</term> |
| 8833 |
<listitem> |
| 8834 |
<para> |
| 8835 |
Determines the behavior when cumulative statistics are accessed |
| 8836 |
multiple times within a transaction. When set to |
| 8837 |
<literal>none</literal>, each access re-fetches counters from shared |
| 8838 |
memory. When set to <literal>cache</literal>, the first access to |
| 8839 |
statistics for an object caches those statistics until the end of the |
| 8840 |
transaction unless <function>pg_stat_clear_snapshot()</function> is |
| 8841 |
called. When set to <literal>snapshot</literal>, the first statistics |
| 8842 |
access caches all statistics accessible in the current database, until |
| 8843 |
the end of the transaction unless |
| 8844 |
<function>pg_stat_clear_snapshot()</function> is called. Changing this |
| 8845 |
parameter in a transaction discards the statistics snapshot. |
| 8846 |
The default is <literal>cache</literal>. |
| 8847 |
</para> |
| 8848 |
<note> |
| 8849 |
<para> |
| 8850 |
<literal>none</literal> is most suitable for monitoring systems. If |
| 8851 |
values are only accessed once, it is the most |
| 8852 |
efficient. <literal>cache</literal> ensures repeat accesses yield the |
| 8853 |
same values, which is important for queries involving |
| 8854 |
e.g. self-joins. <literal>snapshot</literal> can be useful when |
| 8855 |
interactively inspecting statistics, but has higher overhead, |
| 8856 |
particularly if many database objects exist. |
| 8857 |
</para> |
| 8858 |
</note> |
| 8859 |
</listitem> |
| 8860 |
</varlistentry> |
| 8861 |
|
| 8862 |
</variablelist> |
| 8863 |
</sect2> |
| 8864 |
|
| 8865 |
<sect2 id="runtime-config-statistics-monitor"> |
| 8866 |
<title>Statistics Monitoring</title> |
| 8867 |
<variablelist> |
| 8868 |
|
| 8869 |
<varlistentry id="guc-compute-query-id" xreflabel="compute_query_id"> |
| 8870 |
<term><varname>compute_query_id</varname> (<type>enum</type>) |
| 8871 |
<indexterm> |
| 8872 |
<primary><varname>compute_query_id</varname> configuration parameter</primary> |
| 8873 |
</indexterm> |
| 8874 |
</term> |
| 8875 |
<listitem> |
| 8876 |
<para> |
| 8877 |
Enables in-core computation of a query identifier. |
| 8878 |
Query identifiers can be displayed in the <link |
| 8879 |
linkend="monitoring-pg-stat-activity-view"><structname>pg_stat_activity</structname></link> |
| 8880 |
view, using <command>EXPLAIN</command>, or emitted in the log if |
| 8881 |
configured via the <xref linkend="guc-log-line-prefix"/> parameter. |
| 8882 |
The <xref linkend="pgstatstatements"/> extension also requires a query |
| 8883 |
identifier to be computed. Note that an external module can |
| 8884 |
alternatively be used if the in-core query identifier computation |
| 8885 |
method is not acceptable. In this case, in-core computation |
| 8886 |
must be always disabled. |
| 8887 |
Valid values are <literal>off</literal> (always disabled), |
| 8888 |
<literal>on</literal> (always enabled), <literal>auto</literal>, |
| 8889 |
which lets modules such as <xref linkend="pgstatstatements"/> |
| 8890 |
automatically enable it, and <literal>regress</literal> which |
| 8891 |
has the same effect as <literal>auto</literal>, except that the |
| 8892 |
query identifier is not shown in the <literal>EXPLAIN</literal> output |
| 8893 |
in order to facilitate automated regression testing. |
| 8894 |
The default is <literal>auto</literal>. |
| 8895 |
</para> |
| 8896 |
<note> |
| 8897 |
<para> |
| 8898 |
To ensure that only one query identifier is calculated and |
| 8899 |
displayed, extensions that calculate query identifiers should |
| 8900 |
throw an error if a query identifier has already been computed. |
| 8901 |
</para> |
| 8902 |
</note> |
| 8903 |
</listitem> |
| 8904 |
</varlistentry> |
| 8905 |
|
| 8906 |
<varlistentry id="guc-log-statement-stats"> |
| 8907 |
<term><varname>log_statement_stats</varname> (<type>boolean</type>) |
| 8908 |
<indexterm> |
| 8909 |
<primary><varname>log_statement_stats</varname> configuration parameter</primary> |
| 8910 |
</indexterm> |
| 8911 |
</term> |
| 8912 |
<term><varname>log_parser_stats</varname> (<type>boolean</type>) |
| 8913 |
<indexterm> |
| 8914 |
<primary><varname>log_parser_stats</varname> configuration parameter</primary> |
| 8915 |
</indexterm> |
| 8916 |
</term> |
| 8917 |
<term><varname>log_planner_stats</varname> (<type>boolean</type>) |
| 8918 |
<indexterm> |
| 8919 |
<primary><varname>log_planner_stats</varname> configuration parameter</primary> |
| 8920 |
</indexterm> |
| 8921 |
</term> |
| 8922 |
<term><varname>log_executor_stats</varname> (<type>boolean</type>) |
| 8923 |
<indexterm> |
| 8924 |
<primary><varname>log_executor_stats</varname> configuration parameter</primary> |
| 8925 |
</indexterm> |
| 8926 |
</term> |
| 8927 |
<listitem> |
| 8928 |
<para> |
| 8929 |
For each query, output performance statistics of the respective |
| 8930 |
module to the server log. This is a crude profiling |
| 8931 |
instrument, similar to the Unix <function>getrusage()</function> operating |
| 8932 |
system facility. <varname>log_statement_stats</varname> reports total |
| 8933 |
statement statistics, while the others report per-module statistics. |
| 8934 |
<varname>log_statement_stats</varname> cannot be enabled together with |
| 8935 |
any of the per-module options. All of these options are disabled by |
| 8936 |
default. |
| 8937 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 8938 |
privilege can change these settings. |
| 8939 |
</para> |
| 8940 |
</listitem> |
| 8941 |
</varlistentry> |
| 8942 |
|
| 8943 |
</variablelist> |
| 8944 |
|
| 8945 |
</sect2> |
| 8946 |
</sect1> |
| 8947 |
|
| 8948 |
<sect1 id="runtime-config-vacuum"> |
| 8949 |
<title>Vacuuming</title> |
| 8950 |
|
| 8951 |
<indexterm> |
| 8952 |
<primary>vacuum</primary> |
| 8953 |
<secondary>configuration parameters</secondary> |
| 8954 |
</indexterm> |
| 8955 |
|
| 8956 |
<para> |
| 8957 |
These parameters control vacuuming behavior. For more information on the |
| 8958 |
purpose and responsibilities of vacuum, see <xref linkend="routine-vacuuming"/>. |
| 8959 |
</para> |
| 8960 |
|
| 8961 |
<sect2 id="runtime-config-autovacuum"> |
| 8962 |
<title>Automatic Vacuuming</title> |
| 8963 |
|
| 8964 |
<para> |
| 8965 |
These settings control the behavior of the <firstterm>autovacuum</firstterm> |
| 8966 |
feature. Refer to <xref linkend="autovacuum"/> for more information. |
| 8967 |
Note that many of these settings can be overridden on a per-table |
| 8968 |
basis; see <xref linkend="sql-createtable-storage-parameters"/>. |
| 8969 |
</para> |
| 8970 |
|
| 8971 |
<variablelist> |
| 8972 |
|
| 8973 |
<varlistentry id="guc-autovacuum" xreflabel="autovacuum"> |
| 8974 |
<term><varname>autovacuum</varname> (<type>boolean</type>) |
| 8975 |
<indexterm> |
| 8976 |
<primary><varname>autovacuum</varname> configuration parameter</primary> |
| 8977 |
</indexterm> |
| 8978 |
</term> |
| 8979 |
<listitem> |
| 8980 |
<para> |
| 8981 |
Controls whether the server should run the |
| 8982 |
autovacuum launcher daemon. This is on by default; however, |
| 8983 |
<xref linkend="guc-track-counts"/> must also be enabled for |
| 8984 |
autovacuum to work. |
| 8985 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 8986 |
file or on the server command line; however, autovacuuming can be |
| 8987 |
disabled for individual tables by changing table storage parameters. |
| 8988 |
</para> |
| 8989 |
<para> |
| 8990 |
Note that even when this parameter is disabled, the system |
| 8991 |
will launch autovacuum processes if necessary to |
| 8992 |
prevent transaction ID wraparound. See <xref |
| 8993 |
linkend="vacuum-for-wraparound"/> for more information. |
| 8994 |
</para> |
| 8995 |
</listitem> |
| 8996 |
</varlistentry> |
| 8997 |
|
| 8998 |
<varlistentry id="guc-autovacuum-worker-slots" xreflabel="autovacuum_worker_slots"> |
| 8999 |
<term><varname>autovacuum_worker_slots</varname> (<type>integer</type>) |
| 9000 |
<indexterm> |
| 9001 |
<primary><varname>autovacuum_worker_slots</varname> configuration parameter</primary> |
| 9002 |
</indexterm> |
| 9003 |
</term> |
| 9004 |
<listitem> |
| 9005 |
<para> |
| 9006 |
Specifies the number of backend slots to reserve for autovacuum worker |
| 9007 |
processes. The default is typically 16 slots, but might be less if |
| 9008 |
your kernel settings will not support it (as determined during initdb). |
| 9009 |
This parameter can only be set at server start. |
| 9010 |
</para> |
| 9011 |
<para> |
| 9012 |
When changing this value, consider also adjusting |
| 9013 |
<xref linkend="guc-autovacuum-max-workers"/>. |
| 9014 |
</para> |
| 9015 |
</listitem> |
| 9016 |
</varlistentry> |
| 9017 |
|
| 9018 |
<varlistentry id="guc-autovacuum-max-workers" xreflabel="autovacuum_max_workers"> |
| 9019 |
<term><varname>autovacuum_max_workers</varname> (<type>integer</type>) |
| 9020 |
<indexterm> |
| 9021 |
<primary><varname>autovacuum_max_workers</varname> configuration parameter</primary> |
| 9022 |
</indexterm> |
| 9023 |
</term> |
| 9024 |
<listitem> |
| 9025 |
<para> |
| 9026 |
Specifies the maximum number of autovacuum processes (other than the |
| 9027 |
autovacuum launcher) that may be running at any one time. The default |
| 9028 |
is <literal>3</literal>. This parameter can only be set in the |
| 9029 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 9030 |
</para> |
| 9031 |
<para> |
| 9032 |
Note that a setting for this value which is higher than |
| 9033 |
<xref linkend="guc-autovacuum-worker-slots"/> will have no effect, |
| 9034 |
since autovacuum workers are taken from the pool of slots established |
| 9035 |
by that setting. |
| 9036 |
</para> |
| 9037 |
</listitem> |
| 9038 |
</varlistentry> |
| 9039 |
|
| 9040 |
<varlistentry id="guc-autovacuum-naptime" xreflabel="autovacuum_naptime"> |
| 9041 |
<term><varname>autovacuum_naptime</varname> (<type>integer</type>) |
| 9042 |
<indexterm> |
| 9043 |
<primary><varname>autovacuum_naptime</varname> configuration parameter</primary> |
| 9044 |
</indexterm> |
| 9045 |
</term> |
| 9046 |
<listitem> |
| 9047 |
<para> |
| 9048 |
Specifies the minimum delay between autovacuum runs on any given |
| 9049 |
database. In each round the daemon examines the |
| 9050 |
database and issues <command>VACUUM</command> and <command>ANALYZE</command> commands |
| 9051 |
as needed for tables in that database. |
| 9052 |
If this value is specified without units, it is taken as seconds. |
| 9053 |
The default is one minute (<literal>1min</literal>). |
| 9054 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9055 |
file or on the server command line. |
| 9056 |
</para> |
| 9057 |
</listitem> |
| 9058 |
</varlistentry> |
| 9059 |
|
| 9060 |
<varlistentry id="guc-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold"> |
| 9061 |
<term><varname>autovacuum_vacuum_threshold</varname> (<type>integer</type>) |
| 9062 |
<indexterm> |
| 9063 |
<primary><varname>autovacuum_vacuum_threshold</varname></primary> |
| 9064 |
<secondary>configuration parameter</secondary> |
| 9065 |
</indexterm> |
| 9066 |
</term> |
| 9067 |
<listitem> |
| 9068 |
<para> |
| 9069 |
Specifies the minimum number of updated or deleted tuples needed |
| 9070 |
to trigger a <command>VACUUM</command> in any one table. |
| 9071 |
The default is 50 tuples. |
| 9072 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9073 |
file or on the server command line; |
| 9074 |
but the setting can be overridden for individual tables by |
| 9075 |
changing table storage parameters. |
| 9076 |
</para> |
| 9077 |
</listitem> |
| 9078 |
</varlistentry> |
| 9079 |
|
| 9080 |
<varlistentry id="guc-autovacuum-vacuum-insert-threshold" xreflabel="autovacuum_vacuum_insert_threshold"> |
| 9081 |
<term><varname>autovacuum_vacuum_insert_threshold</varname> (<type>integer</type>) |
| 9082 |
<indexterm> |
| 9083 |
<primary><varname>autovacuum_vacuum_insert_threshold</varname></primary> |
| 9084 |
<secondary>configuration parameter</secondary> |
| 9085 |
</indexterm> |
| 9086 |
</term> |
| 9087 |
<listitem> |
| 9088 |
<para> |
| 9089 |
Specifies the number of inserted tuples needed to trigger a |
| 9090 |
<command>VACUUM</command> in any one table. |
| 9091 |
The default is 1000 tuples. If -1 is specified, autovacuum will not |
| 9092 |
trigger a <command>VACUUM</command> operation on any tables based on |
| 9093 |
the number of inserts. |
| 9094 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9095 |
file or on the server command line; |
| 9096 |
but the setting can be overridden for individual tables by |
| 9097 |
changing table storage parameters. |
| 9098 |
</para> |
| 9099 |
</listitem> |
| 9100 |
</varlistentry> |
| 9101 |
|
| 9102 |
<varlistentry id="guc-autovacuum-analyze-threshold" xreflabel="autovacuum_analyze_threshold"> |
| 9103 |
<term><varname>autovacuum_analyze_threshold</varname> (<type>integer</type>) |
| 9104 |
<indexterm> |
| 9105 |
<primary><varname>autovacuum_analyze_threshold</varname></primary> |
| 9106 |
<secondary>configuration parameter</secondary> |
| 9107 |
</indexterm> |
| 9108 |
</term> |
| 9109 |
<listitem> |
| 9110 |
<para> |
| 9111 |
Specifies the minimum number of inserted, updated or deleted tuples |
| 9112 |
needed to trigger an <command>ANALYZE</command> in any one table. |
| 9113 |
The default is 50 tuples. |
| 9114 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9115 |
file or on the server command line; |
| 9116 |
but the setting can be overridden for individual tables by |
| 9117 |
changing table storage parameters. |
| 9118 |
</para> |
| 9119 |
</listitem> |
| 9120 |
</varlistentry> |
| 9121 |
|
| 9122 |
<varlistentry id="guc-autovacuum-vacuum-scale-factor" xreflabel="autovacuum_vacuum_scale_factor"> |
| 9123 |
<term><varname>autovacuum_vacuum_scale_factor</varname> (<type>floating point</type>) |
| 9124 |
<indexterm> |
| 9125 |
<primary><varname>autovacuum_vacuum_scale_factor</varname></primary> |
| 9126 |
<secondary>configuration parameter</secondary> |
| 9127 |
</indexterm> |
| 9128 |
</term> |
| 9129 |
<listitem> |
| 9130 |
<para> |
| 9131 |
Specifies a fraction of the table size to add to |
| 9132 |
<varname>autovacuum_vacuum_threshold</varname> |
| 9133 |
when deciding whether to trigger a <command>VACUUM</command>. |
| 9134 |
The default is <literal>0.2</literal> (20% of table size). |
| 9135 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9136 |
file or on the server command line; |
| 9137 |
but the setting can be overridden for individual tables by |
| 9138 |
changing table storage parameters. |
| 9139 |
</para> |
| 9140 |
</listitem> |
| 9141 |
</varlistentry> |
| 9142 |
|
| 9143 |
<varlistentry id="guc-autovacuum-vacuum-insert-scale-factor" xreflabel="autovacuum_vacuum_insert_scale_factor"> |
| 9144 |
<term><varname>autovacuum_vacuum_insert_scale_factor</varname> (<type>floating point</type>) |
| 9145 |
<indexterm> |
| 9146 |
<primary><varname>autovacuum_vacuum_insert_scale_factor</varname></primary> |
| 9147 |
<secondary>configuration parameter</secondary> |
| 9148 |
</indexterm> |
| 9149 |
</term> |
| 9150 |
<listitem> |
| 9151 |
<para> |
| 9152 |
Specifies a fraction of the unfrozen pages in the table to add to |
| 9153 |
<varname>autovacuum_vacuum_insert_threshold</varname> when deciding |
| 9154 |
whether to trigger a <command>VACUUM</command>. The default is |
| 9155 |
<literal>0.2</literal> (20% of unfrozen pages in table). This |
| 9156 |
parameter can only be set in the <filename>postgresql.conf</filename> |
| 9157 |
file or on the server command line; but the setting can be overridden |
| 9158 |
for individual tables by changing table storage parameters. |
| 9159 |
</para> |
| 9160 |
</listitem> |
| 9161 |
</varlistentry> |
| 9162 |
|
| 9163 |
<varlistentry id="guc-autovacuum-analyze-scale-factor" xreflabel="autovacuum_analyze_scale_factor"> |
| 9164 |
<term><varname>autovacuum_analyze_scale_factor</varname> (<type>floating point</type>) |
| 9165 |
<indexterm> |
| 9166 |
<primary><varname>autovacuum_analyze_scale_factor</varname></primary> |
| 9167 |
<secondary>configuration parameter</secondary> |
| 9168 |
</indexterm> |
| 9169 |
</term> |
| 9170 |
<listitem> |
| 9171 |
<para> |
| 9172 |
Specifies a fraction of the table size to add to |
| 9173 |
<varname>autovacuum_analyze_threshold</varname> |
| 9174 |
when deciding whether to trigger an <command>ANALYZE</command>. |
| 9175 |
The default is <literal>0.1</literal> (10% of table size). |
| 9176 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9177 |
file or on the server command line; |
| 9178 |
but the setting can be overridden for individual tables by |
| 9179 |
changing table storage parameters. |
| 9180 |
</para> |
| 9181 |
</listitem> |
| 9182 |
</varlistentry> |
| 9183 |
|
| 9184 |
<varlistentry id="guc-autovacuum-vacuum-max-threshold" xreflabel="autovacuum_vacuum_max_threshold"> |
| 9185 |
<term><varname>autovacuum_vacuum_max_threshold</varname> (<type>integer</type>) |
| 9186 |
<indexterm> |
| 9187 |
<primary><varname>autovacuum_vacuum_max_threshold</varname></primary> |
| 9188 |
<secondary>configuration parameter</secondary> |
| 9189 |
</indexterm> |
| 9190 |
</term> |
| 9191 |
<listitem> |
| 9192 |
<para> |
| 9193 |
Specifies the maximum number of updated or deleted tuples needed to |
| 9194 |
trigger a <command>VACUUM</command> in any one table, i.e., a limit on |
| 9195 |
the value calculated with |
| 9196 |
<varname>autovacuum_vacuum_threshold</varname> and |
| 9197 |
<varname>autovacuum_vacuum_scale_factor</varname>. The default is |
| 9198 |
100,000,000 tuples. If -1 is specified, autovacuum will not enforce a |
| 9199 |
maximum number of updated or deleted tuples that will trigger a |
| 9200 |
<command>VACUUM</command> operation. This parameter can only be set |
| 9201 |
in the <filename>postgresql.conf</filename> file or on the server |
| 9202 |
command line; but the setting can be overridden for individual tables |
| 9203 |
by changing storage parameters. |
| 9204 |
</para> |
| 9205 |
</listitem> |
| 9206 |
</varlistentry> |
| 9207 |
|
| 9208 |
<varlistentry id="guc-autovacuum-freeze-max-age" xreflabel="autovacuum_freeze_max_age"> |
| 9209 |
<term><varname>autovacuum_freeze_max_age</varname> (<type>integer</type>) |
| 9210 |
<indexterm> |
| 9211 |
<primary><varname>autovacuum_freeze_max_age</varname></primary> |
| 9212 |
<secondary>configuration parameter</secondary> |
| 9213 |
</indexterm> |
| 9214 |
</term> |
| 9215 |
<listitem> |
| 9216 |
<para> |
| 9217 |
Specifies the maximum age (in transactions) that a table's |
| 9218 |
<structname>pg_class</structname>.<structfield>relfrozenxid</structfield> field can |
| 9219 |
attain before a <command>VACUUM</command> operation is forced |
| 9220 |
to prevent transaction ID wraparound within the table. |
| 9221 |
Note that the system will launch autovacuum processes to |
| 9222 |
prevent wraparound even when autovacuum is otherwise disabled. |
| 9223 |
</para> |
| 9224 |
|
| 9225 |
<para> |
| 9226 |
Vacuum also allows removal of old files from the |
| 9227 |
<filename>pg_xact</filename> subdirectory, which is why the default |
| 9228 |
is a relatively low 200 million transactions. |
| 9229 |
This parameter can only be set at server start, but the setting |
| 9230 |
can be reduced for individual tables by |
| 9231 |
changing table storage parameters. |
| 9232 |
For more information see <xref linkend="vacuum-for-wraparound"/>. |
| 9233 |
</para> |
| 9234 |
</listitem> |
| 9235 |
</varlistentry> |
| 9236 |
|
| 9237 |
<varlistentry id="guc-autovacuum-multixact-freeze-max-age" xreflabel="autovacuum_multixact_freeze_max_age"> |
| 9238 |
<term><varname>autovacuum_multixact_freeze_max_age</varname> (<type>integer</type>) |
| 9239 |
<indexterm> |
| 9240 |
<primary><varname>autovacuum_multixact_freeze_max_age</varname></primary> |
| 9241 |
<secondary>configuration parameter</secondary> |
| 9242 |
</indexterm> |
| 9243 |
</term> |
| 9244 |
<listitem> |
| 9245 |
<para> |
| 9246 |
Specifies the maximum age (in multixacts) that a table's |
| 9247 |
<structname>pg_class</structname>.<structfield>relminmxid</structfield> field can |
| 9248 |
attain before a <command>VACUUM</command> operation is forced to |
| 9249 |
prevent multixact ID wraparound within the table. |
| 9250 |
Note that the system will launch autovacuum processes to |
| 9251 |
prevent wraparound even when autovacuum is otherwise disabled. |
| 9252 |
</para> |
| 9253 |
|
| 9254 |
<para> |
| 9255 |
Vacuuming multixacts also allows removal of old files from the |
| 9256 |
<filename>pg_multixact/members</filename> and <filename>pg_multixact/offsets</filename> |
| 9257 |
subdirectories, which is why the default is a relatively low |
| 9258 |
400 million multixacts. |
| 9259 |
This parameter can only be set at server start, but the setting can |
| 9260 |
be reduced for individual tables by changing table storage parameters. |
| 9261 |
For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. |
| 9262 |
</para> |
| 9263 |
</listitem> |
| 9264 |
</varlistentry> |
| 9265 |
|
| 9266 |
<varlistentry id="guc-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay"> |
| 9267 |
<term><varname>autovacuum_vacuum_cost_delay</varname> (<type>floating point</type>) |
| 9268 |
<indexterm> |
| 9269 |
<primary><varname>autovacuum_vacuum_cost_delay</varname></primary> |
| 9270 |
<secondary>configuration parameter</secondary> |
| 9271 |
</indexterm> |
| 9272 |
</term> |
| 9273 |
<listitem> |
| 9274 |
<para> |
| 9275 |
Specifies the cost delay value that will be used in automatic |
| 9276 |
<command>VACUUM</command> operations. If -1 is specified, the regular |
| 9277 |
<xref linkend="guc-vacuum-cost-delay"/> value will be used. |
| 9278 |
If this value is specified without units, it is taken as milliseconds. |
| 9279 |
The default value is 2 milliseconds. |
| 9280 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9281 |
file or on the server command line; |
| 9282 |
but the setting can be overridden for individual tables by |
| 9283 |
changing table storage parameters. |
| 9284 |
</para> |
| 9285 |
</listitem> |
| 9286 |
</varlistentry> |
| 9287 |
|
| 9288 |
<varlistentry id="guc-autovacuum-vacuum-cost-limit" xreflabel="autovacuum_vacuum_cost_limit"> |
| 9289 |
<term><varname>autovacuum_vacuum_cost_limit</varname> (<type>integer</type>) |
| 9290 |
<indexterm> |
| 9291 |
<primary><varname>autovacuum_vacuum_cost_limit</varname></primary> |
| 9292 |
<secondary>configuration parameter</secondary> |
| 9293 |
</indexterm> |
| 9294 |
</term> |
| 9295 |
<listitem> |
| 9296 |
<para> |
| 9297 |
Specifies the cost limit value that will be used in automatic |
| 9298 |
<command>VACUUM</command> operations. If <literal>-1</literal> |
| 9299 |
is specified (which is the default), the regular |
| 9300 |
<xref linkend="guc-vacuum-cost-limit"/> value will be used. Note that |
| 9301 |
the value is distributed proportionally among the running autovacuum |
| 9302 |
workers, if there is more than one, so that the sum of the limits for |
| 9303 |
each worker does not exceed the value of this variable. |
| 9304 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 9305 |
file or on the server command line; |
| 9306 |
but the setting can be overridden for individual tables by |
| 9307 |
changing table storage parameters. |
| 9308 |
</para> |
| 9309 |
</listitem> |
| 9310 |
</varlistentry> |
| 9311 |
|
| 9312 |
</variablelist> |
| 9313 |
</sect2> |
| 9314 |
|
| 9315 |
<sect2 id="runtime-config-resource-vacuum-cost"> |
| 9316 |
<title>Cost-based Vacuum Delay</title> |
| 9317 |
|
| 9318 |
<para> |
| 9319 |
During the execution of <xref linkend="sql-vacuum"/> |
| 9320 |
and <xref linkend="sql-analyze"/> |
| 9321 |
commands, the system maintains an |
| 9322 |
internal counter that keeps track of the estimated cost of the |
| 9323 |
various I/O operations that are performed. When the accumulated |
| 9324 |
cost reaches a limit (specified by |
| 9325 |
<varname>vacuum_cost_limit</varname>), the process performing |
| 9326 |
the operation will sleep for a short period of time, as specified by |
| 9327 |
<varname>vacuum_cost_delay</varname>. Then it will reset the |
| 9328 |
counter and continue execution. |
| 9329 |
</para> |
| 9330 |
|
| 9331 |
<para> |
| 9332 |
The intent of this feature is to allow administrators to reduce |
| 9333 |
the I/O impact of these commands on concurrent database |
| 9334 |
activity. There are many situations where it is not |
| 9335 |
important that maintenance commands like |
| 9336 |
<command>VACUUM</command> and <command>ANALYZE</command> finish |
| 9337 |
quickly; however, it is usually very important that these |
| 9338 |
commands do not significantly interfere with the ability of the |
| 9339 |
system to perform other database operations. Cost-based vacuum |
| 9340 |
delay provides a way for administrators to achieve this. |
| 9341 |
</para> |
| 9342 |
|
| 9343 |
<para> |
| 9344 |
This feature is disabled by default for manually issued |
| 9345 |
<command>VACUUM</command> commands. To enable it, set the |
| 9346 |
<varname>vacuum_cost_delay</varname> variable to a nonzero |
| 9347 |
value. |
| 9348 |
</para> |
| 9349 |
|
| 9350 |
<variablelist> |
| 9351 |
<varlistentry id="guc-vacuum-cost-delay" xreflabel="vacuum_cost_delay"> |
| 9352 |
<term><varname>vacuum_cost_delay</varname> (<type>floating point</type>) |
| 9353 |
<indexterm> |
| 9354 |
<primary><varname>vacuum_cost_delay</varname> configuration parameter</primary> |
| 9355 |
</indexterm> |
| 9356 |
</term> |
| 9357 |
<listitem> |
| 9358 |
<para> |
| 9359 |
The amount of time that the process will sleep when the cost |
| 9360 |
limit has been exceeded. If this value is specified without |
| 9361 |
units, it is taken as milliseconds. The default value is |
| 9362 |
<literal>0</literal>, which disables the cost-based vacuum delay |
| 9363 |
feature. Positive values enable cost-based vacuuming. |
| 9364 |
</para> |
| 9365 |
|
| 9366 |
<para> |
| 9367 |
When using cost-based vacuuming, appropriate values for |
| 9368 |
<varname>vacuum_cost_delay</varname> are usually quite small, perhaps |
| 9369 |
less than 1 millisecond. While <varname>vacuum_cost_delay</varname> |
| 9370 |
can be set to fractional-millisecond values, such delays may not be |
| 9371 |
measured accurately on older platforms. On such platforms, |
| 9372 |
increasing <command>VACUUM</command>'s throttled resource consumption |
| 9373 |
above what you get at 1ms will require changing the other vacuum cost |
| 9374 |
parameters. You should, nonetheless, |
| 9375 |
keep <varname>vacuum_cost_delay</varname> as small as your platform |
| 9376 |
will consistently measure; large delays are not helpful. |
| 9377 |
</para> |
| 9378 |
</listitem> |
| 9379 |
</varlistentry> |
| 9380 |
|
| 9381 |
<varlistentry id="guc-vacuum-cost-page-hit" xreflabel="vacuum_cost_page_hit"> |
| 9382 |
<term><varname>vacuum_cost_page_hit</varname> (<type>integer</type>) |
| 9383 |
<indexterm> |
| 9384 |
<primary><varname>vacuum_cost_page_hit</varname> configuration parameter</primary> |
| 9385 |
</indexterm> |
| 9386 |
</term> |
| 9387 |
<listitem> |
| 9388 |
<para> |
| 9389 |
The estimated cost for vacuuming a buffer found in the shared |
| 9390 |
buffer cache. It represents the cost to lock the buffer pool, |
| 9391 |
lookup the shared hash table and scan the content of the page. |
| 9392 |
The default value is <literal>1</literal>. |
| 9393 |
</para> |
| 9394 |
</listitem> |
| 9395 |
</varlistentry> |
| 9396 |
|
| 9397 |
<varlistentry id="guc-vacuum-cost-page-miss" xreflabel="vacuum_cost_page_miss"> |
| 9398 |
<term><varname>vacuum_cost_page_miss</varname> (<type>integer</type>) |
| 9399 |
<indexterm> |
| 9400 |
<primary><varname>vacuum_cost_page_miss</varname> configuration parameter</primary> |
| 9401 |
</indexterm> |
| 9402 |
</term> |
| 9403 |
<listitem> |
| 9404 |
<para> |
| 9405 |
The estimated cost for vacuuming a buffer that has to be read from |
| 9406 |
disk. This represents the effort to lock the buffer pool, |
| 9407 |
lookup the shared hash table, read the desired block in from |
| 9408 |
the disk and scan its content. The default value is |
| 9409 |
<literal>2</literal>. |
| 9410 |
</para> |
| 9411 |
</listitem> |
| 9412 |
</varlistentry> |
| 9413 |
|
| 9414 |
<varlistentry id="guc-vacuum-cost-page-dirty" xreflabel="vacuum_cost_page_dirty"> |
| 9415 |
<term><varname>vacuum_cost_page_dirty</varname> (<type>integer</type>) |
| 9416 |
<indexterm> |
| 9417 |
<primary><varname>vacuum_cost_page_dirty</varname> configuration parameter</primary> |
| 9418 |
</indexterm> |
| 9419 |
</term> |
| 9420 |
<listitem> |
| 9421 |
<para> |
| 9422 |
The estimated cost charged when vacuum modifies a block that was |
| 9423 |
previously clean. It represents the extra I/O required to |
| 9424 |
flush the dirty block out to disk again. The default value is |
| 9425 |
<literal>20</literal>. |
| 9426 |
</para> |
| 9427 |
</listitem> |
| 9428 |
</varlistentry> |
| 9429 |
|
| 9430 |
<varlistentry id="guc-vacuum-cost-limit" xreflabel="vacuum_cost_limit"> |
| 9431 |
<term><varname>vacuum_cost_limit</varname> (<type>integer</type>) |
| 9432 |
<indexterm> |
| 9433 |
<primary><varname>vacuum_cost_limit</varname> configuration parameter</primary> |
| 9434 |
</indexterm> |
| 9435 |
</term> |
| 9436 |
<listitem> |
| 9437 |
<para> |
| 9438 |
This is the accumulated cost that will cause the vacuuming |
| 9439 |
process to sleep for <varname>vacuum_cost_delay</varname>. The |
| 9440 |
default is <literal>200</literal>. |
| 9441 |
</para> |
| 9442 |
</listitem> |
| 9443 |
</varlistentry> |
| 9444 |
</variablelist> |
| 9445 |
|
| 9446 |
<note> |
| 9447 |
<para> |
| 9448 |
There are certain operations that hold critical locks and should |
| 9449 |
therefore complete as quickly as possible. Cost-based vacuum |
| 9450 |
delays do not occur during such operations. Therefore it is |
| 9451 |
possible that the cost accumulates far higher than the specified |
| 9452 |
limit. To avoid uselessly long delays in such cases, the actual |
| 9453 |
delay is calculated as <varname>vacuum_cost_delay</varname> * |
| 9454 |
<varname>accumulated_balance</varname> / |
| 9455 |
<varname>vacuum_cost_limit</varname> with a maximum of |
| 9456 |
<varname>vacuum_cost_delay</varname> * 4. |
| 9457 |
</para> |
| 9458 |
</note> |
| 9459 |
</sect2> |
| 9460 |
|
| 9461 |
<sect2 id="runtime-config-vacuum-default"> |
| 9462 |
<title>Default Behavior</title> |
| 9463 |
|
| 9464 |
<variablelist> |
| 9465 |
<varlistentry id="guc-vacuum-truncate" xreflabel="vacuum_truncate"> |
| 9466 |
<term><varname>vacuum_truncate</varname> (<type>boolean</type>) |
| 9467 |
<indexterm> |
| 9468 |
<primary><varname>vacuum_truncate</varname></primary> |
| 9469 |
<secondary>configuration parameter</secondary> |
| 9470 |
</indexterm> |
| 9471 |
</term> |
| 9472 |
<listitem> |
| 9473 |
<para> |
| 9474 |
Enables or disables vacuum to try to truncate off any empty pages at |
| 9475 |
the end of the table. The default value is <literal>true</literal>. |
| 9476 |
If <literal>true</literal>, <command>VACUUM</command> and autovacuum |
| 9477 |
do the truncation and the disk space for the truncated pages is |
| 9478 |
returned to the operating system. Note that the truncation requires |
| 9479 |
an <literal>ACCESS EXCLUSIVE</literal> lock on the table. The |
| 9480 |
<literal>TRUNCATE</literal> parameter of |
| 9481 |
<link linkend="sql-vacuum"><command>VACUUM</command></link>, if |
| 9482 |
specified, overrides the value of this parameter. The setting can |
| 9483 |
also be overridden for individual tables by changing table storage |
| 9484 |
parameters. |
| 9485 |
</para> |
| 9486 |
</listitem> |
| 9487 |
</varlistentry> |
| 9488 |
</variablelist> |
| 9489 |
</sect2> |
| 9490 |
|
| 9491 |
<sect2 id="runtime-config-vacuum-freezing"> |
| 9492 |
<title>Freezing</title> |
| 9493 |
|
| 9494 |
<para> |
| 9495 |
To maintain correctness even after transaction IDs wrap around, |
| 9496 |
<productname>PostgreSQL</productname> marks rows that are sufficiently |
| 9497 |
old as <emphasis>frozen</emphasis>. These rows are visible to everyone; |
| 9498 |
other transactions do not need to examine their inserting XID to |
| 9499 |
determine visibility. <command>VACUUM</command> is responsible for |
| 9500 |
marking rows as frozen. The following settings control |
| 9501 |
<command>VACUUM</command>'s freezing behavior and should be tuned based |
| 9502 |
on the XID consumption rate of the system and data access patterns of the |
| 9503 |
dominant workloads. See <xref linkend="vacuum-for-wraparound"/> for more |
| 9504 |
information on transaction ID wraparound and tuning these parameters. |
| 9505 |
</para> |
| 9506 |
|
| 9507 |
<variablelist> |
| 9508 |
<varlistentry id="guc-vacuum-freeze-table-age" xreflabel="vacuum_freeze_table_age"> |
| 9509 |
<term><varname>vacuum_freeze_table_age</varname> (<type>integer</type>) |
| 9510 |
<indexterm> |
| 9511 |
<primary><varname>vacuum_freeze_table_age</varname> configuration parameter</primary> |
| 9512 |
</indexterm> |
| 9513 |
</term> |
| 9514 |
<listitem> |
| 9515 |
<para> |
| 9516 |
<command>VACUUM</command> performs an aggressive scan if the table's |
| 9517 |
<structname>pg_class</structname>.<structfield>relfrozenxid</structfield> field has reached |
| 9518 |
the age specified by this setting. An aggressive scan differs from |
| 9519 |
a regular <command>VACUUM</command> in that it visits every page that might |
| 9520 |
contain unfrozen XIDs or MXIDs, not just those that might contain dead |
| 9521 |
tuples. The default is 150 million transactions. Although users can |
| 9522 |
set this value anywhere from zero to two billion, <command>VACUUM</command> |
| 9523 |
will silently limit the effective value to 95% of |
| 9524 |
<xref linkend="guc-autovacuum-freeze-max-age"/>, so that a |
| 9525 |
periodic manual <command>VACUUM</command> has a chance to run before an |
| 9526 |
anti-wraparound autovacuum is launched for the table. For more |
| 9527 |
information see |
| 9528 |
<xref linkend="vacuum-for-wraparound"/>. |
| 9529 |
</para> |
| 9530 |
</listitem> |
| 9531 |
</varlistentry> |
| 9532 |
|
| 9533 |
<varlistentry id="guc-vacuum-freeze-min-age" xreflabel="vacuum_freeze_min_age"> |
| 9534 |
<term><varname>vacuum_freeze_min_age</varname> (<type>integer</type>) |
| 9535 |
<indexterm> |
| 9536 |
<primary><varname>vacuum_freeze_min_age</varname> configuration parameter</primary> |
| 9537 |
</indexterm> |
| 9538 |
</term> |
| 9539 |
<listitem> |
| 9540 |
<para> |
| 9541 |
Specifies the cutoff age (in transactions) that |
| 9542 |
<command>VACUUM</command> should use to decide whether to |
| 9543 |
trigger freezing of pages that have an older XID. |
| 9544 |
The default is 50 million transactions. Although |
| 9545 |
users can set this value anywhere from zero to one billion, |
| 9546 |
<command>VACUUM</command> will silently limit the effective value to half |
| 9547 |
the value of <xref linkend="guc-autovacuum-freeze-max-age"/>, so |
| 9548 |
that there is not an unreasonably short time between forced |
| 9549 |
autovacuums. For more information see <xref |
| 9550 |
linkend="vacuum-for-wraparound"/>. |
| 9551 |
</para> |
| 9552 |
</listitem> |
| 9553 |
</varlistentry> |
| 9554 |
|
| 9555 |
<varlistentry id="guc-vacuum-failsafe-age" xreflabel="vacuum_failsafe_age"> |
| 9556 |
<term><varname>vacuum_failsafe_age</varname> (<type>integer</type>) |
| 9557 |
<indexterm> |
| 9558 |
<primary><varname>vacuum_failsafe_age</varname> configuration parameter</primary> |
| 9559 |
</indexterm> |
| 9560 |
</term> |
| 9561 |
<listitem> |
| 9562 |
<para> |
| 9563 |
Specifies the maximum age (in transactions) that a table's |
| 9564 |
<structname>pg_class</structname>.<structfield>relfrozenxid</structfield> |
| 9565 |
field can attain before <command>VACUUM</command> takes |
| 9566 |
extraordinary measures to avoid system-wide transaction ID |
| 9567 |
wraparound failure. This is <command>VACUUM</command>'s |
| 9568 |
strategy of last resort. The failsafe typically triggers |
| 9569 |
when an autovacuum to prevent transaction ID wraparound has |
| 9570 |
already been running for some time, though it's possible for |
| 9571 |
the failsafe to trigger during any <command>VACUUM</command>. |
| 9572 |
</para> |
| 9573 |
<para> |
| 9574 |
When the failsafe is triggered, any cost-based delay that is |
| 9575 |
in effect will no longer be applied, further non-essential |
| 9576 |
maintenance tasks (such as index vacuuming) are bypassed, and any |
| 9577 |
<glossterm linkend="glossary-buffer-access-strategy">Buffer Access Strategy</glossterm> |
| 9578 |
in use will be disabled resulting in <command>VACUUM</command> being |
| 9579 |
free to make use of all of |
| 9580 |
<glossterm linkend="glossary-shared-memory">shared buffers</glossterm>. |
| 9581 |
</para> |
| 9582 |
<para> |
| 9583 |
The default is 1.6 billion transactions. Although users can |
| 9584 |
set this value anywhere from zero to 2.1 billion, |
| 9585 |
<command>VACUUM</command> will silently adjust the effective |
| 9586 |
value to no less than 105% of <xref |
| 9587 |
linkend="guc-autovacuum-freeze-max-age"/>. |
| 9588 |
</para> |
| 9589 |
</listitem> |
| 9590 |
</varlistentry> |
| 9591 |
|
| 9592 |
<varlistentry id="guc-vacuum-multixact-freeze-table-age" xreflabel="vacuum_multixact_freeze_table_age"> |
| 9593 |
<term><varname>vacuum_multixact_freeze_table_age</varname> (<type>integer</type>) |
| 9594 |
<indexterm> |
| 9595 |
<primary><varname>vacuum_multixact_freeze_table_age</varname> configuration parameter</primary> |
| 9596 |
</indexterm> |
| 9597 |
</term> |
| 9598 |
<listitem> |
| 9599 |
<para> |
| 9600 |
<command>VACUUM</command> performs an aggressive scan if the table's |
| 9601 |
<structname>pg_class</structname>.<structfield>relminmxid</structfield> field has reached |
| 9602 |
the age specified by this setting. An aggressive scan differs from |
| 9603 |
a regular <command>VACUUM</command> in that it visits every page that might |
| 9604 |
contain unfrozen XIDs or MXIDs, not just those that might contain dead |
| 9605 |
tuples. The default is 150 million multixacts. |
| 9606 |
Although users can set this value anywhere from zero to two billion, |
| 9607 |
<command>VACUUM</command> will silently limit the effective value to 95% of |
| 9608 |
<xref linkend="guc-autovacuum-multixact-freeze-max-age"/>, so that a |
| 9609 |
periodic manual <command>VACUUM</command> has a chance to run before an |
| 9610 |
anti-wraparound is launched for the table. |
| 9611 |
For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. |
| 9612 |
</para> |
| 9613 |
</listitem> |
| 9614 |
</varlistentry> |
| 9615 |
|
| 9616 |
<varlistentry id="guc-vacuum-multixact-freeze-min-age" xreflabel="vacuum_multixact_freeze_min_age"> |
| 9617 |
<term><varname>vacuum_multixact_freeze_min_age</varname> (<type>integer</type>) |
| 9618 |
<indexterm> |
| 9619 |
<primary><varname>vacuum_multixact_freeze_min_age</varname> configuration parameter</primary> |
| 9620 |
</indexterm> |
| 9621 |
</term> |
| 9622 |
<listitem> |
| 9623 |
<para> |
| 9624 |
Specifies the cutoff age (in multixacts) that <command>VACUUM</command> |
| 9625 |
should use to decide whether to trigger freezing of pages with |
| 9626 |
an older multixact ID. The default is 5 million multixacts. |
| 9627 |
Although users can set this value anywhere from zero to one billion, |
| 9628 |
<command>VACUUM</command> will silently limit the effective value to half |
| 9629 |
the value of <xref linkend="guc-autovacuum-multixact-freeze-max-age"/>, |
| 9630 |
so that there is not an unreasonably short time between forced |
| 9631 |
autovacuums. |
| 9632 |
For more information see <xref linkend="vacuum-for-multixact-wraparound"/>. |
| 9633 |
</para> |
| 9634 |
</listitem> |
| 9635 |
</varlistentry> |
| 9636 |
|
| 9637 |
<varlistentry id="guc-vacuum-multixact-failsafe-age" xreflabel="vacuum_multixact_failsafe_age"> |
| 9638 |
<term><varname>vacuum_multixact_failsafe_age</varname> (<type>integer</type>) |
| 9639 |
<indexterm> |
| 9640 |
<primary><varname>vacuum_multixact_failsafe_age</varname> configuration parameter</primary> |
| 9641 |
</indexterm> |
| 9642 |
</term> |
| 9643 |
<listitem> |
| 9644 |
<para> |
| 9645 |
Specifies the maximum age (in multixacts) that a table's |
| 9646 |
<structname>pg_class</structname>.<structfield>relminmxid</structfield> |
| 9647 |
field can attain before <command>VACUUM</command> takes |
| 9648 |
extraordinary measures to avoid system-wide multixact ID |
| 9649 |
wraparound failure. This is <command>VACUUM</command>'s |
| 9650 |
strategy of last resort. The failsafe typically triggers when |
| 9651 |
an autovacuum to prevent transaction ID wraparound has already |
| 9652 |
been running for some time, though it's possible for the |
| 9653 |
failsafe to trigger during any <command>VACUUM</command>. |
| 9654 |
</para> |
| 9655 |
<para> |
| 9656 |
When the failsafe is triggered, any cost-based delay that is |
| 9657 |
in effect will no longer be applied, and further non-essential |
| 9658 |
maintenance tasks (such as index vacuuming) are bypassed. |
| 9659 |
</para> |
| 9660 |
<para> |
| 9661 |
The default is 1.6 billion multixacts. Although users can set |
| 9662 |
this value anywhere from zero to 2.1 billion, |
| 9663 |
<command>VACUUM</command> will silently adjust the effective |
| 9664 |
value to no less than 105% of <xref |
| 9665 |
linkend="guc-autovacuum-multixact-freeze-max-age"/>. |
| 9666 |
</para> |
| 9667 |
</listitem> |
| 9668 |
</varlistentry> |
| 9669 |
|
| 9670 |
<varlistentry id="guc-vacuum-max-eager-freeze-failure-rate" xreflabel="vacuum_max_eager_freeze_failure_rate"> |
| 9671 |
<term><varname>vacuum_max_eager_freeze_failure_rate</varname> (<type>floating point</type>) |
| 9672 |
<indexterm> |
| 9673 |
<primary><varname>vacuum_max_eager_freeze_failure_rate</varname></primary> |
| 9674 |
<secondary>configuration parameter</secondary> |
| 9675 |
</indexterm> |
| 9676 |
</term> |
| 9677 |
<listitem> |
| 9678 |
<para> |
| 9679 |
Specifies the maximum number of pages (as a fraction of total pages in |
| 9680 |
the relation) that <command>VACUUM</command> may scan and |
| 9681 |
<emphasis>fail</emphasis> to set all-frozen in the visibility map |
| 9682 |
before disabling eager scanning. A value of <literal>0</literal> |
| 9683 |
disables eager scanning altogether. The default is |
| 9684 |
<literal>0.03</literal> (3%). |
| 9685 |
</para> |
| 9686 |
|
| 9687 |
<para> |
| 9688 |
Note that when eager scanning is enabled, only freeze failures |
| 9689 |
count against the cap, not successful freezing. Successful page |
| 9690 |
freezes are capped internally at 20% of the all-visible but not |
| 9691 |
all-frozen pages in the relation. Capping successful page freezes helps |
| 9692 |
amortize the overhead across multiple normal vacuums and limits the |
| 9693 |
potential downside of wasted eager freezes of pages that are modified |
| 9694 |
again before the next aggressive vacuum. |
| 9695 |
</para> |
| 9696 |
|
| 9697 |
<para> |
| 9698 |
This parameter can only be set in the |
| 9699 |
<filename>postgresql.conf</filename> file or on the server command |
| 9700 |
line; but the setting can be overridden for individual tables by |
| 9701 |
changing the |
| 9702 |
<link linkend="reloption-vacuum-max-eager-freeze-failure-rate"> |
| 9703 |
corresponding table storage parameter</link>. |
| 9704 |
For more information on tuning vacuum's freezing behavior, |
| 9705 |
see <xref linkend="vacuum-for-wraparound"/>. |
| 9706 |
</para> |
| 9707 |
</listitem> |
| 9708 |
</varlistentry> |
| 9709 |
|
| 9710 |
</variablelist> |
| 9711 |
</sect2> |
| 9712 |
</sect1> |
| 9713 |
|
| 9714 |
<sect1 id="runtime-config-client"> |
| 9715 |
<title>Client Connection Defaults</title> |
| 9716 |
|
| 9717 |
<sect2 id="runtime-config-client-statement"> |
| 9718 |
<title>Statement Behavior</title> |
| 9719 |
<variablelist> |
| 9720 |
|
| 9721 |
<varlistentry id="guc-client-min-messages" xreflabel="client_min_messages"> |
| 9722 |
<term><varname>client_min_messages</varname> (<type>enum</type>) |
| 9723 |
<indexterm> |
| 9724 |
<primary><varname>client_min_messages</varname> configuration parameter</primary> |
| 9725 |
</indexterm> |
| 9726 |
</term> |
| 9727 |
<listitem> |
| 9728 |
<para> |
| 9729 |
Controls which |
| 9730 |
<link linkend="runtime-config-severity-levels">message levels</link> |
| 9731 |
are sent to the client. |
| 9732 |
Valid values are <literal>DEBUG5</literal>, |
| 9733 |
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>, <literal>DEBUG2</literal>, |
| 9734 |
<literal>DEBUG1</literal>, <literal>LOG</literal>, <literal>NOTICE</literal>, |
| 9735 |
<literal>WARNING</literal>, and <literal>ERROR</literal>. |
| 9736 |
Each level includes all the levels that follow it. The later the level, |
| 9737 |
the fewer messages are sent. The default is |
| 9738 |
<literal>NOTICE</literal>. Note that <literal>LOG</literal> has a different |
| 9739 |
rank here than in <xref linkend="guc-log-min-messages"/>. |
| 9740 |
</para> |
| 9741 |
<para> |
| 9742 |
<literal>INFO</literal> level messages are always sent to the client. |
| 9743 |
</para> |
| 9744 |
</listitem> |
| 9745 |
</varlistentry> |
| 9746 |
|
| 9747 |
<varlistentry id="guc-search-path" xreflabel="search_path"> |
| 9748 |
<term><varname>search_path</varname> (<type>string</type>) |
| 9749 |
<indexterm> |
| 9750 |
<primary><varname>search_path</varname> configuration parameter</primary> |
| 9751 |
</indexterm> |
| 9752 |
<indexterm><primary>path</primary><secondary>for schemas</secondary></indexterm> |
| 9753 |
</term> |
| 9754 |
<listitem> |
| 9755 |
<para> |
| 9756 |
This variable specifies the order in which schemas are searched |
| 9757 |
when an object (table, data type, function, etc.) is referenced by a |
| 9758 |
simple name with no schema specified. When there are objects of |
| 9759 |
identical names in different schemas, the one found first |
| 9760 |
in the search path is used. An object that is not in any of the |
| 9761 |
schemas in the search path can only be referenced by specifying |
| 9762 |
its containing schema with a qualified (dotted) name. |
| 9763 |
</para> |
| 9764 |
|
| 9765 |
<para> |
| 9766 |
The value for <varname>search_path</varname> must be a comma-separated |
| 9767 |
list of schema names. Any name that is not an existing schema, or is |
| 9768 |
a schema for which the user does not have <literal>USAGE</literal> |
| 9769 |
permission, is silently ignored. |
| 9770 |
</para> |
| 9771 |
|
| 9772 |
<para> |
| 9773 |
If one of the list items is the special name |
| 9774 |
<literal>$user</literal>, then the schema having the name returned by |
| 9775 |
<function>CURRENT_USER</function> is substituted, if there is such a schema |
| 9776 |
and the user has <literal>USAGE</literal> permission for it. |
| 9777 |
(If not, <literal>$user</literal> is ignored.) |
| 9778 |
</para> |
| 9779 |
|
| 9780 |
<para> |
| 9781 |
The system catalog schema, <literal>pg_catalog</literal>, is always |
| 9782 |
searched, whether it is mentioned in the path or not. If it is |
| 9783 |
mentioned in the path then it will be searched in the specified |
| 9784 |
order. If <literal>pg_catalog</literal> is not in the path then it will |
| 9785 |
be searched <emphasis>before</emphasis> searching any of the path items. |
| 9786 |
</para> |
| 9787 |
|
| 9788 |
<!-- To further split hairs, funcname('foo') does not use the temporary |
| 9789 |
schema, even when it considers typname='funcname'. This paragraph |
| 9790 |
refers to function names in a loose sense, "pg_proc.proname or |
| 9791 |
func_name grammar production". --> |
| 9792 |
<para> |
| 9793 |
Likewise, the current session's temporary-table schema, |
| 9794 |
<literal>pg_temp_<replaceable>nnn</replaceable></literal>, is always searched if it |
| 9795 |
exists. It can be explicitly listed in the path by using the |
| 9796 |
alias <literal>pg_temp</literal><indexterm><primary>pg_temp</primary></indexterm>. If it is not listed in the path then |
| 9797 |
it is searched first (even before <literal>pg_catalog</literal>). However, |
| 9798 |
the temporary schema is only searched for relation (table, view, |
| 9799 |
sequence, etc.) and data type names. It is never searched for |
| 9800 |
function or operator names. |
| 9801 |
</para> |
| 9802 |
|
| 9803 |
<para> |
| 9804 |
When objects are created without specifying a particular target |
| 9805 |
schema, they will be placed in the first valid schema named in |
| 9806 |
<varname>search_path</varname>. An error is reported if the search |
| 9807 |
path is empty. |
| 9808 |
</para> |
| 9809 |
|
| 9810 |
<para> |
| 9811 |
The default value for this parameter is |
| 9812 |
<literal>"$user", public</literal>. |
| 9813 |
This setting supports shared use of a database (where no users |
| 9814 |
have private schemas, and all share use of <literal>public</literal>), |
| 9815 |
private per-user schemas, and combinations of these. Other |
| 9816 |
effects can be obtained by altering the default search path |
| 9817 |
setting, either globally or per-user. |
| 9818 |
</para> |
| 9819 |
|
| 9820 |
<para> |
| 9821 |
For more information on schema handling, see |
| 9822 |
<xref linkend="ddl-schemas"/>. In particular, the default |
| 9823 |
configuration is suitable only when the database has a single user or |
| 9824 |
a few mutually-trusting users. |
| 9825 |
</para> |
| 9826 |
|
| 9827 |
<para> |
| 9828 |
The current effective value of the search path can be examined |
| 9829 |
via the <acronym>SQL</acronym> function |
| 9830 |
<function>current_schemas</function> |
| 9831 |
(see <xref linkend="functions-info"/>). |
| 9832 |
This is not quite the same as |
| 9833 |
examining the value of <varname>search_path</varname>, since |
| 9834 |
<function>current_schemas</function> shows how the items |
| 9835 |
appearing in <varname>search_path</varname> were resolved. |
| 9836 |
</para> |
| 9837 |
|
| 9838 |
</listitem> |
| 9839 |
</varlistentry> |
| 9840 |
|
| 9841 |
<varlistentry id="guc-row-security" xreflabel="row_security"> |
| 9842 |
<term><varname>row_security</varname> (<type>boolean</type>) |
| 9843 |
<indexterm> |
| 9844 |
<primary><varname>row_security</varname> configuration parameter</primary> |
| 9845 |
</indexterm> |
| 9846 |
</term> |
| 9847 |
<listitem> |
| 9848 |
<para> |
| 9849 |
This variable controls whether to raise an error in lieu of applying a |
| 9850 |
row security policy. When set to <literal>on</literal>, policies apply |
| 9851 |
normally. When set to <literal>off</literal>, queries fail which would |
| 9852 |
otherwise apply at least one policy. The default is <literal>on</literal>. |
| 9853 |
Change to <literal>off</literal> where limited row visibility could cause |
| 9854 |
incorrect results; for example, <application>pg_dump</application> makes that |
| 9855 |
change by default. This variable has no effect on roles which bypass |
| 9856 |
every row security policy, to wit, superusers and roles with |
| 9857 |
the <literal>BYPASSRLS</literal> attribute. |
| 9858 |
</para> |
| 9859 |
|
| 9860 |
<para> |
| 9861 |
For more information on row security policies, |
| 9862 |
see <xref linkend="sql-createpolicy"/>. |
| 9863 |
</para> |
| 9864 |
</listitem> |
| 9865 |
</varlistentry> |
| 9866 |
|
| 9867 |
<varlistentry id="guc-default-table-access-method" xreflabel="default_table_access_method"> |
| 9868 |
<term><varname>default_table_access_method</varname> (<type>string</type>) |
| 9869 |
<indexterm> |
| 9870 |
<primary><varname>default_table_access_method</varname> configuration parameter</primary> |
| 9871 |
</indexterm> |
| 9872 |
</term> |
| 9873 |
<listitem> |
| 9874 |
<para> |
| 9875 |
This parameter specifies the default table access method to use when |
| 9876 |
creating tables or materialized views if the <command>CREATE</command> |
| 9877 |
command does not explicitly specify an access method, or when |
| 9878 |
<command>SELECT ... INTO</command> is used, which does not allow |
| 9879 |
specifying a table access method. The default is <literal>heap</literal>. |
| 9880 |
</para> |
| 9881 |
</listitem> |
| 9882 |
</varlistentry> |
| 9883 |
|
| 9884 |
<varlistentry id="guc-default-tablespace" xreflabel="default_tablespace"> |
| 9885 |
<term><varname>default_tablespace</varname> (<type>string</type>) |
| 9886 |
<indexterm> |
| 9887 |
<primary><varname>default_tablespace</varname> configuration parameter</primary> |
| 9888 |
</indexterm> |
| 9889 |
<indexterm><primary>tablespace</primary><secondary>default</secondary></indexterm> |
| 9890 |
</term> |
| 9891 |
<listitem> |
| 9892 |
<para> |
| 9893 |
This variable specifies the default tablespace in which to create |
| 9894 |
objects (tables and indexes) when a <command>CREATE</command> command does |
| 9895 |
not explicitly specify a tablespace. |
| 9896 |
</para> |
| 9897 |
|
| 9898 |
<para> |
| 9899 |
The value is either the name of a tablespace, or an empty string |
| 9900 |
to specify using the default tablespace of the current database. |
| 9901 |
If the value does not match the name of any existing tablespace, |
| 9902 |
<productname>PostgreSQL</productname> will automatically use the default |
| 9903 |
tablespace of the current database. If a nondefault tablespace |
| 9904 |
is specified, the user must have <literal>CREATE</literal> privilege |
| 9905 |
for it, or creation attempts will fail. |
| 9906 |
</para> |
| 9907 |
|
| 9908 |
<para> |
| 9909 |
This variable is not used for temporary tables; for them, |
| 9910 |
<xref linkend="guc-temp-tablespaces"/> is consulted instead. |
| 9911 |
</para> |
| 9912 |
|
| 9913 |
<para> |
| 9914 |
This variable is also not used when creating databases. |
| 9915 |
By default, a new database inherits its tablespace setting from |
| 9916 |
the template database it is copied from. |
| 9917 |
</para> |
| 9918 |
|
| 9919 |
<para> |
| 9920 |
If this parameter is set to a value other than the empty string |
| 9921 |
when a partitioned table is created, the partitioned table's |
| 9922 |
tablespace will be set to that value, which will be used as |
| 9923 |
the default tablespace for partitions created in the future, |
| 9924 |
even if <varname>default_tablespace</varname> has changed since then. |
| 9925 |
</para> |
| 9926 |
|
| 9927 |
<para> |
| 9928 |
For more information on tablespaces, |
| 9929 |
see <xref linkend="manage-ag-tablespaces"/>. |
| 9930 |
</para> |
| 9931 |
</listitem> |
| 9932 |
</varlistentry> |
| 9933 |
|
| 9934 |
<varlistentry id="guc-default-toast-compression" xreflabel="default_toast_compression"> |
| 9935 |
<term><varname>default_toast_compression</varname> (<type>enum</type>) |
| 9936 |
<indexterm> |
| 9937 |
<primary><varname>default_toast_compression</varname> configuration parameter</primary> |
| 9938 |
</indexterm> |
| 9939 |
</term> |
| 9940 |
<listitem> |
| 9941 |
<para> |
| 9942 |
This variable sets the default |
| 9943 |
<link linkend="storage-toast">TOAST</link> |
| 9944 |
compression method for values of compressible columns. |
| 9945 |
(This can be overridden for individual columns by setting |
| 9946 |
the <literal>COMPRESSION</literal> column option in |
| 9947 |
<command>CREATE TABLE</command> or |
| 9948 |
<command>ALTER TABLE</command>.) |
| 9949 |
The supported compression methods are <literal>pglz</literal> and |
| 9950 |
(if <productname>PostgreSQL</productname> was compiled with |
| 9951 |
<option>--with-lz4</option>) <literal>lz4</literal>. |
| 9952 |
The default is <literal>pglz</literal>. |
| 9953 |
</para> |
| 9954 |
</listitem> |
| 9955 |
</varlistentry> |
| 9956 |
|
| 9957 |
<varlistentry id="guc-temp-tablespaces" xreflabel="temp_tablespaces"> |
| 9958 |
<term><varname>temp_tablespaces</varname> (<type>string</type>) |
| 9959 |
<indexterm> |
| 9960 |
<primary><varname>temp_tablespaces</varname> configuration parameter</primary> |
| 9961 |
</indexterm> |
| 9962 |
<indexterm><primary>tablespace</primary><secondary>temporary</secondary></indexterm> |
| 9963 |
</term> |
| 9964 |
<listitem> |
| 9965 |
<para> |
| 9966 |
This variable specifies tablespaces in which to create temporary |
| 9967 |
objects (temp tables and indexes on temp tables) when a |
| 9968 |
<command>CREATE</command> command does not explicitly specify a tablespace. |
| 9969 |
Temporary files for purposes such as sorting large data sets |
| 9970 |
are also created in these tablespaces. |
| 9971 |
</para> |
| 9972 |
|
| 9973 |
<para> |
| 9974 |
The value is a list of names of tablespaces. When there is more than |
| 9975 |
one name in the list, <productname>PostgreSQL</productname> chooses a random |
| 9976 |
member of the list each time a temporary object is to be created; |
| 9977 |
except that within a transaction, successively created temporary |
| 9978 |
objects are placed in successive tablespaces from the list. |
| 9979 |
If the selected element of the list is an empty string, |
| 9980 |
<productname>PostgreSQL</productname> will automatically use the default |
| 9981 |
tablespace of the current database instead. |
| 9982 |
</para> |
| 9983 |
|
| 9984 |
<para> |
| 9985 |
When <varname>temp_tablespaces</varname> is set interactively, specifying a |
| 9986 |
nonexistent tablespace is an error, as is specifying a tablespace for |
| 9987 |
which the user does not have <literal>CREATE</literal> privilege. However, |
| 9988 |
when using a previously set value, nonexistent tablespaces are |
| 9989 |
ignored, as are tablespaces for which the user lacks |
| 9990 |
<literal>CREATE</literal> privilege. In particular, this rule applies when |
| 9991 |
using a value set in <filename>postgresql.conf</filename>. |
| 9992 |
</para> |
| 9993 |
|
| 9994 |
<para> |
| 9995 |
The default value is an empty string, which results in all temporary |
| 9996 |
objects being created in the default tablespace of the current |
| 9997 |
database. |
| 9998 |
</para> |
| 9999 |
|
| 10000 |
<para> |
| 10001 |
See also <xref linkend="guc-default-tablespace"/>. |
| 10002 |
</para> |
| 10003 |
</listitem> |
| 10004 |
</varlistentry> |
| 10005 |
|
| 10006 |
<varlistentry id="guc-check-function-bodies" xreflabel="check_function_bodies"> |
| 10007 |
<term><varname>check_function_bodies</varname> (<type>boolean</type>) |
| 10008 |
<indexterm> |
| 10009 |
<primary><varname>check_function_bodies</varname> configuration parameter</primary> |
| 10010 |
</indexterm> |
| 10011 |
</term> |
| 10012 |
<listitem> |
| 10013 |
<para> |
| 10014 |
This parameter is normally on. When set to <literal>off</literal>, it |
| 10015 |
disables validation of the routine body string during <xref |
| 10016 |
linkend="sql-createfunction"/> and <xref |
| 10017 |
linkend="sql-createprocedure"/>. Disabling validation avoids side |
| 10018 |
effects of the validation process, in particular preventing false |
| 10019 |
positives due to problems such as forward references. |
| 10020 |
Set this parameter |
| 10021 |
to <literal>off</literal> before loading functions on behalf of other |
| 10022 |
users; <application>pg_dump</application> does so automatically. |
| 10023 |
</para> |
| 10024 |
</listitem> |
| 10025 |
</varlistentry> |
| 10026 |
|
| 10027 |
<varlistentry id="guc-default-transaction-isolation" xreflabel="default_transaction_isolation"> |
| 10028 |
<term><varname>default_transaction_isolation</varname> (<type>enum</type>) |
| 10029 |
<indexterm> |
| 10030 |
<primary>transaction isolation level</primary> |
| 10031 |
<secondary>setting default</secondary> |
| 10032 |
</indexterm> |
| 10033 |
<indexterm> |
| 10034 |
<primary><varname>default_transaction_isolation</varname> configuration parameter</primary> |
| 10035 |
</indexterm> |
| 10036 |
</term> |
| 10037 |
<listitem> |
| 10038 |
<para> |
| 10039 |
Each SQL transaction has an isolation level, which can be |
| 10040 |
either <quote>read uncommitted</quote>, <quote>read |
| 10041 |
committed</quote>, <quote>repeatable read</quote>, or |
| 10042 |
<quote>serializable</quote>. This parameter controls the |
| 10043 |
default isolation level of each new transaction. The default |
| 10044 |
is <quote>read committed</quote>. |
| 10045 |
</para> |
| 10046 |
|
| 10047 |
<para> |
| 10048 |
Consult <xref linkend="mvcc"/> and <xref |
| 10049 |
linkend="sql-set-transaction"/> for more information. |
| 10050 |
</para> |
| 10051 |
</listitem> |
| 10052 |
</varlistentry> |
| 10053 |
|
| 10054 |
<varlistentry id="guc-default-transaction-read-only" xreflabel="default_transaction_read_only"> |
| 10055 |
<term><varname>default_transaction_read_only</varname> (<type>boolean</type>) |
| 10056 |
<indexterm> |
| 10057 |
<primary>read-only transaction</primary> |
| 10058 |
<secondary>setting default</secondary> |
| 10059 |
</indexterm> |
| 10060 |
<indexterm> |
| 10061 |
<primary><varname>default_transaction_read_only</varname> configuration parameter</primary> |
| 10062 |
</indexterm> |
| 10063 |
</term> |
| 10064 |
<listitem> |
| 10065 |
<para> |
| 10066 |
A read-only SQL transaction cannot alter non-temporary tables. |
| 10067 |
This parameter controls the default read-only status of each new |
| 10068 |
transaction. The default is <literal>off</literal> (read/write). |
| 10069 |
</para> |
| 10070 |
|
| 10071 |
<para> |
| 10072 |
Consult <xref linkend="sql-set-transaction"/> for more information. |
| 10073 |
</para> |
| 10074 |
</listitem> |
| 10075 |
</varlistentry> |
| 10076 |
|
| 10077 |
<varlistentry id="guc-default-transaction-deferrable" xreflabel="default_transaction_deferrable"> |
| 10078 |
<term><varname>default_transaction_deferrable</varname> (<type>boolean</type>) |
| 10079 |
<indexterm> |
| 10080 |
<primary>deferrable transaction</primary> |
| 10081 |
<secondary>setting default</secondary> |
| 10082 |
</indexterm> |
| 10083 |
<indexterm> |
| 10084 |
<primary><varname>default_transaction_deferrable</varname> configuration parameter</primary> |
| 10085 |
</indexterm> |
| 10086 |
</term> |
| 10087 |
<listitem> |
| 10088 |
<para> |
| 10089 |
When running at the <literal>serializable</literal> isolation level, |
| 10090 |
a deferrable read-only SQL transaction may be delayed before |
| 10091 |
it is allowed to proceed. However, once it begins executing |
| 10092 |
it does not incur any of the overhead required to ensure |
| 10093 |
serializability; so serialization code will have no reason to |
| 10094 |
force it to abort because of concurrent updates, making this |
| 10095 |
option suitable for long-running read-only transactions. |
| 10096 |
</para> |
| 10097 |
|
| 10098 |
<para> |
| 10099 |
This parameter controls the default deferrable status of each |
| 10100 |
new transaction. It currently has no effect on read-write |
| 10101 |
transactions or those operating at isolation levels lower |
| 10102 |
than <literal>serializable</literal>. The default is <literal>off</literal>. |
| 10103 |
</para> |
| 10104 |
|
| 10105 |
<para> |
| 10106 |
Consult <xref linkend="sql-set-transaction"/> for more information. |
| 10107 |
</para> |
| 10108 |
</listitem> |
| 10109 |
</varlistentry> |
| 10110 |
|
| 10111 |
<varlistentry id="guc-transaction-isolation" xreflabel="transaction_isolation"> |
| 10112 |
<term><varname>transaction_isolation</varname> (<type>enum</type>) |
| 10113 |
<indexterm> |
| 10114 |
<primary>transaction isolation level</primary> |
| 10115 |
</indexterm> |
| 10116 |
<indexterm> |
| 10117 |
<primary><varname>transaction_isolation</varname> configuration parameter</primary> |
| 10118 |
</indexterm> |
| 10119 |
</term> |
| 10120 |
<listitem> |
| 10121 |
<para> |
| 10122 |
This parameter reflects the current transaction's isolation level. |
| 10123 |
At the beginning of each transaction, it is set to the current value |
| 10124 |
of <xref linkend="guc-default-transaction-isolation"/>. |
| 10125 |
Any subsequent attempt to change it is equivalent to a <xref |
| 10126 |
linkend="sql-set-transaction"/> command. |
| 10127 |
</para> |
| 10128 |
</listitem> |
| 10129 |
</varlistentry> |
| 10130 |
|
| 10131 |
<varlistentry id="guc-transaction-read-only" xreflabel="transaction_read_only"> |
| 10132 |
<term><varname>transaction_read_only</varname> (<type>boolean</type>) |
| 10133 |
<indexterm> |
| 10134 |
<primary>read-only transaction</primary> |
| 10135 |
</indexterm> |
| 10136 |
<indexterm> |
| 10137 |
<primary><varname>transaction_read_only</varname> configuration parameter</primary> |
| 10138 |
</indexterm> |
| 10139 |
</term> |
| 10140 |
<listitem> |
| 10141 |
<para> |
| 10142 |
This parameter reflects the current transaction's read-only status. |
| 10143 |
At the beginning of each transaction, it is set to the current value |
| 10144 |
of <xref linkend="guc-default-transaction-read-only"/>. |
| 10145 |
Any subsequent attempt to change it is equivalent to a <xref |
| 10146 |
linkend="sql-set-transaction"/> command. |
| 10147 |
</para> |
| 10148 |
</listitem> |
| 10149 |
</varlistentry> |
| 10150 |
|
| 10151 |
<varlistentry id="guc-transaction-deferrable" xreflabel="transaction_deferrable"> |
| 10152 |
<term><varname>transaction_deferrable</varname> (<type>boolean</type>) |
| 10153 |
<indexterm> |
| 10154 |
<primary>deferrable transaction</primary> |
| 10155 |
</indexterm> |
| 10156 |
<indexterm> |
| 10157 |
<primary><varname>transaction_deferrable</varname> configuration parameter</primary> |
| 10158 |
</indexterm> |
| 10159 |
</term> |
| 10160 |
<listitem> |
| 10161 |
<para> |
| 10162 |
This parameter reflects the current transaction's deferrability status. |
| 10163 |
At the beginning of each transaction, it is set to the current value |
| 10164 |
of <xref linkend="guc-default-transaction-deferrable"/>. |
| 10165 |
Any subsequent attempt to change it is equivalent to a <xref |
| 10166 |
linkend="sql-set-transaction"/> command. |
| 10167 |
</para> |
| 10168 |
</listitem> |
| 10169 |
</varlistentry> |
| 10170 |
|
| 10171 |
|
| 10172 |
<varlistentry id="guc-session-replication-role" xreflabel="session_replication_role"> |
| 10173 |
<term><varname>session_replication_role</varname> (<type>enum</type>) |
| 10174 |
<indexterm> |
| 10175 |
<primary><varname>session_replication_role</varname> configuration parameter</primary> |
| 10176 |
</indexterm> |
| 10177 |
</term> |
| 10178 |
<listitem> |
| 10179 |
<para> |
| 10180 |
Controls firing of replication-related triggers and rules for the |
| 10181 |
current session. |
| 10182 |
Possible values are <literal>origin</literal> (the default), |
| 10183 |
<literal>replica</literal> and <literal>local</literal>. |
| 10184 |
Setting this parameter results in discarding any previously cached |
| 10185 |
query plans. |
| 10186 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 10187 |
privilege can change this setting. |
| 10188 |
</para> |
| 10189 |
|
| 10190 |
<para> |
| 10191 |
The intended use of this setting is that logical replication systems |
| 10192 |
set it to <literal>replica</literal> when they are applying replicated |
| 10193 |
changes. The effect of that will be that triggers and rules (that |
| 10194 |
have not been altered from their default configuration) will not fire |
| 10195 |
on the replica. See the <link linkend="sql-altertable"><command>ALTER TABLE</command></link> clauses |
| 10196 |
<literal>ENABLE TRIGGER</literal> and <literal>ENABLE RULE</literal> |
| 10197 |
for more information. |
| 10198 |
</para> |
| 10199 |
|
| 10200 |
<para> |
| 10201 |
PostgreSQL treats the settings <literal>origin</literal> and |
| 10202 |
<literal>local</literal> the same internally. Third-party replication |
| 10203 |
systems may use these two values for their internal purposes, for |
| 10204 |
example using <literal>local</literal> to designate a session whose |
| 10205 |
changes should not be replicated. |
| 10206 |
</para> |
| 10207 |
|
| 10208 |
<para> |
| 10209 |
Since foreign keys are implemented as triggers, setting this parameter |
| 10210 |
to <literal>replica</literal> also disables all foreign key checks, |
| 10211 |
which can leave data in an inconsistent state if improperly used. |
| 10212 |
</para> |
| 10213 |
</listitem> |
| 10214 |
</varlistentry> |
| 10215 |
|
| 10216 |
<varlistentry id="guc-statement-timeout" xreflabel="statement_timeout"> |
| 10217 |
<term><varname>statement_timeout</varname> (<type>integer</type>) |
| 10218 |
<indexterm> |
| 10219 |
<primary><varname>statement_timeout</varname> configuration parameter</primary> |
| 10220 |
</indexterm> |
| 10221 |
</term> |
| 10222 |
<listitem> |
| 10223 |
<para> |
| 10224 |
Abort any statement that takes more than the specified amount of time. |
| 10225 |
If <varname>log_min_error_statement</varname> is set |
| 10226 |
to <literal>ERROR</literal> or lower, the statement that timed out |
| 10227 |
will also be logged. |
| 10228 |
If this value is specified without units, it is taken as milliseconds. |
| 10229 |
A value of zero (the default) disables the timeout. |
| 10230 |
</para> |
| 10231 |
|
| 10232 |
<para> |
| 10233 |
The timeout is measured from the time a command arrives at the |
| 10234 |
server until it is completed by the server. If multiple SQL |
| 10235 |
statements appear in a single simple-query message, the timeout |
| 10236 |
is applied to each statement separately. |
| 10237 |
(<productname>PostgreSQL</productname> versions before 13 usually |
| 10238 |
treated the timeout as applying to the whole query string.) |
| 10239 |
In extended query protocol, the timeout starts running when any |
| 10240 |
query-related message (Parse, Bind, Execute, Describe) arrives, and |
| 10241 |
it is canceled by completion of an Execute or Sync message. |
| 10242 |
</para> |
| 10243 |
|
| 10244 |
<para> |
| 10245 |
Setting <varname>statement_timeout</varname> in |
| 10246 |
<filename>postgresql.conf</filename> is not recommended because it would |
| 10247 |
affect all sessions. |
| 10248 |
</para> |
| 10249 |
</listitem> |
| 10250 |
</varlistentry> |
| 10251 |
|
| 10252 |
<varlistentry id="guc-transaction-timeout" xreflabel="transaction_timeout"> |
| 10253 |
<term><varname>transaction_timeout</varname> (<type>integer</type>) |
| 10254 |
<indexterm> |
| 10255 |
<primary><varname>transaction_timeout</varname> configuration parameter</primary> |
| 10256 |
</indexterm> |
| 10257 |
</term> |
| 10258 |
<listitem> |
| 10259 |
<para> |
| 10260 |
Terminate any session that spans longer than the specified amount of |
| 10261 |
time in a transaction. The limit applies both to explicit transactions |
| 10262 |
(started with <command>BEGIN</command>) and to an implicitly started |
| 10263 |
transaction corresponding to a single statement. |
| 10264 |
If this value is specified without units, it is taken as milliseconds. |
| 10265 |
A value of zero (the default) disables the timeout. |
| 10266 |
</para> |
| 10267 |
|
| 10268 |
<para> |
| 10269 |
If <varname>transaction_timeout</varname> is shorter or equal to |
| 10270 |
<varname>idle_in_transaction_session_timeout</varname> or <varname>statement_timeout</varname> |
| 10271 |
then the longer timeout is ignored. |
| 10272 |
</para> |
| 10273 |
|
| 10274 |
<para> |
| 10275 |
Setting <varname>transaction_timeout</varname> in |
| 10276 |
<filename>postgresql.conf</filename> is not recommended because it would |
| 10277 |
affect all sessions. |
| 10278 |
</para> |
| 10279 |
|
| 10280 |
<note> |
| 10281 |
<para> |
| 10282 |
Prepared transactions are not subject to this timeout. |
| 10283 |
</para> |
| 10284 |
</note> |
| 10285 |
</listitem> |
| 10286 |
</varlistentry> |
| 10287 |
|
| 10288 |
<varlistentry id="guc-lock-timeout" xreflabel="lock_timeout"> |
| 10289 |
<term><varname>lock_timeout</varname> (<type>integer</type>) |
| 10290 |
<indexterm> |
| 10291 |
<primary><varname>lock_timeout</varname> configuration parameter</primary> |
| 10292 |
</indexterm> |
| 10293 |
</term> |
| 10294 |
<listitem> |
| 10295 |
<para> |
| 10296 |
Abort any statement that waits longer than the specified amount of |
| 10297 |
time while attempting to acquire a lock on a table, index, |
| 10298 |
row, or other database object. The time limit applies separately to |
| 10299 |
each lock acquisition attempt. The limit applies both to explicit |
| 10300 |
locking requests (such as <command>LOCK TABLE</command>, or <command>SELECT |
| 10301 |
FOR UPDATE</command> without <literal>NOWAIT</literal>) and to implicitly-acquired |
| 10302 |
locks. |
| 10303 |
If this value is specified without units, it is taken as milliseconds. |
| 10304 |
A value of zero (the default) disables the timeout. |
| 10305 |
</para> |
| 10306 |
|
| 10307 |
<para> |
| 10308 |
Unlike <varname>statement_timeout</varname>, this timeout can only occur |
| 10309 |
while waiting for locks. Note that if <varname>statement_timeout</varname> |
| 10310 |
is nonzero, it is rather pointless to set <varname>lock_timeout</varname> to |
| 10311 |
the same or larger value, since the statement timeout would always |
| 10312 |
trigger first. If <varname>log_min_error_statement</varname> is set to |
| 10313 |
<literal>ERROR</literal> or lower, the statement that timed out will be |
| 10314 |
logged. |
| 10315 |
</para> |
| 10316 |
|
| 10317 |
<para> |
| 10318 |
Setting <varname>lock_timeout</varname> in |
| 10319 |
<filename>postgresql.conf</filename> is not recommended because it would |
| 10320 |
affect all sessions. |
| 10321 |
</para> |
| 10322 |
</listitem> |
| 10323 |
</varlistentry> |
| 10324 |
|
| 10325 |
<varlistentry id="guc-idle-in-transaction-session-timeout" xreflabel="idle_in_transaction_session_timeout"> |
| 10326 |
<term><varname>idle_in_transaction_session_timeout</varname> (<type>integer</type>) |
| 10327 |
<indexterm> |
| 10328 |
<primary><varname>idle_in_transaction_session_timeout</varname> configuration parameter</primary> |
| 10329 |
</indexterm> |
| 10330 |
</term> |
| 10331 |
<listitem> |
| 10332 |
<para> |
| 10333 |
Terminate any session that has been idle (that is, waiting for a |
| 10334 |
client query) within an open transaction for longer than the |
| 10335 |
specified amount of time. |
| 10336 |
If this value is specified without units, it is taken as milliseconds. |
| 10337 |
A value of zero (the default) disables the timeout. |
| 10338 |
</para> |
| 10339 |
|
| 10340 |
<para> |
| 10341 |
This option can be used to ensure that idle sessions do not hold |
| 10342 |
locks for an unreasonable amount of time. Even when no significant |
| 10343 |
locks are held, an open transaction prevents vacuuming away |
| 10344 |
recently-dead tuples that may be visible only to this transaction; |
| 10345 |
so remaining idle for a long time can contribute to table bloat. |
| 10346 |
See <xref linkend="routine-vacuuming"/> for more details. |
| 10347 |
</para> |
| 10348 |
</listitem> |
| 10349 |
</varlistentry> |
| 10350 |
|
| 10351 |
<varlistentry id="guc-idle-session-timeout" xreflabel="idle_session_timeout"> |
| 10352 |
<term><varname>idle_session_timeout</varname> (<type>integer</type>) |
| 10353 |
<indexterm> |
| 10354 |
<primary><varname>idle_session_timeout</varname> configuration parameter</primary> |
| 10355 |
</indexterm> |
| 10356 |
</term> |
| 10357 |
<listitem> |
| 10358 |
<para> |
| 10359 |
Terminate any session that has been idle (that is, waiting for a |
| 10360 |
client query), but not within an open transaction, for longer than |
| 10361 |
the specified amount of time. |
| 10362 |
If this value is specified without units, it is taken as milliseconds. |
| 10363 |
A value of zero (the default) disables the timeout. |
| 10364 |
</para> |
| 10365 |
|
| 10366 |
<para> |
| 10367 |
Unlike the case with an open transaction, an idle session without a |
| 10368 |
transaction imposes no large costs on the server, so there is less |
| 10369 |
need to enable this timeout |
| 10370 |
than <varname>idle_in_transaction_session_timeout</varname>. |
| 10371 |
</para> |
| 10372 |
|
| 10373 |
<para> |
| 10374 |
Be wary of enforcing this timeout on connections made through |
| 10375 |
connection-pooling software or other middleware, as such a layer |
| 10376 |
may not react well to unexpected connection closure. It may be |
| 10377 |
helpful to enable this timeout only for interactive sessions, |
| 10378 |
perhaps by applying it only to particular users. |
| 10379 |
</para> |
| 10380 |
</listitem> |
| 10381 |
</varlistentry> |
| 10382 |
|
| 10383 |
<varlistentry id="guc-bytea-output" xreflabel="bytea_output"> |
| 10384 |
<term><varname>bytea_output</varname> (<type>enum</type>) |
| 10385 |
<indexterm> |
| 10386 |
<primary><varname>bytea_output</varname> configuration parameter</primary> |
| 10387 |
</indexterm> |
| 10388 |
</term> |
| 10389 |
<listitem> |
| 10390 |
<para> |
| 10391 |
Sets the output format for values of type <type>bytea</type>. |
| 10392 |
Valid values are <literal>hex</literal> (the default) |
| 10393 |
and <literal>escape</literal> (the traditional PostgreSQL |
| 10394 |
format). See <xref linkend="datatype-binary"/> for more |
| 10395 |
information. The <type>bytea</type> type always |
| 10396 |
accepts both formats on input, regardless of this setting. |
| 10397 |
</para> |
| 10398 |
</listitem> |
| 10399 |
</varlistentry> |
| 10400 |
|
| 10401 |
<varlistentry id="guc-xmlbinary" xreflabel="xmlbinary"> |
| 10402 |
<term><varname>xmlbinary</varname> (<type>enum</type>) |
| 10403 |
<indexterm> |
| 10404 |
<primary><varname>xmlbinary</varname> configuration parameter</primary> |
| 10405 |
</indexterm> |
| 10406 |
</term> |
| 10407 |
<listitem> |
| 10408 |
<para> |
| 10409 |
Sets how binary values are to be encoded in XML. This applies |
| 10410 |
for example when <type>bytea</type> values are converted to |
| 10411 |
XML by the functions <function>xmlelement</function> or |
| 10412 |
<function>xmlforest</function>. Possible values are |
| 10413 |
<literal>base64</literal> and <literal>hex</literal>, which |
| 10414 |
are both defined in the XML Schema standard. The default is |
| 10415 |
<literal>base64</literal>. For further information about |
| 10416 |
XML-related functions, see <xref linkend="functions-xml"/>. |
| 10417 |
</para> |
| 10418 |
|
| 10419 |
<para> |
| 10420 |
The actual choice here is mostly a matter of taste, |
| 10421 |
constrained only by possible restrictions in client |
| 10422 |
applications. Both methods support all possible values, |
| 10423 |
although the hex encoding will be somewhat larger than the |
| 10424 |
base64 encoding. |
| 10425 |
</para> |
| 10426 |
</listitem> |
| 10427 |
</varlistentry> |
| 10428 |
|
| 10429 |
<varlistentry id="guc-xmloption" xreflabel="xmloption"> |
| 10430 |
<term><varname>xmloption</varname> (<type>enum</type>) |
| 10431 |
<indexterm> |
| 10432 |
<primary><varname>xmloption</varname> configuration parameter</primary> |
| 10433 |
</indexterm> |
| 10434 |
<indexterm> |
| 10435 |
<primary><varname>SET XML OPTION</varname></primary> |
| 10436 |
</indexterm> |
| 10437 |
<indexterm> |
| 10438 |
<primary>XML option</primary> |
| 10439 |
</indexterm> |
| 10440 |
</term> |
| 10441 |
<listitem> |
| 10442 |
<para> |
| 10443 |
Sets whether <literal>DOCUMENT</literal> or |
| 10444 |
<literal>CONTENT</literal> is implicit when converting between |
| 10445 |
XML and character string values. See <xref |
| 10446 |
linkend="datatype-xml"/> for a description of this. Valid |
| 10447 |
values are <literal>DOCUMENT</literal> and |
| 10448 |
<literal>CONTENT</literal>. The default is |
| 10449 |
<literal>CONTENT</literal>. |
| 10450 |
</para> |
| 10451 |
|
| 10452 |
<para> |
| 10453 |
According to the SQL standard, the command to set this option is |
| 10454 |
<synopsis> |
| 10455 |
SET XML OPTION { DOCUMENT | CONTENT }; |
| 10456 |
</synopsis> |
| 10457 |
This syntax is also available in PostgreSQL. |
| 10458 |
</para> |
| 10459 |
</listitem> |
| 10460 |
</varlistentry> |
| 10461 |
|
| 10462 |
<varlistentry id="guc-gin-pending-list-limit" xreflabel="gin_pending_list_limit"> |
| 10463 |
<term><varname>gin_pending_list_limit</varname> (<type>integer</type>) |
| 10464 |
<indexterm> |
| 10465 |
<primary><varname>gin_pending_list_limit</varname></primary> |
| 10466 |
<secondary>configuration parameter</secondary> |
| 10467 |
</indexterm> |
| 10468 |
</term> |
| 10469 |
<listitem> |
| 10470 |
<para> |
| 10471 |
Sets the maximum size of a GIN index's pending list, which is used |
| 10472 |
when <literal>fastupdate</literal> is enabled. If the list grows |
| 10473 |
larger than this maximum size, it is cleaned up by moving |
| 10474 |
the entries in it to the index's main GIN data structure in bulk. |
| 10475 |
If this value is specified without units, it is taken as kilobytes. |
| 10476 |
The default is four megabytes (<literal>4MB</literal>). This setting |
| 10477 |
can be overridden for individual GIN indexes by changing |
| 10478 |
index storage parameters. |
| 10479 |
See <xref linkend="gin-fast-update"/> and <xref linkend="gin-tips"/> |
| 10480 |
for more information. |
| 10481 |
</para> |
| 10482 |
</listitem> |
| 10483 |
</varlistentry> |
| 10484 |
|
| 10485 |
<varlistentry id="guc-createrole-self-grant" xreflabel="createrole_self_grant"> |
| 10486 |
<term><varname>createrole_self_grant</varname> (<type>string</type>) |
| 10487 |
<indexterm> |
| 10488 |
<primary><varname>createrole_self_grant</varname></primary> |
| 10489 |
<secondary>configuration parameter</secondary> |
| 10490 |
</indexterm> |
| 10491 |
</term> |
| 10492 |
<listitem> |
| 10493 |
<para> |
| 10494 |
If a user who has <literal>CREATEROLE</literal> but not |
| 10495 |
<literal>SUPERUSER</literal> creates a role, and if this |
| 10496 |
is set to a non-empty value, the newly-created role will be granted |
| 10497 |
to the creating user with the options specified. The value must be |
| 10498 |
<literal>set</literal>, <literal>inherit</literal>, or a |
| 10499 |
comma-separated list of these. The default value is an empty string, |
| 10500 |
which disables the feature. |
| 10501 |
</para> |
| 10502 |
<para> |
| 10503 |
The purpose of this option is to allow a <literal>CREATEROLE</literal> |
| 10504 |
user who is not a superuser to automatically inherit, or automatically |
| 10505 |
gain the ability to <literal>SET ROLE</literal> to, any created users. |
| 10506 |
Since a <literal>CREATEROLE</literal> user is always implicitly granted |
| 10507 |
<literal>ADMIN OPTION</literal> on created roles, that user could |
| 10508 |
always execute a <literal>GRANT</literal> statement that would achieve |
| 10509 |
the same effect as this setting. However, it can be convenient for |
| 10510 |
usability reasons if the grant happens automatically. A superuser |
| 10511 |
automatically inherits the privileges of every role and can always |
| 10512 |
<literal>SET ROLE</literal> to any role, and this setting can be used |
| 10513 |
to produce a similar behavior for <literal>CREATEROLE</literal> users |
| 10514 |
for users which they create. |
| 10515 |
</para> |
| 10516 |
</listitem> |
| 10517 |
</varlistentry> |
| 10518 |
|
| 10519 |
<varlistentry id="guc-event-triggers" xreflabel="event_triggers"> |
| 10520 |
<term><varname>event_triggers</varname> (<type>boolean</type>) |
| 10521 |
<indexterm> |
| 10522 |
<primary><varname>event_triggers</varname></primary> |
| 10523 |
<secondary>configuration parameter</secondary> |
| 10524 |
</indexterm> |
| 10525 |
</term> |
| 10526 |
<listitem> |
| 10527 |
<para> |
| 10528 |
Allow temporarily disabling execution of event triggers in order to |
| 10529 |
troubleshoot and repair faulty event triggers. All event triggers will |
| 10530 |
be disabled by setting it to <literal>false</literal>. Setting the value |
| 10531 |
to <literal>true</literal> allows all event triggers to fire, this |
| 10532 |
is the default value. Only superusers and users with the appropriate |
| 10533 |
<literal>SET</literal> privilege can change this setting. |
| 10534 |
</para> |
| 10535 |
</listitem> |
| 10536 |
</varlistentry> |
| 10537 |
|
| 10538 |
<varlistentry id="guc-restrict-nonsystem-relation-kind" xreflabel="restrict_nonsystem_relation_kind"> |
| 10539 |
<term><varname>restrict_nonsystem_relation_kind</varname> (<type>string</type>) |
| 10540 |
<indexterm> |
| 10541 |
<primary><varname>restrict_nonsystem_relation_kind</varname></primary> |
| 10542 |
<secondary>configuration parameter</secondary> |
| 10543 |
</indexterm> |
| 10544 |
</term> |
| 10545 |
<listitem> |
| 10546 |
<para> |
| 10547 |
Set relation kinds for which access to non-system relations is prohibited. |
| 10548 |
The value takes the form of a comma-separated list of relation kinds. |
| 10549 |
Currently, the supported relation kinds are <literal>view</literal> and |
| 10550 |
<literal>foreign-table</literal>. |
| 10551 |
</para> |
| 10552 |
</listitem> |
| 10553 |
</varlistentry> |
| 10554 |
|
| 10555 |
</variablelist> |
| 10556 |
</sect2> |
| 10557 |
<sect2 id="runtime-config-client-format"> |
| 10558 |
<title>Locale and Formatting</title> |
| 10559 |
|
| 10560 |
<variablelist> |
| 10561 |
|
| 10562 |
<varlistentry id="guc-datestyle" xreflabel="DateStyle"> |
| 10563 |
<term><varname>DateStyle</varname> (<type>string</type>) |
| 10564 |
<indexterm> |
| 10565 |
<primary><varname>DateStyle</varname> configuration parameter</primary> |
| 10566 |
</indexterm> |
| 10567 |
</term> |
| 10568 |
<listitem> |
| 10569 |
<para> |
| 10570 |
Sets the display format for date and time values, as well as the |
| 10571 |
rules for interpreting ambiguous date input values. For |
| 10572 |
historical reasons, this variable contains two independent |
| 10573 |
components: the output format specification (<literal>ISO</literal>, |
| 10574 |
<literal>Postgres</literal>, <literal>SQL</literal>, or <literal>German</literal>) |
| 10575 |
and the input/output specification for year/month/day ordering |
| 10576 |
(<literal>DMY</literal>, <literal>MDY</literal>, or <literal>YMD</literal>). These |
| 10577 |
can be set separately or together. The keywords <literal>Euro</literal> |
| 10578 |
and <literal>European</literal> are synonyms for <literal>DMY</literal>; the |
| 10579 |
keywords <literal>US</literal>, <literal>NonEuro</literal>, and |
| 10580 |
<literal>NonEuropean</literal> are synonyms for <literal>MDY</literal>. See |
| 10581 |
<xref linkend="datatype-datetime"/> for more information. The |
| 10582 |
built-in default is <literal>ISO, MDY</literal>, but |
| 10583 |
<application>initdb</application> will initialize the |
| 10584 |
configuration file with a setting that corresponds to the |
| 10585 |
behavior of the chosen <varname>lc_time</varname> locale. |
| 10586 |
</para> |
| 10587 |
</listitem> |
| 10588 |
</varlistentry> |
| 10589 |
|
| 10590 |
<varlistentry id="guc-intervalstyle" xreflabel="IntervalStyle"> |
| 10591 |
<term><varname>IntervalStyle</varname> (<type>enum</type>) |
| 10592 |
<indexterm> |
| 10593 |
<primary><varname>IntervalStyle</varname> configuration parameter</primary> |
| 10594 |
</indexterm> |
| 10595 |
</term> |
| 10596 |
<listitem> |
| 10597 |
<para> |
| 10598 |
Sets the display format for interval values. |
| 10599 |
The value <literal>sql_standard</literal> will produce |
| 10600 |
output matching <acronym>SQL</acronym> standard interval literals. |
| 10601 |
The value <literal>postgres</literal> (which is the default) will produce |
| 10602 |
output matching <productname>PostgreSQL</productname> releases prior to 8.4 |
| 10603 |
when the <xref linkend="guc-datestyle"/> |
| 10604 |
parameter was set to <literal>ISO</literal>. |
| 10605 |
The value <literal>postgres_verbose</literal> will produce output |
| 10606 |
matching <productname>PostgreSQL</productname> releases prior to 8.4 |
| 10607 |
when the <varname>DateStyle</varname> |
| 10608 |
parameter was set to non-<literal>ISO</literal> output. |
| 10609 |
The value <literal>iso_8601</literal> will produce output matching the time |
| 10610 |
interval <quote>format with designators</quote> defined in section |
| 10611 |
4.4.3.2 of ISO 8601. |
| 10612 |
</para> |
| 10613 |
<para> |
| 10614 |
The <varname>IntervalStyle</varname> parameter also affects the |
| 10615 |
interpretation of ambiguous interval input. See |
| 10616 |
<xref linkend="datatype-interval-input"/> for more information. |
| 10617 |
</para> |
| 10618 |
</listitem> |
| 10619 |
</varlistentry> |
| 10620 |
|
| 10621 |
<varlistentry id="guc-timezone" xreflabel="TimeZone"> |
| 10622 |
<term><varname>TimeZone</varname> (<type>string</type>) |
| 10623 |
<indexterm> |
| 10624 |
<primary><varname>TimeZone</varname> configuration parameter</primary> |
| 10625 |
</indexterm> |
| 10626 |
<indexterm><primary>time zone</primary></indexterm> |
| 10627 |
</term> |
| 10628 |
<listitem> |
| 10629 |
<para> |
| 10630 |
Sets the time zone for displaying and interpreting time stamps. |
| 10631 |
The built-in default is <literal>GMT</literal>, but that is typically |
| 10632 |
overridden in <filename>postgresql.conf</filename>; <application>initdb</application> |
| 10633 |
will install a setting there corresponding to its system environment. |
| 10634 |
See <xref linkend="datatype-timezones"/> for more information. |
| 10635 |
</para> |
| 10636 |
</listitem> |
| 10637 |
</varlistentry> |
| 10638 |
|
| 10639 |
<varlistentry id="guc-timezone-abbreviations" xreflabel="timezone_abbreviations"> |
| 10640 |
<term><varname>timezone_abbreviations</varname> (<type>string</type>) |
| 10641 |
<indexterm> |
| 10642 |
<primary><varname>timezone_abbreviations</varname> configuration parameter</primary> |
| 10643 |
</indexterm> |
| 10644 |
<indexterm><primary>time zone names</primary></indexterm> |
| 10645 |
</term> |
| 10646 |
<listitem> |
| 10647 |
<para> |
| 10648 |
Sets the collection of additional time zone abbreviations that |
| 10649 |
will be accepted by the server for datetime input (beyond any |
| 10650 |
abbreviations defined by the current <varname>TimeZone</varname> |
| 10651 |
setting). The default is <literal>'Default'</literal>, |
| 10652 |
which is a collection that works in most of the world; there are |
| 10653 |
also <literal>'Australia'</literal> and <literal>'India'</literal>, |
| 10654 |
and other collections can be defined for a particular installation. |
| 10655 |
See <xref linkend="datetime-config-files"/> for more information. |
| 10656 |
</para> |
| 10657 |
</listitem> |
| 10658 |
</varlistentry> |
| 10659 |
|
| 10660 |
<varlistentry id="guc-extra-float-digits" xreflabel="extra_float_digits"> |
| 10661 |
<term><varname>extra_float_digits</varname> (<type>integer</type>) |
| 10662 |
<indexterm> |
| 10663 |
<primary>significant digits</primary> |
| 10664 |
</indexterm> |
| 10665 |
<indexterm> |
| 10666 |
<primary>floating-point</primary> |
| 10667 |
<secondary>display</secondary> |
| 10668 |
</indexterm> |
| 10669 |
<indexterm> |
| 10670 |
<primary><varname>extra_float_digits</varname> configuration parameter</primary> |
| 10671 |
</indexterm> |
| 10672 |
</term> |
| 10673 |
<listitem> |
| 10674 |
<para> |
| 10675 |
This parameter adjusts the number of digits used for textual output of |
| 10676 |
floating-point values, including <type>float4</type>, <type>float8</type>, |
| 10677 |
and geometric data types. |
| 10678 |
</para> |
| 10679 |
<para> |
| 10680 |
If the value is 1 (the default) or above, float values are output in |
| 10681 |
shortest-precise format; see <xref linkend="datatype-float"/>. The |
| 10682 |
actual number of digits generated depends only on the value being |
| 10683 |
output, not on the value of this parameter. At most 17 digits are |
| 10684 |
required for <type>float8</type> values, and 9 for <type>float4</type> |
| 10685 |
values. This format is both fast and precise, preserving the original |
| 10686 |
binary float value exactly when correctly read. For historical |
| 10687 |
compatibility, values up to 3 are permitted. |
| 10688 |
</para> |
| 10689 |
<para> |
| 10690 |
If the value is zero or negative, then the output is rounded to a |
| 10691 |
given decimal precision. The precision used is the standard number of |
| 10692 |
digits for the type (<literal>FLT_DIG</literal> |
| 10693 |
or <literal>DBL_DIG</literal> as appropriate) reduced according to the |
| 10694 |
value of this parameter. (For example, specifying -1 will cause |
| 10695 |
<type>float4</type> values to be output rounded to 5 significant |
| 10696 |
digits, and <type>float8</type> values |
| 10697 |
rounded to 14 digits.) This format is slower and does not preserve all |
| 10698 |
the bits of the binary float value, but may be more human-readable. |
| 10699 |
</para> |
| 10700 |
<note> |
| 10701 |
<para> |
| 10702 |
The meaning of this parameter, and its default value, changed |
| 10703 |
in <productname>PostgreSQL</productname> 12; |
| 10704 |
see <xref linkend="datatype-float"/> for further discussion. |
| 10705 |
</para> |
| 10706 |
</note> |
| 10707 |
</listitem> |
| 10708 |
</varlistentry> |
| 10709 |
|
| 10710 |
<varlistentry id="guc-client-encoding" xreflabel="client_encoding"> |
| 10711 |
<term><varname>client_encoding</varname> (<type>string</type>) |
| 10712 |
<indexterm> |
| 10713 |
<primary><varname>client_encoding</varname> configuration parameter</primary> |
| 10714 |
</indexterm> |
| 10715 |
<indexterm><primary>character set</primary></indexterm> |
| 10716 |
</term> |
| 10717 |
<listitem> |
| 10718 |
<para> |
| 10719 |
Sets the client-side encoding (character set). |
| 10720 |
The default is to use the database encoding. |
| 10721 |
The character sets supported by the <productname>PostgreSQL</productname> |
| 10722 |
server are described in <xref linkend="multibyte-charset-supported"/>. |
| 10723 |
</para> |
| 10724 |
</listitem> |
| 10725 |
</varlistentry> |
| 10726 |
|
| 10727 |
<varlistentry id="guc-lc-messages" xreflabel="lc_messages"> |
| 10728 |
<term><varname>lc_messages</varname> (<type>string</type>) |
| 10729 |
<indexterm> |
| 10730 |
<primary><varname>lc_messages</varname> configuration parameter</primary> |
| 10731 |
</indexterm> |
| 10732 |
</term> |
| 10733 |
<listitem> |
| 10734 |
<para> |
| 10735 |
Sets the language in which messages are displayed. Acceptable |
| 10736 |
values are system-dependent; see <xref linkend="locale"/> for |
| 10737 |
more information. If this variable is set to the empty string |
| 10738 |
(which is the default) then the value is inherited from the |
| 10739 |
execution environment of the server in a system-dependent way. |
| 10740 |
</para> |
| 10741 |
|
| 10742 |
<para> |
| 10743 |
On some systems, this locale category does not exist. Setting |
| 10744 |
this variable will still work, but there will be no effect. |
| 10745 |
Also, there is a chance that no translated messages for the |
| 10746 |
desired language exist. In that case you will continue to see |
| 10747 |
the English messages. |
| 10748 |
</para> |
| 10749 |
|
| 10750 |
<para> |
| 10751 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 10752 |
privilege can change this setting. |
| 10753 |
</para> |
| 10754 |
</listitem> |
| 10755 |
</varlistentry> |
| 10756 |
|
| 10757 |
<varlistentry id="guc-lc-monetary" xreflabel="lc_monetary"> |
| 10758 |
<term><varname>lc_monetary</varname> (<type>string</type>) |
| 10759 |
<indexterm> |
| 10760 |
<primary><varname>lc_monetary</varname> configuration parameter</primary> |
| 10761 |
</indexterm> |
| 10762 |
</term> |
| 10763 |
<listitem> |
| 10764 |
<para> |
| 10765 |
Sets the locale to use for formatting monetary amounts, for |
| 10766 |
example with the <function>to_char</function> family of |
| 10767 |
functions. Acceptable values are system-dependent; see <xref |
| 10768 |
linkend="locale"/> for more information. If this variable is |
| 10769 |
set to the empty string (which is the default) then the value |
| 10770 |
is inherited from the execution environment of the server in a |
| 10771 |
system-dependent way. |
| 10772 |
</para> |
| 10773 |
</listitem> |
| 10774 |
</varlistentry> |
| 10775 |
|
| 10776 |
<varlistentry id="guc-lc-numeric" xreflabel="lc_numeric"> |
| 10777 |
<term><varname>lc_numeric</varname> (<type>string</type>) |
| 10778 |
<indexterm> |
| 10779 |
<primary><varname>lc_numeric</varname> configuration parameter</primary> |
| 10780 |
</indexterm> |
| 10781 |
</term> |
| 10782 |
<listitem> |
| 10783 |
<para> |
| 10784 |
Sets the locale to use for formatting numbers, for example |
| 10785 |
with the <function>to_char</function> family of |
| 10786 |
functions. Acceptable values are system-dependent; see <xref |
| 10787 |
linkend="locale"/> for more information. If this variable is |
| 10788 |
set to the empty string (which is the default) then the value |
| 10789 |
is inherited from the execution environment of the server in a |
| 10790 |
system-dependent way. |
| 10791 |
</para> |
| 10792 |
</listitem> |
| 10793 |
</varlistentry> |
| 10794 |
|
| 10795 |
<varlistentry id="guc-lc-time" xreflabel="lc_time"> |
| 10796 |
<term><varname>lc_time</varname> (<type>string</type>) |
| 10797 |
<indexterm> |
| 10798 |
<primary><varname>lc_time</varname> configuration parameter</primary> |
| 10799 |
</indexterm> |
| 10800 |
</term> |
| 10801 |
<listitem> |
| 10802 |
<para> |
| 10803 |
Sets the locale to use for formatting dates and times, for example |
| 10804 |
with the <function>to_char</function> family of |
| 10805 |
functions. Acceptable values are system-dependent; see <xref |
| 10806 |
linkend="locale"/> for more information. If this variable is |
| 10807 |
set to the empty string (which is the default) then the value |
| 10808 |
is inherited from the execution environment of the server in a |
| 10809 |
system-dependent way. |
| 10810 |
</para> |
| 10811 |
</listitem> |
| 10812 |
</varlistentry> |
| 10813 |
|
| 10814 |
<varlistentry id="guc-icu-validation-level" xreflabel="icu_validation_level"> |
| 10815 |
<term><varname>icu_validation_level</varname> (<type>enum</type>) |
| 10816 |
<indexterm> |
| 10817 |
<primary><varname>icu_validation_level</varname> configuration parameter</primary> |
| 10818 |
</indexterm> |
| 10819 |
</term> |
| 10820 |
<listitem> |
| 10821 |
<para> |
| 10822 |
When ICU locale validation problems are encountered, controls which |
| 10823 |
<link linkend="runtime-config-severity-levels">message level</link> is |
| 10824 |
used to report the problem. Valid values are |
| 10825 |
<literal>DISABLED</literal>, <literal>DEBUG5</literal>, |
| 10826 |
<literal>DEBUG4</literal>, <literal>DEBUG3</literal>, |
| 10827 |
<literal>DEBUG2</literal>, <literal>DEBUG1</literal>, |
| 10828 |
<literal>INFO</literal>, <literal>NOTICE</literal>, |
| 10829 |
<literal>WARNING</literal>, <literal>ERROR</literal>, and |
| 10830 |
<literal>LOG</literal>. |
| 10831 |
</para> |
| 10832 |
<para> |
| 10833 |
If set to <literal>DISABLED</literal>, does not report validation |
| 10834 |
problems at all. Otherwise reports problems at the given message |
| 10835 |
level. The default is <literal>WARNING</literal>. |
| 10836 |
</para> |
| 10837 |
</listitem> |
| 10838 |
</varlistentry> |
| 10839 |
|
| 10840 |
<varlistentry id="guc-default-text-search-config" xreflabel="default_text_search_config"> |
| 10841 |
<term><varname>default_text_search_config</varname> (<type>string</type>) |
| 10842 |
<indexterm> |
| 10843 |
<primary><varname>default_text_search_config</varname> configuration parameter</primary> |
| 10844 |
</indexterm> |
| 10845 |
</term> |
| 10846 |
<listitem> |
| 10847 |
<para> |
| 10848 |
Selects the text search configuration that is used by those variants |
| 10849 |
of the text search functions that do not have an explicit argument |
| 10850 |
specifying the configuration. |
| 10851 |
See <xref linkend="textsearch"/> for further information. |
| 10852 |
The built-in default is <literal>pg_catalog.simple</literal>, but |
| 10853 |
<application>initdb</application> will initialize the |
| 10854 |
configuration file with a setting that corresponds to the |
| 10855 |
chosen <varname>lc_ctype</varname> locale, if a configuration |
| 10856 |
matching that locale can be identified. |
| 10857 |
</para> |
| 10858 |
</listitem> |
| 10859 |
</varlistentry> |
| 10860 |
|
| 10861 |
</variablelist> |
| 10862 |
|
| 10863 |
</sect2> |
| 10864 |
|
| 10865 |
<sect2 id="runtime-config-client-preload"> |
| 10866 |
<title>Shared Library Preloading</title> |
| 10867 |
|
| 10868 |
<para> |
| 10869 |
Several settings are available for preloading shared libraries into the |
| 10870 |
server, in order to load additional functionality or achieve performance |
| 10871 |
benefits. For example, a setting of |
| 10872 |
<literal>'$libdir/mylib'</literal> would cause |
| 10873 |
<literal>mylib.so</literal> (or on some platforms, |
| 10874 |
<literal>mylib.sl</literal>) to be preloaded from the installation's standard |
| 10875 |
library directory. The differences between the settings are when they |
| 10876 |
take effect and what privileges are required to change them. |
| 10877 |
</para> |
| 10878 |
|
| 10879 |
<para> |
| 10880 |
<productname>PostgreSQL</productname> procedural language libraries can |
| 10881 |
be preloaded in this way, typically by using the |
| 10882 |
syntax <literal>'$libdir/plXXX'</literal> where |
| 10883 |
<literal>XXX</literal> is <literal>pgsql</literal>, <literal>perl</literal>, |
| 10884 |
<literal>tcl</literal>, or <literal>python</literal>. |
| 10885 |
</para> |
| 10886 |
|
| 10887 |
<para> |
| 10888 |
Only shared libraries specifically intended to be used with PostgreSQL |
| 10889 |
can be loaded this way. Every PostgreSQL-supported library has |
| 10890 |
a <quote>magic block</quote> that is checked to guarantee compatibility. For |
| 10891 |
this reason, non-PostgreSQL libraries cannot be loaded in this way. You |
| 10892 |
might be able to use operating-system facilities such |
| 10893 |
as <envar>LD_PRELOAD</envar> for that. |
| 10894 |
</para> |
| 10895 |
|
| 10896 |
<para> |
| 10897 |
In general, refer to the documentation of a specific module for the |
| 10898 |
recommended way to load that module. |
| 10899 |
</para> |
| 10900 |
|
| 10901 |
<variablelist> |
| 10902 |
<varlistentry id="guc-local-preload-libraries" xreflabel="local_preload_libraries"> |
| 10903 |
<term><varname>local_preload_libraries</varname> (<type>string</type>) |
| 10904 |
<indexterm> |
| 10905 |
<primary><varname>local_preload_libraries</varname> configuration parameter</primary> |
| 10906 |
</indexterm> |
| 10907 |
<indexterm> |
| 10908 |
<primary><filename>$libdir/plugins</filename></primary> |
| 10909 |
</indexterm> |
| 10910 |
</term> |
| 10911 |
<listitem> |
| 10912 |
<para> |
| 10913 |
This variable specifies one or more shared libraries that are to be |
| 10914 |
preloaded at connection start. |
| 10915 |
It contains a comma-separated list of library names, where each name |
| 10916 |
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command. |
| 10917 |
Whitespace between entries is ignored; surround a library name with |
| 10918 |
double quotes if you need to include whitespace or commas in the name. |
| 10919 |
The parameter value only takes effect at the start of the connection. |
| 10920 |
Subsequent changes have no effect. If a specified library is not |
| 10921 |
found, the connection attempt will fail. |
| 10922 |
</para> |
| 10923 |
|
| 10924 |
<para> |
| 10925 |
This option can be set by any user. Because of that, the libraries |
| 10926 |
that can be loaded are restricted to those appearing in the |
| 10927 |
<filename>plugins</filename> subdirectory of the installation's |
| 10928 |
standard library directory. (It is the database administrator's |
| 10929 |
responsibility to ensure that only <quote>safe</quote> libraries |
| 10930 |
are installed there.) Entries in <varname>local_preload_libraries</varname> |
| 10931 |
can specify this directory explicitly, for example |
| 10932 |
<literal>$libdir/plugins/mylib</literal>, or just specify |
| 10933 |
the library name — <literal>mylib</literal> would have |
| 10934 |
the same effect as <literal>$libdir/plugins/mylib</literal>. |
| 10935 |
</para> |
| 10936 |
|
| 10937 |
<para> |
| 10938 |
The intent of this feature is to allow unprivileged users to load |
| 10939 |
debugging or performance-measurement libraries into specific sessions |
| 10940 |
without requiring an explicit <command>LOAD</command> command. To that end, |
| 10941 |
it would be typical to set this parameter using |
| 10942 |
the <envar>PGOPTIONS</envar> environment variable on the client or by |
| 10943 |
using |
| 10944 |
<command>ALTER ROLE SET</command>. |
| 10945 |
</para> |
| 10946 |
|
| 10947 |
<para> |
| 10948 |
However, unless a module is specifically designed to be used in this way by |
| 10949 |
non-superusers, this is usually not the right setting to use. Look |
| 10950 |
at <xref linkend="guc-session-preload-libraries"/> instead. |
| 10951 |
</para> |
| 10952 |
</listitem> |
| 10953 |
</varlistentry> |
| 10954 |
|
| 10955 |
|
| 10956 |
<varlistentry id="guc-session-preload-libraries" xreflabel="session_preload_libraries"> |
| 10957 |
<term><varname>session_preload_libraries</varname> (<type>string</type>) |
| 10958 |
<indexterm> |
| 10959 |
<primary><varname>session_preload_libraries</varname> configuration parameter</primary> |
| 10960 |
</indexterm> |
| 10961 |
</term> |
| 10962 |
<listitem> |
| 10963 |
<para> |
| 10964 |
This variable specifies one or more shared libraries that are to be |
| 10965 |
preloaded at connection start. |
| 10966 |
It contains a comma-separated list of library names, where each name |
| 10967 |
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command. |
| 10968 |
Whitespace between entries is ignored; surround a library name with |
| 10969 |
double quotes if you need to include whitespace or commas in the name. |
| 10970 |
The parameter value only takes effect at the start of the connection. |
| 10971 |
Subsequent changes have no effect. If a specified library is not |
| 10972 |
found, the connection attempt will fail. |
| 10973 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 10974 |
privilege can change this setting. |
| 10975 |
</para> |
| 10976 |
|
| 10977 |
<para> |
| 10978 |
The intent of this feature is to allow debugging or |
| 10979 |
performance-measurement libraries to be loaded into specific sessions |
| 10980 |
without an explicit |
| 10981 |
<command>LOAD</command> command being given. For |
| 10982 |
example, <xref linkend="auto-explain"/> could be enabled for all |
| 10983 |
sessions under a given user name by setting this parameter |
| 10984 |
with <command>ALTER ROLE SET</command>. Also, this parameter can be changed |
| 10985 |
without restarting the server (but changes only take effect when a new |
| 10986 |
session is started), so it is easier to add new modules this way, even |
| 10987 |
if they should apply to all sessions. |
| 10988 |
</para> |
| 10989 |
|
| 10990 |
<para> |
| 10991 |
Unlike <xref linkend="guc-shared-preload-libraries"/>, there is no large |
| 10992 |
performance advantage to loading a library at session start rather than |
| 10993 |
when it is first used. There is some advantage, however, when |
| 10994 |
connection pooling is used. |
| 10995 |
</para> |
| 10996 |
</listitem> |
| 10997 |
</varlistentry> |
| 10998 |
|
| 10999 |
<varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries"> |
| 11000 |
<term><varname>shared_preload_libraries</varname> (<type>string</type>) |
| 11001 |
<indexterm> |
| 11002 |
<primary><varname>shared_preload_libraries</varname> configuration parameter</primary> |
| 11003 |
</indexterm> |
| 11004 |
</term> |
| 11005 |
<listitem> |
| 11006 |
<para> |
| 11007 |
This variable specifies one or more shared libraries to be preloaded at |
| 11008 |
server start. |
| 11009 |
It contains a comma-separated list of library names, where each name |
| 11010 |
is interpreted as for the <link linkend="sql-load"><command>LOAD</command></link> command. |
| 11011 |
Whitespace between entries is ignored; surround a library name with |
| 11012 |
double quotes if you need to include whitespace or commas in the name. |
| 11013 |
This parameter can only be set at server start. If a specified |
| 11014 |
library is not found, the server will fail to start. |
| 11015 |
</para> |
| 11016 |
|
| 11017 |
<para> |
| 11018 |
Some libraries need to perform certain operations that can only take |
| 11019 |
place at postmaster start, such as allocating shared memory, reserving |
| 11020 |
light-weight locks, or starting background workers. Those libraries |
| 11021 |
must be loaded at server start through this parameter. See the |
| 11022 |
documentation of each library for details. |
| 11023 |
</para> |
| 11024 |
|
| 11025 |
<para> |
| 11026 |
Other libraries can also be preloaded. By preloading a shared library, |
| 11027 |
the library startup time is avoided when the library is first used. |
| 11028 |
However, the time to start each new server process might increase |
| 11029 |
slightly, even if that process never uses the library. So this |
| 11030 |
parameter is recommended only for libraries that will be used in most |
| 11031 |
sessions. Also, changing this parameter requires a server restart, so |
| 11032 |
this is not the right setting to use for short-term debugging tasks, |
| 11033 |
say. Use <xref linkend="guc-session-preload-libraries"/> for that |
| 11034 |
instead. |
| 11035 |
</para> |
| 11036 |
|
| 11037 |
<note> |
| 11038 |
<para> |
| 11039 |
On Windows hosts, preloading a library at server start will not reduce |
| 11040 |
the time required to start each new server process; each server process |
| 11041 |
will re-load all preload libraries. However, <varname>shared_preload_libraries |
| 11042 |
</varname> is still useful on Windows hosts for libraries that need to |
| 11043 |
perform operations at postmaster start time. |
| 11044 |
</para> |
| 11045 |
</note> |
| 11046 |
</listitem> |
| 11047 |
</varlistentry> |
| 11048 |
|
| 11049 |
<varlistentry id="guc-jit-provider" xreflabel="jit_provider"> |
| 11050 |
<term><varname>jit_provider</varname> (<type>string</type>) |
| 11051 |
<indexterm> |
| 11052 |
<primary><varname>jit_provider</varname> configuration parameter</primary> |
| 11053 |
</indexterm> |
| 11054 |
</term> |
| 11055 |
<listitem> |
| 11056 |
<para> |
| 11057 |
This variable is the name of the JIT provider library to be used |
| 11058 |
(see <xref linkend="jit-pluggable"/>). |
| 11059 |
The default is <literal>llvmjit</literal>. |
| 11060 |
This parameter can only be set at server start. |
| 11061 |
</para> |
| 11062 |
|
| 11063 |
<para> |
| 11064 |
If set to a non-existent library, <acronym>JIT</acronym> will not be |
| 11065 |
available, but no error will be raised. This allows JIT support to be |
| 11066 |
installed separately from the main |
| 11067 |
<productname>PostgreSQL</productname> package. |
| 11068 |
</para> |
| 11069 |
</listitem> |
| 11070 |
</varlistentry> |
| 11071 |
|
| 11072 |
</variablelist> |
| 11073 |
</sect2> |
| 11074 |
|
| 11075 |
<sect2 id="runtime-config-client-other"> |
| 11076 |
<title>Other Defaults</title> |
| 11077 |
|
| 11078 |
<variablelist> |
| 11079 |
|
| 11080 |
<varlistentry id="guc-dynamic-library-path" xreflabel="dynamic_library_path"> |
| 11081 |
<term><varname>dynamic_library_path</varname> (<type>string</type>) |
| 11082 |
<indexterm> |
| 11083 |
<primary><varname>dynamic_library_path</varname> configuration parameter</primary> |
| 11084 |
</indexterm> |
| 11085 |
<indexterm><primary>dynamic loading</primary></indexterm> |
| 11086 |
</term> |
| 11087 |
<listitem> |
| 11088 |
<para> |
| 11089 |
If a dynamically loadable module needs to be opened and the |
| 11090 |
file name specified in the <command>CREATE FUNCTION</command> or |
| 11091 |
<command>LOAD</command> command |
| 11092 |
does not have a directory component (i.e., the |
| 11093 |
name does not contain a slash), the system will search this |
| 11094 |
path for the required file. |
| 11095 |
</para> |
| 11096 |
|
| 11097 |
<para> |
| 11098 |
The value for <varname>dynamic_library_path</varname> must be a |
| 11099 |
list of absolute directory paths separated by colons (or semi-colons |
| 11100 |
on Windows). If a list element starts |
| 11101 |
with the special string <literal>$libdir</literal>, the |
| 11102 |
compiled-in <productname>PostgreSQL</productname> package |
| 11103 |
library directory is substituted for <literal>$libdir</literal>; this |
| 11104 |
is where the modules provided by the standard |
| 11105 |
<productname>PostgreSQL</productname> distribution are installed. |
| 11106 |
(Use <literal>pg_config --pkglibdir</literal> to find out the name of |
| 11107 |
this directory.) For example: |
| 11108 |
<programlisting> |
| 11109 |
dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' |
| 11110 |
</programlisting> |
| 11111 |
or, in a Windows environment: |
| 11112 |
<programlisting> |
| 11113 |
dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' |
| 11114 |
</programlisting> |
| 11115 |
</para> |
| 11116 |
|
| 11117 |
<para> |
| 11118 |
The default value for this parameter is |
| 11119 |
<literal>'$libdir'</literal>. If the value is set to an empty |
| 11120 |
string, the automatic path search is turned off. |
| 11121 |
</para> |
| 11122 |
|
| 11123 |
<para> |
| 11124 |
This parameter can be changed at run time by superusers and users |
| 11125 |
with the appropriate <literal>SET</literal> privilege, but a |
| 11126 |
setting done that way will only persist until the end of the |
| 11127 |
client connection, so this method should be reserved for |
| 11128 |
development purposes. The recommended way to set this parameter |
| 11129 |
is in the <filename>postgresql.conf</filename> configuration |
| 11130 |
file. |
| 11131 |
</para> |
| 11132 |
</listitem> |
| 11133 |
</varlistentry> |
| 11134 |
|
| 11135 |
<varlistentry id="guc-extension-control-path" xreflabel="extension_control_path"> |
| 11136 |
<term><varname>extension_control_path</varname> (<type>string</type>) |
| 11137 |
<indexterm> |
| 11138 |
<primary><varname>extension_control_path</varname> configuration parameter</primary> |
| 11139 |
</indexterm> |
| 11140 |
</term> |
| 11141 |
<listitem> |
| 11142 |
<para> |
| 11143 |
A path to search for extensions, specifically extension control files |
| 11144 |
(<filename><replaceable>name</replaceable>.control</filename>). The |
| 11145 |
remaining extension script and secondary control files are then loaded |
| 11146 |
from the same directory where the primary control file was found. |
| 11147 |
See <xref linkend="extend-extensions-files"/> for details. |
| 11148 |
</para> |
| 11149 |
|
| 11150 |
<para> |
| 11151 |
The value for <varname>extension_control_path</varname> must be a |
| 11152 |
list of absolute directory paths separated by colons (or semi-colons |
| 11153 |
on Windows). If a list element starts |
| 11154 |
with the special string <literal>$system</literal>, the |
| 11155 |
compiled-in <productname>PostgreSQL</productname> extension |
| 11156 |
directory is substituted for <literal>$system</literal>; this |
| 11157 |
is where the extensions provided by the standard |
| 11158 |
<productname>PostgreSQL</productname> distribution are installed. |
| 11159 |
(Use <literal>pg_config --sharedir</literal> to find out the name of |
| 11160 |
this directory.) For example: |
| 11161 |
<programlisting> |
| 11162 |
extension_control_path = '/usr/local/share/postgresql:/home/my_project/share:$system' |
| 11163 |
</programlisting> |
| 11164 |
or, in a Windows environment: |
| 11165 |
<programlisting> |
| 11166 |
extension_control_path = 'C:\tools\postgresql;H:\my_project\share;$system' |
| 11167 |
</programlisting> |
| 11168 |
Note that the specified paths elements are expected to have a |
| 11169 |
subdirectory <filename>extension</filename> which will contain the |
| 11170 |
<filename>.control</filename> and <filename>.sql</filename> files; the |
| 11171 |
<filename>extension</filename> suffix is automatically appended to |
| 11172 |
each path element. |
| 11173 |
</para> |
| 11174 |
|
| 11175 |
<para> |
| 11176 |
The default value for this parameter is |
| 11177 |
<literal>'$system'</literal>. If the value is set to an empty |
| 11178 |
string, the default <literal>'$system'</literal> is also assumed. |
| 11179 |
</para> |
| 11180 |
|
| 11181 |
<para> |
| 11182 |
If extensions with equal names are present in multiple directories in |
| 11183 |
the configured path, only the instance found first in the path will be |
| 11184 |
used. |
| 11185 |
</para> |
| 11186 |
|
| 11187 |
<para> |
| 11188 |
This parameter can be changed at run time by superusers and users |
| 11189 |
with the appropriate <literal>SET</literal> privilege, but a |
| 11190 |
setting done that way will only persist until the end of the |
| 11191 |
client connection, so this method should be reserved for |
| 11192 |
development purposes. The recommended way to set this parameter |
| 11193 |
is in the <filename>postgresql.conf</filename> configuration |
| 11194 |
file. |
| 11195 |
</para> |
| 11196 |
|
| 11197 |
<para> |
| 11198 |
Note that if you set this parameter to be able to load extensions from |
| 11199 |
nonstandard locations, you will most likely also need to set <xref |
| 11200 |
linkend="guc-dynamic-library-path"/> to a correspondent location, for |
| 11201 |
example, |
| 11202 |
<programlisting> |
| 11203 |
extension_control_path = '/usr/local/share/postgresql:$system' |
| 11204 |
dynamic_library_path = '/usr/local/lib/postgresql:$libdir' |
| 11205 |
</programlisting> |
| 11206 |
</para> |
| 11207 |
</listitem> |
| 11208 |
</varlistentry> |
| 11209 |
|
| 11210 |
<varlistentry id="guc-gin-fuzzy-search-limit" xreflabel="gin_fuzzy_search_limit"> |
| 11211 |
<term><varname>gin_fuzzy_search_limit</varname> (<type>integer</type>) |
| 11212 |
<indexterm> |
| 11213 |
<primary><varname>gin_fuzzy_search_limit</varname> configuration parameter</primary> |
| 11214 |
</indexterm> |
| 11215 |
</term> |
| 11216 |
<listitem> |
| 11217 |
<para> |
| 11218 |
Soft upper limit of the size of the set returned by GIN index scans. For more |
| 11219 |
information see <xref linkend="gin-tips"/>. |
| 11220 |
</para> |
| 11221 |
</listitem> |
| 11222 |
</varlistentry> |
| 11223 |
|
| 11224 |
</variablelist> |
| 11225 |
</sect2> |
| 11226 |
</sect1> |
| 11227 |
|
| 11228 |
<sect1 id="runtime-config-locks"> |
| 11229 |
<title>Lock Management</title> |
| 11230 |
|
| 11231 |
<variablelist> |
| 11232 |
|
| 11233 |
<varlistentry id="guc-deadlock-timeout" xreflabel="deadlock_timeout"> |
| 11234 |
<term><varname>deadlock_timeout</varname> (<type>integer</type>) |
| 11235 |
<indexterm> |
| 11236 |
<primary>deadlock</primary> |
| 11237 |
<secondary>timeout during</secondary> |
| 11238 |
</indexterm> |
| 11239 |
<indexterm> |
| 11240 |
<primary>timeout</primary> |
| 11241 |
<secondary>deadlock</secondary> |
| 11242 |
</indexterm> |
| 11243 |
<indexterm> |
| 11244 |
<primary><varname>deadlock_timeout</varname> configuration parameter</primary> |
| 11245 |
</indexterm> |
| 11246 |
</term> |
| 11247 |
<listitem> |
| 11248 |
<para> |
| 11249 |
This is the amount of time to wait on a lock |
| 11250 |
before checking to see if there is a deadlock condition. The |
| 11251 |
check for deadlock is relatively expensive, so the server doesn't run |
| 11252 |
it every time it waits for a lock. We optimistically assume |
| 11253 |
that deadlocks are not common in production applications and |
| 11254 |
just wait on the lock for a while before checking for a |
| 11255 |
deadlock. Increasing this value reduces the amount of time |
| 11256 |
wasted in needless deadlock checks, but slows down reporting of |
| 11257 |
real deadlock errors. |
| 11258 |
If this value is specified without units, it is taken as milliseconds. |
| 11259 |
The default is one second (<literal>1s</literal>), |
| 11260 |
which is probably about the smallest value you would want in |
| 11261 |
practice. On a heavily loaded server you might want to raise it. |
| 11262 |
Ideally the setting should exceed your typical transaction time, |
| 11263 |
so as to improve the odds that a lock will be released before |
| 11264 |
the waiter decides to check for deadlock. |
| 11265 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 11266 |
privilege can change this setting. |
| 11267 |
</para> |
| 11268 |
|
| 11269 |
<para> |
| 11270 |
When <xref linkend="guc-log-lock-waits"/> is set, |
| 11271 |
this parameter also determines the amount of time to wait before |
| 11272 |
a log message is issued about the lock wait. If you are trying |
| 11273 |
to investigate locking delays you might want to set a shorter than |
| 11274 |
normal <varname>deadlock_timeout</varname>. |
| 11275 |
</para> |
| 11276 |
</listitem> |
| 11277 |
</varlistentry> |
| 11278 |
|
| 11279 |
<varlistentry id="guc-max-locks-per-transaction" xreflabel="max_locks_per_transaction"> |
| 11280 |
<term><varname>max_locks_per_transaction</varname> (<type>integer</type>) |
| 11281 |
<indexterm> |
| 11282 |
<primary><varname>max_locks_per_transaction</varname> configuration parameter</primary> |
| 11283 |
</indexterm> |
| 11284 |
</term> |
| 11285 |
<listitem> |
| 11286 |
<para> |
| 11287 |
The shared lock table has space for |
| 11288 |
<varname>max_locks_per_transaction</varname> objects |
| 11289 |
(e.g., tables) per server process or prepared transaction; |
| 11290 |
hence, no more than this many distinct objects can be locked at |
| 11291 |
any one time. This parameter limits the average number of object |
| 11292 |
locks used by each transaction; individual transactions |
| 11293 |
can lock more objects as long as the locks of all transactions |
| 11294 |
fit in the lock table. This is <emphasis>not</emphasis> the number of |
| 11295 |
rows that can be locked; that value is unlimited. The default, |
| 11296 |
64, has historically proven sufficient, but you might need to |
| 11297 |
raise this value if you have queries that touch many different |
| 11298 |
tables in a single transaction, e.g., query of a parent table with |
| 11299 |
many children. This parameter can only be set at server start. |
| 11300 |
</para> |
| 11301 |
|
| 11302 |
<para> |
| 11303 |
When running a standby server, you must set this parameter to have the |
| 11304 |
same or higher value as on the primary server. Otherwise, queries |
| 11305 |
will not be allowed in the standby server. |
| 11306 |
</para> |
| 11307 |
</listitem> |
| 11308 |
</varlistentry> |
| 11309 |
|
| 11310 |
<varlistentry id="guc-max-pred-locks-per-transaction" xreflabel="max_pred_locks_per_transaction"> |
| 11311 |
<term><varname>max_pred_locks_per_transaction</varname> (<type>integer</type>) |
| 11312 |
<indexterm> |
| 11313 |
<primary><varname>max_pred_locks_per_transaction</varname> configuration parameter</primary> |
| 11314 |
</indexterm> |
| 11315 |
</term> |
| 11316 |
<listitem> |
| 11317 |
<para> |
| 11318 |
The shared predicate lock table has space for |
| 11319 |
<varname>max_pred_locks_per_transaction</varname> objects |
| 11320 |
(e.g., tables) per server process or prepared transaction; |
| 11321 |
hence, no more than this many distinct objects can be locked at |
| 11322 |
any one time. This parameter limits the average number of object |
| 11323 |
locks used by each transaction; individual transactions |
| 11324 |
can lock more objects as long as the locks of all transactions |
| 11325 |
fit in the lock table. This is <emphasis>not</emphasis> the number of |
| 11326 |
rows that can be locked; that value is unlimited. The default, |
| 11327 |
64, has historically proven sufficient, but you might need to |
| 11328 |
raise this value if you have clients that touch many different |
| 11329 |
tables in a single serializable transaction. This parameter can |
| 11330 |
only be set at server start. |
| 11331 |
</para> |
| 11332 |
</listitem> |
| 11333 |
</varlistentry> |
| 11334 |
|
| 11335 |
<varlistentry id="guc-max-pred-locks-per-relation" xreflabel="max_pred_locks_per_relation"> |
| 11336 |
<term><varname>max_pred_locks_per_relation</varname> (<type>integer</type>) |
| 11337 |
<indexterm> |
| 11338 |
<primary><varname>max_pred_locks_per_relation</varname> configuration parameter</primary> |
| 11339 |
</indexterm> |
| 11340 |
</term> |
| 11341 |
<listitem> |
| 11342 |
<para> |
| 11343 |
This controls how many pages or tuples of a single relation can be |
| 11344 |
predicate-locked before the lock is promoted to covering the whole |
| 11345 |
relation. Values greater than or equal to zero mean an absolute |
| 11346 |
limit, while negative values |
| 11347 |
mean <xref linkend="guc-max-pred-locks-per-transaction"/> divided by |
| 11348 |
the absolute value of this setting. The default is -2, which keeps |
| 11349 |
the behavior from previous versions of <productname>PostgreSQL</productname>. |
| 11350 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 11351 |
file or on the server command line. |
| 11352 |
</para> |
| 11353 |
</listitem> |
| 11354 |
</varlistentry> |
| 11355 |
|
| 11356 |
<varlistentry id="guc-max-pred-locks-per-page" xreflabel="max_pred_locks_per_page"> |
| 11357 |
<term><varname>max_pred_locks_per_page</varname> (<type>integer</type>) |
| 11358 |
<indexterm> |
| 11359 |
<primary><varname>max_pred_locks_per_page</varname> configuration parameter</primary> |
| 11360 |
</indexterm> |
| 11361 |
</term> |
| 11362 |
<listitem> |
| 11363 |
<para> |
| 11364 |
This controls how many rows on a single page can be predicate-locked |
| 11365 |
before the lock is promoted to covering the whole page. The default |
| 11366 |
is 2. This parameter can only be set in |
| 11367 |
the <filename>postgresql.conf</filename> file or on the server command line. |
| 11368 |
</para> |
| 11369 |
</listitem> |
| 11370 |
</varlistentry> |
| 11371 |
|
| 11372 |
</variablelist> |
| 11373 |
</sect1> |
| 11374 |
|
| 11375 |
<sect1 id="runtime-config-compatible"> |
| 11376 |
<title>Version and Platform Compatibility</title> |
| 11377 |
|
| 11378 |
<sect2 id="runtime-config-compatible-version"> |
| 11379 |
<title>Previous PostgreSQL Versions</title> |
| 11380 |
|
| 11381 |
<variablelist> |
| 11382 |
|
| 11383 |
<varlistentry id="guc-array-nulls" xreflabel="array_nulls"> |
| 11384 |
<term><varname>array_nulls</varname> (<type>boolean</type>) |
| 11385 |
<indexterm> |
| 11386 |
<primary><varname>array_nulls</varname> configuration parameter</primary> |
| 11387 |
</indexterm> |
| 11388 |
</term> |
| 11389 |
<listitem> |
| 11390 |
<para> |
| 11391 |
This controls whether the array input parser recognizes |
| 11392 |
unquoted <literal>NULL</literal> as specifying a null array element. |
| 11393 |
By default, this is <literal>on</literal>, allowing array values containing |
| 11394 |
null values to be entered. However, <productname>PostgreSQL</productname> versions |
| 11395 |
before 8.2 did not support null values in arrays, and therefore would |
| 11396 |
treat <literal>NULL</literal> as specifying a normal array element with |
| 11397 |
the string value <quote>NULL</quote>. For backward compatibility with |
| 11398 |
applications that require the old behavior, this variable can be |
| 11399 |
turned <literal>off</literal>. |
| 11400 |
</para> |
| 11401 |
|
| 11402 |
<para> |
| 11403 |
Note that it is possible to create array values containing null values |
| 11404 |
even when this variable is <literal>off</literal>. |
| 11405 |
</para> |
| 11406 |
</listitem> |
| 11407 |
</varlistentry> |
| 11408 |
|
| 11409 |
<varlistentry id="guc-backslash-quote" xreflabel="backslash_quote"> |
| 11410 |
<term><varname>backslash_quote</varname> (<type>enum</type>) |
| 11411 |
<indexterm><primary>strings</primary><secondary>backslash quotes</secondary></indexterm> |
| 11412 |
<indexterm> |
| 11413 |
<primary><varname>backslash_quote</varname> configuration parameter</primary> |
| 11414 |
</indexterm> |
| 11415 |
</term> |
| 11416 |
<listitem> |
| 11417 |
<para> |
| 11418 |
This controls whether a quote mark can be represented by |
| 11419 |
<literal>\'</literal> in a string literal. The preferred, SQL-standard way |
| 11420 |
to represent a quote mark is by doubling it (<literal>''</literal>) but |
| 11421 |
<productname>PostgreSQL</productname> has historically also accepted |
| 11422 |
<literal>\'</literal>. However, use of <literal>\'</literal> creates security risks |
| 11423 |
because in some client character set encodings, there are multibyte |
| 11424 |
characters in which the last byte is numerically equivalent to ASCII |
| 11425 |
<literal>\</literal>. If client-side code does escaping incorrectly then an |
| 11426 |
SQL-injection attack is possible. This risk can be prevented by |
| 11427 |
making the server reject queries in which a quote mark appears to be |
| 11428 |
escaped by a backslash. |
| 11429 |
The allowed values of <varname>backslash_quote</varname> are |
| 11430 |
<literal>on</literal> (allow <literal>\'</literal> always), |
| 11431 |
<literal>off</literal> (reject always), and |
| 11432 |
<literal>safe_encoding</literal> (allow only if client encoding does not |
| 11433 |
allow ASCII <literal>\</literal> within a multibyte character). |
| 11434 |
<literal>safe_encoding</literal> is the default setting. |
| 11435 |
</para> |
| 11436 |
|
| 11437 |
<para> |
| 11438 |
Note that in a standard-conforming string literal, <literal>\</literal> just |
| 11439 |
means <literal>\</literal> anyway. This parameter only affects the handling of |
| 11440 |
non-standard-conforming literals, including |
| 11441 |
escape string syntax (<literal>E'...'</literal>). |
| 11442 |
</para> |
| 11443 |
</listitem> |
| 11444 |
</varlistentry> |
| 11445 |
|
| 11446 |
<varlistentry id="guc-escape-string-warning" xreflabel="escape_string_warning"> |
| 11447 |
<term><varname>escape_string_warning</varname> (<type>boolean</type>) |
| 11448 |
<indexterm><primary>strings</primary><secondary>escape warning</secondary></indexterm> |
| 11449 |
<indexterm> |
| 11450 |
<primary><varname>escape_string_warning</varname> configuration parameter</primary> |
| 11451 |
</indexterm> |
| 11452 |
</term> |
| 11453 |
<listitem> |
| 11454 |
<para> |
| 11455 |
When on, a warning is issued if a backslash (<literal>\</literal>) |
| 11456 |
appears in an ordinary string literal (<literal>'...'</literal> |
| 11457 |
syntax) and <varname>standard_conforming_strings</varname> is off. |
| 11458 |
The default is <literal>on</literal>. |
| 11459 |
</para> |
| 11460 |
<para> |
| 11461 |
Applications that wish to use backslash as escape should be |
| 11462 |
modified to use escape string syntax (<literal>E'...'</literal>), |
| 11463 |
because the default behavior of ordinary strings is now to treat |
| 11464 |
backslash as an ordinary character, per SQL standard. This variable |
| 11465 |
can be enabled to help locate code that needs to be changed. |
| 11466 |
</para> |
| 11467 |
</listitem> |
| 11468 |
</varlistentry> |
| 11469 |
|
| 11470 |
<varlistentry id="guc-lo-compat-privileges" xreflabel="lo_compat_privileges"> |
| 11471 |
<term><varname>lo_compat_privileges</varname> (<type>boolean</type>) |
| 11472 |
<indexterm> |
| 11473 |
<primary><varname>lo_compat_privileges</varname> configuration parameter</primary> |
| 11474 |
</indexterm> |
| 11475 |
</term> |
| 11476 |
<listitem> |
| 11477 |
<para> |
| 11478 |
In <productname>PostgreSQL</productname> releases prior to 9.0, large objects |
| 11479 |
did not have access privileges and were, therefore, always readable |
| 11480 |
and writable by all users. Setting this variable to <literal>on</literal> |
| 11481 |
disables the new privilege checks, for compatibility with prior |
| 11482 |
releases. The default is <literal>off</literal>. |
| 11483 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 11484 |
privilege can change this setting. |
| 11485 |
</para> |
| 11486 |
<para> |
| 11487 |
Setting this variable does not disable all security checks related to |
| 11488 |
large objects — only those for which the default behavior has |
| 11489 |
changed in <productname>PostgreSQL</productname> 9.0. |
| 11490 |
</para> |
| 11491 |
</listitem> |
| 11492 |
</varlistentry> |
| 11493 |
|
| 11494 |
<varlistentry id="guc-quote-all-identifiers" xreflabel="quote-all-identifiers"> |
| 11495 |
<term><varname>quote_all_identifiers</varname> (<type>boolean</type>) |
| 11496 |
<indexterm> |
| 11497 |
<primary><varname>quote_all_identifiers</varname> configuration parameter</primary> |
| 11498 |
</indexterm> |
| 11499 |
</term> |
| 11500 |
<listitem> |
| 11501 |
<para> |
| 11502 |
When the database generates SQL, force all identifiers to be quoted, |
| 11503 |
even if they are not (currently) keywords. This will affect the |
| 11504 |
output of <command>EXPLAIN</command> as well as the results of functions |
| 11505 |
like <function>pg_get_viewdef</function>. See also the |
| 11506 |
<option>--quote-all-identifiers</option> option of |
| 11507 |
<xref linkend="app-pgdump"/> and <xref linkend="app-pg-dumpall"/>. |
| 11508 |
</para> |
| 11509 |
</listitem> |
| 11510 |
</varlistentry> |
| 11511 |
|
| 11512 |
<varlistentry id="guc-standard-conforming-strings" xreflabel="standard_conforming_strings"> |
| 11513 |
<term><varname>standard_conforming_strings</varname> (<type>boolean</type>) |
| 11514 |
<indexterm><primary>strings</primary><secondary>standard conforming</secondary></indexterm> |
| 11515 |
<indexterm> |
| 11516 |
<primary><varname>standard_conforming_strings</varname> configuration parameter</primary> |
| 11517 |
</indexterm> |
| 11518 |
</term> |
| 11519 |
<listitem> |
| 11520 |
<para> |
| 11521 |
This controls whether ordinary string literals |
| 11522 |
(<literal>'...'</literal>) treat backslashes literally, as specified in |
| 11523 |
the SQL standard. |
| 11524 |
Beginning in <productname>PostgreSQL</productname> 9.1, the default is |
| 11525 |
<literal>on</literal> (prior releases defaulted to <literal>off</literal>). |
| 11526 |
Applications can check this |
| 11527 |
parameter to determine how string literals will be processed. |
| 11528 |
The presence of this parameter can also be taken as an indication |
| 11529 |
that the escape string syntax (<literal>E'...'</literal>) is supported. |
| 11530 |
Escape string syntax (<xref linkend="sql-syntax-strings-escape"/>) |
| 11531 |
should be used if an application desires |
| 11532 |
backslashes to be treated as escape characters. |
| 11533 |
</para> |
| 11534 |
</listitem> |
| 11535 |
</varlistentry> |
| 11536 |
|
| 11537 |
<varlistentry id="guc-synchronize-seqscans" xreflabel="synchronize_seqscans"> |
| 11538 |
<term><varname>synchronize_seqscans</varname> (<type>boolean</type>) |
| 11539 |
<indexterm> |
| 11540 |
<primary><varname>synchronize_seqscans</varname> configuration parameter</primary> |
| 11541 |
</indexterm> |
| 11542 |
</term> |
| 11543 |
<listitem> |
| 11544 |
<para> |
| 11545 |
This allows sequential scans of large tables to synchronize with each |
| 11546 |
other, so that concurrent scans read the same block at about the |
| 11547 |
same time and hence share the I/O workload. When this is enabled, |
| 11548 |
a scan might start in the middle of the table and then <quote>wrap |
| 11549 |
around</quote> the end to cover all rows, so as to synchronize with the |
| 11550 |
activity of scans already in progress. This can result in |
| 11551 |
unpredictable changes in the row ordering returned by queries that |
| 11552 |
have no <literal>ORDER BY</literal> clause. Setting this parameter to |
| 11553 |
<literal>off</literal> ensures the pre-8.3 behavior in which a sequential |
| 11554 |
scan always starts from the beginning of the table. The default |
| 11555 |
is <literal>on</literal>. |
| 11556 |
</para> |
| 11557 |
</listitem> |
| 11558 |
</varlistentry> |
| 11559 |
|
| 11560 |
</variablelist> |
| 11561 |
</sect2> |
| 11562 |
|
| 11563 |
<sect2 id="runtime-config-compatible-clients"> |
| 11564 |
<title>Platform and Client Compatibility</title> |
| 11565 |
<variablelist> |
| 11566 |
|
| 11567 |
<varlistentry id="guc-transform-null-equals" xreflabel="transform_null_equals"> |
| 11568 |
<term><varname>transform_null_equals</varname> (<type>boolean</type>) |
| 11569 |
<indexterm><primary>IS NULL</primary></indexterm> |
| 11570 |
<indexterm> |
| 11571 |
<primary><varname>transform_null_equals</varname> configuration parameter</primary> |
| 11572 |
</indexterm> |
| 11573 |
</term> |
| 11574 |
<listitem> |
| 11575 |
<para> |
| 11576 |
When on, expressions of the form <literal><replaceable>expr</replaceable> = |
| 11577 |
NULL</literal> (or <literal>NULL = |
| 11578 |
<replaceable>expr</replaceable></literal>) are treated as |
| 11579 |
<literal><replaceable>expr</replaceable> IS NULL</literal>, that is, they |
| 11580 |
return true if <replaceable>expr</replaceable> evaluates to the null value, |
| 11581 |
and false otherwise. The correct SQL-spec-compliant behavior of |
| 11582 |
<literal><replaceable>expr</replaceable> = NULL</literal> is to always |
| 11583 |
return null (unknown). Therefore this parameter defaults to |
| 11584 |
<literal>off</literal>. |
| 11585 |
</para> |
| 11586 |
|
| 11587 |
<para> |
| 11588 |
However, filtered forms in <productname>Microsoft |
| 11589 |
Access</productname> generate queries that appear to use |
| 11590 |
<literal><replaceable>expr</replaceable> = NULL</literal> to test for |
| 11591 |
null values, so if you use that interface to access the database you |
| 11592 |
might want to turn this option on. Since expressions of the |
| 11593 |
form <literal><replaceable>expr</replaceable> = NULL</literal> always |
| 11594 |
return the null value (using the SQL standard interpretation), they are not |
| 11595 |
very useful and do not appear often in normal applications so |
| 11596 |
this option does little harm in practice. But new users are |
| 11597 |
frequently confused about the semantics of expressions |
| 11598 |
involving null values, so this option is off by default. |
| 11599 |
</para> |
| 11600 |
|
| 11601 |
<para> |
| 11602 |
Note that this option only affects the exact form <literal>= NULL</literal>, |
| 11603 |
not other comparison operators or other expressions |
| 11604 |
that are computationally equivalent to some expression |
| 11605 |
involving the equals operator (such as <literal>IN</literal>). |
| 11606 |
Thus, this option is not a general fix for bad programming. |
| 11607 |
</para> |
| 11608 |
|
| 11609 |
<para> |
| 11610 |
Refer to <xref linkend="functions-comparison"/> for related information. |
| 11611 |
</para> |
| 11612 |
</listitem> |
| 11613 |
</varlistentry> |
| 11614 |
|
| 11615 |
<varlistentry id="guc-allow-alter-system" xreflabel="allow_alter_system"> |
| 11616 |
<term><varname>allow_alter_system</varname> (<type>boolean</type>) |
| 11617 |
<indexterm> |
| 11618 |
<primary><varname>allow_alter_system</varname> configuration parameter</primary> |
| 11619 |
</indexterm> |
| 11620 |
</term> |
| 11621 |
<listitem> |
| 11622 |
<para> |
| 11623 |
When <literal>allow_alter_system</literal> is set to |
| 11624 |
<literal>off</literal>, an error is returned if the <command>ALTER |
| 11625 |
SYSTEM</command> command is executed. This parameter can only be set in |
| 11626 |
the <filename>postgresql.conf</filename> file or on the server command |
| 11627 |
line. The default value is <literal>on</literal>. |
| 11628 |
</para> |
| 11629 |
|
| 11630 |
<para> |
| 11631 |
Note that this setting must not be regarded as a security feature. It |
| 11632 |
only disables the <literal>ALTER SYSTEM</literal> command. It does not |
| 11633 |
prevent a superuser from changing the configuration using other SQL |
| 11634 |
commands. A superuser has many ways of executing shell commands at |
| 11635 |
the operating system level, and can therefore modify |
| 11636 |
<literal>postgresql.auto.conf</literal> regardless of the value of |
| 11637 |
this setting. |
| 11638 |
</para> |
| 11639 |
|
| 11640 |
<para> |
| 11641 |
Turning this setting off is intended for environments where the |
| 11642 |
configuration of <productname>PostgreSQL</productname> is managed by |
| 11643 |
some external tool. |
| 11644 |
In such environments, a well-intentioned superuser might |
| 11645 |
<emphasis>mistakenly</emphasis> use <command>ALTER SYSTEM</command> |
| 11646 |
to change the configuration instead of using the external tool. |
| 11647 |
This might result in unintended behavior, such as the external tool |
| 11648 |
overwriting the change at some later point in time when it updates the |
| 11649 |
configuration. |
| 11650 |
Setting this parameter to <literal>off</literal> can |
| 11651 |
help avoid such mistakes. |
| 11652 |
</para> |
| 11653 |
|
| 11654 |
<para> |
| 11655 |
This parameter only controls the use of <command>ALTER SYSTEM</command>. |
| 11656 |
The settings stored in <filename>postgresql.auto.conf</filename> |
| 11657 |
take effect even if <literal>allow_alter_system</literal> is set to |
| 11658 |
<literal>off</literal>. |
| 11659 |
</para> |
| 11660 |
</listitem> |
| 11661 |
</varlistentry> |
| 11662 |
|
| 11663 |
</variablelist> |
| 11664 |
</sect2> |
| 11665 |
</sect1> |
| 11666 |
|
| 11667 |
<sect1 id="runtime-config-error-handling"> |
| 11668 |
<title>Error Handling</title> |
| 11669 |
|
| 11670 |
<variablelist> |
| 11671 |
|
| 11672 |
<varlistentry id="guc-exit-on-error" xreflabel="exit_on_error"> |
| 11673 |
<term><varname>exit_on_error</varname> (<type>boolean</type>) |
| 11674 |
<indexterm> |
| 11675 |
<primary><varname>exit_on_error</varname> configuration parameter</primary> |
| 11676 |
</indexterm> |
| 11677 |
</term> |
| 11678 |
<listitem> |
| 11679 |
<para> |
| 11680 |
If on, any error will terminate the current session. By default, |
| 11681 |
this is set to off, so that only FATAL errors will terminate the |
| 11682 |
session. |
| 11683 |
</para> |
| 11684 |
</listitem> |
| 11685 |
</varlistentry> |
| 11686 |
|
| 11687 |
<varlistentry id="guc-restart-after-crash" xreflabel="restart_after_crash"> |
| 11688 |
<term><varname>restart_after_crash</varname> (<type>boolean</type>) |
| 11689 |
<indexterm> |
| 11690 |
<primary><varname>restart_after_crash</varname> configuration parameter</primary> |
| 11691 |
</indexterm> |
| 11692 |
</term> |
| 11693 |
<listitem> |
| 11694 |
<para> |
| 11695 |
When set to on, which is the default, <productname>PostgreSQL</productname> |
| 11696 |
will automatically reinitialize after a backend crash. Leaving this |
| 11697 |
value set to on is normally the best way to maximize the availability |
| 11698 |
of the database. However, in some circumstances, such as when |
| 11699 |
<productname>PostgreSQL</productname> is being invoked by clusterware, it may be |
| 11700 |
useful to disable the restart so that the clusterware can gain |
| 11701 |
control and take any actions it deems appropriate. |
| 11702 |
</para> |
| 11703 |
|
| 11704 |
<para> |
| 11705 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 11706 |
file or on the server command line. |
| 11707 |
</para> |
| 11708 |
</listitem> |
| 11709 |
</varlistentry> |
| 11710 |
|
| 11711 |
<varlistentry id="guc-data-sync-retry" xreflabel="data_sync_retry"> |
| 11712 |
<term><varname>data_sync_retry</varname> (<type>boolean</type>) |
| 11713 |
<indexterm> |
| 11714 |
<primary><varname>data_sync_retry</varname> configuration parameter</primary> |
| 11715 |
</indexterm> |
| 11716 |
</term> |
| 11717 |
<listitem> |
| 11718 |
<para> |
| 11719 |
When set to off, which is the default, <productname>PostgreSQL</productname> |
| 11720 |
will raise a PANIC-level error on failure to flush modified data files |
| 11721 |
to the file system. This causes the database server to crash. This |
| 11722 |
parameter can only be set at server start. |
| 11723 |
</para> |
| 11724 |
<para> |
| 11725 |
On some operating systems, the status of data in the kernel's page |
| 11726 |
cache is unknown after a write-back failure. In some cases it might |
| 11727 |
have been entirely forgotten, making it unsafe to retry; the second |
| 11728 |
attempt may be reported as successful, when in fact the data has been |
| 11729 |
lost. In these circumstances, the only way to avoid data loss is to |
| 11730 |
recover from the WAL after any failure is reported, preferably |
| 11731 |
after investigating the root cause of the failure and replacing any |
| 11732 |
faulty hardware. |
| 11733 |
</para> |
| 11734 |
<para> |
| 11735 |
If set to on, <productname>PostgreSQL</productname> will instead |
| 11736 |
report an error but continue to run so that the data flushing |
| 11737 |
operation can be retried in a later checkpoint. Only set it to on |
| 11738 |
after investigating the operating system's treatment of buffered data |
| 11739 |
in case of write-back failure. |
| 11740 |
</para> |
| 11741 |
</listitem> |
| 11742 |
</varlistentry> |
| 11743 |
|
| 11744 |
<varlistentry id="guc-recovery-init-sync-method" xreflabel="recovery_init_sync_method"> |
| 11745 |
<term><varname>recovery_init_sync_method</varname> (<type>enum</type>) |
| 11746 |
<indexterm> |
| 11747 |
<primary><varname>recovery_init_sync_method</varname> configuration parameter</primary> |
| 11748 |
</indexterm> |
| 11749 |
</term> |
| 11750 |
<listitem> |
| 11751 |
<para> |
| 11752 |
When set to <literal>fsync</literal>, which is the default, |
| 11753 |
<productname>PostgreSQL</productname> will recursively open and |
| 11754 |
synchronize all files in the data directory before crash recovery |
| 11755 |
begins. The search for files will follow symbolic links for the WAL |
| 11756 |
directory and each configured tablespace (but not any other symbolic |
| 11757 |
links). This is intended to make sure that all WAL and data files are |
| 11758 |
durably stored on disk before replaying changes. This applies whenever |
| 11759 |
starting a database cluster that did not shut down cleanly, including |
| 11760 |
copies created with <application>pg_basebackup</application>. |
| 11761 |
</para> |
| 11762 |
<para> |
| 11763 |
On Linux, <literal>syncfs</literal> may be used instead, to ask the |
| 11764 |
operating system to synchronize the file systems that contain the |
| 11765 |
data directory, the WAL files and each tablespace (but not any other |
| 11766 |
file systems that may be reachable through symbolic links). This may |
| 11767 |
be a lot faster than the <literal>fsync</literal> setting, because it |
| 11768 |
doesn't need to open each file one by one. On the other hand, it may |
| 11769 |
be slower if a file system is shared by other applications that |
| 11770 |
modify a lot of files, since those files will also be written to disk. |
| 11771 |
Furthermore, on versions of Linux before 5.8, I/O errors encountered |
| 11772 |
while writing data to disk may not be reported to |
| 11773 |
<productname>PostgreSQL</productname>, and relevant error messages may |
| 11774 |
appear only in kernel logs. |
| 11775 |
</para> |
| 11776 |
<para> |
| 11777 |
This parameter can only be set in the |
| 11778 |
<filename>postgresql.conf</filename> file or on the server command line. |
| 11779 |
</para> |
| 11780 |
</listitem> |
| 11781 |
</varlistentry> |
| 11782 |
|
| 11783 |
</variablelist> |
| 11784 |
|
| 11785 |
</sect1> |
| 11786 |
|
| 11787 |
<sect1 id="runtime-config-preset"> |
| 11788 |
<title>Preset Options</title> |
| 11789 |
|
| 11790 |
<para> |
| 11791 |
The following <quote>parameters</quote> are read-only. |
| 11792 |
As such, they have been excluded from the sample |
| 11793 |
<filename>postgresql.conf</filename> file. These options report |
| 11794 |
various aspects of <productname>PostgreSQL</productname> behavior |
| 11795 |
that might be of interest to certain applications, particularly |
| 11796 |
administrative front-ends. |
| 11797 |
Most of them are determined when <productname>PostgreSQL</productname> |
| 11798 |
is compiled or when it is installed. |
| 11799 |
</para> |
| 11800 |
|
| 11801 |
<variablelist> |
| 11802 |
|
| 11803 |
<varlistentry id="guc-block-size" xreflabel="block_size"> |
| 11804 |
<term><varname>block_size</varname> (<type>integer</type>) |
| 11805 |
<indexterm> |
| 11806 |
<primary><varname>block_size</varname> configuration parameter</primary> |
| 11807 |
</indexterm> |
| 11808 |
</term> |
| 11809 |
<listitem> |
| 11810 |
<para> |
| 11811 |
Reports the size of a disk block. It is determined by the value |
| 11812 |
of <literal>BLCKSZ</literal> when building the server. The default |
| 11813 |
value is 8192 bytes. The meaning of some configuration |
| 11814 |
variables (such as <xref linkend="guc-shared-buffers"/>) is |
| 11815 |
influenced by <varname>block_size</varname>. See <xref |
| 11816 |
linkend="runtime-config-resource"/> for information. |
| 11817 |
</para> |
| 11818 |
</listitem> |
| 11819 |
</varlistentry> |
| 11820 |
|
| 11821 |
<varlistentry id="guc-data-checksums" xreflabel="data_checksums"> |
| 11822 |
<term><varname>data_checksums</varname> (<type>boolean</type>) |
| 11823 |
<indexterm> |
| 11824 |
<primary><varname>data_checksums</varname> configuration parameter</primary> |
| 11825 |
</indexterm> |
| 11826 |
</term> |
| 11827 |
<listitem> |
| 11828 |
<para> |
| 11829 |
Reports whether data checksums are enabled for this cluster. |
| 11830 |
See <xref linkend="app-initdb-data-checksums"/> for more information. |
| 11831 |
</para> |
| 11832 |
</listitem> |
| 11833 |
</varlistentry> |
| 11834 |
|
| 11835 |
<varlistentry id="guc-data-directory-mode" xreflabel="data_directory_mode"> |
| 11836 |
<term><varname>data_directory_mode</varname> (<type>integer</type>) |
| 11837 |
<indexterm> |
| 11838 |
<primary><varname>data_directory_mode</varname> configuration parameter</primary> |
| 11839 |
</indexterm> |
| 11840 |
</term> |
| 11841 |
<listitem> |
| 11842 |
<para> |
| 11843 |
On Unix systems this parameter reports the permissions the data |
| 11844 |
directory (defined by <xref linkend="guc-data-directory"/>) |
| 11845 |
had at server startup. |
| 11846 |
(On Microsoft Windows this parameter will always display |
| 11847 |
<literal>0700</literal>.) See |
| 11848 |
<link linkend="app-initdb-allow-group-access">the |
| 11849 |
<application>initdb</application> <option>-g</option> option</link> |
| 11850 |
for more information. |
| 11851 |
</para> |
| 11852 |
</listitem> |
| 11853 |
</varlistentry> |
| 11854 |
|
| 11855 |
<varlistentry id="guc-debug-assertions" xreflabel="debug_assertions"> |
| 11856 |
<term><varname>debug_assertions</varname> (<type>boolean</type>) |
| 11857 |
<indexterm> |
| 11858 |
<primary><varname>debug_assertions</varname> configuration parameter</primary> |
| 11859 |
</indexterm> |
| 11860 |
</term> |
| 11861 |
<listitem> |
| 11862 |
<para> |
| 11863 |
Reports whether <productname>PostgreSQL</productname> has been built |
| 11864 |
with assertions enabled. That is the case if the |
| 11865 |
macro <symbol>USE_ASSERT_CHECKING</symbol> is defined |
| 11866 |
when <productname>PostgreSQL</productname> is built (accomplished |
| 11867 |
e.g., by the <command>configure</command> option |
| 11868 |
<option>--enable-cassert</option>). By |
| 11869 |
default <productname>PostgreSQL</productname> is built without |
| 11870 |
assertions. |
| 11871 |
</para> |
| 11872 |
</listitem> |
| 11873 |
</varlistentry> |
| 11874 |
|
| 11875 |
<varlistentry id="guc-huge-pages-status" xreflabel="huge_pages_status"> |
| 11876 |
<term><varname>huge_pages_status</varname> (<type>enum</type>) |
| 11877 |
<indexterm> |
| 11878 |
<primary><varname>huge_pages_status</varname> configuration parameter</primary> |
| 11879 |
</indexterm> |
| 11880 |
</term> |
| 11881 |
<listitem> |
| 11882 |
<para> |
| 11883 |
Reports the state of huge pages in the current instance: |
| 11884 |
<literal>on</literal>, <literal>off</literal>, or |
| 11885 |
<literal>unknown</literal> (if displayed with |
| 11886 |
<literal>postgres -C</literal>). |
| 11887 |
This parameter is useful to determine whether allocation of huge pages |
| 11888 |
was successful under <literal>huge_pages=try</literal>. |
| 11889 |
See <xref linkend="guc-huge-pages"/> for more information. |
| 11890 |
</para> |
| 11891 |
</listitem> |
| 11892 |
</varlistentry> |
| 11893 |
|
| 11894 |
<varlistentry id="guc-integer-datetimes" xreflabel="integer_datetimes"> |
| 11895 |
<term><varname>integer_datetimes</varname> (<type>boolean</type>) |
| 11896 |
<indexterm> |
| 11897 |
<primary><varname>integer_datetimes</varname> configuration parameter</primary> |
| 11898 |
</indexterm> |
| 11899 |
</term> |
| 11900 |
<listitem> |
| 11901 |
<para> |
| 11902 |
Reports whether <productname>PostgreSQL</productname> was built with support for |
| 11903 |
64-bit-integer dates and times. As of <productname>PostgreSQL</productname> 10, |
| 11904 |
this is always <literal>on</literal>. |
| 11905 |
</para> |
| 11906 |
</listitem> |
| 11907 |
</varlistentry> |
| 11908 |
|
| 11909 |
<varlistentry id="guc-in-hot-standby" xreflabel="in_hot_standby"> |
| 11910 |
<term><varname>in_hot_standby</varname> (<type>boolean</type>) |
| 11911 |
<indexterm> |
| 11912 |
<primary><varname>in_hot_standby</varname> configuration parameter</primary> |
| 11913 |
</indexterm> |
| 11914 |
</term> |
| 11915 |
<listitem> |
| 11916 |
<para> |
| 11917 |
Reports whether the server is currently in hot standby mode. When |
| 11918 |
this is <literal>on</literal>, all transactions are forced to be |
| 11919 |
read-only. Within a session, this can change only if the server is |
| 11920 |
promoted to be primary. See <xref linkend="hot-standby"/> for more |
| 11921 |
information. |
| 11922 |
</para> |
| 11923 |
</listitem> |
| 11924 |
</varlistentry> |
| 11925 |
|
| 11926 |
<varlistentry id="guc-max-function-args" xreflabel="max_function_args"> |
| 11927 |
<term><varname>max_function_args</varname> (<type>integer</type>) |
| 11928 |
<indexterm> |
| 11929 |
<primary><varname>max_function_args</varname> configuration parameter</primary> |
| 11930 |
</indexterm> |
| 11931 |
</term> |
| 11932 |
<listitem> |
| 11933 |
<para> |
| 11934 |
Reports the maximum number of function arguments. It is determined by |
| 11935 |
the value of <literal>FUNC_MAX_ARGS</literal> when building the server. The |
| 11936 |
default value is 100 arguments. |
| 11937 |
</para> |
| 11938 |
</listitem> |
| 11939 |
</varlistentry> |
| 11940 |
|
| 11941 |
<varlistentry id="guc-max-identifier-length" xreflabel="max_identifier_length"> |
| 11942 |
<term><varname>max_identifier_length</varname> (<type>integer</type>) |
| 11943 |
<indexterm> |
| 11944 |
<primary><varname>max_identifier_length</varname> configuration parameter</primary> |
| 11945 |
</indexterm> |
| 11946 |
</term> |
| 11947 |
<listitem> |
| 11948 |
<para> |
| 11949 |
Reports the maximum identifier length. It is determined as one |
| 11950 |
less than the value of <literal>NAMEDATALEN</literal> when building |
| 11951 |
the server. The default value of <literal>NAMEDATALEN</literal> is |
| 11952 |
64; therefore the default |
| 11953 |
<varname>max_identifier_length</varname> is 63 bytes, which |
| 11954 |
can be less than 63 characters when using multibyte encodings. |
| 11955 |
</para> |
| 11956 |
</listitem> |
| 11957 |
</varlistentry> |
| 11958 |
|
| 11959 |
<varlistentry id="guc-max-index-keys" xreflabel="max_index_keys"> |
| 11960 |
<term><varname>max_index_keys</varname> (<type>integer</type>) |
| 11961 |
<indexterm> |
| 11962 |
<primary><varname>max_index_keys</varname> configuration parameter</primary> |
| 11963 |
</indexterm> |
| 11964 |
</term> |
| 11965 |
<listitem> |
| 11966 |
<para> |
| 11967 |
Reports the maximum number of index keys. It is determined by |
| 11968 |
the value of <literal>INDEX_MAX_KEYS</literal> when building the server. The |
| 11969 |
default value is 32 keys. |
| 11970 |
</para> |
| 11971 |
</listitem> |
| 11972 |
</varlistentry> |
| 11973 |
|
| 11974 |
<varlistentry id="guc-num-os-semaphores" xreflabel="num_os_semaphores"> |
| 11975 |
<term><varname>num_os_semaphores</varname> (<type>integer</type>) |
| 11976 |
<indexterm> |
| 11977 |
<primary><varname>num_os_semaphores</varname> configuration parameter</primary> |
| 11978 |
</indexterm> |
| 11979 |
</term> |
| 11980 |
<listitem> |
| 11981 |
<para> |
| 11982 |
Reports the number of semaphores that are needed for the server based |
| 11983 |
on the configured number of allowed connections |
| 11984 |
(<xref linkend="guc-max-connections"/>), allowed autovacuum worker |
| 11985 |
processes (<xref linkend="guc-autovacuum-max-workers"/>), allowed WAL |
| 11986 |
sender processes (<xref linkend="guc-max-wal-senders"/>), allowed |
| 11987 |
background processes (<xref linkend="guc-max-worker-processes"/>), etc. |
| 11988 |
</para> |
| 11989 |
</listitem> |
| 11990 |
</varlistentry> |
| 11991 |
|
| 11992 |
<varlistentry id="guc-segment-size" xreflabel="segment_size"> |
| 11993 |
<term><varname>segment_size</varname> (<type>integer</type>) |
| 11994 |
<indexterm> |
| 11995 |
<primary><varname>segment_size</varname> configuration parameter</primary> |
| 11996 |
</indexterm> |
| 11997 |
</term> |
| 11998 |
<listitem> |
| 11999 |
<para> |
| 12000 |
Reports the number of blocks (pages) that can be stored within a file |
| 12001 |
segment. It is determined by the value of <literal>RELSEG_SIZE</literal> |
| 12002 |
when building the server. The maximum size of a segment file in bytes |
| 12003 |
is equal to <varname>segment_size</varname> multiplied by |
| 12004 |
<varname>block_size</varname>; by default this is 1GB. |
| 12005 |
</para> |
| 12006 |
</listitem> |
| 12007 |
</varlistentry> |
| 12008 |
|
| 12009 |
<varlistentry id="guc-server-encoding" xreflabel="server_encoding"> |
| 12010 |
<term><varname>server_encoding</varname> (<type>string</type>) |
| 12011 |
<indexterm> |
| 12012 |
<primary><varname>server_encoding</varname> configuration parameter</primary> |
| 12013 |
</indexterm> |
| 12014 |
<indexterm><primary>character set</primary></indexterm> |
| 12015 |
</term> |
| 12016 |
<listitem> |
| 12017 |
<para> |
| 12018 |
Reports the database encoding (character set). |
| 12019 |
It is determined when the database is created. Ordinarily, |
| 12020 |
clients need only be concerned with the value of <xref |
| 12021 |
linkend="guc-client-encoding"/>. |
| 12022 |
</para> |
| 12023 |
</listitem> |
| 12024 |
</varlistentry> |
| 12025 |
|
| 12026 |
<varlistentry id="guc-server-version" xreflabel="server_version"> |
| 12027 |
<term><varname>server_version</varname> (<type>string</type>) |
| 12028 |
<indexterm> |
| 12029 |
<primary><varname>server_version</varname> configuration parameter</primary> |
| 12030 |
</indexterm> |
| 12031 |
</term> |
| 12032 |
<listitem> |
| 12033 |
<para> |
| 12034 |
Reports the version number of the server. It is determined by the |
| 12035 |
value of <literal>PG_VERSION</literal> when building the server. |
| 12036 |
</para> |
| 12037 |
</listitem> |
| 12038 |
</varlistentry> |
| 12039 |
|
| 12040 |
<varlistentry id="guc-server-version-num" xreflabel="server_version_num"> |
| 12041 |
<term><varname>server_version_num</varname> (<type>integer</type>) |
| 12042 |
<indexterm> |
| 12043 |
<primary><varname>server_version_num</varname> configuration parameter</primary> |
| 12044 |
</indexterm> |
| 12045 |
</term> |
| 12046 |
<listitem> |
| 12047 |
<para> |
| 12048 |
Reports the version number of the server as an integer. It is determined |
| 12049 |
by the value of <literal>PG_VERSION_NUM</literal> when building the server. |
| 12050 |
</para> |
| 12051 |
</listitem> |
| 12052 |
</varlistentry> |
| 12053 |
|
| 12054 |
<varlistentry id="guc-shared-memory-size" xreflabel="shared_memory_size"> |
| 12055 |
<term><varname>shared_memory_size</varname> (<type>integer</type>) |
| 12056 |
<indexterm> |
| 12057 |
<primary><varname>shared_memory_size</varname> configuration parameter</primary> |
| 12058 |
</indexterm> |
| 12059 |
</term> |
| 12060 |
<listitem> |
| 12061 |
<para> |
| 12062 |
Reports the size of the main shared memory area, rounded up to the |
| 12063 |
nearest megabyte. |
| 12064 |
</para> |
| 12065 |
</listitem> |
| 12066 |
</varlistentry> |
| 12067 |
|
| 12068 |
<varlistentry id="guc-shared-memory-size-in-huge-pages" xreflabel="shared_memory_size_in_huge_pages"> |
| 12069 |
<term><varname>shared_memory_size_in_huge_pages</varname> (<type>integer</type>) |
| 12070 |
<indexterm> |
| 12071 |
<primary><varname>shared_memory_size_in_huge_pages</varname> configuration parameter</primary> |
| 12072 |
</indexterm> |
| 12073 |
</term> |
| 12074 |
<listitem> |
| 12075 |
<para> |
| 12076 |
Reports the number of huge pages that are needed for the main shared |
| 12077 |
memory area based on the specified <xref linkend="guc-huge-page-size"/>. |
| 12078 |
If huge pages are not supported, this will be <literal>-1</literal>. |
| 12079 |
</para> |
| 12080 |
<para> |
| 12081 |
This setting is supported only on <productname>Linux</productname>. It |
| 12082 |
is always set to <literal>-1</literal> on other platforms. For more |
| 12083 |
details about using huge pages on <productname>Linux</productname>, see |
| 12084 |
<xref linkend="linux-huge-pages"/>. |
| 12085 |
</para> |
| 12086 |
</listitem> |
| 12087 |
</varlistentry> |
| 12088 |
|
| 12089 |
<varlistentry id="guc-ssl-library" xreflabel="ssl_library"> |
| 12090 |
<term><varname>ssl_library</varname> (<type>string</type>) |
| 12091 |
<indexterm> |
| 12092 |
<primary><varname>ssl_library</varname> configuration parameter</primary> |
| 12093 |
</indexterm> |
| 12094 |
</term> |
| 12095 |
<listitem> |
| 12096 |
<para> |
| 12097 |
Reports the name of the SSL library that this |
| 12098 |
<productname>PostgreSQL</productname> server was built with (even if |
| 12099 |
SSL is not currently configured or in use on this instance), for |
| 12100 |
example <literal>OpenSSL</literal>, or an empty string if none. |
| 12101 |
</para> |
| 12102 |
</listitem> |
| 12103 |
</varlistentry> |
| 12104 |
|
| 12105 |
<varlistentry id="guc-wal-block-size" xreflabel="wal_block_size"> |
| 12106 |
<term><varname>wal_block_size</varname> (<type>integer</type>) |
| 12107 |
<indexterm> |
| 12108 |
<primary><varname>wal_block_size</varname> configuration parameter</primary> |
| 12109 |
</indexterm> |
| 12110 |
</term> |
| 12111 |
<listitem> |
| 12112 |
<para> |
| 12113 |
Reports the size of a WAL disk block. It is determined by the value |
| 12114 |
of <literal>XLOG_BLCKSZ</literal> when building the server. The default value |
| 12115 |
is 8192 bytes. |
| 12116 |
</para> |
| 12117 |
</listitem> |
| 12118 |
</varlistentry> |
| 12119 |
|
| 12120 |
<varlistentry id="guc-wal-segment-size" xreflabel="wal_segment_size"> |
| 12121 |
<term><varname>wal_segment_size</varname> (<type>integer</type>) |
| 12122 |
<indexterm> |
| 12123 |
<primary><varname>wal_segment_size</varname> configuration parameter</primary> |
| 12124 |
</indexterm> |
| 12125 |
</term> |
| 12126 |
<listitem> |
| 12127 |
<para> |
| 12128 |
Reports the size of write ahead log segments. The default value is |
| 12129 |
16MB. See <xref linkend="wal-configuration"/> for more information. |
| 12130 |
</para> |
| 12131 |
</listitem> |
| 12132 |
</varlistentry> |
| 12133 |
|
| 12134 |
</variablelist> |
| 12135 |
</sect1> |
| 12136 |
|
| 12137 |
<sect1 id="runtime-config-custom"> |
| 12138 |
<title>Customized Options</title> |
| 12139 |
|
| 12140 |
<para> |
| 12141 |
This feature was designed to allow parameters not normally known to |
| 12142 |
<productname>PostgreSQL</productname> to be added by add-on modules |
| 12143 |
(such as procedural languages). This allows extension modules to be |
| 12144 |
configured in the standard ways. |
| 12145 |
</para> |
| 12146 |
|
| 12147 |
<para> |
| 12148 |
Custom options have two-part names: an extension name, then a dot, then |
| 12149 |
the parameter name proper, much like qualified names in SQL. An example |
| 12150 |
is <literal>plpgsql.variable_conflict</literal>. |
| 12151 |
</para> |
| 12152 |
|
| 12153 |
<para> |
| 12154 |
Because custom options may need to be set in processes that have not |
| 12155 |
loaded the relevant extension module, <productname>PostgreSQL</productname> |
| 12156 |
will accept a setting for any two-part parameter name. Such variables |
| 12157 |
are treated as placeholders and have no function until the module that |
| 12158 |
defines them is loaded. When an extension module is loaded, it will add |
| 12159 |
its variable definitions and convert any placeholder values according to |
| 12160 |
those definitions. If there are any unrecognized placeholders |
| 12161 |
that begin with its extension name, warnings are issued and those |
| 12162 |
placeholders are removed. |
| 12163 |
</para> |
| 12164 |
</sect1> |
| 12165 |
|
| 12166 |
<sect1 id="runtime-config-developer"> |
| 12167 |
<title>Developer Options</title> |
| 12168 |
|
| 12169 |
<para> |
| 12170 |
The following parameters are intended for developer testing, and |
| 12171 |
should never be used on a production database. However, some of |
| 12172 |
them can be used to assist with the recovery of severely damaged |
| 12173 |
databases. As such, they have been excluded from the sample |
| 12174 |
<filename>postgresql.conf</filename> file. Note that many of these |
| 12175 |
parameters require special source compilation flags to work at all. |
| 12176 |
</para> |
| 12177 |
|
| 12178 |
<variablelist> |
| 12179 |
<varlistentry id="guc-allow-in-place-tablespaces" xreflabel="allow_in_place_tablespaces"> |
| 12180 |
<term><varname>allow_in_place_tablespaces</varname> (<type>boolean</type>) |
| 12181 |
<indexterm> |
| 12182 |
<primary><varname>allow_in_place_tablespaces</varname> configuration parameter</primary> |
| 12183 |
</indexterm> |
| 12184 |
</term> |
| 12185 |
<listitem> |
| 12186 |
<para> |
| 12187 |
Allows tablespaces to be created as directories inside |
| 12188 |
<filename>pg_tblspc</filename>, when an empty location string |
| 12189 |
is provided to the <command>CREATE TABLESPACE</command> command. This |
| 12190 |
is intended to allow testing replication scenarios where primary and |
| 12191 |
standby servers are running on the same machine. Such directories |
| 12192 |
are likely to confuse backup tools that expect to find only symbolic |
| 12193 |
links in that location. |
| 12194 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12195 |
privilege can change this setting. |
| 12196 |
</para> |
| 12197 |
</listitem> |
| 12198 |
</varlistentry> |
| 12199 |
|
| 12200 |
<varlistentry id="guc-allow-system-table-mods" xreflabel="allow_system_table_mods"> |
| 12201 |
<term><varname>allow_system_table_mods</varname> (<type>boolean</type>) |
| 12202 |
<indexterm> |
| 12203 |
<primary><varname>allow_system_table_mods</varname> configuration parameter</primary> |
| 12204 |
</indexterm> |
| 12205 |
</term> |
| 12206 |
<listitem> |
| 12207 |
<para> |
| 12208 |
Allows modification of the structure of system tables as well as |
| 12209 |
certain other risky actions on system tables. This is otherwise not |
| 12210 |
allowed even for superusers. Ill-advised use of this setting can |
| 12211 |
cause irretrievable data loss or seriously corrupt the database |
| 12212 |
system. |
| 12213 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12214 |
privilege can change this setting. |
| 12215 |
</para> |
| 12216 |
</listitem> |
| 12217 |
</varlistentry> |
| 12218 |
|
| 12219 |
<varlistentry id="guc-backtrace-functions" xreflabel="backtrace_functions"> |
| 12220 |
<term><varname>backtrace_functions</varname> (<type>string</type>) |
| 12221 |
<indexterm> |
| 12222 |
<primary><varname>backtrace_functions</varname> configuration parameter</primary> |
| 12223 |
</indexterm> |
| 12224 |
</term> |
| 12225 |
<listitem> |
| 12226 |
<para> |
| 12227 |
This parameter contains a comma-separated list of C function names. |
| 12228 |
If an error is raised and the name of the internal C function where |
| 12229 |
the error happens matches a value in the list, then a backtrace is |
| 12230 |
written to the server log together with the error message. This can |
| 12231 |
be used to debug specific areas of the source code. |
| 12232 |
</para> |
| 12233 |
|
| 12234 |
<para> |
| 12235 |
Backtrace support is not available on all platforms, and the quality |
| 12236 |
of the backtraces depends on compilation options. |
| 12237 |
</para> |
| 12238 |
|
| 12239 |
<para> |
| 12240 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12241 |
privilege can change this setting. |
| 12242 |
</para> |
| 12243 |
</listitem> |
| 12244 |
</varlistentry> |
| 12245 |
|
| 12246 |
<varlistentry id="guc-debug-copy-parse-plan-trees" xreflabel="debug_copy_parse_plan_trees"> |
| 12247 |
<term><varname>debug_copy_parse_plan_trees</varname> (<type>boolean</type>) |
| 12248 |
<indexterm> |
| 12249 |
<primary><varname>debug_copy_parse_plan_trees</varname> configuration parameter</primary> |
| 12250 |
</indexterm> |
| 12251 |
</term> |
| 12252 |
<listitem> |
| 12253 |
<para> |
| 12254 |
Enabling this forces all parse and plan trees to be passed through |
| 12255 |
<function>copyObject()</function>, to facilitate catching errors and |
| 12256 |
omissions in <function>copyObject()</function>. The default is off. |
| 12257 |
</para> |
| 12258 |
|
| 12259 |
<para> |
| 12260 |
This parameter is only available when |
| 12261 |
<symbol>DEBUG_NODE_TESTS_ENABLED</symbol> was defined at compile time |
| 12262 |
(which happens automatically when using the |
| 12263 |
<application>configure</application> option |
| 12264 |
<option>--enable-cassert</option>). |
| 12265 |
</para> |
| 12266 |
</listitem> |
| 12267 |
</varlistentry> |
| 12268 |
|
| 12269 |
<varlistentry id="guc-debug-discard-caches" xreflabel="debug_discard_caches"> |
| 12270 |
<term><varname>debug_discard_caches</varname> (<type>integer</type>) |
| 12271 |
<indexterm> |
| 12272 |
<primary><varname>debug_discard_caches</varname> configuration parameter</primary> |
| 12273 |
</indexterm> |
| 12274 |
</term> |
| 12275 |
<listitem> |
| 12276 |
<para> |
| 12277 |
When set to <literal>1</literal>, each system catalog cache entry is |
| 12278 |
invalidated at the first possible opportunity, whether or not |
| 12279 |
anything that would render it invalid really occurred. Caching of |
| 12280 |
system catalogs is effectively disabled as a result, so the server |
| 12281 |
will run extremely slowly. Higher values run the cache invalidation |
| 12282 |
recursively, which is even slower and only useful for testing |
| 12283 |
the caching logic itself. The default value of <literal>0</literal> |
| 12284 |
selects normal catalog caching behavior. |
| 12285 |
</para> |
| 12286 |
|
| 12287 |
<para> |
| 12288 |
This parameter can be very helpful when trying to trigger |
| 12289 |
hard-to-reproduce bugs involving concurrent catalog changes, but it |
| 12290 |
is otherwise rarely needed. See the source code files |
| 12291 |
<filename>inval.c</filename> and |
| 12292 |
<filename>pg_config_manual.h</filename> for details. |
| 12293 |
</para> |
| 12294 |
|
| 12295 |
<para> |
| 12296 |
This parameter is supported when |
| 12297 |
<symbol>DISCARD_CACHES_ENABLED</symbol> was defined at compile time |
| 12298 |
(which happens automatically when using the |
| 12299 |
<application>configure</application> option |
| 12300 |
<option>--enable-cassert</option>). In production builds, its value |
| 12301 |
will always be <literal>0</literal> and attempts to set it to another |
| 12302 |
value will raise an error. |
| 12303 |
</para> |
| 12304 |
</listitem> |
| 12305 |
</varlistentry> |
| 12306 |
|
| 12307 |
<varlistentry id="guc-debug-io-direct" xreflabel="debug_io_direct"> |
| 12308 |
<term><varname>debug_io_direct</varname> (<type>string</type>) |
| 12309 |
<indexterm> |
| 12310 |
<primary><varname>debug_io_direct</varname> configuration parameter</primary> |
| 12311 |
</indexterm> |
| 12312 |
</term> |
| 12313 |
<listitem> |
| 12314 |
<para> |
| 12315 |
Ask the kernel to minimize caching effects for relation data and WAL |
| 12316 |
files using <literal>O_DIRECT</literal> (most Unix-like systems), |
| 12317 |
<literal>F_NOCACHE</literal> (macOS) or |
| 12318 |
<literal>FILE_FLAG_NO_BUFFERING</literal> (Windows). |
| 12319 |
</para> |
| 12320 |
<para> |
| 12321 |
May be set to an empty string (the default) to disable use of direct |
| 12322 |
I/O, or a comma-separated list of operations that should use direct I/O. |
| 12323 |
The valid options are <literal>data</literal> for |
| 12324 |
main data files, <literal>wal</literal> for WAL files, and |
| 12325 |
<literal>wal_init</literal> for WAL files when being initially |
| 12326 |
allocated. |
| 12327 |
This parameter can only be set at server start. |
| 12328 |
</para> |
| 12329 |
<para> |
| 12330 |
Some operating systems and file systems do not support direct I/O, so |
| 12331 |
non-default settings may be rejected at startup or cause errors. |
| 12332 |
</para> |
| 12333 |
<para> |
| 12334 |
Currently this feature reduces performance, and is intended for |
| 12335 |
developer testing only. |
| 12336 |
</para> |
| 12337 |
</listitem> |
| 12338 |
</varlistentry> |
| 12339 |
|
| 12340 |
<varlistentry id="guc-debug-parallel-query" xreflabel="debug_parallel_query"> |
| 12341 |
<term><varname>debug_parallel_query</varname> (<type>enum</type>) |
| 12342 |
<indexterm> |
| 12343 |
<primary><varname>debug_parallel_query</varname> configuration parameter</primary> |
| 12344 |
</indexterm> |
| 12345 |
</term> |
| 12346 |
<listitem> |
| 12347 |
<para> |
| 12348 |
Allows the use of parallel queries for testing purposes even in cases |
| 12349 |
where no performance benefit is expected. |
| 12350 |
The allowed values of <varname>debug_parallel_query</varname> are |
| 12351 |
<literal>off</literal> (use parallel mode only when it is expected to improve |
| 12352 |
performance), <literal>on</literal> (force parallel query for all queries |
| 12353 |
for which it is thought to be safe), and <literal>regress</literal> (like |
| 12354 |
<literal>on</literal>, but with additional behavior changes as explained |
| 12355 |
below). |
| 12356 |
</para> |
| 12357 |
|
| 12358 |
<para> |
| 12359 |
More specifically, setting this value to <literal>on</literal> will add |
| 12360 |
a <literal>Gather</literal> node to the top of any query plan for which this |
| 12361 |
appears to be safe, so that the query runs inside of a parallel worker. |
| 12362 |
Even when a parallel worker is not available or cannot be used, |
| 12363 |
operations such as starting a subtransaction that would be prohibited |
| 12364 |
in a parallel query context will be prohibited unless the planner |
| 12365 |
believes that this will cause the query to fail. If failures or |
| 12366 |
unexpected results occur when this option is set, some functions used |
| 12367 |
by the query may need to be marked <literal>PARALLEL UNSAFE</literal> |
| 12368 |
(or, possibly, <literal>PARALLEL RESTRICTED</literal>). |
| 12369 |
</para> |
| 12370 |
|
| 12371 |
<para> |
| 12372 |
Setting this value to <literal>regress</literal> has all of the same effects |
| 12373 |
as setting it to <literal>on</literal> plus some additional effects that are |
| 12374 |
intended to facilitate automated regression testing. Normally, |
| 12375 |
messages from a parallel worker include a context line indicating that, |
| 12376 |
but a setting of <literal>regress</literal> suppresses this line so that the |
| 12377 |
output is the same as in non-parallel execution. Also, |
| 12378 |
the <literal>Gather</literal> nodes added to plans by this setting are hidden |
| 12379 |
in <literal>EXPLAIN</literal> output so that the output matches what |
| 12380 |
would be obtained if this setting were turned <literal>off</literal>. |
| 12381 |
</para> |
| 12382 |
</listitem> |
| 12383 |
</varlistentry> |
| 12384 |
|
| 12385 |
<varlistentry id="guc-debug-raw-expression-coverage-test" xreflabel="debug_raw_expression_coverage_test"> |
| 12386 |
<term><varname>debug_raw_expression_coverage_test</varname> (<type>boolean</type>) |
| 12387 |
<indexterm> |
| 12388 |
<primary><varname>debug_raw_expression_coverage_test</varname> configuration parameter</primary> |
| 12389 |
</indexterm> |
| 12390 |
</term> |
| 12391 |
<listitem> |
| 12392 |
<para> |
| 12393 |
Enabling this forces all raw parse trees for DML statements to be |
| 12394 |
scanned by <function>raw_expression_tree_walker()</function>, to |
| 12395 |
facilitate catching errors and omissions in that function. The |
| 12396 |
default is off. |
| 12397 |
</para> |
| 12398 |
|
| 12399 |
<para> |
| 12400 |
This parameter is only available when |
| 12401 |
<symbol>DEBUG_NODE_TESTS_ENABLED</symbol> was defined at compile time |
| 12402 |
(which happens automatically when using the |
| 12403 |
<application>configure</application> option |
| 12404 |
<option>--enable-cassert</option>). |
| 12405 |
</para> |
| 12406 |
</listitem> |
| 12407 |
</varlistentry> |
| 12408 |
|
| 12409 |
<varlistentry id="guc-debug-write-read-parse-plan-trees" xreflabel="debug_write_read_parse_plan_trees"> |
| 12410 |
<term><varname>debug_write_read_parse_plan_trees</varname> (<type>boolean</type>) |
| 12411 |
<indexterm> |
| 12412 |
<primary><varname>debug_write_read_parse_plan_trees</varname> configuration parameter</primary> |
| 12413 |
</indexterm> |
| 12414 |
</term> |
| 12415 |
<listitem> |
| 12416 |
<para> |
| 12417 |
Enabling this forces all parse and plan trees to be passed through |
| 12418 |
<filename>outfuncs.c</filename>/<filename>readfuncs.c</filename>, to |
| 12419 |
facilitate catching errors and omissions in those modules. The |
| 12420 |
default is off. |
| 12421 |
</para> |
| 12422 |
|
| 12423 |
<para> |
| 12424 |
This parameter is only available when |
| 12425 |
<symbol>DEBUG_NODE_TESTS_ENABLED</symbol> was defined at compile time |
| 12426 |
(which happens automatically when using the |
| 12427 |
<application>configure</application> option |
| 12428 |
<option>--enable-cassert</option>). |
| 12429 |
</para> |
| 12430 |
</listitem> |
| 12431 |
</varlistentry> |
| 12432 |
|
| 12433 |
<varlistentry id="guc-ignore-system-indexes" xreflabel="ignore_system_indexes"> |
| 12434 |
<term><varname>ignore_system_indexes</varname> (<type>boolean</type>) |
| 12435 |
<indexterm> |
| 12436 |
<primary><varname>ignore_system_indexes</varname> configuration parameter</primary> |
| 12437 |
</indexterm> |
| 12438 |
</term> |
| 12439 |
<listitem> |
| 12440 |
<para> |
| 12441 |
Ignore system indexes when reading system tables (but still |
| 12442 |
update the indexes when modifying the tables). This is useful |
| 12443 |
when recovering from damaged system indexes. |
| 12444 |
This parameter cannot be changed after session start. |
| 12445 |
</para> |
| 12446 |
</listitem> |
| 12447 |
</varlistentry> |
| 12448 |
|
| 12449 |
<varlistentry id="guc-post-auth-delay" xreflabel="post_auth_delay"> |
| 12450 |
<term><varname>post_auth_delay</varname> (<type>integer</type>) |
| 12451 |
<indexterm> |
| 12452 |
<primary><varname>post_auth_delay</varname> configuration parameter</primary> |
| 12453 |
</indexterm> |
| 12454 |
</term> |
| 12455 |
<listitem> |
| 12456 |
<para> |
| 12457 |
The amount of time to delay when a new |
| 12458 |
server process is started, after it conducts the |
| 12459 |
authentication procedure. This is intended to give developers an |
| 12460 |
opportunity to attach to the server process with a debugger. |
| 12461 |
If this value is specified without units, it is taken as seconds. |
| 12462 |
A value of zero (the default) disables the delay. |
| 12463 |
This parameter cannot be changed after session start. |
| 12464 |
</para> |
| 12465 |
</listitem> |
| 12466 |
</varlistentry> |
| 12467 |
|
| 12468 |
<varlistentry id="guc-pre-auth-delay" xreflabel="pre_auth_delay"> |
| 12469 |
<term><varname>pre_auth_delay</varname> (<type>integer</type>) |
| 12470 |
<indexterm> |
| 12471 |
<primary><varname>pre_auth_delay</varname> configuration parameter</primary> |
| 12472 |
</indexterm> |
| 12473 |
</term> |
| 12474 |
<listitem> |
| 12475 |
<para> |
| 12476 |
The amount of time to delay just after a |
| 12477 |
new server process is forked, before it conducts the |
| 12478 |
authentication procedure. This is intended to give developers an |
| 12479 |
opportunity to attach to the server process with a debugger to |
| 12480 |
trace down misbehavior in authentication. |
| 12481 |
If this value is specified without units, it is taken as seconds. |
| 12482 |
A value of zero (the default) disables the delay. |
| 12483 |
This parameter can only be set in the <filename>postgresql.conf</filename> |
| 12484 |
file or on the server command line. |
| 12485 |
</para> |
| 12486 |
</listitem> |
| 12487 |
</varlistentry> |
| 12488 |
|
| 12489 |
<varlistentry id="guc-trace-notify" xreflabel="trace_notify"> |
| 12490 |
<term><varname>trace_notify</varname> (<type>boolean</type>) |
| 12491 |
<indexterm> |
| 12492 |
<primary><varname>trace_notify</varname> configuration parameter</primary> |
| 12493 |
</indexterm> |
| 12494 |
</term> |
| 12495 |
<listitem> |
| 12496 |
<para> |
| 12497 |
Generates a great amount of debugging output for the |
| 12498 |
<command>LISTEN</command> and <command>NOTIFY</command> |
| 12499 |
commands. <xref linkend="guc-client-min-messages"/> or |
| 12500 |
<xref linkend="guc-log-min-messages"/> must be |
| 12501 |
<literal>DEBUG1</literal> or lower to send this output to the |
| 12502 |
client or server logs, respectively. |
| 12503 |
</para> |
| 12504 |
</listitem> |
| 12505 |
</varlistentry> |
| 12506 |
|
| 12507 |
<varlistentry id="guc-trace-sort" xreflabel="trace_sort"> |
| 12508 |
<term><varname>trace_sort</varname> (<type>boolean</type>) |
| 12509 |
<indexterm> |
| 12510 |
<primary><varname>trace_sort</varname> configuration parameter</primary> |
| 12511 |
</indexterm> |
| 12512 |
</term> |
| 12513 |
<listitem> |
| 12514 |
<para> |
| 12515 |
If on, emit information about resource usage during sort operations. |
| 12516 |
</para> |
| 12517 |
</listitem> |
| 12518 |
</varlistentry> |
| 12519 |
|
| 12520 |
<varlistentry id="guc-trace-locks" xreflabel="trace_locks"> |
| 12521 |
<term><varname>trace_locks</varname> (<type>boolean</type>) |
| 12522 |
<indexterm> |
| 12523 |
<primary><varname>trace_locks</varname> configuration parameter</primary> |
| 12524 |
</indexterm> |
| 12525 |
</term> |
| 12526 |
<listitem> |
| 12527 |
<para> |
| 12528 |
If on, emit information about lock usage. Information dumped |
| 12529 |
includes the type of lock operation, the type of lock and the unique |
| 12530 |
identifier of the object being locked or unlocked. Also included |
| 12531 |
are bit masks for the lock types already granted on this object as |
| 12532 |
well as for the lock types awaited on this object. For each lock |
| 12533 |
type a count of the number of granted locks and waiting locks is |
| 12534 |
also dumped as well as the totals. An example of the log file output |
| 12535 |
is shown here: |
| 12536 |
<screen> |
| 12537 |
LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) |
| 12538 |
grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 |
| 12539 |
wait(0) type(AccessShareLock) |
| 12540 |
LOG: GrantLock: lock(0xb7acd844) id(24688,24696,0,0,0,1) |
| 12541 |
grantMask(2) req(1,0,0,0,0,0,0)=1 grant(1,0,0,0,0,0,0)=1 |
| 12542 |
wait(0) type(AccessShareLock) |
| 12543 |
LOG: UnGrantLock: updated: lock(0xb7acd844) id(24688,24696,0,0,0,1) |
| 12544 |
grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 |
| 12545 |
wait(0) type(AccessShareLock) |
| 12546 |
LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) |
| 12547 |
grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 |
| 12548 |
wait(0) type(INVALID) |
| 12549 |
</screen> |
| 12550 |
Details of the structure being dumped may be found in |
| 12551 |
<filename>src/include/storage/lock.h</filename>. |
| 12552 |
</para> |
| 12553 |
<para> |
| 12554 |
This parameter is only available if the <symbol>LOCK_DEBUG</symbol> |
| 12555 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12556 |
compiled. |
| 12557 |
</para> |
| 12558 |
</listitem> |
| 12559 |
</varlistentry> |
| 12560 |
|
| 12561 |
<varlistentry id="guc-trace-lwlocks" xreflabel="trace_lwlocks"> |
| 12562 |
<term><varname>trace_lwlocks</varname> (<type>boolean</type>) |
| 12563 |
<indexterm> |
| 12564 |
<primary><varname>trace_lwlocks</varname> configuration parameter</primary> |
| 12565 |
</indexterm> |
| 12566 |
</term> |
| 12567 |
<listitem> |
| 12568 |
<para> |
| 12569 |
If on, emit information about lightweight lock usage. Lightweight |
| 12570 |
locks are intended primarily to provide mutual exclusion of access |
| 12571 |
to shared-memory data structures. |
| 12572 |
</para> |
| 12573 |
<para> |
| 12574 |
This parameter is only available if the <symbol>LOCK_DEBUG</symbol> |
| 12575 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12576 |
compiled. |
| 12577 |
</para> |
| 12578 |
</listitem> |
| 12579 |
</varlistentry> |
| 12580 |
|
| 12581 |
<varlistentry id="guc-trace-userlocks" xreflabel="trace_userlocks"> |
| 12582 |
<term><varname>trace_userlocks</varname> (<type>boolean</type>) |
| 12583 |
<indexterm> |
| 12584 |
<primary><varname>trace_userlocks</varname> configuration parameter</primary> |
| 12585 |
</indexterm> |
| 12586 |
</term> |
| 12587 |
<listitem> |
| 12588 |
<para> |
| 12589 |
If on, emit information about user lock usage. Output is the same |
| 12590 |
as for <symbol>trace_locks</symbol>, only for advisory locks. |
| 12591 |
</para> |
| 12592 |
<para> |
| 12593 |
This parameter is only available if the <symbol>LOCK_DEBUG</symbol> |
| 12594 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12595 |
compiled. |
| 12596 |
</para> |
| 12597 |
</listitem> |
| 12598 |
</varlistentry> |
| 12599 |
|
| 12600 |
<varlistentry id="guc-trace-lock-oidmin" xreflabel="trace_lock_oidmin"> |
| 12601 |
<term><varname>trace_lock_oidmin</varname> (<type>integer</type>) |
| 12602 |
<indexterm> |
| 12603 |
<primary><varname>trace_lock_oidmin</varname> configuration parameter</primary> |
| 12604 |
</indexterm> |
| 12605 |
</term> |
| 12606 |
<listitem> |
| 12607 |
<para> |
| 12608 |
If set, do not trace locks for tables below this OID (used to avoid |
| 12609 |
output on system tables). |
| 12610 |
</para> |
| 12611 |
<para> |
| 12612 |
This parameter is only available if the <symbol>LOCK_DEBUG</symbol> |
| 12613 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12614 |
compiled. |
| 12615 |
</para> |
| 12616 |
</listitem> |
| 12617 |
</varlistentry> |
| 12618 |
|
| 12619 |
<varlistentry id="guc-trace-lock-table" xreflabel="trace_lock_table"> |
| 12620 |
<term><varname>trace_lock_table</varname> (<type>integer</type>) |
| 12621 |
<indexterm> |
| 12622 |
<primary><varname>trace_lock_table</varname> configuration parameter</primary> |
| 12623 |
</indexterm> |
| 12624 |
</term> |
| 12625 |
<listitem> |
| 12626 |
<para> |
| 12627 |
Unconditionally trace locks on this table (OID). |
| 12628 |
</para> |
| 12629 |
<para> |
| 12630 |
This parameter is only available if the <symbol>LOCK_DEBUG</symbol> |
| 12631 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12632 |
compiled. |
| 12633 |
</para> |
| 12634 |
</listitem> |
| 12635 |
</varlistentry> |
| 12636 |
|
| 12637 |
<varlistentry id="guc-debug-deadlocks" xreflabel="debug_deadlocks"> |
| 12638 |
<term><varname>debug_deadlocks</varname> (<type>boolean</type>) |
| 12639 |
<indexterm> |
| 12640 |
<primary><varname>debug_deadlocks</varname> configuration parameter</primary> |
| 12641 |
</indexterm> |
| 12642 |
</term> |
| 12643 |
<listitem> |
| 12644 |
<para> |
| 12645 |
If set, dumps information about all current locks when a |
| 12646 |
deadlock timeout occurs. |
| 12647 |
</para> |
| 12648 |
<para> |
| 12649 |
This parameter is only available if the <symbol>LOCK_DEBUG</symbol> |
| 12650 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12651 |
compiled. |
| 12652 |
</para> |
| 12653 |
</listitem> |
| 12654 |
</varlistentry> |
| 12655 |
|
| 12656 |
<varlistentry id="guc-log-btree-build-stats" xreflabel="log_btree_build_stats"> |
| 12657 |
<term><varname>log_btree_build_stats</varname> (<type>boolean</type>) |
| 12658 |
<indexterm> |
| 12659 |
<primary><varname>log_btree_build_stats</varname> configuration parameter</primary> |
| 12660 |
</indexterm> |
| 12661 |
</term> |
| 12662 |
<listitem> |
| 12663 |
<para> |
| 12664 |
If set, logs system resource usage statistics (memory and CPU) on |
| 12665 |
various B-tree operations. |
| 12666 |
</para> |
| 12667 |
<para> |
| 12668 |
This parameter is only available if the <symbol>BTREE_BUILD_STATS</symbol> |
| 12669 |
macro was defined when <productname>PostgreSQL</productname> was |
| 12670 |
compiled. |
| 12671 |
</para> |
| 12672 |
</listitem> |
| 12673 |
</varlistentry> |
| 12674 |
|
| 12675 |
<varlistentry id="guc-wal-consistency-checking" xreflabel="wal_consistency_checking"> |
| 12676 |
<term><varname>wal_consistency_checking</varname> (<type>string</type>) |
| 12677 |
<indexterm> |
| 12678 |
<primary><varname>wal_consistency_checking</varname> configuration parameter</primary> |
| 12679 |
</indexterm> |
| 12680 |
</term> |
| 12681 |
<listitem> |
| 12682 |
<para> |
| 12683 |
This parameter is intended to be used to check for bugs in the WAL |
| 12684 |
redo routines. When enabled, full-page images of any buffers modified |
| 12685 |
in conjunction with the WAL record are added to the record. |
| 12686 |
If the record is subsequently replayed, the system will first apply |
| 12687 |
each record and then test whether the buffers modified by the record |
| 12688 |
match the stored images. In certain cases (such as hint bits), minor |
| 12689 |
variations are acceptable, and will be ignored. Any unexpected |
| 12690 |
differences will result in a fatal error, terminating recovery. |
| 12691 |
</para> |
| 12692 |
|
| 12693 |
<para> |
| 12694 |
The default value of this setting is the empty string, which disables |
| 12695 |
the feature. It can be set to <literal>all</literal> to check all |
| 12696 |
records, or to a comma-separated list of resource managers to check |
| 12697 |
only records originating from those resource managers. Currently, |
| 12698 |
the supported resource managers are <literal>heap</literal>, |
| 12699 |
<literal>heap2</literal>, <literal>btree</literal>, <literal>hash</literal>, |
| 12700 |
<literal>gin</literal>, <literal>gist</literal>, <literal>sequence</literal>, |
| 12701 |
<literal>spgist</literal>, <literal>brin</literal>, and <literal>generic</literal>. |
| 12702 |
Extensions may define additional resource managers. Only superusers and users with |
| 12703 |
the appropriate <literal>SET</literal> privilege can change this setting. |
| 12704 |
</para> |
| 12705 |
</listitem> |
| 12706 |
</varlistentry> |
| 12707 |
|
| 12708 |
<varlistentry id="guc-wal-debug" xreflabel="wal_debug"> |
| 12709 |
<term><varname>wal_debug</varname> (<type>boolean</type>) |
| 12710 |
<indexterm> |
| 12711 |
<primary><varname>wal_debug</varname> configuration parameter</primary> |
| 12712 |
</indexterm> |
| 12713 |
</term> |
| 12714 |
<listitem> |
| 12715 |
<para> |
| 12716 |
If on, emit WAL-related debugging output. This parameter is |
| 12717 |
only available if the <symbol>WAL_DEBUG</symbol> macro was |
| 12718 |
defined when <productname>PostgreSQL</productname> was |
| 12719 |
compiled. |
| 12720 |
</para> |
| 12721 |
</listitem> |
| 12722 |
</varlistentry> |
| 12723 |
|
| 12724 |
<varlistentry id="guc-ignore-checksum-failure" xreflabel="ignore_checksum_failure"> |
| 12725 |
<term><varname>ignore_checksum_failure</varname> (<type>boolean</type>) |
| 12726 |
<indexterm> |
| 12727 |
<primary><varname>ignore_checksum_failure</varname> configuration parameter</primary> |
| 12728 |
</indexterm> |
| 12729 |
</term> |
| 12730 |
<listitem> |
| 12731 |
<para> |
| 12732 |
Only has effect if <link linkend="checksums">data checksums</link> are enabled. |
| 12733 |
</para> |
| 12734 |
<para> |
| 12735 |
Detection of a checksum failure during a read normally causes |
| 12736 |
<productname>PostgreSQL</productname> to report an error, aborting the current |
| 12737 |
transaction. Setting <varname>ignore_checksum_failure</varname> to on causes |
| 12738 |
the system to ignore the failure (but still report a warning), and |
| 12739 |
continue processing. This behavior may <emphasis>cause crashes, propagate |
| 12740 |
or hide corruption, or other serious problems</emphasis>. However, it may allow |
| 12741 |
you to get past the error and retrieve undamaged tuples that might still be |
| 12742 |
present in the table if the block header is still sane. If the header is |
| 12743 |
corrupt an error will be reported even if this option is enabled. The |
| 12744 |
default setting is <literal>off</literal>. |
| 12745 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12746 |
privilege can change this setting. |
| 12747 |
</para> |
| 12748 |
</listitem> |
| 12749 |
</varlistentry> |
| 12750 |
|
| 12751 |
<varlistentry id="guc-zero-damaged-pages" xreflabel="zero_damaged_pages"> |
| 12752 |
<term><varname>zero_damaged_pages</varname> (<type>boolean</type>) |
| 12753 |
<indexterm> |
| 12754 |
<primary><varname>zero_damaged_pages</varname> configuration parameter</primary> |
| 12755 |
</indexterm> |
| 12756 |
</term> |
| 12757 |
<listitem> |
| 12758 |
<para> |
| 12759 |
Detection of a damaged page header normally causes |
| 12760 |
<productname>PostgreSQL</productname> to report an error, aborting the current |
| 12761 |
transaction. Setting <varname>zero_damaged_pages</varname> to on causes |
| 12762 |
the system to instead report a warning, zero out the damaged |
| 12763 |
page in memory, and continue processing. This behavior <emphasis>will destroy data</emphasis>, |
| 12764 |
namely all the rows on the damaged page. However, it does allow you to get |
| 12765 |
past the error and retrieve rows from any undamaged pages that might |
| 12766 |
be present in the table. It is useful for recovering data if |
| 12767 |
corruption has occurred due to a hardware or software error. You should |
| 12768 |
generally not set this on until you have given up hope of recovering |
| 12769 |
data from the damaged pages of a table. Zeroed-out pages are not |
| 12770 |
forced to disk so it is recommended to recreate the table or |
| 12771 |
the index before turning this parameter off again. The |
| 12772 |
default setting is <literal>off</literal>. |
| 12773 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12774 |
privilege can change this setting. |
| 12775 |
</para> |
| 12776 |
</listitem> |
| 12777 |
</varlistentry> |
| 12778 |
|
| 12779 |
<varlistentry id="guc-ignore-invalid-pages" xreflabel="ignore_invalid_pages"> |
| 12780 |
<term><varname>ignore_invalid_pages</varname> (<type>boolean</type>) |
| 12781 |
<indexterm> |
| 12782 |
<primary><varname>ignore_invalid_pages</varname> configuration parameter</primary> |
| 12783 |
</indexterm> |
| 12784 |
</term> |
| 12785 |
<listitem> |
| 12786 |
<para> |
| 12787 |
If set to <literal>off</literal> (the default), detection of |
| 12788 |
WAL records having references to invalid pages during |
| 12789 |
recovery causes <productname>PostgreSQL</productname> to |
| 12790 |
raise a PANIC-level error, aborting the recovery. Setting |
| 12791 |
<varname>ignore_invalid_pages</varname> to <literal>on</literal> |
| 12792 |
causes the system to ignore invalid page references in WAL records |
| 12793 |
(but still report a warning), and continue the recovery. |
| 12794 |
This behavior may <emphasis>cause crashes, data loss, |
| 12795 |
propagate or hide corruption, or other serious problems</emphasis>. |
| 12796 |
However, it may allow you to get past the PANIC-level error, |
| 12797 |
to finish the recovery, and to cause the server to start up. |
| 12798 |
The parameter can only be set at server start. It only has effect |
| 12799 |
during recovery or in standby mode. |
| 12800 |
</para> |
| 12801 |
</listitem> |
| 12802 |
</varlistentry> |
| 12803 |
|
| 12804 |
<varlistentry id="guc-jit-debugging-support" xreflabel="jit_debugging_support"> |
| 12805 |
<term><varname>jit_debugging_support</varname> (<type>boolean</type>) |
| 12806 |
<indexterm> |
| 12807 |
<primary><varname>jit_debugging_support</varname> configuration parameter</primary> |
| 12808 |
</indexterm> |
| 12809 |
</term> |
| 12810 |
<listitem> |
| 12811 |
<para> |
| 12812 |
If LLVM has the required functionality, register generated functions |
| 12813 |
with <productname>GDB</productname>. This makes debugging easier. |
| 12814 |
The default setting is <literal>off</literal>. |
| 12815 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12816 |
privilege can change this parameter at session start, |
| 12817 |
and it cannot be changed at all within a session. |
| 12818 |
</para> |
| 12819 |
</listitem> |
| 12820 |
</varlistentry> |
| 12821 |
|
| 12822 |
<varlistentry id="guc-jit-dump-bitcode" xreflabel="jit_dump_bitcode"> |
| 12823 |
<term><varname>jit_dump_bitcode</varname> (<type>boolean</type>) |
| 12824 |
<indexterm> |
| 12825 |
<primary><varname>jit_dump_bitcode</varname> configuration parameter</primary> |
| 12826 |
</indexterm> |
| 12827 |
</term> |
| 12828 |
<listitem> |
| 12829 |
<para> |
| 12830 |
Writes the generated <productname>LLVM</productname> IR out to the |
| 12831 |
file system, inside <xref linkend="guc-data-directory"/>. This is only |
| 12832 |
useful for working on the internals of the JIT implementation. |
| 12833 |
The default setting is <literal>off</literal>. |
| 12834 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12835 |
privilege can change this setting. |
| 12836 |
</para> |
| 12837 |
</listitem> |
| 12838 |
</varlistentry> |
| 12839 |
|
| 12840 |
<varlistentry id="guc-jit-expressions" xreflabel="jit_expressions"> |
| 12841 |
<term><varname>jit_expressions</varname> (<type>boolean</type>) |
| 12842 |
<indexterm> |
| 12843 |
<primary><varname>jit_expressions</varname> configuration parameter</primary> |
| 12844 |
</indexterm> |
| 12845 |
</term> |
| 12846 |
<listitem> |
| 12847 |
<para> |
| 12848 |
Determines whether expressions are JIT compiled, when JIT compilation |
| 12849 |
is activated (see <xref linkend="jit-decision"/>). The default is |
| 12850 |
<literal>on</literal>. |
| 12851 |
</para> |
| 12852 |
</listitem> |
| 12853 |
</varlistentry> |
| 12854 |
|
| 12855 |
<varlistentry id="guc-jit-profiling-support" xreflabel="jit_profiling_support"> |
| 12856 |
<term><varname>jit_profiling_support</varname> (<type>boolean</type>) |
| 12857 |
<indexterm> |
| 12858 |
<primary><varname>jit_profiling_support</varname> configuration parameter</primary> |
| 12859 |
</indexterm> |
| 12860 |
</term> |
| 12861 |
<listitem> |
| 12862 |
<para> |
| 12863 |
If LLVM has the required functionality, emit the data needed to allow |
| 12864 |
<productname>perf</productname> to profile functions generated by JIT. |
| 12865 |
This writes out files to <filename>~/.debug/jit/</filename>; the |
| 12866 |
user is responsible for performing cleanup when desired. |
| 12867 |
The default setting is <literal>off</literal>. |
| 12868 |
Only superusers and users with the appropriate <literal>SET</literal> |
| 12869 |
privilege can change this parameter at session start, |
| 12870 |
and it cannot be changed at all within a session. |
| 12871 |
</para> |
| 12872 |
</listitem> |
| 12873 |
</varlistentry> |
| 12874 |
|
| 12875 |
<varlistentry id="guc-jit-tuple-deforming" xreflabel="jit_tuple_deforming"> |
| 12876 |
<term><varname>jit_tuple_deforming</varname> (<type>boolean</type>) |
| 12877 |
<indexterm> |
| 12878 |
<primary><varname>jit_tuple_deforming</varname> configuration parameter</primary> |
| 12879 |
</indexterm> |
| 12880 |
</term> |
| 12881 |
<listitem> |
| 12882 |
<para> |
| 12883 |
Determines whether tuple deforming is JIT compiled, when JIT |
| 12884 |
compilation is activated (see <xref linkend="jit-decision"/>). |
| 12885 |
The default is <literal>on</literal>. |
| 12886 |
</para> |
| 12887 |
</listitem> |
| 12888 |
</varlistentry> |
| 12889 |
|
| 12890 |
<varlistentry id="guc-remove-temp-files-after-crash" xreflabel="remove_temp_files_after_crash"> |
| 12891 |
<term><varname>remove_temp_files_after_crash</varname> (<type>boolean</type>) |
| 12892 |
<indexterm> |
| 12893 |
<primary><varname>remove_temp_files_after_crash</varname> configuration parameter</primary> |
| 12894 |
</indexterm> |
| 12895 |
</term> |
| 12896 |
<listitem> |
| 12897 |
<para> |
| 12898 |
When set to <literal>on</literal>, which is the default, |
| 12899 |
<productname>PostgreSQL</productname> will automatically remove |
| 12900 |
temporary files after a backend crash. If disabled, the files will be |
| 12901 |
retained and may be used for debugging, for example. Repeated crashes |
| 12902 |
may however result in accumulation of useless files. This parameter |
| 12903 |
can only be set in the <filename>postgresql.conf</filename> file or on |
| 12904 |
the server command line. |
| 12905 |
</para> |
| 12906 |
</listitem> |
| 12907 |
</varlistentry> |
| 12908 |
|
| 12909 |
<varlistentry id="guc-send-abort-for-crash" xreflabel="send_abort_for_crash"> |
| 12910 |
<term><varname>send_abort_for_crash</varname> (<type>boolean</type>) |
| 12911 |
<indexterm> |
| 12912 |
<primary><varname>send_abort_for_crash</varname> configuration parameter</primary> |
| 12913 |
</indexterm> |
| 12914 |
</term> |
| 12915 |
<listitem> |
| 12916 |
<para> |
| 12917 |
By default, after a backend crash the postmaster will stop remaining |
| 12918 |
child processes by sending them <systemitem>SIGQUIT</systemitem> |
| 12919 |
signals, which permits them to exit more-or-less gracefully. When |
| 12920 |
this option is set to <literal>on</literal>, |
| 12921 |
<systemitem>SIGABRT</systemitem> is sent instead. That normally |
| 12922 |
results in production of a core dump file for each such child |
| 12923 |
process. |
| 12924 |
This can be handy for investigating the states of other processes |
| 12925 |
after a crash. It can also consume lots of disk space in the event |
| 12926 |
of repeated crashes, so do not enable this on systems you are not |
| 12927 |
monitoring carefully. |
| 12928 |
Beware that no support exists for cleaning up the core file(s) |
| 12929 |
automatically. |
| 12930 |
This parameter can only be set in |
| 12931 |
the <filename>postgresql.conf</filename> file or on the server |
| 12932 |
command line. |
| 12933 |
</para> |
| 12934 |
</listitem> |
| 12935 |
</varlistentry> |
| 12936 |
|
| 12937 |
<varlistentry id="guc-send-abort-for-kill" xreflabel="send_abort_for_kill"> |
| 12938 |
<term><varname>send_abort_for_kill</varname> (<type>boolean</type>) |
| 12939 |
<indexterm> |
| 12940 |
<primary><varname>send_abort_for_kill</varname> configuration parameter</primary> |
| 12941 |
</indexterm> |
| 12942 |
</term> |
| 12943 |
<listitem> |
| 12944 |
<para> |
| 12945 |
By default, after attempting to stop a child process with |
| 12946 |
<systemitem>SIGQUIT</systemitem>, the postmaster will wait five |
| 12947 |
seconds and then send <systemitem>SIGKILL</systemitem> to force |
| 12948 |
immediate termination. When this option is set |
| 12949 |
to <literal>on</literal>, <systemitem>SIGABRT</systemitem> is sent |
| 12950 |
instead of <systemitem>SIGKILL</systemitem>. That normally results |
| 12951 |
in production of a core dump file for each such child process. |
| 12952 |
This can be handy for investigating the states |
| 12953 |
of <quote>stuck</quote> child processes. It can also consume lots |
| 12954 |
of disk space in the event of repeated crashes, so do not enable |
| 12955 |
this on systems you are not monitoring carefully. |
| 12956 |
Beware that no support exists for cleaning up the core file(s) |
| 12957 |
automatically. |
| 12958 |
This parameter can only be set in |
| 12959 |
the <filename>postgresql.conf</filename> file or on the server |
| 12960 |
command line. |
| 12961 |
</para> |
| 12962 |
</listitem> |
| 12963 |
</varlistentry> |
| 12964 |
|
| 12965 |
<varlistentry id="guc-debug-logical-replication-streaming" xreflabel="debug_logical_replication_streaming"> |
| 12966 |
<term><varname>debug_logical_replication_streaming</varname> (<type>enum</type>) |
| 12967 |
<indexterm> |
| 12968 |
<primary><varname>debug_logical_replication_streaming</varname> configuration parameter</primary> |
| 12969 |
</indexterm> |
| 12970 |
</term> |
| 12971 |
<listitem> |
| 12972 |
<para> |
| 12973 |
The allowed values are <literal>buffered</literal> and |
| 12974 |
<literal>immediate</literal>. The default is <literal>buffered</literal>. |
| 12975 |
This parameter is intended to be used to test logical decoding and |
| 12976 |
replication of large transactions. The effect of |
| 12977 |
<varname>debug_logical_replication_streaming</varname> is different for the |
| 12978 |
publisher and subscriber: |
| 12979 |
</para> |
| 12980 |
|
| 12981 |
<para> |
| 12982 |
On the publisher side, <varname>debug_logical_replication_streaming</varname> |
| 12983 |
allows streaming or serializing changes immediately in logical decoding. |
| 12984 |
When set to <literal>immediate</literal>, stream each change if the |
| 12985 |
<link linkend="sql-createsubscription-params-with-streaming"><literal>streaming</literal></link> |
| 12986 |
option of |
| 12987 |
<link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link> |
| 12988 |
is enabled, otherwise, serialize each change. When set to |
| 12989 |
<literal>buffered</literal>, the decoding will stream or serialize |
| 12990 |
changes when <varname>logical_decoding_work_mem</varname> is reached. |
| 12991 |
</para> |
| 12992 |
|
| 12993 |
<para> |
| 12994 |
On the subscriber side, if the <literal>streaming</literal> option is set to |
| 12995 |
<literal>parallel</literal>, <varname>debug_logical_replication_streaming</varname> |
| 12996 |
can be used to direct the leader apply worker to send changes to the |
| 12997 |
shared memory queue or to serialize all changes to the file. When set to |
| 12998 |
<literal>buffered</literal>, the leader sends changes to parallel apply |
| 12999 |
workers via a shared memory queue. When set to |
| 13000 |
<literal>immediate</literal>, the leader serializes all changes to files |
| 13001 |
and notifies the parallel apply workers to read and apply them at the |
| 13002 |
end of the transaction. |
| 13003 |
</para> |
| 13004 |
</listitem> |
| 13005 |
</varlistentry> |
| 13006 |
|
| 13007 |
</variablelist> |
| 13008 |
</sect1> |
| 13009 |
<sect1 id="runtime-config-short"> |
| 13010 |
<title>Short Options</title> |
| 13011 |
|
| 13012 |
<para> |
| 13013 |
For convenience there are also single letter command-line option |
| 13014 |
switches available for some parameters. They are described in |
| 13015 |
<xref linkend="runtime-config-short-table"/>. Some of these |
| 13016 |
options exist for historical reasons, and their presence as a |
| 13017 |
single-letter option does not necessarily indicate an endorsement |
| 13018 |
to use the option heavily. |
| 13019 |
</para> |
| 13020 |
|
| 13021 |
<table id="runtime-config-short-table"> |
| 13022 |
<title>Short Option Key</title> |
| 13023 |
<tgroup cols="2"> |
| 13024 |
<colspec colname="col1" colwidth="1*"/> |
| 13025 |
<colspec colname="col2" colwidth="2*"/> |
| 13026 |
<thead> |
| 13027 |
<row> |
| 13028 |
<entry>Short Option</entry> |
| 13029 |
<entry>Equivalent</entry> |
| 13030 |
</row> |
| 13031 |
</thead> |
| 13032 |
|
| 13033 |
<tbody> |
| 13034 |
<row> |
| 13035 |
<entry><option>-B <replaceable>x</replaceable></option></entry> |
| 13036 |
<entry><literal>shared_buffers = <replaceable>x</replaceable></literal></entry> |
| 13037 |
</row> |
| 13038 |
<row> |
| 13039 |
<entry><option>-d <replaceable>x</replaceable></option></entry> |
| 13040 |
<entry><literal>log_min_messages = DEBUG<replaceable>x</replaceable></literal></entry> |
| 13041 |
</row> |
| 13042 |
<row> |
| 13043 |
<entry><option>-e</option></entry> |
| 13044 |
<entry><literal>datestyle = euro</literal></entry> |
| 13045 |
</row> |
| 13046 |
<row> |
| 13047 |
<entry> |
| 13048 |
<option>-fb</option>, <option>-fh</option>, <option>-fi</option>, |
| 13049 |
<option>-fm</option>, <option>-fn</option>, <option>-fo</option>, |
| 13050 |
<option>-fs</option>, <option>-ft</option> |
| 13051 |
</entry> |
| 13052 |
<entry> |
| 13053 |
<literal>enable_bitmapscan = off</literal>, |
| 13054 |
<literal>enable_hashjoin = off</literal>, |
| 13055 |
<literal>enable_indexscan = off</literal>, |
| 13056 |
<literal>enable_mergejoin = off</literal>, |
| 13057 |
<literal>enable_nestloop = off</literal>, |
| 13058 |
<literal>enable_indexonlyscan = off</literal>, |
| 13059 |
<literal>enable_seqscan = off</literal>, |
| 13060 |
<literal>enable_tidscan = off</literal> |
| 13061 |
</entry> |
| 13062 |
</row> |
| 13063 |
<row> |
| 13064 |
<entry><option>-F</option></entry> |
| 13065 |
<entry><literal>fsync = off</literal></entry> |
| 13066 |
</row> |
| 13067 |
<row> |
| 13068 |
<entry><option>-h <replaceable>x</replaceable></option></entry> |
| 13069 |
<entry><literal>listen_addresses = <replaceable>x</replaceable></literal></entry> |
| 13070 |
</row> |
| 13071 |
<row> |
| 13072 |
<entry><option>-i</option></entry> |
| 13073 |
<entry><literal>listen_addresses = '*'</literal></entry> |
| 13074 |
</row> |
| 13075 |
<row> |
| 13076 |
<entry><option>-k <replaceable>x</replaceable></option></entry> |
| 13077 |
<entry><literal>unix_socket_directories = <replaceable>x</replaceable></literal></entry> |
| 13078 |
</row> |
| 13079 |
<row> |
| 13080 |
<entry><option>-l</option></entry> |
| 13081 |
<entry><literal>ssl = on</literal></entry> |
| 13082 |
</row> |
| 13083 |
<row> |
| 13084 |
<entry><option>-N <replaceable>x</replaceable></option></entry> |
| 13085 |
<entry><literal>max_connections = <replaceable>x</replaceable></literal></entry> |
| 13086 |
</row> |
| 13087 |
<row> |
| 13088 |
<entry><option>-O</option></entry> |
| 13089 |
<entry><literal>allow_system_table_mods = on</literal></entry> |
| 13090 |
</row> |
| 13091 |
<row> |
| 13092 |
<entry><option>-p <replaceable>x</replaceable></option></entry> |
| 13093 |
<entry><literal>port = <replaceable>x</replaceable></literal></entry> |
| 13094 |
</row> |
| 13095 |
<row> |
| 13096 |
<entry><option>-P</option></entry> |
| 13097 |
<entry><literal>ignore_system_indexes = on</literal></entry> |
| 13098 |
</row> |
| 13099 |
<row> |
| 13100 |
<entry><option>-s</option></entry> |
| 13101 |
<entry><literal>log_statement_stats = on</literal></entry> |
| 13102 |
</row> |
| 13103 |
<row> |
| 13104 |
<entry><option>-S <replaceable>x</replaceable></option></entry> |
| 13105 |
<entry><literal>work_mem = <replaceable>x</replaceable></literal></entry> |
| 13106 |
</row> |
| 13107 |
<row> |
| 13108 |
<entry><option>-tpa</option>, <option>-tpl</option>, <option>-te</option></entry> |
| 13109 |
<entry><literal>log_parser_stats = on</literal>, |
| 13110 |
<literal>log_planner_stats = on</literal>, |
| 13111 |
<literal>log_executor_stats = on</literal></entry> |
| 13112 |
</row> |
| 13113 |
<row> |
| 13114 |
<entry><option>-W <replaceable>x</replaceable></option></entry> |
| 13115 |
<entry><literal>post_auth_delay = <replaceable>x</replaceable></literal></entry> |
| 13116 |
</row> |
| 13117 |
</tbody> |
| 13118 |
</tgroup> |
| 13119 |
</table> |
| 13120 |
|
| 13121 |
</sect1> |
| 13122 |
</chapter> |