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 也可以是一个 connection string。
下列命令行选项控制要检查的内容:
-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* 来选择匹配 myschema* 且位于匹配 mydb* 的数据库中的那些模式。
-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 表(如果有的话)也将被检查,即使它没有被 --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 指定一个数据库或 connection string,用于发现待检查数据库的列表。如果既未使用 --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 命令行参数的帮助信息,然后退出。
pg_amcheck 与大多数其他 PostgreSQL 工具一样,也使用 libpq 支持的环境变量(参见 Section 32.15)。
环境变量 PG_COLOR 指定是否在诊断消息中使用颜色。可能的值为 always、auto 和 never。
pg_amcheck 被设计为与 PostgreSQL 14.0 及更高版本一起工作。