PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗
F.23. pageinspect — 数据库页面的低层级检查
上一页 上一级Appendix F. 随附额外模块与扩展首页 下一页

F.23. pageinspect — 数据库页面的低层级检查 #

F.23.1. 通用函数
F.23.2. 堆函数
F.23.3. B 树函数
F.23.4. BRIN 函数
F.23.5. GIN 函数
F.23.6. GiST 函数
F.23.7. 哈希函数

pageinspect 模块提供允许你在低层级检查数据库页面内容的函数，这对调试很有用。所有这些函数只能由超级用户使用。

F.23.1. 通用函数 #

get_raw_page(relname text, fork text, blkno bigint) returns bytea

get_raw_page 读取命名关系的指定块，并返回一个 bytea 值的副本。这样可以获得该块的单个时间一致的副本。fork 对主数据分支应为 'main'，对 空闲空间映射 为 'fsm'，对 可见性映射 为 'vm'，对初始化分支为 'init'。

get_raw_page(relname text, blkno bigint) returns bytea

get_raw_page 的简写版本，用于从主分支读取。等效于 get_raw_page(relname, 'main', blkno)

page_header(page bytea) returns record

page_header 显示所有 PostgreSQL 堆与索引页面共有的字段。

应传入用 get_raw_page 获得的页面镜像。例如： 

test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
    lsn    | checksum | flags  | lower | upper | special | pagesize | version | prune_xid
-----------+----------+--------+-------+-------+---------+----------+---------+-----------
 0/24A1B50 |        0 |      1 |   232 |   368 |    8192 |     8192 |       4 |         0

返回的列对应 PageHeaderData 结构中的字段。详情请参见 src/include/storage/bufpage.h。

checksum 字段是存储在页面中的校验和，如果页面因故损坏，它可能不正确。如果此实例禁用了数据校验和，存储的值没有意义。

page_checksum(page bytea, blkno bigint) returns smallint

page_checksum 计算页面的校验和，如同它位于给定块上一样。

应传入用 get_raw_page 获得的页面镜像。例如： 

test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
 page_checksum
---------------
         13443

注意校验和取决于块号，因此应传入匹配的块号（进行深奥的调试时除外）。

用该函数计算的校验和可以与 page_header 函数的 checksum 结果字段比较。如果此实例启用了数据校验和，这两个值应当相等。

fsm_page_contents(page bytea) returns text

fsm_page_contents 显示 FSM 页面的内部节点结构。例如： 

test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));

输出是一个多行字符串，页面内二叉树的每个节点对应一行。只打印非零节点。指向要从页面返回的下一个槽位的所谓 "next" 指针也会被打印。

有关 FSM 页面结构的更多信息，请参见 src/backend/storage/freespace/README。

F.23.2. 堆函数 #

heap_page_items(page bytea) returns setof record

heap_page_items 显示堆页面上的所有行指针。对使用中的行指针，还会显示元组头部以及元组原始数据。所有元组都会显示，无论复制原始页面时它们对 MVCC 快照是否可见。

应传入用 get_raw_page 获得的堆页面镜像。例如： 

test=# SELECT * FROM heap_page_items(get_raw_page('pg_class', 0));

返回字段的解释请参见 src/include/storage/itemid.h 与 src/include/access/htup_details.h。

heap_tuple_infomask_flags 函数可用于解包堆元组的 t_infomask 与 t_infomask2 标志位。

tuple_data_split(rel_oid oid, t_data bytea, t_infomask integer, t_infomask2 integer, t_bits text [, do_detoast bool]) returns bytea[]

tuple_data_split 以与后端内部相同的方式把元组数据拆分为属性。 

test=# SELECT tuple_data_split('pg_class'::regclass, t_data, t_infomask, t_infomask2, t_bits) FROM heap_page_items(get_raw_page('pg_class', 0));

该函数应使用与 heap_page_items 返回属性相同的参数调用。

如果 do_detoast 为 true，属性将按需解除外置。默认值为 false。

heap_page_item_attrs(page bytea, rel_oid regclass [, do_detoast bool]) returns setof record

heap_page_item_attrs 等效于 heap_page_items，区别在于它把元组原始数据作为属性数组返回，并可通过 do_detoast（默认为 false）可选地解除外置。

应传入用 get_raw_page 获得的堆页面镜像。例如： 

test=# SELECT * FROM heap_page_item_attrs(get_raw_page('pg_class', 0), 'pg_class'::regclass);

heap_tuple_infomask_flags(t_infomask integer, t_infomask2 integer) returns record

heap_tuple_infomask_flags 把 heap_page_items 返回的 t_infomask 与 t_infomask2 解码为人类可读的标志名数组集合，一列存放所有标志，一列存放组合标志。例如： 

test=# SELECT t_ctid, raw_flags, combined_flags
         FROM heap_page_items(get_raw_page('pg_class', 0)),
           LATERAL heap_tuple_infomask_flags(t_infomask, t_infomask2)
         WHERE t_infomask IS NOT NULL OR t_infomask2 IS NOT NULL;

该函数应使用与 heap_page_items 返回属性相同的参数调用。

组合标志针对会考虑多个原始位取值的源码级宏显示，例如 HEAP_XMIN_FROZEN。

返回标志名的解释请参见 src/include/access/htup_details.h。

F.23.3. B 树函数 #

bt_metap(relname text) returns record

bt_metap 返回 B 树索引元页面的信息。例如： 

test=# SELECT * FROM bt_metap('pg_cast_oid_index');
-[ RECORD 1 ]-------------+-------
magic                     | 340322
version                   | 4
root                      | 1
level                     | 0
fastroot                  | 1
fastlevel                 | 0
last_cleanup_num_delpages | 0
last_cleanup_num_tuples   | 230
allequalimage             | f

bt_page_stats(relname text, blkno bigint) returns record

bt_page_stats 返回 B 树索引数据页面的摘要信息。例如： 

test=# SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
-[ RECORD 1 ]-+-----
blkno         | 1
type          | l
live_items    | 224
dead_items    | 0
avg_item_size | 16
page_size     | 8192
free_size     | 3668
btpo_prev     | 0
btpo_next     | 0
btpo_level    | 0
btpo_flags    | 3

bt_multi_page_stats(relname text, blkno bigint, blk_count bigint) returns setof record

bt_multi_page_stats 返回与 bt_page_stats 相同的信息，但针对从 blkno 开始、延伸 blk_count 个页面的页面范围中的每一页。如果 blk_count 为负，则报告从 blkno 到索引末尾的所有页面。例如： 

test=# SELECT * FROM bt_multi_page_stats('pg_proc_oid_index', 5, 2);
-[ RECORD 1 ]-+-----
blkno         | 5
type          | l
live_items    | 367
dead_items    | 0
avg_item_size | 16
page_size     | 8192
free_size     | 808
btpo_prev     | 4
btpo_next     | 6
btpo_level    | 0
btpo_flags    | 1
-[ RECORD 2 ]-+-----
blkno         | 6
type          | l
live_items    | 367
dead_items    | 0
avg_item_size | 16
page_size     | 8192
free_size     | 808
btpo_prev     | 5
btpo_next     | 7
btpo_level    | 0
btpo_flags    | 1

bt_page_items(relname text, blkno bigint) returns setof record

bt_page_items 返回 B 树索引页面上所有条目的详细信息。例如： 

test=# SELECT itemoffset, ctid, itemlen, nulls, vars, data, dead, htid, tids[0:2] AS some_tids
        FROM bt_page_items('tenk2_hundred', 5);
 itemoffset |   ctid    | itemlen | nulls | vars |          data           | dead |  htid  |      some_tids
------------+-----------+---------+-------+------+-------------------------+------+--------+---------------------
          1 | (16,1)    |      16 | f     | f    | 30 00 00 00 00 00 00 00 |      |        |
          2 | (16,8292) |     616 | f     | f    | 24 00 00 00 00 00 00 00 | f    | (1,6)  | {"(1,6)","(10,22)"}
          3 | (16,8292) |     616 | f     | f    | 25 00 00 00 00 00 00 00 | f    | (1,18) | {"(1,18)","(4,22)"}
          4 | (16,8292) |     616 | f     | f    | 26 00 00 00 00 00 00 00 | f    | (4,18) | {"(4,18)","(6,17)"}
          5 | (16,8292) |     616 | f     | f    | 27 00 00 00 00 00 00 00 | f    | (1,2)  | {"(1,2)","(1,19)"}
          6 | (16,8292) |     616 | f     | f    | 28 00 00 00 00 00 00 00 | f    | (2,24) | {"(2,24)","(4,11)"}
          7 | (16,8292) |     616 | f     | f    | 29 00 00 00 00 00 00 00 | f    | (2,17) | {"(2,17)","(11,2)"}
          8 | (16,8292) |     616 | f     | f    | 2a 00 00 00 00 00 00 00 | f    | (0,25) | {"(0,25)","(3,20)"}
          9 | (16,8292) |     616 | f     | f    | 2b 00 00 00 00 00 00 00 | f    | (0,10) | {"(0,10)","(0,14)"}
         10 | (16,8292) |     616 | f     | f    | 2c 00 00 00 00 00 00 00 | f    | (1,3)  | {"(1,3)","(3,9)"}
         11 | (16,8292) |     616 | f     | f    | 2d 00 00 00 00 00 00 00 | f    | (6,28) | {"(6,28)","(11,1)"}
         12 | (16,8292) |     616 | f     | f    | 2e 00 00 00 00 00 00 00 | f    | (0,27) | {"(0,27)","(1,13)"}
         13 | (16,8292) |     616 | f     | f    | 2f 00 00 00 00 00 00 00 | f    | (4,17) | {"(4,17)","(4,21)"}
(13 rows)

这是一个 B 树叶子页面。所有指向该表的元组碰巧都是 posting list 元组（每个存储共 100 个 6 字节 TID）。在 itemoffset 编号 1 处还有一个 “高键” 元组。在本例中，ctid 被用来存储每个元组的编码信息，不过叶子页面的元组通常直接把堆 TID 存储在 ctid 字段中。tids 是作为 posting list 存储的 TID 列表。

在内部页面（未显示）中，ctid 的块号部分是一个 “下行链接”，即索引自身另一个页面的块号。ctid 的偏移部分（第二个数字）存储关于元组的编码信息，例如存在的列数（后缀截断可能已移除不需要的后缀列）。被截断的列被视为值为“负无穷”。

htid 显示元组的堆 TID，与底层元组表示方式无关。该值可能与 ctid 一致，也可能是从 posting list 元组与内部页面元组使用的替代表示中解码出来的。内部页面中的元组通常会把实现层级的堆 TID 列截断掉，表示为 NULL 的 htid 值。

请注意，任何非最右页面（btpo_next 字段非零值的页面）的第一个条目是该页面的 “高键”，也就是说它的 data 作为该页面上所有条目的上界，而它的 ctid 字段不指向另一个块。此外，在内部页面上，第一个真实数据条目（第一个非高键条目）可靠地被截断了每一列，其 data 字段中不保留实际值。不过这样的条目在 ctid 字段中确实有有效的下行链接。

关于 B 树索引结构的更多细节，请参见 Section 65.1.4.1。关于去重与 posting list 的更多细节，请参见 Section 65.1.4.3。

bt_page_items(page bytea) returns setof record

也可以把页面作为 bytea 值传给 bt_page_items。应传入用 get_raw_page 获得的页面镜像。因此最后一个例子也可以改写为： 

test=# SELECT itemoffset, ctid, itemlen, nulls, vars, data, dead, htid, tids[0:2] AS some_tids
        FROM bt_page_items(get_raw_page('tenk2_hundred', 5));
 itemoffset |   ctid    | itemlen | nulls | vars |          data           | dead |  htid  |      some_tids
------------+-----------+---------+-------+------+-------------------------+------+--------+---------------------
          1 | (16,1)    |      16 | f     | f    | 30 00 00 00 00 00 00 00 |      |        |
          2 | (16,8292) |     616 | f     | f    | 24 00 00 00 00 00 00 00 | f    | (1,6)  | {"(1,6)","(10,22)"}
          3 | (16,8292) |     616 | f     | f    | 25 00 00 00 00 00 00 00 | f    | (1,18) | {"(1,18)","(4,22)"}
          4 | (16,8292) |     616 | f     | f    | 26 00 00 00 00 00 00 00 | f    | (4,18) | {"(4,18)","(6,17)"}
          5 | (16,8292) |     616 | f     | f    | 27 00 00 00 00 00 00 00 | f    | (1,2)  | {"(1,2)","(1,19)"}
          6 | (16,8292) |     616 | f     | f    | 28 00 00 00 00 00 00 00 | f    | (2,24) | {"(2,24)","(4,11)"}
          7 | (16,8292) |     616 | f     | f    | 29 00 00 00 00 00 00 00 | f    | (2,17) | {"(2,17)","(11,2)"}
          8 | (16,8292) |     616 | f     | f    | 2a 00 00 00 00 00 00 00 | f    | (0,25) | {"(0,25)","(3,20)"}
          9 | (16,8292) |     616 | f     | f    | 2b 00 00 00 00 00 00 00 | f    | (0,10) | {"(0,10)","(0,14)"}
         10 | (16,8292) |     616 | f     | f    | 2c 00 00 00 00 00 00 00 | f    | (1,3)  | {"(1,3)","(3,9)"}
         11 | (16,8292) |     616 | f     | f    | 2d 00 00 00 00 00 00 00 | f    | (6,28) | {"(6,28)","(11,1)"}
         12 | (16,8292) |     616 | f     | f    | 2e 00 00 00 00 00 00 00 | f    | (0,27) | {"(0,27)","(1,13)"}
         13 | (16,8292) |     616 | f     | f    | 2f 00 00 00 00 00 00 00 | f    | (4,17) | {"(4,17)","(4,21)"}
(13 rows)

其他所有细节与上一个条目中的说明相同。

F.23.4. BRIN 函数 #

brin_page_type(page bytea) returns text

brin_page_type 返回给定 BRIN 索引页面的页面类型；如果页面不是有效的 BRIN 页面则抛出错误。例如： 

test=# SELECT brin_page_type(get_raw_page('brinidx', 0));
 brin_page_type
----------------
 meta

brin_metapage_info(page bytea) returns record

brin_metapage_info 返回 BRIN 索引元页面的各种信息。例如： 

test=# SELECT * FROM brin_metapage_info(get_raw_page('brinidx', 0));
   magic    | version | pagesperrange | lastrevmappage
------------+---------+---------------+----------------
 0xA8109CFA |       1 |             4 |              2

brin_revmap_data(page bytea) returns setof tid

brin_revmap_data 返回 BRIN 索引范围映射页面中的元组标识符列表。例如： 

test=# SELECT * FROM brin_revmap_data(get_raw_page('brinidx', 2)) LIMIT 5;
  pages
---------
 (6,137)
 (6,138)
 (6,139)
 (6,140)
 (6,141)

brin_page_items(page bytea, index oid) returns setof record

brin_page_items 返回存储在 BRIN 数据页面中的数据。例如： 

test=# SELECT * FROM brin_page_items(get_raw_page('brinidx', 5),
                                     'brinidx')
       ORDER BY blknum, attnum LIMIT 6;
 itemoffset | blknum | attnum | allnulls | hasnulls | placeholder | empty |    value
------------+--------+--------+----------+----------+-------------+-------+--------------
        137 |      0 |      1 | t        | f        | f           | f     |
        137 |      0 |      2 | f        | f        | f           | f     | {1 .. 88}
        138 |      4 |      1 | t        | f        | f           | f     |
        138 |      4 |      2 | f        | f        | f           | f     | {89 .. 176}
        139 |      8 |      1 | t        | f        | f           | f     |
        139 |      8 |      2 | f        | f        | f           | f     | {177 .. 264}

返回的列对应 BrinMemTuple 与 BrinValues 结构中的字段。详情请参见 src/include/access/brin_tuple.h。

F.23.5. GIN 函数 #

gin_metapage_info(page bytea) returns record

gin_metapage_info 返回 GIN 索引元页面的信息。例如： 

test=# SELECT * FROM gin_metapage_info(get_raw_page('gin_index', 0));
-[ RECORD 1 ]----+-----------
pending_head     | 4294967295
pending_tail     | 4294967295
tail_free_size   | 0
n_pending_pages  | 0
n_pending_tuples | 0
n_total_pages    | 7
n_entry_pages    | 6
n_data_pages     | 0
n_entries        | 693
version          | 2

gin_page_opaque_info(page bytea) returns record

gin_page_opaque_info 返回 GIN 索引不透明区域的信息，例如页面类型。例如： 

test=# SELECT * FROM gin_page_opaque_info(get_raw_page('gin_index', 2));
 rightlink | maxoff |         flags
-----------+--------+------------------------
         5 |      0 | {data,leaf,compressed}
(1 row)

gin_leafpage_items(page bytea) returns setof record

gin_leafpage_items 返回压缩 GIN 叶子页面中所存数据的信息。例如： 

test=# SELECT first_tid, nbytes, tids[0:5] AS some_tids
        FROM gin_leafpage_items(get_raw_page('gin_test_idx', 2));
 first_tid | nbytes |                        some_tids
-----------+--------+----------------------------------------------------------
 (8,41)    |    244 | {"(8,41)","(8,43)","(8,44)","(8,45)","(8,46)"}
 (10,45)   |    248 | {"(10,45)","(10,46)","(10,47)","(10,48)","(10,49)"}
 (12,52)   |    248 | {"(12,52)","(12,53)","(12,54)","(12,55)","(12,56)"}
 (14,59)   |    320 | {"(14,59)","(14,60)","(14,61)","(14,62)","(14,63)"}
 (167,16)  |    376 | {"(167,16)","(167,17)","(167,18)","(167,19)","(167,20)"}
 (170,30)  |    376 | {"(170,30)","(170,31)","(170,32)","(170,33)","(170,34)"}
 (173,44)  |    197 | {"(173,44)","(173,45)","(173,46)","(173,47)","(173,48)"}
(7 rows)

F.23.6. GiST 函数 #

gist_page_opaque_info(page bytea) returns record

gist_page_opaque_info 返回 GiST 索引页面不透明区域的信息，例如 NSN、rightlink 与页面类型。例如： 

test=# SELECT * FROM gist_page_opaque_info(get_raw_page('test_gist_idx', 2));
 lsn | nsn | rightlink | flags
-----+-----+-----------+--------
 0/1 | 0/0 |         1 | {leaf}
(1 row)

gist_page_items(page bytea, index_oid regclass) returns setof record

gist_page_items 返回 GiST 索引页面中所存数据的信息。例如： 

test=# SELECT * FROM gist_page_items(get_raw_page('test_gist_idx', 0), 'test_gist_idx');
 itemoffset |   ctid    | itemlen | dead |             keys
------------+-----------+---------+------+-------------------------------
          1 | (1,65535) |      40 | f    | (p)=("(185,185),(1,1)")
          2 | (2,65535) |      40 | f    | (p)=("(370,370),(186,186)")
          3 | (3,65535) |      40 | f    | (p)=("(555,555),(371,371)")
          4 | (4,65535) |      40 | f    | (p)=("(740,740),(556,556)")
          5 | (5,65535) |      40 | f    | (p)=("(870,870),(741,741)")
          6 | (6,65535) |      40 | f    | (p)=("(1000,1000),(871,871)")
(6 rows)

gist_page_items_bytea(page bytea) returns setof record

与 gist_page_items 相同，但把键数据作为原始 bytea 块返回。由于它不尝试解码键，因此不需要知道涉及哪个索引。例如： 

test=# SELECT * FROM gist_page_items_bytea(get_raw_page('test_gist_idx', 0));
 itemoffset |   ctid    | itemlen | dead |                                      key_data
------------+-----------+---------+------+-----------------------------------------​-------------------------------------------
          1 | (1,65535) |      40 | f    | \x00000100ffff28000000000000c0644000000000​00c06440000000000000f03f000000000000f03f
          2 | (2,65535) |      40 | f    | \x00000200ffff28000000000000c0744000000000​00c074400000000000e064400000000000e06440
          3 | (3,65535) |      40 | f    | \x00000300ffff28000000000000207f4000000000​00207f400000000000d074400000000000d07440
          4 | (4,65535) |      40 | f    | \x00000400ffff28000000000000c0844000000000​00c084400000000000307f400000000000307f40
          5 | (5,65535) |      40 | f    | \x00000500ffff28000000000000f0894000000000​00f089400000000000c884400000000000c88440
          6 | (6,65535) |      40 | f    | \x00000600ffff28000000000000208f4000000000​00208f400000000000f889400000000000f88940
          7 | (7,65535) |      40 | f    | \x00000700ffff28000000000000408f4000000000​00408f400000000000288f400000000000288f40
(7 rows)

F.23.7. 哈希函数 #

hash_page_type(page bytea) returns text

hash_page_type 返回给定 HASH 索引页面的页面类型。例如： 

test=# SELECT hash_page_type(get_raw_page('con_hash_index', 0));
 hash_page_type
----------------
 metapage

hash_page_stats(page bytea) returns setof record

hash_page_stats 返回 HASH 索引桶页面或溢出页面的信息。例如： 

test=# SELECT * FROM hash_page_stats(get_raw_page('con_hash_index', 1));
-[ RECORD 1 ]---+-----------
live_items      | 407
dead_items      | 0
page_size       | 8192
free_size       | 8
hasho_prevblkno | 4096
hasho_nextblkno | 8474
hasho_bucket    | 0
hasho_flag      | 66
hasho_page_id   | 65408

hash_page_items(page bytea) returns setof record

hash_page_items 返回 HASH 索引页面的桶页面或溢出页面中所存数据的信息。例如： 

test=# SELECT * FROM hash_page_items(get_raw_page('con_hash_index', 1)) LIMIT 5;
 itemoffset |   ctid    |    data
------------+-----------+------------
          1 | (899,77)  | 1053474816
          2 | (897,29)  | 1053474816
          3 | (894,207) | 1053474816
          4 | (892,159) | 1053474816
          5 | (890,111) | 1053474816

hash_bitmap_info(index oid, blkno bigint) returns record

hash_bitmap_info 显示 HASH 索引特定溢出页面的位图页中某一位的状态。例如： 

test=# SELECT * FROM hash_bitmap_info('con_hash_index', 2052);
 bitmapblkno | bitmapbit | bitstatus
-------------+-----------+-----------
          65 |         3 | t

hash_metapage_info(page bytea) returns record

hash_metapage_info 返回存储在 HASH 索引元页面中的信息。例如： 

test=# SELECT magic, version, ntuples, ffactor, bsize, bmsize, bmshift,
test-#     maxbucket, highmask, lowmask, ovflpoint, firstfree, nmaps, procid,
test-#     regexp_replace(spares::text, '(,0)*}', '}') as spares,
test-#     regexp_replace(mapp::text, '(,0)*}', '}') as mapp
test-# FROM hash_metapage_info(get_raw_page('con_hash_index', 0));
-[ RECORD 1 ]-------------------------------------------------​------------------------------
magic     | 105121344
version   | 4
ntuples   | 500500
ffactor   | 40
bsize     | 8152
bmsize    | 4096
bmshift   | 15
maxbucket | 12512
highmask  | 16383
lowmask   | 8191
ovflpoint | 28
firstfree | 1204
nmaps     | 1
procid    | 450
spares    | {0,0,0,0,0,0,1,1,1,1,1,1,1,1,3,4,4,4,45,55,58,59,​508,567,628,704,1193,1202,1204}
mapp      | {65}

上一页 上一级 下一页
F.22. ltree — 层次树状数据类型 首页 F.24. passwordcheck — 检查密码强度