当前位置：首页 > news >正文

PostgreSQL的pg_filedump工具

news 2026/2/3 6:19:39

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_filedumpVersion 16.0 (for PostgreSQL 8.x .. 16.x)
Copyright (c) 2002-2010 Red Hat, Inc.
Copyright (c) 2011-2023, PostgreSQL Global Development GroupUsage: pg_filedump [-abcdfhikxy] [-R startblock [endblock]] [-D attrlist] [-S blocksize] [-s segsize] [-n segnumber] fileDisplay formatted contents of a PostgreSQL heap/index/control file
Defaults are: relative addressing, range of the entire file, blocksize as listed on block 0 in the fileThe following options are valid for heap and index files:-a  Display absolute addresses when formatting (Block headerinformation is always block relative)-b  Display binary block images within a range (Option will turnoff all formatting options)-d  Display formatted block content dump (Option will turn offall other formatting options)-D  Decode tuples using given comma separated list of typesSupported types:bigint bigserial bool char charN date float float4 float8 intjson macaddr name numeric oid real serial smallint smallserial texttime 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 areindexed from 0)[startblock]: block to start at[endblock]: block to end atA 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 itemsThe 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 (allother 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:   68Checksum: 0x7062  Prune XID: 0x00000000  Flags: 0x0000 ()Length (including item array): 764<Data> -----Item   1 -- Length:   36  Offset: 8152 (0x1fd8)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 0Block Id: 0  linp Index: 1   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   2 -- Length:   36  Offset: 8112 (0x1fb0)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 1Block Id: 0  linp Index: 2   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   3 -- Length:   36  Offset: 8072 (0x1f88)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 2Block Id: 0  linp Index: 3   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   4 -- Length:   36  Offset: 8032 (0x1f60)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 3Block Id: 0  linp Index: 4   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   5 -- Length:   36  Offset: 7992 (0x1f38)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 4Block Id: 0  linp Index: 5   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   6 -- Length:   36  Offset: 7952 (0x1f10)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 5Block Id: 0  linp Index: 6   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   7 -- Length:   36  Offset: 7912 (0x1ee8)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 6Block Id: 0  linp Index: 7   Attributes: 2   Size: 24infomask: 0x0902 (HASVARWIDTH|XMIN_COMMITTED|XMAX_INVALID) Item   8 -- Length:   36  Offset: 7872 (0x1ec0)  Flags: NORMALXMIN: 268814  XMAX: 0  CID|XVAC: 7Block Id: 0  linp Index: 8   Attributes: 2   Size: 24infomask: 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:   68Checksum: 0x7062  Prune XID: 0x00000000  Flags: 0x0000 ()Length (including item array): 7640000: 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:   28Checksum: 0x4cb1  Prune XID: 0x00000000  Flags: 0x0004 (ALL_VISIBLE)Length (including item array): 764<Data> -----Item   1 -- Length:   38  Offset: 8152 (0x1fd8)  Flags: NORMALItem   2 -- Length:   38  Offset: 8112 (0x1fb0)  Flags: NORMALItem   3 -- Length:   38  Offset: 8072 (0x1f88)  Flags: NORMALItem   4 -- Length:   38  Offset: 8032 (0x1f60)  Flags: NORMALItem   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:   68Checksum: 0x7062  Prune XID: 0x00000000  Flags: 0x0000 ()Length (including item array): 764<Data> -----Item   1 -- Length:   36  Offset: 8152 (0x1fd8)  Flags: NORMAL
COPY: 1 white 1Item   2 -- Length:   36  Offset: 8112 (0x1fb0)  Flags: NORMAL
COPY: 2 white 2Item   3 -- Length:   36  Offset: 8072 (0x1f88)  Flags: NORMAL
COPY: 3 white 3Item   4 -- Length:   36  Offset: 8032 (0x1f60)  Flags: NORMAL
COPY: 4 white 4Item   5 -- Length:   36  Offset: 7992 (0x1f38)  Flags: NORMAL
COPY: 5 white 5Item   6 -- Length:   36  Offset: 7952 (0x1f10)  Flags: NORMAL
COPY: 6 white 6Item   7 -- Length:   36  Offset: 7912 (0x1ee8)  Flags: NORMAL
COPY: 7 white 7Item   8 -- Length:   36  Offset: 7872 (0x1ec0)  Flags: NORMAL
COPY: 8 white 8Item   9 -- Length:   36  Offset: 7832 (0x1e98)  Flags: NORMAL
COPY: 9 white 9Item  10 -- Length:   37  Offset: 7792 (0x1e70)  Flags: NORMAL
COPY: 10        white 10
。。。省略。。。

注意事项

权限：运行 pg_filedump 需要对 PostgreSQL 数据目录有读取权限。通常需要以 PostgreSQL 服务用户（如 postgres 用户）运行。
性能影响：直接操作数据文件不会影响运行中的 PostgreSQL 实例，但在生产环境中应谨慎执行。
只读操作：pg_filedump 是只读工具，不会修改数据文件的内容。

总结

pg_filedump 提供了一种方式来直接查看 PostgreSQL 数据文件的内部结构。
通过解析输出，可以深入理解表和索引的存储布局，帮助问题诊断和性能调优。