↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 命令行工具 / 客户端程序

pg_amcheck

pg_amcheck — 检查一个或多个 PostgreSQL 数据库中的损坏情况

当前查看 PostgreSQL 18.6。

说明

pg_amcheck — 检查一个或多个 PostgreSQL 数据库中的损坏情况

手册中的可执行程序
pg_amcheck
程序版本
18.6
参考清单
客户端程序
选项定义组
36

用法

pg_amcheck [ option ...] [ dbname ]

手册中的选项

选项与参数说明
-a --all检查所有数据库，但通过 --exclude-database 排除的除外。
-d pattern --database= pattern检查匹配指定 pattern 的数据库，但通过 --exclude-database 排除的除外。此选项可指定多次。
-D pattern --exclude-database= pattern排除匹配指定 pattern 的数据库。此选项可指定多次。
-i pattern --index= pattern检查匹配指定 pattern 的索引，除非另有排除。此选项可指定多次。
-I pattern --exclude-index= pattern排除匹配指定 pattern 的索引。此选项可指定多次。
-r pattern --relation= pattern检查匹配指定 pattern 的关系，除非另有排除。此选项可指定多次。
-R pattern --exclude-relation= pattern排除匹配指定 pattern 的关系。此选项可指定多次。
-s pattern --schema= pattern检查匹配指定 pattern 的模式中的表和索引，除非另有排除。此选项可指定多次。
-S pattern --exclude-schema= pattern排除匹配指定 pattern 的模式中的表和索引。此选项可指定多次。
-t pattern --table= pattern检查匹配指定 pattern 的表，除非另有排除。此选项可指定多次。
-T pattern --exclude-table= pattern排除匹配指定 pattern 的表。此选项可指定多次。
--no-dependent-indexes默认情况下，如果检查某个表，则该表上的任何 B-树索引也会一并检查，即使它们没有通过 --index 或 --relation 等选项显式选中。此选项会禁止这种行为。
--no-dependent-toast默认情况下，如果检查某个表，则它的 TOAST 表（如果有）也会一并检查，即使该 TOAST 表没有通过 --table 或 --relation 等选项显式选中。此选项会禁止这种行为。
--no-strict-names默认情况下，如果 --database 、 --table 、 --index 或 --relation 的某个参数没有匹配到任何对象，就会报致命错误。此选项会将该错误降级为警告。
--exclude-toast-pointers默认情况下，只要在表中遇到 TOAST 指针，就会执行查找，以确保它引用的是 TOAST 表中表面看来有效的条目。这些检查可能相当慢，可用此选项跳过。
--on-error-stop在某个表中发现损坏后，在报告完该表第一个损坏页面上的全部损坏后，停止处理该表关系并转到下一个表或索引。
--skip= option如果给定 all-frozen ，表损坏检查会跳过所有表中标记为全冻结的页面。
--startblock= block从指定块号开始检查。如果被检查的表关系块数少于这个数字，将发生错误。此选项不适用于索引，而且大概只在检查单个表关系时才有用。进一步的注意事项见 --endblock 。
--endblock= block在指定块号结束检查。如果被检查的表关系块数少于这个数字，将发生错误。此选项不适用于索引，而且大概只在检查单个表关系时才有用。如果同时检查普通表和 TOAST 表，此选项会同时作用于两者；但在验证 TOAST 指针时，仍可能访问更高编号的 TOAST 块，除非使用 --exclude-toast-pointers 抑制这一行为。
--checkunique对于检查的每个带唯一约束的索引，使用 amcheck 的 checkunique 选项，验证重复条目中在索引里可见的项不超过一个。
--heapallindexed对于检查的每个索引，使用 amcheck 的 heapallindexed 选项，验证所有堆元组都以索引元组的形式出现在该索引中。
--parent-check对于检查的每个 B-树索引，使用 amcheck 的 bt_index_parent_check 函数，该函数会在索引检查期间额外检查父子关系。
--rootdescend对于检查的每个索引，使用 amcheck 的 rootdescend 选项，为每个元组从根页重新执行一次搜索，从而在叶级重新找到这些元组。
-h hostname --host= hostname指定服务器所在机器的主机名。如果该值以斜杠开头，则将其用作 Unix 域套接字所在的目录。
-p port --port= port指定服务器监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。
-U --username= username连接时使用的用户名。
-w --no-password永不发出密码提示。如果服务器要求密码认证，而又无法通过其他方式获取密码，例如通过 .pgpass 文件，则连接尝试会失败。此选项可用于没有用户在场输入密码的批处理作业和脚本。
-W --password强制 pg_amcheck 在连接数据库前提示输入密码。
--maintenance-db= dbname指定一个数据库或 连接字符串 ，用于确定待检查的数据库列表。如果既未使用 --all ，也未使用任何包含数据库名称匹配模式的选项，则不需要这样的连接，此选项也不起作用。否则，此选项值中除数据库名之外的任何连接字符串参数，在连接待检查的数据库时也会一并使用。如果省略此选项，默认值为 postgres ；若失败，则为 template1 。
-e --echo将发送到服务器的所有 SQL 回显到标准输出。
-j num --jobs= num使用 num 个到服务器的并发连接，或者为每个待检查对象使用一个连接，以较小者为准。
-P --progress显示进度信息。进度信息包括已完成检查的关系数量及其总大小，也包括最终将要检查的关系总数及这些关系的估计大小。
-v --verbose打印更多消息。特别是，它会为每个正在检查的关系打印一条消息，并提高服务器错误显示的详细程度。
-V --version打印 pg_amcheck 版本并退出。
--install-missing --install-missing= schema安装检查数据库所需的任何缺失扩展。如果某个扩展尚未安装，则其对象将安装到给定的 schema 中；如果未指定，则安装到 pg_catalog 模式中。
-? --help显示 pg_amcheck 命令行参数的帮助并退出。

手册定义

pg_amcheck

pg_amcheck — 检查一个或多个PostgreSQL数据库中的损坏情况

大纲

pg_amcheck [option...] [dbname]

说明

pg_amcheck支持针对一个或多个数据库运行amcheck的损坏检查函数，并提供选项来选择要检查哪些模式、表和索引，执行哪些检查，以及是否并行执行这些检查；如果并行执行，还可指定要建立并使用的并行连接数。

当前仅支持普通表关系、TOAST 表关系、物化视图、序列以及 B-树索引。其他关系类型会被静默跳过。

如果指定了dbname，它应是要检查的单个数据库的名称，并且不应再出现其他数据库选择选项。否则，如果存在任何数据库选择选项，就会检查所有匹配的数据库。如果不存在这类选项，则检查默认数据库。数据库选择选项包括--all、--database和--exclude-database。它们还包括--relation、--exclude-relation、--table、--exclude-table、--index和--exclude-index，但仅限于这些选项与三部分模式一起使用时（例如 mydb*.myschema*.myrel*）。最后，当--schema和--exclude-schema与两部分模式一起使用时（例如 mydb*.myschema*），它们也属于数据库选择选项。

dbname也可以是连接字符串。

选项

下列命令行选项控制要检查的内容：

-a
--all

检查所有数据库，但通过--exclude-database排除的除外。

-d pattern
--database=pattern

检查匹配指定pattern的数据库，但通过--exclude-database排除的除外。此选项可指定多次。

-D pattern
--exclude-database=pattern

排除匹配指定pattern的数据库。此选项可指定多次。

-i pattern
--index=pattern

检查匹配指定pattern的索引，除非另有排除。此选项可指定多次。

这与--relation选项类似，但它只适用于索引，不适用于其他关系类型。

-I pattern
--exclude-index=pattern

排除匹配指定pattern的索引。此选项可指定多次。

这与--exclude-relation选项类似，但它只适用于索引，不适用于其他关系类型。

-r pattern
--relation=pattern

检查匹配指定pattern的关系，除非另有排除。此选项可指定多次。

匹配模式可以是未经限定的，例如myrel*；也可以是模式限定的，例如myschema*.myrel*；或者同时带数据库限定和模式限定，例如mydb*.myschema*.myrel*。数据库限定的模式会把匹配的数据库加入待检查数据库列表。

-R pattern
--exclude-relation=pattern

排除匹配指定pattern的关系。此选项可指定多次。

与--relation一样，pattern可以是未经限定的、模式限定的，或者同时带数据库限定和模式限定的。

-s pattern
--schema=pattern

检查匹配指定pattern的模式中的表和索引，除非另有排除。此选项可指定多次。

若只想选择名称匹配特定模式的那些模式中的表，可考虑使用类似--table=SCHEMAPAT.* --no-dependent-indexes的写法。若只想选择索引，可考虑使用类似--index=SCHEMAPAT.*的写法。

模式名匹配模式可以带有数据库限定。例如，可以使用 --schema=mydb*.myschema*，选择名称匹配 mydb* 的数据库中名称匹配 myschema* 的模式。

-S pattern
--exclude-schema=pattern

排除匹配指定pattern的模式中的表和索引。此选项可指定多次。

与--schema一样，该模式可以带数据库限定。

-t pattern
--table=pattern

检查匹配指定pattern的表，除非另有排除。此选项可指定多次。

这与--relation选项类似，但它只适用于表、物化视图和序列，不适用于索引。

-T pattern
--exclude-table=pattern

排除匹配指定pattern的表。此选项可指定多次。

这与--exclude-relation选项类似，但它只适用于表、物化视图和序列，不适用于索引。

--no-dependent-indexes

默认情况下，如果检查某个表，则该表上的任何 B-树索引也会一并检查，即使它们没有通过--index或--relation等选项显式选中。此选项会禁止这种行为。

--no-dependent-toast

默认情况下，如果检查某个表，则它的 TOAST 表（如果有）也会一并检查，即使该 TOAST 表没有通过--table或--relation等选项显式选中。此选项会禁止这种行为。

--no-strict-names

默认情况下，如果--database、--table、--index或--relation的某个参数没有匹配到任何对象，就会报致命错误。此选项会将该错误降级为警告。

下列命令行选项控制表的检查：

--exclude-toast-pointers

默认情况下，只要在表中遇到 TOAST 指针，就会执行查找，以确保它引用的是 TOAST 表中表面看来有效的条目。这些检查可能相当慢，可用此选项跳过。

--on-error-stop

在某个表中发现损坏后，在报告完该表第一个损坏页面上的全部损坏后，停止处理该表关系并转到下一个表或索引。

注意，索引检查总是在第一个损坏页后停止。此选项只对表关系有意义。

--skip=option

如果给定all-frozen，表损坏检查会跳过所有表中标记为全冻结的页面。

如果给定all-visible，表损坏检查会跳过所有表中标记为全可见的页面。

默认不跳过任何页面。这可以显式指定为none，但因为这是默认值，通常无需写出。

--startblock=block

从指定块号开始检查。如果被检查的表关系块数少于这个数字，将发生错误。此选项不适用于索引，而且大概只在检查单个表关系时才有用。进一步的注意事项见--endblock。

--endblock=block

在指定块号结束检查。如果被检查的表关系块数少于这个数字，将发生错误。此选项不适用于索引，而且大概只在检查单个表关系时才有用。如果同时检查普通表和 TOAST 表，此选项会同时作用于两者；但在验证 TOAST 指针时，仍可能访问更高编号的 TOAST 块，除非使用--exclude-toast-pointers抑制这一行为。

下列命令行选项控制 B-树索引的检查：

--checkunique

对于检查的每个带唯一约束的索引，使用amcheck的checkunique选项，验证重复条目中在索引里可见的项不超过一个。

--heapallindexed

对于检查的每个索引，使用amcheck的heapallindexed选项，验证所有堆元组都以索引元组的形式出现在该索引中。

--parent-check

对于检查的每个 B-树索引，使用amcheck的bt_index_parent_check函数，该函数会在索引检查期间额外检查父子关系。

默认使用amcheck的bt_index_check函数，但请注意，使用--rootdescend选项会隐式选择bt_index_parent_check。

--rootdescend

对于检查的每个索引，使用amcheck的rootdescend选项，为每个元组从根页重新执行一次搜索，从而在叶级重新找到这些元组。

使用此选项也会隐式选择--parent-check选项。

这种验证形式最初是为协助开发 B-树索引特性而编写的。它在帮助检测实际发生的那类损坏方面可能用途有限，甚至毫无帮助。它还可能使损坏检查耗时显著增加，并显著增加服务器上的资源消耗。

警告

当指定--parent-check或--rootdescend时，对 B-树索引执行的额外检查需要相对较强的关系级锁。这些检查也是唯一会阻塞INSERT、UPDATE和DELETE命令并发修改数据的检查。

下列命令行选项控制与服务器的连接：

-h hostname
--host=hostname

指定服务器所在机器的主机名。如果该值以斜杠开头，则将其用作 Unix 域套接字所在的目录。

-p port
--port=port

指定服务器监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。

-U
--username=username

连接时使用的用户名。

-w
--no-password

永不发出密码提示。如果服务器要求密码认证，而又无法通过其他方式获取密码，例如通过.pgpass文件，则连接尝试会失败。此选项可用于没有用户在场输入密码的批处理作业和脚本。

-W
--password

强制pg_amcheck在连接数据库前提示输入密码。

该选项并非必需，因为如果服务器要求密码认证，pg_amcheck会自动提示输入密码。不过，pg_amcheck会先浪费一次连接尝试，才能发现服务器需要密码。在某些场景下，值得显式指定-W，以避免这次额外的连接尝试。

--maintenance-db=dbname

指定一个数据库或连接字符串，用于确定待检查的数据库列表。如果既未使用--all，也未使用任何包含数据库名称匹配模式的选项，则不需要这样的连接，此选项也不起作用。否则，此选项值中除数据库名之外的任何连接字符串参数，在连接待检查的数据库时也会一并使用。如果省略此选项，默认值为postgres；若失败，则为template1。

还提供下列其他选项：

-e
--echo

将发送到服务器的所有 SQL 回显到标准输出。

-j num
--jobs=num

使用num个到服务器的并发连接，或者为每个待检查对象使用一个连接，以较小者为准。

默认使用单个连接。

-P
--progress

显示进度信息。进度信息包括已完成检查的关系数量及其总大小，也包括最终将要检查的关系总数及这些关系的估计大小。

-v
--verbose

打印更多消息。特别是，它会为每个正在检查的关系打印一条消息，并提高服务器错误显示的详细程度。

-V
--version

打印pg_amcheck版本并退出。

--install-missing
--install-missing=schema

安装检查数据库所需的任何缺失扩展。如果某个扩展尚未安装，则其对象将安装到给定的schema中；如果未指定，则安装到pg_catalog模式中。

目前，唯一必需的扩展是amcheck。

-?
--help

显示pg_amcheck命令行参数的帮助并退出。

环境

与大多数其他PostgreSQL工具一样，pg_amcheck也使用libpq支持的环境变量（见第 32.15 节）。

环境变量PG_COLOR指定是否在诊断消息中使用颜色。可能的值为always、auto和never。

注解

pg_amcheck旨在与PostgreSQL 14.0 及以后版本配合使用。

另见

amcheck

文档与源码

来源构建
版本
18.6
构建
https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹
ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 16 → 17: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 16
+++ PostgreSQL 17
@@ -144,6 +144,13 @@
         "--endblock= block"
       ],
       "signature": "--endblock= block"
+    },
+    {
+      "description": "For each index with unique constraint checked, verify that no more than one among duplicate entries is visible in the index using amcheck 's checkunique option.",
+      "names": [
+        "--checkunique"
+      ],
+      "signature": "--checkunique"
     },
     {
       "description": "For each index checked, verify the presence of all heap tuples as index tuples in the index using amcheck 's heapallindexed option.",

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

相关条目

导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 14 至 20；最早采样版本不一定是实际引入版本。