Debian Codegraph @

doc/src/sgml/config.sgml

raw
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">&bull;</entry>
3280 <entry align="center">&bull;</entry>
3281 <entry align="center">&bull;</entry>
3282 <entry align="center">&bull;</entry>
3283 </row>
3284
3285 <row>
3286 <entry>on</entry>
3287 <entry align="center">&bull;</entry>
3288 <entry align="center">&bull;</entry>
3289 <entry align="center">&bull;</entry>
3290 <entry align="center"></entry>
3291 </row>
3292
3293 <row>
3294 <entry>remote_write</entry>
3295 <entry align="center">&bull;</entry>
3296 <entry align="center">&bull;</entry>
3297 <entry align="center"></entry>
3298 <entry align="center"></entry>
3299 </row>
3300
3301 <row>
3302 <entry>local</entry>
3303 <entry align="center">&bull;</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> &mdash; 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 &mdash; <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 &mdash; 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>