text, index tuples should be in collated lexical order). If that particular invariant somehow fails to hold, we can expect binary searches on the affected page to incorrectly guide index scans, resulting in wrong answers to SQL queries.
amcheckfunctions may only be used by superusers.
bt_index_check(index regclass, heapallindexed boolean) returns void
bt_index_checktests that its target, a B-Tree index, respects a variety of invariants. Example usage:
bt_index_checkfor every index in the database where verification is supported.
AccessShareLockon the target index and the heap relation it belongs to. This lock mode is the same lock mode acquired on relations by simple
bt_index_checkdoes not verify invariants that span child/parent relationships, but will verify the presence of all heap tuples as index tuples within the index when
true. When a routine, lightweight test for corruption is required in a live production environment, using
bt_index_checkoften provides the best trade-off between thoroughness of verification and limiting the impact on application performance and availability.
bt_index_parent_check(index regclass, heapallindexed boolean, rootdescend boolean) returns void
bt_index_parent_checktests that its target, a B-Tree index, respects a variety of invariants. Optionally, when the
true, the function verifies the presence of all heap tuples that should be found within the index. When the optional
true, 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
bt_index_parent_checkare a superset of the checks that can be performed by
bt_index_parent_checkcan be thought of as a more thorough variant of
bt_index_parent_checkalso checks invariants that span parent/child relationships, including checking that there are no missing downlinks in the index structure.
bt_index_parent_checkfollows the general convention of raising an error if it finds a logical inconsistency or other problem.
ShareLockis required on the target index by
ShareLockis also acquired on the heap relation). These locks prevent concurrent data modification from
DELETEcommands. The locks also prevent the underlying relation from being concurrently processed by
VACUUM, as well as all other utility commands. Note that the function holds locks only while running, not for the entire transaction.
bt_index_parent_check'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
bt_index_parent_checkcannot be used when Hot Standby mode is enabled (i.e., on read-only physical replicas), unlike
bt_index_parent_checkboth output log messages about the verification process at
DEBUG2severity levels. These messages provide detailed information about the verification process that may be of interest to PostgreSQL developers. Advanced users may also find this information helpful, since it provides additional context should verification actually detect an inconsistency. Running:
heapallindexedargument to verification functions is
true, an additional phase of verification is performed against the table associated with the target index relation. This consists of a “dummy”
CREATE INDEXoperation, 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 “fingerprints” every tuple found within the target index. The high level principle behind
heapallindexedverification 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.
heapallindexedphase adds significant overhead: verification will typically take several times longer. However, there is no change to the relation-level locks acquired when
heapallindexedverification is performed.
maintenance_work_mem. 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.
textmust 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 master server and a standby server is implicated, possibly because the major 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.
heapallindexedverification is performed).
amcheckfunctions continuously when running the standard regression tests. See Section 32.1 for details on running the tests.
amcheckexamines a page as represented in some shared memory buffer at the time of verification if there is only a shared buffer hit when accessing the block. Consequently,
amcheckdoes not necessarily examine data read from the file system at the time of verification. Note that when checksums are enabled,
amcheckmay raise an error due to a checksum failure when a corrupt block is read into a buffer.
heapallindexedverification is performed, there is generally a greatly increased chance of detecting single-bit errors, since strict binary equality is tested, and the indexed attributes within the heap are tested.
amcheckcan only prove the presence of corruption; it cannot prove its absence.
amcheckshould ever be a false positive.
amcheckraises errors in the event of conditions that, by definition, should never happen, and so careful analysis of
amcheckerrors is often required.
amcheckdetects. An explanation for the root cause of an invariant violation should be sought. pageinspect may play a useful role in diagnosing corruption that
REINDEXmay not be effective in repairing corruption.