Home Explore Blog CI



postgresql

6th chunk of `doc/src/sgml/amcheck.sgml`
efeefcadf075052c7faa0a78568f284b8c5928e976fef5ed0000000100000fa1
 <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.

Title: Optional Heapallindexed Verification and Using Amcheck Effectively
Summary
This section describes the optional heapallindexed verification phase for B-Tree verification functions, which checks the table associated with the target index relation and can detect structural inconsistencies, and provides guidance on using the amcheck tool effectively, including its ability to detect failure modes that data checksums may miss, such as issues caused by incorrect operator class implementations and inconsistencies in collation order.