aboutsummaryrefslogtreecommitdiff
path: root/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/sgml/config.sgml70
-rw-r--r--doc/src/sgml/maintenance.sgml56
-rw-r--r--doc/src/sgml/ref/create_table.sgml39
3 files changed, 162 insertions, 3 deletions
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 000a46fabb0..e12778b263c 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4892,6 +4892,33 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
</listitem>
</varlistentry>
+ <varlistentry id="guc-autovacuum-multixact-freeze-max-age" xreflabel="autovacuum_multixact_freeze_max_age">
+ <term><varname>autovacuum_multixact_freeze_max_age</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>autovacuum_multixact_freeze_max_age</varname> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the maximum age (in multixacts) that a table's
+ <structname>pg_class</>.<structfield>relminmxid</> field can
+ attain before a <command>VACUUM</> operation is forced to
+ prevent multixact ID wraparound within the table.
+ Note that the system will launch autovacuum processes to
+ prevent wraparound even when autovacuum is otherwise disabled.
+ </para>
+
+ <para>
+ Vacuuming multixacts also allows removal of old files from the
+ <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.
+ For more information see <xref linkend="vacuum-for-multixact-wraparound">.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="guc-autovacuum-vacuum-cost-delay" xreflabel="autovacuum_vacuum_cost_delay">
<term><varname>autovacuum_vacuum_cost_delay</varname> (<type>integer</type>)</term>
<indexterm>
@@ -5300,7 +5327,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<structname>pg_class</>.<structfield>relfrozenxid</> field has reached
the age specified by this setting. The default is 150 million
transactions. Although users can set this value anywhere from zero to
- one billion, <command>VACUUM</> will silently limit the effective value
+ two billions, <command>VACUUM</> will silently limit the effective value
to 95% of <xref linkend="guc-autovacuum-freeze-max-age">, so that a
periodical manual <command>VACUUM</> has a chance to run before an
anti-wraparound autovacuum is launched for the table. For more
@@ -5331,6 +5358,47 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
</listitem>
</varlistentry>
+ <varlistentry id="guc-vacuum-multixact-freeze-table-age" xreflabel="vacuum_multixact_freeze_table_age">
+ <term><varname>vacuum_multixact_freeze_table_age</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>vacuum_multixact_freeze_table_age</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ <command>VACUUM</> performs a whole-table scan if the table's
+ <structname>pg_class</>.<structfield>relminmxid</> field has reached
+ the age specified by this setting. The default is 150 million multixacts.
+ Although users can set this value anywhere from zero to two billions,
+ <command>VACUUM</> will silently limit the effective value to 95% of
+ <xref linkend="guc-autovacuum-multixact-freeze-max-age">, so that a
+ periodical manual <command>VACUUM</> has a chance to run before an
+ anti-wraparound is launched for the table.
+ For more information see <xref linkend="vacuum-for-multixact-wraparound">.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-vacuum-multixact-freeze-min-age" xreflabel="vacuum_multixact_freeze_min_age">
+ <term><varname>vacuum_multixact_freeze_min_age</varname> (<type>integer</type>)</term>
+ <indexterm>
+ <primary><varname>vacuum_multixact_freeze_min_age</> configuration parameter</primary>
+ </indexterm>
+ <listitem>
+ <para>
+ Specifies the cutoff age (in multixacts) that <command>VACUUM</>
+ should use to decide whether to replace multixact IDs with a newer
+ transaction ID or multixact ID while scanning a table. The default
+ is 5 million multixacts.
+ Although users can set this value anywhere from zero to one billion,
+ <command>VACUUM</> will silently limit the effective value to half
+ the value of <xref linkend="guc-autovacuum-multixact-freeze-max-age">,
+ so that there is not an unreasonably short time between forced
+ autovacuums.
+ For more information see <xref linkend="vacuum-for-multixact-wraparound">.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id="guc-bytea-output" xreflabel="bytea_output">
<term><varname>bytea_output</varname> (<type>enum</type>)</term>
<indexterm>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 339891e8a0c..8ff309b78fe 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -108,7 +108,8 @@
<listitem>
<simpara>To protect against loss of very old data due to
- <firstterm>transaction ID wraparound</>.</simpara>
+ <firstterm>transaction ID wraparound</> or
+ <firstterm>multixact ID wraparound</>.</simpara>
</listitem>
</orderedlist>
@@ -379,6 +380,11 @@
<secondary>wraparound</secondary>
</indexterm>
+ <indexterm>
+ <primary>wraparound</primary>
+ <secondary>of transaction IDs</secondary>
+ </indexterm>
+
<para>
<productname>PostgreSQL</productname>'s MVCC transaction semantics
depend on being able to compare transaction ID (<acronym>XID</>)
@@ -597,6 +603,54 @@ HINT: Stop the postmaster and vacuum that database in single-user mode.
page for details about using single-user mode.
</para>
+ <sect3 id="vacuum-for-multixact-wraparound">
+ <title>Multixacts and Wraparound</title>
+
+ <indexterm>
+ <primary>MultiXactId</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>wraparound</primary>
+ <secondary>of multixact IDs</secondary>
+ </indexterm>
+
+ <para>
+ <firstterm>Multixacts</> are used to implement row locking by
+ multiple transactions: since there is limited space in the tuple
+ header to store lock information, that information is stored as a
+ multixact separately in the <filename>pg_multixact</> subdirectory,
+ and only its ID is in the <structfield>xmax</> field
+ in the tuple header.
+ Similar to transaction IDs, multixact IDs are implemented as a
+ 32-bit counter and corresponding storage, all of which requires
+ careful aging management, storage cleanup, and wraparound handling.
+ </para>
+
+ <para>
+ During a <command>VACUUM</> table scan, either partial or of the whole
+ table, any multixact ID older than
+ <xref linkend="guc-vacuum-multixact-freeze-min-age">
+ is replaced by a different value, which can be the zero value, a single
+ transaction ID, or a newer multixact ID. For each table,
+ <structname>pg_class</>.<structfield>relminmxid</> stores the oldest
+ possible value still stored in any tuple of that table. Every time this
+ value is older than
+ <xref linkend="guc-vacuum-multixact-freeze-table-age">, a whole-table
+ scan is forced. Whole-table <command>VACUUM</> scans, regardless of
+ what causes them, enable advancing the value for that table.
+ Eventually, as all tables in all databases are scanned and their
+ oldest multixact values are advanced, on-disk storage for older
+ multixacts can be removed.
+ </para>
+
+ <para>
+ As a safety device, a whole-table vacuum scan will occur for any table
+ whose multixact-age is greater than
+ <xref linkend="guc-autovacuum-multixact-freeze-max-age">.
+ This will occur even if autovacuum is nominally disabled.
+ </para>
+ </sect3>
</sect2>
<sect2 id="autovacuum">
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index e0b8a4ecaf6..7a01c63d5f0 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -985,7 +985,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<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 the half system-wide
+ <literal>autovacuum_freeze_min_age</> larger than half the system-wide
<xref linkend="guc-autovacuum-freeze-max-age"> setting.
</para>
</listitem>
@@ -1014,6 +1014,43 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
</listitem>
</varlistentry>
+ <varlistentry>
+ <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
+ system-wide <xref linkend="guc-autovacuum-multixact-freeze-max-age">
+ setting.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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). Note that while you
+ can set <literal>autovacuum_multixact_freeze_max_age</> very small,
+ or even zero, this is usually unwise since it will force frequent
+ vacuuming.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</refsect2>
generated by cgit v1.2.3 (git 2.25.1) at 2025-06-19 01:17:20 +0000