PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

19.17. 开发者调试选项 #

以下参数用于开发者测试, 不应当被用在生产数据库上。 不过,其中一些可以用来协助恢复严重受损的数据库。 因此,它们已被排除在示例 postgresql.conf 文件之外。 注意,其中许多参数需要特殊的源代码编译标志才能工作。

allow_in_place_tablespaces (boolean) #

当向 CREATE TABLESPACE 命令提供一个空的位置字符串时, 允许把表空间创建为 pg_tblspc 内部的目录。 这是为了允许测试主服务器与备用服务器运行在同一台机器上的 复制场景。 这样的目录很可能让那些期望在该位置只找到符号链接的备份工具 感到困惑。 只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

allow_system_table_mods (boolean) #

允许修改系统表的结构以及对系统表执行某些其他有风险的操作。 在其他情况下这些是不允许的,即便是超级用户也是如此。 不明智地使用这个设置可能导致无法挽回的数据丢失或严重破坏 数据库系统。 只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

backtrace_functions (string) #

这个参数包含一个以逗号分隔的 C 函数名列表。 如果抛出一个错误,并且错误发生所在的内部 C 函数的名字与列表中的某个值匹配, 那么一条回溯将与错误消息一起被写入服务器日志。 这可用于调试源代码的特定区域。

回溯支持并非在所有平台上都可用, 并且回溯的质量取决于编译选项。

只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

debug_copy_parse_plan_trees (boolean) #

启用这个会强制所有解析树和计划树都通过 copyObject(), 以便于发现 copyObject() 中的错误和遗漏。 默认值为 off。

这个参数只有在编译时定义了 DEBUG_NODE_TESTS_ENABLED 时才可用(使用 configure 选项 --enable-cassert 时会自动定义)。

debug_discard_caches (integer) #

当设置为 1 时, 每个系统目录缓存条目都会在第一个可能的机会被失效, 无论是否真的发生了会使它失效的事情。 系统目录的缓存实际上因此被禁用, 所以服务器将运行得极其缓慢。 更高的值会递归地运行缓存失效, 这甚至更慢,只对测试缓存逻辑本身有用。 默认值 0 选择正常的目录缓存行为。

当试图触发涉及并发目录更改、难以重现的 bug 时, 这个参数可能非常有帮助, 但除此之外很少需要它。 详情请参见源代码文件 inval.c 和 pg_config_manual.h。

只有当编译时定义了 DISCARD_CACHES_ENABLED 时才支持这个参数 (使用 configure 选项 --enable-cassert 时会自动定义)。 在生产构建中,它的值将总是 0, 把它设置为其他值的尝试会抛出错误。

debug_io_direct (string) #

请求内核使用 O_DIRECT (大多数类 Unix 系统)、 F_NOCACHE(macOS)或 FILE_FLAG_NO_BUFFERING(Windows) 来最小化对关系数据和 WAL 文件的缓存效果。

可以被设置为一个空字符串(默认值)以禁用直接 I/O 的使用, 或者设置为应当使用直接 I/O 的操作的以逗号分隔的列表。 有效选项是主数据文件用的 data、 WAL 文件用的 wal, 以及 WAL 文件初始分配时用的 wal_init。 这个参数只能在服务器启动时设置。

某些操作系统和文件系统不支持直接 I/O, 因此非默认的设置可能在启动时被拒绝或导致错误。

目前这个特性会降低性能, 并且只预期用于开发者测试。

debug_parallel_query (enum) #

出于测试目的,允许在没有预期性能收益的情形下使用并行查询。 debug_parallel_query 的允许值是 off(只在预期能改善性能时使用并行模式)、 on(对认为安全的所有查询强制并行查询) 和 regress(与 on 类似,但有额外的行为变化, 下文解释)。

更具体地说,把这个值设置为 on 会在任何看起来安全的查询计划顶部添加一个 Gather 节点, 这样查询就会在一个并行工作进程内运行。 即使并行工作进程不可用或无法被使用, 在并行查询上下文中会被禁止的操作(例如启动子事务) 也将被禁止,除非计划器认为这会导致查询失败。 如果设置了这个选项时出现失败或意外的结果, 查询使用的某些函数可能需要被标记为 PARALLEL UNSAFE (或者可能是 PARALLEL RESTRICTED)。

把这个值设置为 regress 具有与设置为 on 相同的所有效果, 加上一些为便于自动回归测试而设的额外效果。 通常,来自并行工作进程的消息会包括一个指示这一点的上下文行, 但 regress 设置会抑制这一行, 使输出与非并行执行时相同。 此外,由这个设置添加到计划中的 Gather 节点会在 EXPLAIN 输出中被隐藏, 这样输出就与把这个设置关闭时得到的一致。

debug_raw_expression_coverage_test (boolean) #

启用这个会强制 DML 语句的所有原始解析树都被 raw_expression_tree_walker() 扫描,以便于发现该函数中的错误和遗漏。 默认值为 off。

这个参数只有在编译时定义了 DEBUG_NODE_TESTS_ENABLED 时才可用(使用 configure 选项 --enable-cassert 时会自动定义)。

debug_write_read_parse_plan_trees (boolean) #

启用这个会强制所有解析树和计划树都经过 outfuncs.c/readfuncs.c, 以便于发现那些模块中的错误和遗漏。 默认值为 off。

这个参数只有在编译时定义了 DEBUG_NODE_TESTS_ENABLED 时才可用(使用 configure 选项 --enable-cassert 时会自动定义)。

ignore_system_indexes (boolean) #

读取系统表时忽略系统索引 (但在修改表时仍然更新索引)。 这在从受损的系统索引中恢复时很有用。 这个参数在会话开始之后不能被更改。

post_auth_delay (integer) #

新服务器进程启动时在完成身份验证过程之后延迟的时间量。 这是为了给开发者一个用调试器附加到服务器进程的机会。 如果这个值没有指定单位,则以秒为单位。 值为零(默认值)会禁用该延迟。 这个参数在会话开始之后不能被更改。

pre_auth_delay (integer) #

新服务器进程被 fork 出来之后、开始身份验证过程之前 延迟的时间量。 这是为了给开发者一个用调试器附加到服务器进程 来追查身份验证中不当行为的机会。 如果这个值没有指定单位,则以秒为单位。 值为零(默认值)会禁用该延迟。 这个参数只能在 postgresql.conf 文件中或服务器命令行上设置。

trace_notify (boolean) #

为 LISTEN 和 NOTIFY 命令产生大量的调试输出。 client_min_messages 或 log_min_messages 必须为 DEBUG1 或更低,才能分别把这些输出发送到客户端或服务器日志。

trace_sort (boolean) #

如果开启,发出关于排序操作期间资源使用情况的信息。

trace_locks (boolean) #

如果开启,发出关于锁使用的信息。 转储的信息包括锁操作的类型、锁的类型以及被锁定或解锁对象的 唯一标识符。 还包括此对象上已授予锁类型的位掩码, 以及此对象上正在等待的锁类型的位掩码。 对于每种锁类型,还会转储已授予锁和等待锁的数量以及总计。 日志文件输出的一个示例如下所示:

LOG:  LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1)
      grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
      wait(0) type(AccessShareLock)
LOG:  GrantLock: lock(0xb7acd844) id(24688,24696,0,0,0,1)
      grantMask(2) req(1,0,0,0,0,0,0)=1 grant(1,0,0,0,0,0,0)=1
      wait(0) type(AccessShareLock)
LOG:  UnGrantLock: updated: lock(0xb7acd844) id(24688,24696,0,0,0,1)
      grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
      wait(0) type(AccessShareLock)
LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
      grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0
      wait(0) type(INVALID)

被转储结构的细节可以在 src/include/storage/lock.h 中找到。

只有当 PostgreSQL 编译时定义了 LOCK_DEBUG 宏,这个参数才可用。

trace_lwlocks (boolean) #

如果开启,发出关于轻量级锁使用的信息。 轻量级锁主要用于提供对共享内存数据结构访问的互斥。

只有当 PostgreSQL 编译时定义了 LOCK_DEBUG 宏,这个参数才可用。

trace_userlocks (boolean) #

如果开启,发出关于用户锁使用的信息。 输出与 trace_locks 相同, 只是针对建议锁。

只有当 PostgreSQL 编译时定义了 LOCK_DEBUG 宏,这个参数才可用。

trace_lock_oidmin (integer) #

如果被设置,则不追踪 OID 低于此值的表上的锁 (用于避免对系统表产生输出)。

只有当 PostgreSQL 编译时定义了 LOCK_DEBUG 宏,这个参数才可用。

trace_lock_table (integer) #

无条件地追踪这个表(OID)上的锁。

只有当 PostgreSQL 编译时定义了 LOCK_DEBUG 宏,这个参数才可用。

debug_deadlocks (boolean) #

如果被设置,则在死锁超时发生时转储关于所有当前锁的信息。

只有当 PostgreSQL 编译时定义了 LOCK_DEBUG 宏,这个参数才可用。

log_btree_build_stats (boolean) #

如果被设置,则在各种 B-tree 操作上记录系统资源使用统计(内存和 CPU)。

只有当 PostgreSQL 编译时定义了 BTREE_BUILD_STATS 宏,这个参数才可用。

wal_consistency_checking (string) #

这个参数被预期用于检查 WAL 重做例程中的 bug。 启用之后,与 WAL 记录相关联而被修改的任何缓冲区的整页映像 都会被加入该记录。 如果该记录随后被重放,系统会首先应用每条记录, 然后测试被该记录修改的缓冲区是否与存储的映像匹配。 在某些情况下(例如提示位),微小的差异是可接受的, 并且会被忽略。 任何意外的差异都将导致致命错误,终止恢复。

这个设置的默认值是空字符串,它禁用该特性。 它可以被设置为 all 来检查所有记录,或者设置为一个以逗号分隔的资源管理器列表, 只检查源自那些资源管理器的记录。 目前,受支持的资源管理器是 heap、 heap2、btree、 hash、 gin、gist、 sequence、 spgist、brin 和 generic。 扩展可以定义额外的资源管理器。 只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

wal_debug (boolean) #

如果开启,发出与 WAL 相关的调试输出。 只有当 PostgreSQL 编译时定义了 WAL_DEBUG 宏,这个参数才可用。

ignore_checksum_failure (boolean) #

只有在启用了 数据校验和 时才有效。

在读取期间检测到校验和失败通常会导致 PostgreSQL 报告一个错误并中止当前事务。 把 ignore_checksum_failure 设置为 on 会让系统忽略该失败 (但仍然报告一个警告),并继续处理。 这种行为可能导致崩溃、传播或隐藏损坏, 或引发其他严重问题。 不过,如果块头部仍然完好, 它可能让你越过错误并检索表中可能仍然存在的未损坏元组。 如果头部已损坏, 即使启用了这个选项也会报告错误。 默认设置为 off。 只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

zero_damaged_pages (boolean) #

检测到损坏的页面头部通常会导致 PostgreSQL 报告一个错误并中止当前事务。 把 zero_damaged_pages 设置为 on 会让系统改为报告一个警告、 把内存中受损的页面清零,并继续处理。 这种行为会破坏数据, 即受损页面上的所有行。 然而,它确实能让你越过错误, 并从表中可能仍然存在的任何未受损页面中检索行。 如果损坏由硬件或软件错误导致, 它对恢复数据很有用。 通常,在你放弃从表的受损页面恢复数据的希望之前, 不应当设置它。 被清零的页面不会被强制写到磁盘, 因此建议在再次关闭这个参数之前重建表或索引。 默认设置为 off。 只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

ignore_invalid_pages (boolean) #

如果设置为 off(默认值), 在恢复期间检测到 WAL 记录引用了无效页面会导致 PostgreSQL 抛出 PANIC 级别的错误并中止恢复。 把 ignore_invalid_pages 设置为 on 会让系统忽略 WAL 记录中的无效页面引用 (但仍然报告一个警告),并继续恢复。 这种行为可能导致崩溃、数据丢失、 传播或隐藏损坏,或引发其他严重问题。 不过,它可能让你越过 PANIC 级别的错误、 完成恢复,并让服务器启动。 这个参数只能在服务器启动时设置。 它只在恢复期间或备用模式下有效。

jit_debugging_support (boolean) #

如果 LLVM 具有所需的功能, 会向 GDB 注册生成的函数。 这使调试更容易。 默认设置为 off。 只有超级用户和具有相应 SET 权限的用户可以在会话开始时更改这个参数, 并且它在会话内完全不能被更改。

jit_dump_bitcode (boolean) #

把生成的 LLVM IR 写出到文件系统, 位置在 data_directory 内。 这只对研究 JIT 实现的内部原理有用。 默认设置为 off。 只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

jit_expressions (boolean) #

决定当 JIT 编译被激活时(参见 Section 30.2)是否对表达式进行 JIT 编译。 默认值为 on。

jit_profiling_support (boolean) #

如果 LLVM 具有所需的功能, 会发出让 perf 能够分析 JIT 生成的函数所需的数据。 这会写出文件到 ~/.debug/jit/; 用户有责任在需要时进行清理。 默认设置为 off。 只有超级用户和具有相应 SET 权限的用户可以在会话开始时更改这个参数, 并且它在会话内完全不能被更改。

jit_tuple_deforming (boolean) #

决定当 JIT 编译被激活时(参见 Section 30.2) 是否对元组解构进行 JIT 编译。 默认值为 on。

remove_temp_files_after_crash (boolean) #

当设置为 on(这是默认值)时, PostgreSQL 会在后端崩溃之后自动移除临时文件。 如果被禁用,这些文件将被保留, 可以用于例如调试。 不过,反复崩溃可能导致无用文件的累积。 这个参数只能在 postgresql.conf 文件中或服务器命令行上 设置。

send_abort_for_crash (boolean) #

默认情况下,在后端崩溃之后,postmaster 会通过向剩余的子进程发送 SIGQUIT 信号来停止它们, 这允许它们或多或少体面地退出。 当这个选项被设置为 on 时, 会改为发送 SIGABRT。 这通常会导致为每个这样的子进程产生一个核心转储文件。 这对于调查崩溃之后其他进程的状态会很方便。 在反复崩溃的情况下它也可能消耗大量磁盘空间, 因此不要在你没有仔细监控的系统上启用它。 注意,目前没有任何自动清理核心文件的支持。 这个参数只能在 postgresql.conf 文件中或服务器命令行上 设置。

send_abort_for_kill (boolean) #

默认情况下,在尝试用 SIGQUIT 停止一个子进程之后,postmaster 会等待五秒,然后发送 SIGKILL 强制立即终止。 当这个选项被设置为 on 时, 会发送 SIGABRT 而不是 SIGKILL。 这通常会导致为每个这样的子进程产生一个核心转储文件。 这对于调查“卡住”的子进程的状态会很方便。 在反复崩溃的情况下它也可能消耗大量磁盘空间, 因此不要在你没有仔细监控的系统上启用它。 注意,目前没有任何自动清理核心文件的支持。 这个参数只能在 postgresql.conf 文件中或服务器命令行上 设置。

debug_logical_replication_streaming (enum) #

允许的值是 buffered 和 immediate。默认值为 buffered。 这个参数被预期用于测试大事务的逻辑解码和复制。 debug_logical_replication_streaming 对发布者和订阅者的效果不同:

在发布者一侧, debug_logical_replication_streaming 允许在逻辑解码中立即流式传输或序列化变更。 当设置为 immediate 时, 如果 CREATE SUBSCRIPTION 的 streaming 选项被启用,则流式传输每个变更, 否则序列化每个变更。 当设置为 buffered 时, 解码将在达到 logical_decoding_work_mem 时流式传输或序列化变更。

在订阅者一侧,如果 streaming 选项被设置为 parallel, debug_logical_replication_streaming 可用于指示领导者应用工作进程把变更发送到共享内存队列, 或把所有变更序列化到文件。 当设置为 buffered 时, 领导者通过共享内存队列把变更发送给并行应用工作进程。 当设置为 immediate 时, 领导者把所有变更序列化到文件, 并通知并行应用工作进程在事务结束时读取并应用它们。