<varlistentry>
<term><literal>msg</literal></term>
<listitem>
<para>
A message describing the problem detected.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="amcheck-optional-heapallindexed-verification">
<title>Optional <parameter>heapallindexed</parameter> Verification</title>
<para>
When the <parameter>heapallindexed</parameter> argument to B-Tree
verification functions is <literal>true</literal>, an additional
phase of verification is performed against the table associated with
the target index relation. This consists of a <quote>dummy</quote>
<command>CREATE INDEX</command> operation, which checks for the
presence of all hypothetical new index tuples against a temporary,
in-memory summarizing structure (this is built when needed during
the basic first phase of verification). The summarizing structure
<quote>fingerprints</quote> every tuple found within the target
index. The high level principle behind
<parameter>heapallindexed</parameter> verification is that a new
index that is equivalent to the existing, target index must only
have entries that can be found in the existing structure.
</para>
<para>
The additional <parameter>heapallindexed</parameter> phase adds
significant overhead: verification will typically take several times
longer. However, there is no change to the relation-level locks
acquired when <parameter>heapallindexed</parameter> verification is
performed.
</para>
<para>
The summarizing structure is bound in size by
<varname>maintenance_work_mem</varname>. In order to ensure that
there is no more than a 2% probability of failure to detect an
inconsistency for each heap tuple that should be represented in the
index, approximately 2 bytes of memory are needed per tuple. As
less memory is made available per tuple, the probability of missing
an inconsistency slowly increases. This approach limits the
overhead of verification significantly, while only slightly reducing
the probability of detecting a problem, especially for installations
where verification is treated as a routine maintenance task. Any
single absent or malformed tuple has a new opportunity to be
detected with each new verification attempt.
</para>
</sect2>
<sect2 id="amcheck-using-amcheck-effectively">
<title>Using <filename>amcheck</filename> Effectively</title>
<para>
<filename>amcheck</filename> can be effective at detecting various types of
failure modes that <link
linkend="app-initdb-data-checksums"><application>data
checksums</application></link> will fail to catch. These include:
<itemizedlist>
<listitem>
<para>
Structural inconsistencies caused by incorrect operator class
implementations.
</para>
<para>
This includes issues caused by the comparison rules of operating
system collations changing. Comparisons of datums of a collatable
type like <type>text</type> must be immutable (just as all
comparisons used for B-Tree index scans must be immutable), which
implies that operating system collation rules must never change.
Though rare, updates to operating system collation rules can
cause these issues. More commonly, an inconsistency in the
collation order between a primary server and a standby server is
implicated, possibly because the <emphasis>major</emphasis> operating
system version in use is inconsistent. Such inconsistencies will
generally only arise on standby servers, and so can generally
only be detected on standby servers.
</para>
<para>
If a problem like this arises, it may not affect each individual
index that is ordered using an affected collation, simply because
<emphasis>indexed</emphasis> values might happen to have the same
absolute ordering regardless of the behavioral inconsistency.