From 6404751ce91fb02999e46700a1ac62b3c6319abf Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 11 Nov 2015 17:13:38 -0500 Subject: [PATCH] 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. --- doc/src/sgml/config.sgml | 65 +++++++++--------- doc/src/sgml/maintenance.sgml | 47 ++++--------- doc/src/sgml/ref/create_table.sgml | 104 +++++++++++++++-------------- 3 files changed, 103 insertions(+), 113 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 5549de7558..6e14851f69 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -5234,8 +5234,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; These settings control the behavior of the autovacuum - feature. Refer to for - more information. + feature. Refer to for more information. + Note that many of these settings can be overridden on a per-table + basis; see . @@ -5253,7 +5255,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; must also be enabled for autovacuum to work. This parameter can only be set in the 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. 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 -1, 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 postgresql.conf file or on the server command line. + in tracking autovacuum activity. This parameter can only be set in + the postgresql.conf file or on the server command line; + but the setting can be overridden for individual tables by + changing table storage parameters. @@ -5296,7 +5301,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; 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. @@ -5333,9 +5338,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; to trigger a VACUUM in any one table. The default is 50 tuples. This parameter can only be set in the 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. @@ -5352,9 +5357,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; needed to trigger an ANALYZE in any one table. The default is 50 tuples. This parameter can only be set in the 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. @@ -5372,9 +5377,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; when deciding whether to trigger a VACUUM. The default is 0.2 (20% of table size). This parameter can only be set in the 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. @@ -5392,9 +5397,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; when deciding whether to trigger an ANALYZE. The default is 0.1 (10% of table size). This parameter can only be set in the 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. @@ -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 . @@ -5448,8 +5453,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; pg_multixact/members and 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 . @@ -5468,9 +5473,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; value will be used. The default value is 20 milliseconds. This parameter can only be set in the 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. @@ -5488,12 +5493,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; default), the regular 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 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. @@ -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 (4MB). This setting can be overridden for individual GIN indexes by changing - storage parameters. + index storage parameters. See and for more information. diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml index b5d405024d..5204b34c75 100644 --- a/doc/src/sgml/maintenance.sgml +++ b/doc/src/sgml/maintenance.sgml @@ -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 VACUUM and/or ANALYZE as needed. - log_autovacuum_min_duration can be used to monitor - autovacuum activity. + can be set to monitor + autovacuum workers' activity. 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 The default thresholds and scale factors are taken from postgresql.conf, 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 for more information. - If a setting - has been changed via storage parameters, that value is used; otherwise the - global settings are used. See 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 for more details on + the global settings. - 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, autovacuum_enabled, - can be set to false 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, - autovacuum_vacuum_cost_delay and - autovacuum_vacuum_cost_limit, are used to set - table-specific values for the cost-based vacuum delay feature - (see ). - autovacuum_freeze_min_age, - autovacuum_freeze_max_age and - autovacuum_freeze_table_age are used to set - values for , - and - respectively. - - - - When multiple workers are running, the cost delay parameters are + When multiple workers are running, the autovacuum cost delay parameters + (see ) are balanced 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 - autovacuum_vacuum_cost_delay or - autovacuum_vacuum_cost_limit have been set are not considered - in the balancing algorithm. + per-table autovacuum_vacuum_cost_delay or + autovacuum_vacuum_cost_limit storage parameters have been set + are not considered in the balancing algorithm. diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index a2d0b0cbe1..f0c94d591e 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -878,14 +878,14 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI Storage parameters for indexes are documented in . 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 - toast., 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 + toast., which controls the behavior of the table's secondary TOAST table, if any (see 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 toast. parameter is not, the TOAST table + will use the table's parameter value. @@ -912,22 +912,19 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_enabled, toast.autovacuum_enabled (boolean) - Enables or disables the autovacuum daemon on a particular table. - If true, the autovacuum daemon will initiate a VACUUM operation - on a particular table when the number of updated or deleted tuples exceeds - autovacuum_vacuum_threshold plus - autovacuum_vacuum_scale_factor times the number of live tuples - currently estimated to be in the relation. - Similarly, it will initiate an ANALYZE operation when the - number of inserted, updated or deleted tuples exceeds - autovacuum_analyze_threshold plus - 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 VACUUM + and/or ANALYZE operations on this table following the rules + discussed in . If false, this table will not be autovacuumed, except to prevent - transaction Id wraparound. See for + transaction ID wraparound. See for more about wraparound prevention. - Observe that this variable inherits its value from the setting. + Note that the autovacuum daemon does not run at all (except to prevent + transaction ID wraparound) if the + 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 true, only + to false. @@ -936,8 +933,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_vacuum_threshold, toast.autovacuum_vacuum_threshold (integer) - Minimum number of updated or deleted tuples before initiate a - VACUUM operation on a particular table. + Per-table value for + parameter. @@ -946,8 +943,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_vacuum_scale_factor, toast.autovacuum_vacuum_scale_factor (float4) - Multiplier for reltuples to add to - autovacuum_vacuum_threshold. + Per-table value for + parameter. @@ -956,8 +953,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_analyze_threshold (integer) - Minimum number of inserted, updated, or deleted tuples before initiate an - ANALYZE operation on a particular table. + Per-table value for + parameter. @@ -966,8 +963,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_analyze_scale_factor (float4) - Multiplier for reltuples to add to - autovacuum_analyze_threshold. + Per-table value for + parameter. @@ -976,7 +973,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_vacuum_cost_delay, toast.autovacuum_vacuum_cost_delay (integer) - Custom parameter. + Per-table value for + parameter. @@ -985,7 +983,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_vacuum_cost_limit, toast.autovacuum_vacuum_cost_limit (integer) - Custom parameter. + Per-table value for + parameter. @@ -994,10 +993,11 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_freeze_min_age, toast.autovacuum_freeze_min_age (integer) - Custom parameter. Note that - autovacuum will ignore attempts to set a per-table - autovacuum_freeze_min_age larger than half the system-wide - setting. + Per-table value for + parameter. Note that autovacuum will ignore + per-table autovacuum_freeze_min_age parameters that are + larger than half the + system-wide setting. @@ -1006,10 +1006,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_freeze_max_age, toast.autovacuum_freeze_max_age (integer) - Custom parameter. Note that - autovacuum will ignore attempts to set a per-table - autovacuum_freeze_max_age larger than the system-wide setting - (it can only be set smaller). + Per-table value for + parameter. Note that autovacuum will ignore + per-table autovacuum_freeze_max_age parameters that are + larger than the system-wide setting (it can only be set smaller). @@ -1018,7 +1018,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_freeze_table_age, toast.autovacuum_freeze_table_age (integer) - Custom parameter. + Per-table value for + parameter. @@ -1027,9 +1028,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_multixact_freeze_min_age, toast.autovacuum_multixact_freeze_min_age (integer) - Custom parameter. - Note that autovacuum will ignore attempts to set a per-table - autovacuum_multixact_freeze_min_age larger than half the + Per-table value for + parameter. Note that autovacuum will ignore + per-table autovacuum_multixact_freeze_min_age parameters + that are larger than half the system-wide setting. @@ -1040,10 +1042,12 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_multixact_freeze_max_age, toast.autovacuum_multixact_freeze_max_age (integer) - Custom parameter. Note - that autovacuum will ignore attempts to set a per-table - autovacuum_multixact_freeze_max_age larger than the - system-wide setting (it can only be set smaller). + Per-table value + for parameter. + Note that autovacuum will ignore + per-table autovacuum_multixact_freeze_max_age parameters + that are larger than the system-wide setting (it can only be set + smaller). @@ -1052,7 +1056,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI autovacuum_multixact_freeze_table_age, toast.autovacuum_multixact_freeze_table_age (integer) - Custom parameter. + Per-table value + for parameter. @@ -1061,7 +1066,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI log_autovacuum_min_duration, toast.log_autovacuum_min_duration (integer) - Custom parameter. + Per-table value for + parameter. @@ -1070,7 +1076,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI user_catalog_table (boolean) - 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 for details. This parameter cannot be set for TOAST tables.