rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation around autovacuum-related storage parameters. 

These were discussed in three different sections of the manual, which
unsurprisingly had diverged over time; and the descriptions of individual
variables lacked stylistic consistency even within each section (and
frequently weren't in very good English anyway).  Clean up the mess, and
remove some of the redundant information in hopes that future additions
will be less likely to re-introduce inconsistency.  For instance I see
no need for maintenance.sgml to include its very own list of all the
autovacuum storage parameters, especially since that list was already
incomplete.
This commit is contained in:
Tom Lane 2015-11-11 17:13:38 -05:00
parent da3751c8ea
commit 6404751ce9
3 changed files with 103 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
doc/src/sgml/config.sgml
View File

@ -5234,8 +5234,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<para>
These settings control the behavior of the <firstterm>autovacuum</>
feature. Refer to <xref linkend="autovacuum"> for
more information.
feature. Refer to <xref linkend="autovacuum"> for more information.
Note that many of these settings can be overridden on a per-table
basis; see <xref linkend="sql-createtable-storage-parameters"
endterm="sql-createtable-storage-parameters-title">.
</para>
<variablelist>
@ -5253,7 +5255,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<xref linkend="guc-track-counts"> must also be enabled for
autovacuum to work.
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
file or on the server command line; however, autovacuuming can be
disabled for individual tables by changing table storage parameters.
</para>
<para>
Note that even when this parameter is disabled, the system
@ -5281,8 +5284,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
set to any value other than <literal>-1</literal>, a message will be
logged if an autovacuum action is skipped due to the existence of a
conflicting lock. Enabling this parameter can be helpful
in tracking autovacuum activity. This setting can only be set in
the <filename>postgresql.conf</> file or on the server command line.
in tracking autovacuum activity. This parameter can only be set in
the <filename>postgresql.conf</> file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -5296,7 +5301,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<listitem>
<para>
Specifies the maximum number of autovacuum processes (other than the
autovacuum launcher) which may be running at any one time. The default
autovacuum launcher) that may be running at any one time. The default
is three. This parameter can only be set at server start.
</para>
</listitem>
@ -5333,9 +5338,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
to trigger a <command>VACUUM</> in any one table.
The default is 50 tuples.
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
This setting can be overridden for individual tables by
changing storage parameters.
file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -5352,9 +5357,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
needed to trigger an <command>ANALYZE</> in any one table.
The default is 50 tuples.
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
This setting can be overridden for individual tables by
changing storage parameters.
file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -5372,9 +5377,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
when deciding whether to trigger a <command>VACUUM</>.
The default is 0.2 (20% of table size).
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
This setting can be overridden for individual tables by
changing storage parameters.
file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -5392,9 +5397,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
when deciding whether to trigger an <command>ANALYZE</>.
The default is 0.1 (10% of table size).
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
This setting can be overridden for individual tables by
changing storage parameters.
file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -5421,7 +5426,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
is a relatively low 200 million transactions.
This parameter can only be set at server start, but the setting
can be reduced for individual tables by
changing storage parameters.
changing table storage parameters.
For more information see <xref linkend="vacuum-for-wraparound">.
</para>
</listitem>
@ -5448,8 +5453,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<filename>pg_multixact/members</> and <filename>pg_multixact/offsets</>
subdirectories, which is why the default is a relatively low
400 million multixacts.
This parameter can only be set at server start, but the setting
can be reduced for individual tables by changing storage parameters.
This parameter can only be set at server start, but the setting can
be reduced for individual tables by changing table storage parameters.
For more information see <xref linkend="vacuum-for-multixact-wraparound">.
</para>
</listitem>
@ -5468,9 +5473,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<xref linkend="guc-vacuum-cost-delay"> value will be used.
The default value is 20 milliseconds.
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
This setting can be overridden for individual tables by
changing storage parameters.
file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -5488,12 +5493,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
default), the regular
<xref linkend="guc-vacuum-cost-limit"> value will be used. Note that
the value is distributed proportionally among the running autovacuum
workers, if there is more than one, so that the sum of the limits of
each worker never exceeds the limit on this variable.
workers, if there is more than one, so that the sum of the limits for
each worker does not exceed the value of this variable.
This parameter can only be set in the <filename>postgresql.conf</>
file or on the server command line.
This setting can be overridden for individual tables by
changing storage parameters.
file or on the server command line;
but the setting can be overridden for individual tables by
changing table storage parameters.
</para>
</listitem>
</varlistentry>
@ -6072,7 +6077,7 @@ SET XML OPTION { DOCUMENT | CONTENT };
the entries in it to the main GIN data structure in bulk.
The default is four megabytes (<literal>4MB</>). This setting
can be overridden for individual GIN indexes by changing
storage parameters.
index storage parameters.
See <xref linkend="gin-fast-update"> and <xref linkend="gin-tips">
for more information.
</para>

47
doc/src/sgml/maintenance.sgml
View File

@ -705,15 +705,15 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
the next database will be processed as soon as the first worker finishes.
Each worker process will check each table within its database and
execute <command>VACUUM</> and/or <command>ANALYZE</> as needed.
<varname>log_autovacuum_min_duration</varname> can be used to monitor
autovacuum activity.
<xref linkend="guc-log-autovacuum-min-duration"> can be set to monitor
autovacuum workers' activity.
</para>
<para>
If several large tables all become eligible for vacuuming in a short
amount of time, all autovacuum workers might become occupied with
vacuuming those tables for a long period. This would result
in other tables and databases not being vacuumed until a worker became
in other tables and databases not being vacuumed until a worker becomes
available. There is no limit on how many workers might be in a
single database, but workers do try to avoid repeating work that has
already been done by other workers. Note that the number of running
@ -767,45 +767,24 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
<para>
The default thresholds and scale factors are taken from
<filename>postgresql.conf</filename>, but it is possible to override them
on a table-by-table basis; see
(and many other autovacuum control parameters) on a per-table basis; see
<xref linkend="sql-createtable-storage-parameters"
endterm="sql-createtable-storage-parameters-title"> for more information.
If a setting
has been changed via storage parameters, that value is used; otherwise the
global settings are used. See <xref linkend="runtime-config-autovacuum"> for
more details on the global settings.
If a setting has been changed via a table's storage parameters, that value
is used when processing that table; otherwise the global settings are
used. See <xref linkend="runtime-config-autovacuum"> for more details on
the global settings.
</para>
<para>
Besides the base threshold values and scale factors, there are six
more autovacuum parameters that can be set for each table via
storage parameters.
The first parameter, <literal>autovacuum_enabled</>,
can be set to <literal>false</literal> to instruct the autovacuum daemon
to skip that particular table entirely. In this case
autovacuum will only touch the table if it must do so
to prevent transaction ID wraparound.
Another two parameters,
<varname>autovacuum_vacuum_cost_delay</> and
<varname>autovacuum_vacuum_cost_limit</>, are used to set
table-specific values for the cost-based vacuum delay feature
(see <xref linkend="runtime-config-resource-vacuum-cost">).
<varname>autovacuum_freeze_min_age</>,
<varname>autovacuum_freeze_max_age</> and
<varname>autovacuum_freeze_table_age</> are used to set
values for <xref linkend="guc-vacuum-freeze-min-age">,
<xref linkend="guc-autovacuum-freeze-max-age"> and
<xref linkend="guc-vacuum-freeze-table-age"> respectively.
</para>
<para>
When multiple workers are running, the cost delay parameters are
When multiple workers are running, the autovacuum cost delay parameters
(see <xref linkend="runtime-config-resource-vacuum-cost">) are
<quote>balanced</quote> among all the running workers, so that the
total I/O impact on the system is the same regardless of the number
of workers actually running. However, any workers processing tables whose
<literal>autovacuum_vacuum_cost_delay</> or
<literal>autovacuum_vacuum_cost_limit</> have been set are not considered
in the balancing algorithm.
per-table <literal>autovacuum_vacuum_cost_delay</> or
<literal>autovacuum_vacuum_cost_limit</> storage parameters have been set
are not considered in the balancing algorithm.
</para>
</sect2>
</sect1>

104
doc/src/sgml/ref/create_table.sgml
View File

@ -878,14 +878,14 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
Storage parameters for
indexes are documented in <xref linkend="SQL-CREATEINDEX">.
The storage parameters currently
available for tables are listed below. For each parameter, unless noted,
there is an additional parameter with the same name prefixed with
<literal>toast.</literal>, which can be used to control the behavior of the
available for tables are listed below. For many of these parameters, as
shown, there is an additional parameter with the same name prefixed with
<literal>toast.</literal>, which controls the behavior of the
table's secondary <acronym>TOAST</> table, if any
(see <xref linkend="storage-toast"> for more information about TOAST).
Note that the TOAST table uses the parameter values defined for
the main table, for each parameter applicable to TOAST tables and
for which no value is set in the TOAST table itself.
If a table parameter value is set and the
equivalent <literal>toast.</literal> parameter is not, the TOAST table
will use the table's parameter value.
</para>
<variablelist>
@ -912,22 +912,19 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_enabled</>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</>)</term>
<listitem>
<para>
Enables or disables the autovacuum daemon on a particular table.
If true, the autovacuum daemon will initiate a <command>VACUUM</> operation
on a particular table when the number of updated or deleted tuples exceeds
<literal>autovacuum_vacuum_threshold</> plus
<literal>autovacuum_vacuum_scale_factor</> times the number of live tuples
currently estimated to be in the relation.
Similarly, it will initiate an <command>ANALYZE</> operation when the
number of inserted, updated or deleted tuples exceeds
<literal>autovacuum_analyze_threshold</> plus
<literal>autovacuum_analyze_scale_factor</> times the number of live tuples
currently estimated to be in the relation.
Enables or disables the autovacuum daemon for a particular table.
If true, the autovacuum daemon will perform automatic <command>VACUUM</>
and/or <command>ANALYZE</> operations on this table following the rules
discussed in <xref linkend="autovacuum">.
If false, this table will not be autovacuumed, except to prevent
transaction Id wraparound. See <xref linkend="vacuum-for-wraparound"> for
transaction ID wraparound. See <xref linkend="vacuum-for-wraparound"> for
more about wraparound prevention.
Observe that this variable inherits its value from the <xref
linkend="guc-autovacuum"> setting.
Note that the autovacuum daemon does not run at all (except to prevent
transaction ID wraparound) if the <xref linkend="guc-autovacuum">
parameter is false; setting individual tables' storage parameters does
not override that. Therefore there is seldom much point in explicitly
setting this storage parameter to <literal>true</>, only
to <literal>false</>.
</para>
</listitem>
</varlistentry>
@ -936,8 +933,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_vacuum_threshold</>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</>)</term>
<listitem>
<para>
Minimum number of updated or deleted tuples before initiate a
<command>VACUUM</> operation on a particular table.
Per-table value for <xref linkend="guc-autovacuum-vacuum-threshold">
parameter.
</para>
</listitem>
</varlistentry>
@ -946,8 +943,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_vacuum_scale_factor</>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>float4</>)</term>
<listitem>
<para>
Multiplier for <structfield>reltuples</> to add to
<literal>autovacuum_vacuum_threshold</>.
Per-table value for <xref linkend="guc-autovacuum-vacuum-scale-factor">
parameter.
</para>
</listitem>
</varlistentry>
@ -956,8 +953,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_analyze_threshold</> (<type>integer</>)</term>
<listitem>
<para>
Minimum number of inserted, updated, or deleted tuples before initiate an
<command>ANALYZE</> operation on a particular table.
Per-table value for <xref linkend="guc-autovacuum-analyze-threshold">
parameter.
</para>
</listitem>
</varlistentry>
@ -966,8 +963,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_analyze_scale_factor</> (<type>float4</>)</term>
<listitem>
<para>
Multiplier for <structfield>reltuples</> to add to
<literal>autovacuum_analyze_threshold</>.
Per-table value for <xref linkend="guc-autovacuum-analyze-scale-factor">
parameter.
</para>
</listitem>
</varlistentry>
@ -976,7 +973,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_vacuum_cost_delay</>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>integer</>)</term>
<listitem>
<para>
Custom <xref linkend="guc-autovacuum-vacuum-cost-delay"> parameter.
Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-delay">
parameter.
</para>
</listitem>
</varlistentry>
@ -985,7 +983,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_vacuum_cost_limit</>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</>)</term>
<listitem>
<para>
Custom <xref linkend="guc-autovacuum-vacuum-cost-limit"> parameter.
Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-limit">
parameter.
</para>
</listitem>
</varlistentry>
@ -994,10 +993,11 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_freeze_min_age</>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</>)</term>
<listitem>
<para>
Custom <xref linkend="guc-vacuum-freeze-min-age"> parameter. Note that
autovacuum will ignore attempts to set a per-table
<literal>autovacuum_freeze_min_age</> larger than half the system-wide
<xref linkend="guc-autovacuum-freeze-max-age"> setting.
Per-table value for <xref linkend="guc-vacuum-freeze-min-age">
parameter. Note that autovacuum will ignore
per-table <literal>autovacuum_freeze_min_age</> parameters that are
larger than half the
system-wide <xref linkend="guc-autovacuum-freeze-max-age"> setting.
</para>
</listitem>
</varlistentry>
@ -1006,10 +1006,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_freeze_max_age</>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</>)</term>
<listitem>
<para>
Custom <xref linkend="guc-autovacuum-freeze-max-age"> parameter. Note that
autovacuum will ignore attempts to set a per-table
<literal>autovacuum_freeze_max_age</> larger than the system-wide setting
(it can only be set smaller).
Per-table value for <xref linkend="guc-autovacuum-freeze-max-age">
parameter. Note that autovacuum will ignore
per-table <literal>autovacuum_freeze_max_age</> parameters that are
larger than the system-wide setting (it can only be set smaller).
</para>
</listitem>
</varlistentry>
@ -1018,7 +1018,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_freeze_table_age</literal>, <literal>toast.autovacuum_freeze_table_age</literal> (<type>integer</type>)</term>
<listitem>
<para>
Custom <xref linkend="guc-vacuum-freeze-table-age"> parameter.
Per-table value for <xref linkend="guc-vacuum-freeze-table-age">
parameter.
</para>
</listitem>
</varlistentry>
@ -1027,9 +1028,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_multixact_freeze_min_age</literal>, <literal>toast.autovacuum_multixact_freeze_min_age</literal> (<type>integer</type>)</term>
<listitem>
<para>
Custom <xref linkend="guc-vacuum-multixact-freeze-min-age"> parameter.
Note that autovacuum will ignore attempts to set a per-table
<literal>autovacuum_multixact_freeze_min_age</> larger than half the
Per-table value for <xref linkend="guc-vacuum-multixact-freeze-min-age">
parameter. Note that autovacuum will ignore
per-table <literal>autovacuum_multixact_freeze_min_age</> parameters
that are larger than half the
system-wide <xref linkend="guc-autovacuum-multixact-freeze-max-age">
setting.
</para>
@ -1040,10 +1042,12 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_multixact_freeze_max_age</literal>, <literal>toast.autovacuum_multixact_freeze_max_age</literal> (<type>integer</type>)</term>
<listitem>
<para>
Custom <xref linkend="guc-autovacuum-multixact-freeze-max-age"> parameter. Note
that autovacuum will ignore attempts to set a per-table
<literal>autovacuum_multixact_freeze_max_age</> larger than the
system-wide setting (it can only be set smaller).
Per-table value
for <xref linkend="guc-autovacuum-multixact-freeze-max-age"> parameter.
Note that autovacuum will ignore
per-table <literal>autovacuum_multixact_freeze_max_age</> parameters
that are larger than the system-wide setting (it can only be set
smaller).
</para>
</listitem>
</varlistentry>
@ -1052,7 +1056,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>autovacuum_multixact_freeze_table_age</literal>, <literal>toast.autovacuum_multixact_freeze_table_age</literal> (<type>integer</type>)</term>
<listitem>
<para>
Custom <xref linkend="guc-vacuum-multixact-freeze-table-age"> parameter.
Per-table value
for <xref linkend="guc-vacuum-multixact-freeze-table-age"> parameter.
</para>
</listitem>
</varlistentry>
@ -1061,7 +1066,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>log_autovacuum_min_duration</literal>, <literal>toast.log_autovacuum_min_duration</literal> (<type>integer</type>)</term>
<listitem>
<para>
Custom <xref linkend="guc-log-autovacuum-min-duration"> parameter.
Per-table value for <xref linkend="guc-log-autovacuum-min-duration">
parameter.
</para>
</listitem>
</varlistentry>
@ -1070,7 +1076,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>user_catalog_table</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Declare a table as an additional catalog table, e.g. for the purpose of
Declare the table as an additional catalog table for purposes of
logical replication. See
<xref linkend="logicaldecoding-capabilities"> for details.
This parameter cannot be set for TOAST tables.