amcheck
amcheck
amcheck : functions for verifying relation integrity
Overview
| ID | Extension | Package | Version | Category | License | Language |
|---|---|---|---|---|---|---|
| 5980 | amcheck
|
amcheck
|
1.4 |
ADMIN
|
PostgreSQL
|
C
|
| Attribute | Has Binary | Has Library | Need Load | Has DDL | Relocatable | Trusted |
|---|---|---|---|---|---|---|
--s-d--
|
No
|
Yes
|
No
|
Yes
|
no
|
no
|
| Relationships | |
|---|---|
| See Also | pg_checksums
pg_catcheck
pg_visibility
pg_surgery
toastinfo
pagevis
pageinspect
pg_freespacemap
|
Packages
| PG18 | PG17 | PG16 | PG15 | PG14 |
|---|---|---|---|---|
1.4
|
1.4
|
1.4
|
1.4
|
1.4
|
This is a built-in contrib extension ship with the PostgreSQL kernel
Install
Create this extension with:
CREATE EXTENSION amcheck;Usage
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:
| Column | Type | Description |
|---|---|---|
blkno |
bigint | Block number with corruption |
offnum |
integer | Offset of corrupt tuple |
attnum |
integer | Attribute number (if column-specific) |
msg |
text | Description of the problem |
Function Summary
| Function | Lock | Use Case |
|---|---|---|
bt_index_check(index, heapallindexed, checkunique) |
AccessShareLock | Routine production checks |
bt_index_parent_check(index, heapallindexed, rootdescend, checkunique) |
ShareLock | Comprehensive verification |
gin_index_check(index) |
AccessShareLock | GIN index verification |
verify_heapam(relation, on_error_stop, check_toast, skip, startblock, endblock) |
AccessShareLock | Table/heap corruption detection |
All amcheck errors are true positives. Use REINDEX or point-in-time recovery for repair after diagnosing with pageinspect.
Last updated on