PostgreSQL的pg_filedump工具
基础信息
OS版本：Red Hat Enterprise Linux Server release 7.9 (Maipo)
DB版本：16.2
pg软件目录：/home/pg16/soft
pg数据目录：/home/pg16/data
端口：5777
pg_filedump 是一个工具，用于转储和分析 PostgreSQL 数据文件的内容。它可以显示数据文件的内部结构，包括页头、元组信息，以及数据的物理存储布局。此工具对数据库管理员和开发人员在深入理解数据库的物理存储结构、进行故障排查和性能调优时非常有用。
安装 pg_filedump
pg_filedump 通常作为 PostgreSQL 的附加工具，并不是默认安装的一部分。
1 下载安装包
https://github.com/df7cb/pg_filedump/tags
2 编译安装
[pg16@test resource]$ unzip pg_filedump-REL_16_0.zip
[pg16@test resource]$ cd pg_filedump-REL_16_0/
[pg16@test pg_filedump-REL_16_0]$ make && make install
3 确认
[pg16@test pg_filedump-REL_16_0]$ pg_filedump
Version 16.0 (for PostgreSQL 8.x .. 16.x)
Copyright (c) 2002-2010 Red Hat, Inc.
Copyright (c) 2011-2023, PostgreSQL Global Development Group
Usage: pg_filedump [-abcdfhikxy] [-R startblock [endblock]] [-D attrlist] [-S blocksize] [-s segsize] [-n segnumber] file
Display formatted contents of a PostgreSQL heap/index/control file
Defaults are: relative addressing, range of the entire file, block
size as listed on block 0 in the file
The following options are valid for heap and index files:
-a Display absolute addresses when formatting (Block header
information is always block relative)
-b Display binary block images within a range (Option will turn
off all formatting options)
-d Display formatted block content dump (Option will turn off
all other formatting options)
-D Decode tuples using given comma separated list of types
Supported types:
bigint bigserial bool char charN date float float4 float8 int
json macaddr name numeric oid real serial smallint smallserial text
time timestamp timestamptz timetz uuid varchar varcharN xid xml
~ ignores all attributes left in a tuple
-f Display formatted block content dump along with interpretation
-h Display this information
-i Display interpreted item details
-k Verify block checksums
-o Do not dump old values.
-R Display specific block ranges within the file (Blocks are
indexed from 0)
[startblock]: block to start at
[endblock]: block to end at
A startblock without an endblock will format the single block
-s Force segment size to [segsize]
-t Dump TOAST files
-v Ouput additional information about TOAST relations
-n Force segment number to [segnumber]
-S Force block size to [blocksize]
-x Force interpreted formatting of block items as index items
-y Force interpreted formatting of block items as heap items
The following options are valid for control files:
-c Interpret the file listed as a control file
-f Display formatted content dump along with interpretation
-S Force block size to [blocksize]
Additional functions:
-m Interpret file as pg_filenode.map file and print contents (all
other options will be ignored)
Report bugs to <pgsql-bugs@postgresql.org>
各个参数：
-a：显示绝对地址。块头信息始终是相对地址。
-b：显示指定范围的二进制块图像（该选项将关闭所有格式选项）。
-d：显示格式化的块内容转储（该选项将关闭所有其他格式选项）。
-D：使用指定的逗号分隔的类型列表解码元组。
-f：显示格式化的块内容转储及解释。
-h：显示帮助信息。
-i：显示解释的项详细信息。
-k：验证块校验和。
-o：不转储旧值。
-R：显示文件中指定的块范围。块从0开始索引。
-s：强制段大小为[segsize]。
-t：转储 TOAST 文件。
-v：输出有关 TOAST 关系的附加信息。
-n：强制段编号为[segnumber]。
-S：强制块大小为[blocksize]。
-x：强制将块项解释为索引项。
-y：强制将块项解释为堆项。
对于控制文件特有的选项：
-c：将文件解释为控制文件。
-m：将文件解释为 pg_filenode.map 文件并打印内容（忽略所有其它选项）。
使用 pg_filedump
下面是一些 pg_filedump 常用的基本用法。
获取数据文件的路径
在使用 pg_filedump 之前，需要获取要分析的表所在的数据文件的路径。可以使用以下 SQL 查询来获取表的文件路径（需要超级用户权限）：
white=# SELECT
white-# pg_relation_filenode(oid), -- 文件节点号，即文件名
white-# reltablespace, -- 表空间 OID
white-# pg_tablespace_location(r.reltablespace) AS tablespace_location -- 表空间路径
white-# FROM
white-# pg_class r
white-# WHERE
white-# relname = 't1';
pg_relation_filenode | reltablespace | tablespace_location
----------------------+---------------+---------------------
17040 | 0 |
(1 row)
white=# SELECT pg_relation_filepath('yewu1.t1');
pg_relation_filepath
----------------------
base/16505/17040
(1 row)
pg_filedump 基本用法
假设我们已经获取到表的文件路径，可以通过以下命令导出数据文件的内容：
[pg16@test bin]$ pg_filedump -i /home/pg16/data/base/16505/17040
*******************************************************************
* PostgreSQL File/Block Formatted Dump Utility
*
* File: /home/pg16/data/base/16505/17040
* Options used: -i
*******************************************************************
Block 0 ********************************************************
<Header> -----
Block Offset: 0x00000000 Offsets: Lower 764 (0x02fc)
Block: Size 8192 Version 4 Upper 832 (0x0340)
LSN: logid 0 recoff 0x7e00fce8 Special 8192 (0x2000)
Items: 185 Free Space: 68
Checksum: 0x7062 Prune XID: 0x00000000 Flags: 0x0000 ()
Length (including item array): 764
<Data> -----
Item 1 -- Length: 36 Offset: 8152 (0x1fd8) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 0
Block Id: 0 linp Index: 1 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 2 -- Length: 36 Offset: 8112 (0x1fb0) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 1
Block Id: 0 linp Index: 2 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 3 -- Length: 36 Offset: 8072 (0x1f88) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 2
Block Id: 0 linp Index: 3 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 4 -- Length: 36 Offset: 8032 (0x1f60) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 3
Block Id: 0 linp Index: 4 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 5 -- Length: 36 Offset: 7992 (0x1f38) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 4
Block Id: 0 linp Index: 5 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 6 -- Length: 36 Offset: 7952 (0x1f10) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 5
Block Id: 0 linp Index: 6 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 7 -- Length: 36 Offset: 7912 (0x1ee8) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 6
Block Id: 0 linp Index: 7 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
Item 8 -- Length: 36 Offset: 7872 (0x1ec0) Flags: NORMAL
XMIN: 268814 XMAX: 0 CID|XVAC: 7
Block Id: 0 linp Index: 8 Attributes: 2 Size: 24
infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID)
。。。。。省略。。。。。
查看页信息
要查看包含详细元组信息的页面内容，可以使用以下命令：
[pg16@test bin]$ pg_filedump -f /home/pg16/data/base/16505/17040
*******************************************************************
* PostgreSQL File/Block Formatted Dump Utility
*
* File: /home/pg16/data/base/16505/17040
* Options used: -f
*******************************************************************
Block 0 ********************************************************
<Header> -----
Block Offset: 0x00000000 Offsets: Lower 764 (0x02fc)
Block: Size 8192 Version 4 Upper 832 (0x0340)
LSN: logid 0 recoff 0x7e00fce8 Special 8192 (0x2000)
Items: 185 Free Space: 68
Checksum: 0x7062 Prune XID: 0x00000000 Flags: 0x0000 ()
Length (including item array): 764
0000: 00000000 e8fc007e 62700000 fc024003 .......~bp....@.
0010: 00200420 00000000 d89f4800 b09f4800 . . ......H...H.
0020: 889f4800 609f4800 389f4800 109f4800 ..H.`.H.8.H...H.
0030: e89e4800 c09e4800 989e4800 709e4a00 ..H...H...H.p.J.
0040: 489e4a00 209e4a00 f89d4a00 d09d4a00 H.J. .J...J...J.
0050: a89d4a00 809d4a00 589d4a00 309d4a00 ..J...J.X.J.0.J.
0060: 089d4a00 e09c4a00 b89c4a00 909c4a00 ..J...J...J...J.
0070: 689c4a00 409c4a00 189c4a00 f09b4a00 h.J.@.J...J...J.
。。。。省略。。。。
查看特定行范围的页信息
要仅查看特定block范围的信息，可以指定 -R <start> <end> 选项：
[pg16@test bin]$ pg_filedump -R 1 2 /home/pg16/data/base/16505/17040
*******************************************************************
* PostgreSQL File/Block Formatted Dump Utility
*
* File: /home/pg16/data/base/16505/17040
* Options used: -R 1 2
*******************************************************************
Block 1 ********************************************************
<Header> -----
Block Offset: 0x00002000 Offsets: Lower 764 (0x02fc)
Block: Size 8192 Version 4 Upper 792 (0x0318)
LSN: logid 0 recoff 0x7d193370 Special 8192 (0x2000)
Items: 185 Free Space: 28
Checksum: 0x4cb1 Prune XID: 0x00000000 Flags: 0x0004 (ALL_VISIBLE)
Length (including item array): 764
<Data> -----
Item 1 -- Length: 38 Offset: 8152 (0x1fd8) Flags: NORMAL
Item 2 -- Length: 38 Offset: 8112 (0x1fb0) Flags: NORMAL
Item 3 -- Length: 38 Offset: 8072 (0x1f88) Flags: NORMAL
Item 4 -- Length: 38 Offset: 8032 (0x1f60) Flags: NORMAL
Item 5 -- Length: 38 Offset: 7992 (0x1f38) Flags: NORMAL
。。。省略。。。
查看真实的数据
通过元组转译查看真实的数据内容，可以帮助我们修复数据。 -D int,text
[pg16@test bin]$ pg_filedump -D int,text /home/pg16/data/base/16505/17040 |more
*******************************************************************
* PostgreSQL File/Block Formatted Dump Utility
*
* File: /home/pg16/data/base/16505/17040
* Options used: -D int,text
*******************************************************************
Block 0 ********************************************************
<Header> -----
Block Offset: 0x00000000 Offsets: Lower 764 (0x02fc)
Block: Size 8192 Version 4 Upper 832 (0x0340)
LSN: logid 0 recoff 0x7e00fce8 Special 8192 (0x2000)
Items: 185 Free Space: 68
Checksum: 0x7062 Prune XID: 0x00000000 Flags: 0x0000 ()
Length (including item array): 764
<Data> -----
Item 1 -- Length: 36 Offset: 8152 (0x1fd8) Flags: NORMAL
COPY: 1 white 1
Item 2 -- Length: 36 Offset: 8112 (0x1fb0) Flags: NORMAL
COPY: 2 white 2
Item 3 -- Length: 36 Offset: 8072 (0x1f88) Flags: NORMAL
COPY: 3 white 3
Item 4 -- Length: 36 Offset: 8032 (0x1f60) Flags: NORMAL
COPY: 4 white 4
Item 5 -- Length: 36 Offset: 7992 (0x1f38) Flags: NORMAL
COPY: 5 white 5
Item 6 -- Length: 36 Offset: 7952 (0x1f10) Flags: NORMAL
COPY: 6 white 6
Item 7 -- Length: 36 Offset: 7912 (0x1ee8) Flags: NORMAL
COPY: 7 white 7
Item 8 -- Length: 36 Offset: 7872 (0x1ec0) Flags: NORMAL
COPY: 8 white 8
Item 9 -- Length: 36 Offset: 7832 (0x1e98) Flags: NORMAL
COPY: 9 white 9
Item 10 -- Length: 37 Offset: 7792 (0x1e70) Flags: NORMAL
COPY: 10 white 10
。。。省略。。。
注意事项
- 权限：运行
pg_filedump需要对 PostgreSQL 数据目录有读取权限。通常需要以 PostgreSQL 服务用户（如postgres用户）运行。 - 性能影响：直接操作数据文件不会影响运行中的 PostgreSQL 实例，但在生产环境中应谨慎执行。
- 只读操作：
pg_filedump是只读工具，不会修改数据文件的内容。
总结
pg_filedump提供了一种方式来直接查看 PostgreSQL 数据文件的内部结构。- 通过解析输出，可以深入理解表和索引的存储布局，帮助问题诊断和性能调优。
