amcheck

functions for verifying relation integrity

Overview

PackageVersionCategoryLicenseLanguage
amcheck1.4ADMINPostgreSQLC
IDExtensionBinLibLoadCreateTrustRelocSchema
5980amcheckNoYesNoYesNoNo-
Relatedpg_checksums pg_catcheck pg_visibility pg_surgery toastinfo pagevis pageinspect pg_freespacemap

Version

PG18PG17PG16PG15PG14
1.41.41.41.41.4

Install

Note: This is a built-in contrib extension of PostgreSQL

CREATE EXTENSION amcheck;

Usage

amcheck: functions for verifying relation integrity

The amcheck extension provides functions to verify the logical consistency of B-tree indexes, GIN indexes, and heap (table) data, detecting corruption without modifying data.

B-Tree Index Verification

-- Lightweight check (AccessShareLock, safe for production)
SELECT bt_index_check('my_index');

-- With heap-all-indexed verification
SELECT bt_index_check('my_index', heapallindexed => true);

-- Thorough check including parent/child invariants (ShareLock, blocks writes)
SELECT bt_index_parent_check('my_index');

-- Most thorough: rootdescend re-finds each tuple from root
SELECT bt_index_parent_check('my_index',
    heapallindexed => true,
    rootdescend => true,
    checkunique => true);

Check All Catalog Indexes

SELECT bt_index_check(c.oid), c.relname, c.relpages
FROM pg_index i
JOIN pg_opclass op ON i.indclass[0] = op.oid
JOIN pg_am am ON op.opcmethod = am.oid
JOIN pg_class c ON i.indexrelid = c.oid
JOIN pg_namespace n ON c.relnamespace = n.oid
WHERE am.amname = 'btree' AND n.nspname = 'pg_catalog'
  AND c.relpersistence != 't' AND c.relkind = 'i'
  AND i.indisready AND i.indisvalid
ORDER BY c.relpages DESC LIMIT 10;

GIN Index Verification

SELECT gin_index_check('my_gin_index');

Heap (Table) Verification

-- Basic heap check
SELECT * FROM verify_heapam('my_table');

-- With TOAST verification (slower)
SELECT * FROM verify_heapam('my_table', check_toast => true);

-- Check specific block range
SELECT * FROM verify_heapam('my_table', startblock => 0, endblock => 1000);

-- Stop at first corrupted block
SELECT * FROM verify_heapam('my_table', on_error_stop => true);

Returns rows for each detected problem:

ColumnTypeDescription
blknobigintBlock number with corruption
offnumintegerOffset of corrupt tuple
attnumintegerAttribute number (if column-specific)
msgtextDescription of the problem

Function Summary

FunctionLockUse Case
bt_index_check(index, heapallindexed, checkunique)AccessShareLockRoutine production checks
bt_index_parent_check(index, heapallindexed, rootdescend, checkunique)ShareLockComprehensive verification
gin_index_check(index)AccessShareLockGIN index verification
verify_heapam(relation, on_error_stop, check_toast, skip, startblock, endblock)AccessShareLockTable/heap corruption detection

All amcheck errors are true positives. Use REINDEX or point-in-time recovery for repair after diagnosing with pageinspect.


Last Modified 2026-03-12: add pg extension catalog (95749bf)