PostgreSQL 的扩展pageinspect

pageinspect 是 PostgreSQL 提供的一个强大的底层扩展，允许数据库管理员和开发者直接检查数据库页面的内部结构。这个扩展对于数据库调试、性能优化和深入学习 PostgreSQL 存储机制非常有价值。

一、扩展概述

功能：提供对 PostgreSQL 堆表、索引等页面级别的低级检查功能
用途：

• 诊断数据损坏问题
• 理解 PostgreSQL 存储结构
• 优化性能（分析页面填充率等）
• 开发数据库工具和扩展

版本支持：PostgreSQL 9.6+（不同版本功能可能略有差异）

二、安装与启用

-- 创建扩展
CREATE EXTENSION pageinspect;

-- 验证是否安装成功
SELECT * FROM pg_available_extensions WHERE name = 'pageinspect';

三、核心功能函数

1. 堆表页面检查

get_raw_page(relname text, fork text, blkno int)

获取表的原始页面数据

-- 获取表'test'的第0块数据
SELECT * FROM get_raw_page('test', 'main', 0);

heap_page_items(page bytea)

显示堆表页面中的所有行指针和元组头部信息

-- 检查表'test'的第0块内容
SELECT * FROM heap_page_items(get_raw_page('test', 0));

page_header(page bytea)

显示页面头部信息

-- 查看页面头部信息
SELECT * FROM page_header(get_raw_page('test', 0));

2. B-tree 索引检查

bt_metap(relname text)

显示B-tree索引的元信息

-- 查看索引'test_pkey'的元信息
SELECT * FROM bt_metap('test_pkey');

bt_page_stats(relname text, blkno int)

显示B-tree索引页面的统计信息

-- 查看索引'test_pkey'的第1页统计信息
SELECT * FROM bt_page_stats('test_pkey', 1);

bt_page_items(relname text, blkno int)

显示B-tree索引页面的项目

-- 查看索引'test_pkey'的第1页内容
SELECT * FROM bt_page_items('test_pkey', 1);

3. 其他功能函数

fsm_page_contents(page bytea)

显示空闲空间映射(FSM)页面内容

-- 查看表的FSM页面
SELECT * FROM fsm_page_contents(get_raw_page('test', 'fsm', 0));

brin_page_items(page bytea, index_oid regclass)

显示BRIN索引页面内容

-- 查看BRIN索引页面
SELECT * FROM brin_page_items(get_raw_page('brin_index', 0), 'brin_index'::regclass);

四、使用示例

示例1：分析表的页面填充率

-- 创建测试表
CREATE TABLE test_fillrate (id serial, data text);
INSERT INTO test_fillrate (data) 
SELECT md5(random()::text) FROM generate_series(1, 1000);

-- 分析页面填充情况
SELECT 
    blkno,
    COUNT(*) AS tuples,
    AVG(length(t_data::text)) AS avg_tuple_size,
    COUNT(*) * 100.0 / (
        SELECT setting::float 
        FROM pg_settings 
        WHERE name = 'block_size'
    ) AS fill_percentage
FROM 
    heap_page_items(get_raw_page('test_fillrate', 0))
GROUP BY 
    blkno;

示例2：诊断TOAST表问题

-- 检查TOAST表页面
SELECT * FROM heap_page_items(
    get_raw_page(
        (SELECT reltoastrelid FROM pg_class WHERE relname = 'large_table'), 
        0
    )
);

示例3：验证索引结构完整性

-- 检查B-tree索引的完整性
SELECT 
    level, 
    count(*) as pages, 
    avg(bt_page_stats.blksize) as avg_page_size
FROM 
    generate_series(0, 
        (SELECT level FROM bt_metap('test_pkey'))
    as level,
    lateral (
        SELECT * 
        FROM bt_page_stats('test_pkey', blkno) 
        WHERE btpo_level = level
    ) as bt_page_stats
GROUP BY 
    level
ORDER BY 
    level;

五、输出解释

heap_page_items 输出字段

字段名	类型	描述
lp	int	行指针编号
lp_off	int	行指针偏移量
lp_flags	int	行指针标志位
lp_len	int	元组长度
t_xmin	text	插入事务ID
t_xmax	text	删除/锁定事务ID
t_field3	text	特殊字段(如ctid)
t_ctid	text	当前元组ID
t_infomask2	int	属性标记
t_infomask	int	元组信息标记
t_hoff	int	头部偏移量
t_bits	text	NULL位图
t_oid	text	对象ID(OID)
t_data	bytea	元组数据

bt_page_stats 输出字段

字段名	类型	描述
blkno	int	页面编号
type	text	页面类型
live_items	int	活动项数量
dead_items	int	死亡项数量
avg_item_size	int	平均项大小
page_size	int	页面大小
free_size	int	空闲空间大小
btpo_prev	int	前一页
btpo_next	int	后一页
btpo_level	int	B-tree层级
btpo_flags	int	页面标志位

六、高级应用场景

场景1：数据损坏修复

-- 1. 识别损坏页面
SELECT corrupt_page 
FROM verify_heapam('table_name');

-- 2. 检查损坏页面内容
SELECT * FROM heap_page_items(get_raw_page('table_name', corrupt_page));

-- 3. 尝试从其他副本恢复或使用pg_resetwal

场景2：索引优化分析

-- 分析索引页面填充率
SELECT 
    blkno, 
    live_items, 
    dead_items,
    free_size,
    (page_size - free_size) * 100.0 / page_size AS fill_percentage
FROM 
    bt_page_stats('index_name', blkno) 
ORDER BY 
    blkno;

场景3：MVCC行为研究

-- 跟踪元组在不同事务中的变化
BEGIN;
INSERT INTO test VALUES (1, 'first');
SELECT lp, t_xmin, t_xmax, t_ctid FROM heap_page_items(get_raw_page('test', 0));

-- 在另一个会话中...
UPDATE test SET data = 'updated' WHERE id = 1;

-- 回到第一个会话
SELECT lp, t_xmin, t_xmax, t_ctid FROM heap_page_items(get_raw_page('test', 0));
COMMIT;

七、注意事项

1. 权限要求：需要超级用户权限才能使用大多数函数
2. 性能影响：直接读取页面会绕过缓冲区，可能影响性能
3. 数据安全：错误使用可能导致数据损坏
4. 版本兼容性：不同PostgreSQL版本的页面格式可能不同
5. 生产环境：建议先在测试环境验证操作

八、与相关工具结合

1. pgstattuple：结合分析表膨胀情况

   CREATE EXTENSION pgstattuple;
   SELECT * FROM pgstattuple('table_name');
   

2. pg_repack：发现页面问题后重组表

   -- 需要单独安装
   pg_repack -d dbname -t table_name
   

3. WAL检查：结合pg_waldump分析WAL记录

通过合理使用pageinspect扩展，可以深入了解PostgreSQL的存储机制，诊断复杂问题，并进行高级性能优化。