Home Explore Blog CI



postgresql

3rd chunk of `doc/src/sgml/amcheck.sgml`
72d508d9c5044dce2e29493a74da5b545d2f2fa0e74117800000000100000fc0
 using
      <function>bt_index_check</function> often provides the best
      trade-off between thoroughness of verification and limiting the
      impact on application performance and availability.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>bt_index_parent_check(index regclass, heapallindexed boolean, rootdescend boolean, checkunique boolean) returns void</function>
     <indexterm>
      <primary>bt_index_parent_check</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      <function>bt_index_parent_check</function> tests that its
      target, a B-Tree index, respects a variety of invariants.
      Optionally, when the <parameter>heapallindexed</parameter>
      argument is <literal>true</literal>, the function verifies the
      presence of all heap tuples that should be found within the
      index.  When <parameter>checkunique</parameter>
      is <literal>true</literal> <function>bt_index_parent_check</function> will
      check that no more than one among duplicate entries in unique
      index is visible.  When the optional <parameter>rootdescend</parameter>
      argument is <literal>true</literal>, verification re-finds
      tuples on the leaf level by performing a new search from the
      root page for each tuple.  The checks that can be performed by
      <function>bt_index_parent_check</function> are a superset of the
      checks that can be performed by <function>bt_index_check</function>.
      <function>bt_index_parent_check</function> can be thought of as
      a more thorough variant of <function>bt_index_check</function>:
      unlike <function>bt_index_check</function>,
      <function>bt_index_parent_check</function> also checks
      invariants that span parent/child relationships, including checking
      that there are no missing downlinks in the index structure.
      <function>bt_index_parent_check</function> follows the general
      convention of raising an error if it finds a logical
      inconsistency or other problem.
     </para>
     <para>
      A <literal>ShareLock</literal> is required on the target index by
      <function>bt_index_parent_check</function> (a
      <literal>ShareLock</literal> is also acquired on the heap relation).
      These locks prevent concurrent data modification from
      <command>INSERT</command>, <command>UPDATE</command>, and <command>DELETE</command>
      commands.  The locks also prevent the underlying relation from
      being concurrently processed by <command>VACUUM</command>, as well as
      all other utility commands.  Note that the function holds locks
      only while running, not for the entire transaction.
     </para>
     <para>
      <function>bt_index_parent_check</function>'s additional
      verification is more likely to detect various pathological
      cases.  These cases may involve an incorrectly implemented
      B-Tree operator class used by the index that is checked, or,
      hypothetically, undiscovered bugs in the underlying B-Tree index
      access method code.  Note that
      <function>bt_index_parent_check</function> cannot be used when
      hot standby mode is enabled (i.e., on read-only physical
      replicas), unlike <function>bt_index_check</function>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <function>gin_index_check(index regclass) returns void</function>
     <indexterm>
      <primary>gin_index_check</primary>
     </indexterm>
    </term>

    <listitem>
     <para>
      <function>gin_index_check</function> tests that its target GIN index
      has consistent parent-child tuples relations (no parent tuples
      require tuple adjustment) and page graph respects balanced-tree
      invariants (internal pages reference only leaf page or only internal
      pages).
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
  <tip>
   <para>
    <function>bt_index_check</function> and
    <function>bt_index_parent_check</function>

Title: Index Check Functions
Summary
This section describes several index check functions, including bt_index_parent_check, which is a more thorough variant of bt_index_check, and gin_index_check, which verifies the consistency of GIN indexes, with details on their usage, locking mechanisms, and error handling, to help detect and prevent index corruption and ensure data integrity.