跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

参数条目

PostgreSQL 9.0–19 Beta 3 中曾出现过的 447 个核心配置参数完整档案。

这里收录 PG9.0–19 Beta 3 实测并集中的 447 个核心 GUC：PG19 Beta 3 仍在档 419 个，期间移除 28 个，PG9.0 之后首次出现 240 个。每页均包含身份、生命周期、默认值历史、机制、调优建议、Pigsty 取值、常见坑、关联条目与来源。

分类

分类 参数数
客户端连接默认 47
连接与认证 45
自定义选项 1
开发者选项 27
错误处理 4
文件位置 7
锁管理 5
预设选项 24
查询调优 55
复制 33
报告与日志 47
资源使用 51
统计信息 14
清理与冻结 34
版本与平台兼容 12
预写日志 41

默认值曾变化

以下参数的 boot_val 或 unit 在 PG9.0–19 Beta 3 间发生过变化：

TimeZone · autovacuum_vacuum_cost_delay · checkpoint_completion_target · default_toast_compression · effective_cache_size · effective_io_concurrency · extra_float_digits · hash_mem_multiplier · hot_standby · jit · krb_server_keyfile · log_autovacuum_min_duration · log_checkpoints · log_connections · log_directory · log_line_prefix · log_lock_waits · log_timezone · maintenance_io_concurrency · maintenance_work_mem · max_locks_per_transaction · max_parallel_workers_per_gather · max_replication_slots · max_wal_senders · max_wal_size · min_wal_size · password_encryption · search_path · server_version · server_version_num · shared_buffers · ssl_ciphers · ssl_min_protocol_version · standard_conforming_strings · timezone_abbreviations · track_activity_query_size · transaction_isolation · vacuum_buffer_usage_limit · vacuum_cost_page_miss · wal_buffers · wal_level · wal_segment_size · wal_sender_delay · work_mem

已移除参数

以下参数在 PG19 Beta 3 前退出 pg_settings 并保留历史档案：

checkpoint_segments · custom_variable_classes · db_user_namespace · default_with_oids · escape_string_warning · extension_destdir · force_parallel_mode · io_workers · krb_srvname · lc_collate · lc_ctype · min_parallel_relation_size · old_snapshot_threshold · operator_precedence_warning · promote_trigger_file · replacement_sort_tuples · replication_timeout · silent_mode · sql_inheritance · ssl_ecdh_curve · ssl_renegotiation_limit · stats_temp_directory · trace_recovery_messages · unix_socket_directory · vacuum_cleanup_index_scale_factor · vacuum_defer_cleanup_age · wal_keep_segments · wal_sender_delay

1 - 客户端连接默认

Client Connection Defaults 分类下的 47 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

1.1 - DateStyle

DateStyle 定义日期和时间值的显示格式。
说明

Fact — 官方简述译文：设置日期和时间值的显示格式。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值ISO, MDY
ISO, MDY

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 ISO, MDY — ISO, MDY

机制详解

DateStyle：设置日期和时间值的显示格式。该值包含两个相互独立的部分：输出样式与 DMY/MDY/YMD 字段顺序；后者也决定如何解释有歧义的输入。

DateStyle 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 DateStyle 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 DateStyle；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 DateStyle 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 DateStyle，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 在意外的 MDY/DMY 顺序下解析 01/02/03 等有歧义值。

关联参数

IntervalStyle · TimeZone · lc_time · timezone_abbreviations · log_timezone

参考资料

1.2 - IntervalStyle

IntervalStyle 定义 interval 值的显示格式。
说明

Fact — 官方简述译文：设置 interval 值的显示格式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值postgres, postgres_verbose, sql_standard, iso_8601
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值postgres
postgres

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 postgres — postgres

机制详解

IntervalStyle：设置 interval 值的显示格式。四种模式分别面向 PostgreSQL 兼容格式、详细格式、SQL 标准字面量与 ISO 8601；它也会改变有歧义 interval 输入的解释方式。

IntervalStyle 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 IntervalStyle 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 IntervalStyle；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 IntervalStyle 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 IntervalStyle，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 IntervalStyle。

关联参数

DateStyle · TimeZone · lc_time · timezone_abbreviations · log_timezone

参考资料

1.3 - TimeZone

TimeZone 定义用于显示和解释时间戳的时区。
说明

Fact — 官方简述译文：设置用于显示和解释时间戳的时区。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值GMT
GMT

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 UNKNOWN — UNKNOWN
PG9.1 — — not set
PG9.2–19 Beta 3 GMT — GMT

机制详解

TimeZone：设置用于显示和解释时间戳的时区。它影响 timestamptz 的显示及未显式带时区的时间戳输入解释，但已存储的时间点本身不随显示时区改变。

TimeZone 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 TimeZone 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 TimeZone；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 TimeZone 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 TimeZone，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 比较显示后的时间戳，却未保留原始时间点与显式时区上下文。

关联参数

DateStyle · IntervalStyle · lc_time · timezone_abbreviations · log_timezone

参考资料

1.4 - bytea_output

bytea_output 定义 bytea 的输出格式。
说明

Fact — 官方简述译文：设置 bytea 的输出格式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值escape, hex
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值hex
hex

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 hex — hex

机制详解

bytea_output：设置 bytea 的输出格式。该选择只影响文本输出；无论如何设置，bytea 输入都接受 hex 与 escape 两种语法。

bytea_output 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 bytea_output 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 bytea_output；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 bytea_output 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 bytea_output，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 bytea_output。

关联参数

extra_float_digits · xmlbinary · xmloption · client_encoding · DateStyle

参考资料

1.5 - check_function_bodies

check_function_bodies 是 PostgreSQL 中用于在 CREATE FUNCTION 和 CREATE PROCEDURE 时检查例程体的参数。
说明

Fact — 官方简述译文：在 CREATE FUNCTION 和 CREATE PROCEDURE 时检查例程体。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

check_function_bodies：在 CREATE FUNCTION 和 CREATE PROCEDURE 时检查例程体。关闭后会跳过创建时验证，适合转储恢复与前向引用，但也会把错误推迟到实际执行时暴露。

check_function_bodies 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 普通迁移保持 check_function_bodies 为 on，让无效例程体尽早失败；只在受控转储恢复或前向引用序列中临时关闭，并立即恢复。
OLAP 分析例程同样需要创建时验证；批量部署不是隐藏语法或依赖错误的理由。
小规格 保持 on；验证成本发生在例程创建时，优于生产执行期间才发现函数损坏。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 check_function_bodies，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 check_function_bodies。

关联参数

default_table_access_method · default_tablespace · temp_tablespaces · default_toast_compression · maintenance_work_mem

参考资料

1.6 - client_encoding

client_encoding 定义客户端字符集编码。
说明

Fact — 官方简述译文：设置客户端字符集编码。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值SQL_ASCII
SQL_ASCII

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 SQL_ASCII — SQL_ASCII

机制详解

client_encoding：设置客户端字符集编码。若存在对应转换，PostgreSQL 会在该编码与数据库编码之间转换文本；SQL_ASCII 并不代表真实字符集，而会绕过有价值的校验。

client_encoding 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 client_encoding 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 client_encoding；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 client_encoding 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 client_encoding，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 把 SQL_ASCII 当作真实编码，允许无效字节序列穿过客户端边界。

关联参数

lc_messages · lc_monetary · lc_numeric · lc_time · default_text_search_config

参考资料

1.7 - client_min_messages

client_min_messages 定义发送给客户端的消息级别。
说明

Fact — 官方简述译文：设置发送给客户端的消息级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值notice
notice

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 notice — notice

机制详解

client_min_messages：设置发送给客户端的消息级别。该阈值控制返回客户端的消息，而非写入服务器日志的消息；INFO 消息不受此阈值抑制。

client_min_messages 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它影响客户端协议中的诊断消息流，而 log_min_messages 与 log_min_error_statement 独立控制服务器端记录；INFO 是始终发送的特殊级别。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按应用诊断契约设置 client_min_messages。保留可操作告警，并按角色或会话调整阈值，而不是让整个集群静音。
OLAP 分析与交互用户可能希望看到 NOTICE，但批处理管线应明确选择可解析的消息，避免把通知当作结果行。
小规格 除非实测客户端消息成为问题，否则保留默认 NOTICE；抑制消息不会显著增加服务器容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 client_min_messages，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 照搬 log_min_messages 的严重级别理解，忽略客户端顺序对 LOG 的处理不同且始终发送 INFO。
  • 全局抑制警告，隐藏应用本应展示的弃用信息或运维指引。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 client_min_messages。

关联参数

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

参考资料

1.8 - createrole_self_grant

createrole_self_grant 定义 CREATEROLE 用户是否将新建角色自动授予自身，以及使用哪些授权选项。
说明

Fact — 官方简述译文：设置 CREATEROLE 用户是否将新建角色自动授予自身，以及使用哪些授权选项。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 e5b8a4c098ad — Add new GUC createrole_self_grant.
提交日期 2023-01-10
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 "" — empty string

机制详解

createrole_self_grant：设置 CREATEROLE 用户是否将新建角色自动授予自身，以及使用哪些授权选项。可选项为 set、inherit 或二者；它自动完成创建者凭 ADMIN OPTION 本可执行的授权，对超级用户没有实际影响。

createrole_self_grant 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 createrole_self_grant 当作正确性或安全控制，而非吞吐旋钮。严格限制 SET 权限，并由可信的角色或应用策略建立取值。
OLAP 若 createrole_self_grant 必须不同，使用专用分析角色，并验证导出、触发器、策略与名称解析仍保持数据正确性。
小规格 除非有文档化的修复或兼容流程，否则保持 createrole_self_grant 的安全默认值；临时变化应留痕并自动恢复。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 createrole_self_grant，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 createrole_self_grant。

关联参数

search_path · row_security · session_replication_role · event_triggers · restrict_nonsystem_relation_kind

参考资料

1.9 - default_table_access_method

default_table_access_method 定义新建表默认使用的表访问方法。
说明

Fact — 官方简述译文：设置新建表默认使用的表访问方法。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值heap
heap

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 8586bf7ed888 — tableam: introduce table AM infrastructure.
提交日期 2019-03-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 heap — heap

机制详解

default_table_access_method：设置新建表默认使用的表访问方法。仅当 CREATE TABLE、CREATE MATERIALIZED VIEW 或 SELECT INTO 未指定访问方法时才会读取它；既有关系不会改变。

default_table_access_method 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非替代表访问方法已通过并发、WAL、备份、复制、升级与工具链测试，否则保持 heap；关键 DDL 应显式写明选择。
OLAP 以代表性扫描、装载、更新和维护压测替代方案，再限定到专用对象，不要过早改变默认值。
小规格 使用 heap；替代访问方法会增加运维依赖，并不是有限硬件的通用补救。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_table_access_method，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_table_access_method。

关联参数

default_tablespace · temp_tablespaces · default_toast_compression · check_function_bodies · maintenance_work_mem

参考资料

1.10 - default_tablespace

default_tablespace 定义创建表和索引时使用的默认表空间。
说明

Fact — 官方简述译文：设置创建表和索引时使用的默认表空间。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

default_tablespace：设置创建表和索引时使用的默认表空间。它选择新建持久表和索引的位置，不用于临时对象或 CREATE DATABASE；某些配置上下文中的无效名称会回退到数据库默认表空间。

default_tablespace 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 default_tablespace 与模式管理策略一致，并在迁移中显式写出重要存储选择；任何物理布局变化都应用接近生产的写负载压测。
OLAP 为批量对象与高溢写作业有意识地使用 default_tablespace，采用前核对 I/O 放置、压缩支持与运维工具。
小规格 除非节点有经验证的替代存储路径或恢复需求，否则保留 default_tablespace 上游默认值；简单配置更少带来恢复意外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_tablespace，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_tablespace。

关联参数

default_table_access_method · temp_tablespaces · default_toast_compression · check_function_bodies · maintenance_work_mem

参考资料

1.11 - default_text_search_config

default_text_search_config 定义默认的文本搜索配置。
说明

Fact — 官方简述译文：设置默认的文本搜索配置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值pg_catalog.simple
pg_catalog.simple

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 pg_catalog.simple — pg_catalog.simple

机制详解

default_text_search_config：设置默认的文本搜索配置。只有调用方未显式指定配置时，文本搜索函数才使用它；initdb 可能选择与区域设置匹配的配置，而非内置 simple。

default_text_search_config 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按语言域与应用角色设置 default_text_search_config，或在长期查询中显式传入配置；在每个副本核对词典与软件包。
OLAP 在可复现索引与报表作业中固定配置，避免区域变化静默改变分词或排名。
小规格 除非需要语言感知搜索，否则使用 pg_catalog.simple 或 initdb 选择的区域配置；额外词典增加维护而非免费提升质量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_text_search_config，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_text_search_config。

关联参数

client_encoding · lc_messages · lc_monetary · lc_numeric · lc_time

参考资料

1.12 - default_toast_compression

default_toast_compression 定义可压缩值默认使用的压缩方法。
说明

Fact — 官方简述译文：设置可压缩值默认使用的压缩方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值pglz, lz4
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值lz4
lz4

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 bbe0a81db69b — Allow configurable LZ4 TOAST compression.
提交日期 2021-03-19
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–18 pglz — pglz
PG19 Beta 3 lz4 — lz4

机制详解

default_toast_compression：设置可压缩值默认使用的压缩方法。它为新写入的可压缩值选择 pglz，或在编译支持时选择 lz4；列级 COMPRESSION 子句优先于会话默认值。

default_toast_compression 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用代表性宽值、更新率、CPU、WAL 与存储压测 pglz 和 lz4；重要模式应优先显式指定列 COMPRESSION，而非依赖意外的会话默认值。
OLAP 构建支持时 LZ4 可能更偏向快速压缩与解压，但改变新写入策略前必须测量真实可压缩性与扫描行为。
小规格 除非 CPU 与空间测量及软件包支持证明 lz4 合适，否则保留 pglz；改变默认值不会重压缩既有值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_toast_compression，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_toast_compression。

关联参数

default_table_access_method · default_tablespace · temp_tablespaces · check_function_bodies · maintenance_work_mem

参考资料

1.13 - default_transaction_deferrable

default_transaction_deferrable 定义新事务默认是否可延迟。
说明

Fact — 官方简述译文：设置新事务默认是否可延迟。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 dafaa3efb75c — Implement genuine serializable isolation level.
提交日期 2011-02-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

default_transaction_deferrable：设置新事务默认是否可延迟。该默认值只对只读可串行化事务有意义：事务可等待安全快照，随后避免序列化失败。

default_transaction_deferrable 属于 USER 上下文，可按角色、数据库或会话设置；新事务开始时才复制该值，因此不会重写已经进行中的事务。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 default_transaction_deferrable。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 default_transaction_deferrable 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_transaction_deferrable，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_transaction_deferrable。

关联参数

default_transaction_isolation · transaction_isolation · default_transaction_read_only · transaction_read_only · transaction_deferrable

参考资料

1.14 - default_transaction_isolation

default_transaction_isolation 定义每个新事务的默认隔离级别。
说明

Fact — 官方简述译文：设置每个新事务的默认隔离级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值serializable, repeatable read, read committed, read uncommitted
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值read committed
read committed

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 read committed — read committed

机制详解

default_transaction_isolation：设置每个新事务的默认隔离级别。每个事务开始时，PostgreSQL 会把该值复制到 transaction_isolation；它改变一致性语义，而不仅是性能。

default_transaction_isolation 属于 USER 上下文，可按角色、数据库或会话设置；新事务开始时才复制该值，因此不会重写已经进行中的事务。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 default_transaction_isolation。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 default_transaction_isolation 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_transaction_isolation，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_transaction_isolation。

关联参数

transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

1.15 - default_transaction_read_only

default_transaction_read_only 定义新事务默认是否只读。
说明

Fact — 官方简述译文：设置新事务默认是否只读。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

default_transaction_read_only：设置新事务默认是否只读。每个事务继承该默认值，但只读模式仍允许修改临时表，也不能替代备用库或权限层面的强制控制。

default_transaction_read_only 属于 USER 上下文，可按角色、数据库或会话设置；新事务开始时才复制该值，因此不会重写已经进行中的事务。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 default_transaction_read_only。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 default_transaction_read_only 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_transaction_read_only，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_transaction_read_only。

关联参数

default_transaction_isolation · transaction_isolation · transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

1.16 - dynamic_library_path

dynamic_library_path 定义动态可加载模块的搜索路径。
说明

Fact — 官方简述译文：设置动态可加载模块的搜索路径。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Other Defaults
上游分类
最后 boot 值 值$libdir
$libdir

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 $libdir — $libdir

机制详解

dynamic_library_path：设置动态可加载模块的搜索路径。只有模块名不含目录部分时才使用该搜索路径；$libdir 指向 PostgreSQL 版本对应的库目录。

dynamic_library_path 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 dynamic_library_path 限制在管理员控制且版本匹配的目录，并保留 $libdir；只有部署与回滚显式管理时才使用绝对模块路径。
OLAP 只有经过评审的分析扩展软件包在所有故障转移目标完全一致时才新增搜索目录。
小规格 保持 $libdir；扩大本地代码搜索路径没有容量收益，只会增加打包与信任风险。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 dynamic_library_path，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 dynamic_library_path。

关联参数

shared_preload_libraries · session_preload_libraries · local_preload_libraries · jit_provider · extension_control_path

参考资料

1.17 - event_triggers

event_triggers 是控制是否启用事件触发器的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用事件触发器。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 7750fefdb2b8 — Add GUC for temporarily disabling event triggers
提交日期 2023-09-25
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 on — on

机制详解

event_triggers：启用事件触发器。该开关会整体禁用所有事件触发器，用于紧急修复；它不是选择性触发策略，并要求较高的 SET 权限。

event_triggers 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应调优 event_triggers，也不应把关闭作为常态。只能在受控修复会话中临时关闭，定位故障触发器后立即恢复。
OLAP 保持事件触发器启用；只有文档化批量装载流程评审过所有丢失的审计或 DDL 副作用后才可例外。
小规格 保持默认 on；禁用事件触发器不会节省有意义的资源，却可能静默绕过控制。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 event_triggers，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 event_triggers。

关联参数

search_path · row_security · session_replication_role · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

1.18 - extension_control_path

extension_control_path 定义扩展控制文件的搜索路径。
说明

Fact — 官方简述译文：设置扩展控制文件的搜索路径。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Other Defaults
上游分类
最后 boot 值 值$system
$system

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 4f7f7b037585 — extension_control_path
提交日期 2025-03-19
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 $system — $system

机制详解

extension_control_path：设置扩展控制文件的搜索路径。PostgreSQL 用该路径查找扩展的主控制文件，随后从找到主文件的同一目录加载脚本与次级控制文件。

extension_control_path 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 $system 优先，只加入管理员控制且控制文件、脚本、本地库、升级与回滚共同版本化的扩展仓库。
OLAP 只有为主库与备用库软件包一致分发经评审扩展目录时才使用独立路径，并测试 CREATE EXTENSION 与每条升级边。
小规格 保持 $system；额外控制文件根目录不会提升容量，却让扩展来源与灾难恢复更难审计。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 extension_control_path，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 extension_control_path。

关联参数

shared_preload_libraries · session_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider

参考资料

1.19 - extra_float_digits

extra_float_digits 定义浮点值文本输出所使用的数字位数。
说明

Fact — 官方简述译文：设置浮点值文本输出所使用的数字位数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值-15 – 3
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–11 0 — 0
PG12–19 Beta 3 1 — 1

机制详解

extra_float_digits：设置浮点值文本输出所使用的数字位数。自 PostgreSQL 12 起，正值选择最短精确输出；零或负值选择旧式舍入输出，可能失去往返精度。

extra_float_digits 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 extra_float_digits 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 extra_float_digits；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 extra_float_digits 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 extra_float_digits，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 沿用 PostgreSQL 12 之前的理解，忽略正值现已选择最短精确输出。

关联参数

bytea_output · xmlbinary · xmloption · client_encoding · DateStyle

参考资料

1.20 - gin_fuzzy_search_limit

gin_fuzzy_search_limit 定义 GIN 精确搜索允许返回的最大结果数。
说明

Fact — 官方简述译文：设置 GIN 精确搜索允许返回的最大结果数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Other Defaults
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

gin_fuzzy_search_limit：设置 GIN 精确搜索允许返回的最大结果数。正值会让宽泛的 GIN 搜索随机返回匹配子集，以结果完整性换取工作量上限；零保留精确结果。

gin_fuzzy_search_limit 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

GIN 行为还取决于索引级存储参数、工作或维护内存、autovacuum，以及被索引值与谓词的形态。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在测量到相关 GIN 维护或搜索路径后才调整 gin_fuzzy_search_limit。若只是单个索引特殊，优先使用索引级覆盖而非全局修改。
OLAP 对批量装载或宽泛搜索，应联合测试 gin_fuzzy_search_limit 对摄取延迟、清理尖峰、结果完整性与维护窗口的影响。
小规格 不要仅因达到默认值就调高 gin_fuzzy_search_limit；应约束内存与 I/O 突发，且除非明确接受近似结果，否则保持精确查询语义。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 gin_fuzzy_search_limit，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 为修复单个特殊索引而修改集群级 GIN 参数，而非使用其存储参数。
  • 调优时忽略清理延迟、I/O 突发、autovacuum 联动或结果完整性。
  • 设置正值却未告知调用方，精确搜索可能只返回不完整的随机子集。

关联参数

gin_pending_list_limit · maintenance_work_mem · work_mem · vacuum_cleanup_index_scale_factor · autovacuum_work_mem

参考资料

1.21 - gin_pending_list_limit

gin_pending_list_limit 定义 GIN 索引待处理列表的最大大小。
说明

Fact — 官方简述译文：设置 GIN 索引待处理列表的最大大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值4096
4 MiB

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 c291503b1c82 — Rename pending_list_cleanup_size to gin_pending_list_limit.
提交日期 2014-11-13
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 4096 kB 4 MiB

机制详解

gin_pending_list_limit：设置 GIN 索引待处理列表的最大大小。当 GIN 索引启用 fastupdate 时，超过该上限会触发待处理列表批量并入主索引；可用索引级存储参数覆盖。

gin_pending_list_limit 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

GIN 行为还取决于索引级存储参数、工作或维护内存、autovacuum，以及被索引值与谓词的形态。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在测量到相关 GIN 维护或搜索路径后才调整 gin_pending_list_limit。若只是单个索引特殊，优先使用索引级覆盖而非全局修改。
OLAP 对批量装载或宽泛搜索，应联合测试 gin_pending_list_limit 对摄取延迟、清理尖峰、结果完整性与维护窗口的影响。
小规格 不要仅因达到默认值就调高 gin_pending_list_limit；应约束内存与 I/O 突发，且除非明确接受近似结果，否则保持精确查询语义。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 未修改；OLAP: PG9.5–19 Beta 3 未修改；CRIT: PG9.5–19 Beta 3 未修改；TINY: PG9.5–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 gin_pending_list_limit，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 为修复单个特殊索引而修改集群级 GIN 参数，而非使用其存储参数。
  • 调优时忽略清理延迟、I/O 突发、autovacuum 联动或结果完整性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 gin_pending_list_limit。

关联参数

gin_fuzzy_search_limit · maintenance_work_mem · work_mem · vacuum_cleanup_index_scale_factor · autovacuum_work_mem

参考资料

1.22 - icu_validation_level

icu_validation_level 定义报告无效 ICU 区域设置字符串所用的消息级别。
说明

Fact — 官方简述译文：设置报告无效 ICU 区域设置字符串所用的消息级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值disabled, debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值warning
warning

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 1671f990dd66 — Validate ICU locales.
提交日期 2023-03-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 warning — warning

机制详解

icu_validation_level：设置报告无效 ICU 区域设置字符串所用的消息级别。该参数改变无效 ICU 区域标识符的报告方式，既可关闭报告，也可提升为错误。

icu_validation_level 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 icu_validation_level 为 WARNING，让无效区域标识可见；只有迁移门禁已清理既有输入时才提升为 ERROR。
OLAP 分析对象创建采用同一验证策略；降低级别可能让不一致区域元数据扩散到可复现作业。
小规格 不要为容量而调节；除非受控兼容问题需要临时降低报告级别，否则保持 WARNING。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 icu_validation_level，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 icu_validation_level。

关联参数

client_encoding · lc_messages · lc_monetary · lc_numeric · lc_time · default_text_search_config

参考资料

1.23 - idle_in_transaction_session_timeout

idle_in_transaction_session_timeout 定义事务内两次查询之间允许空闲的最长时间。
说明

Fact — 官方简述译文：设置事务内两次查询之间允许空闲的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 c6dda1f48e57 — Add idle_in_transaction_session_timeout.
提交日期 2016-03-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 0 ms 0 ms

机制详解

idle_in_transaction_session_timeout：设置事务内两次查询之间允许空闲的最长时间。它终止在打开事务中空闲的会话，释放可能阻碍 vacuum 清理并导致膨胀的锁与旧快照。

idle_in_transaction_session_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 idle_in_transaction_session_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 idle_in_transaction_session_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 idle_in_transaction_session_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 10min 不同于 boot 值 10min
OLAP 0 等于 boot 值 0
CRIT 1min 不同于 boot 值 1min
TINY 10min 不同于 boot 值 10min
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 10min (dcs)；OLAP: PG9.6–19 Beta 3 = 0 (dcs)；CRIT: PG9.6–19 Beta 3 = 1min (dcs)；TINY: PG9.6–19 Beta 3 = 10min (dcs)。 建议（待人工复核）——编辑推断：模板限制被遗弃的打开事务，对 CRIT 使用更严格上限，并为刻意较长的 OLAP 分析事务保留无限；各负载仍需复核连接池与重试行为。

常见坑

  • 只在一个会话中修改 idle_in_transaction_session_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 idle_in_transaction_session_timeout。

关联参数

statement_timeout · lock_timeout · transaction_timeout · idle_session_timeout · deadlock_timeout

参考资料

1.24 - idle_session_timeout

idle_session_timeout 定义不在事务中时两次查询之间允许空闲的最长时间。
说明

Fact — 官方简述译文：设置不在事务中时两次查询之间允许空闲的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 9877374bef76 — Add idle_session_timeout.
提交日期 2021-01-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 0 ms 0 ms

机制详解

idle_session_timeout：设置不在事务中时两次查询之间允许空闲的最长时间。它关闭事务外空闲的会话；这类会话通常成本不高，而连接池可能无法妥善处理服务器端意外断连。

idle_session_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 idle_session_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 idle_session_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 idle_session_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 idle_session_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 idle_session_timeout。

关联参数

statement_timeout · lock_timeout · transaction_timeout · idle_in_transaction_session_timeout · deadlock_timeout

参考资料

1.25 - jit_provider

jit_provider 定义要使用的 JIT 提供程序。
说明

Fact — 官方简述译文：设置要使用的 JIT 提供程序。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值llvmjit
llvmjit

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 432bb9e04da4 — Basic JIT provider and error handling infrastructure.
提交日期 2018-03-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 llvmjit — llvmjit

机制详解

jit_provider：设置要使用的 JIT 提供程序。指定的提供程序实现 PostgreSQL JIT，且必须二进制兼容；更换提供程序需要重启服务器。

jit_provider 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把更换 jit_provider 当作常规调优；软件包支持时保持 llvmjit，并通过 jit 及成本阈值控制是否执行 JIT。
OLAP 只有在代表性编译时间、执行速度、内存、软件包兼容与重启测试后才评估提供程序；提供程序选择次于 JIT 阈值。
小规格 保持软件包提供的实现，通常应控制是否使用 JIT 而非替换实现；提供程序缺失可能破坏启动或 JIT 执行。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 jit_provider，而它实际需要受控重启服务器。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 jit_provider。

关联参数

shared_preload_libraries · session_preload_libraries · local_preload_libraries · dynamic_library_path · extension_control_path

参考资料

1.26 - lc_messages

lc_messages 定义显示消息所使用的语言。
说明

Fact — 官方简述译文：设置显示消息所使用的语言。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

lc_messages：设置显示消息所使用的语言。可接受的区域名称与可用翻译取决于操作系统和构建；空值继承服务器运行环境。

lc_messages 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_messages 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_messages；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_messages 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_messages，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_messages。

关联参数

client_encoding · lc_monetary · lc_numeric · lc_time · default_text_search_config

参考资料

1.27 - lc_monetary

lc_monetary 定义格式化货币金额所使用的区域设置。
说明

Fact — 官方简述译文：设置格式化货币金额所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 C — C

机制详解

lc_monetary：设置格式化货币金额所使用的区域设置。它影响 to_char 等货币格式化函数，而不会改变 money 或 numeric 列中存储的数值。

lc_monetary 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_monetary 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_monetary；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_monetary 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_monetary，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_monetary。

关联参数

client_encoding · lc_messages · lc_numeric · lc_time · default_text_search_config

参考资料

1.28 - lc_numeric

lc_numeric 定义格式化数字所使用的区域设置。
说明

Fact — 官方简述译文：设置格式化数字所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 C — C

机制详解

lc_numeric：设置格式化数字所使用的区域设置。它影响小数符号与分组符号等区域敏感数字格式，而普通 SQL 数字字面量仍遵循 SQL 语法。

lc_numeric 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_numeric 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_numeric；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_numeric 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_numeric，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_numeric。

关联参数

client_encoding · lc_messages · lc_monetary · lc_time · default_text_search_config

参考资料

1.29 - lc_time

lc_time 定义格式化日期和时间所使用的区域设置。
说明

Fact — 官方简述译文：设置格式化日期和时间所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 C — C

机制详解

lc_time：设置格式化日期和时间所使用的区域设置。它控制格式化函数所用的区域敏感名称与布局；DateStyle 与 TimeZone 仍是独立控制项。

lc_time 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_time 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_time；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_time 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_time，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_time。

关联参数

DateStyle · IntervalStyle · TimeZone · timezone_abbreviations · log_timezone

参考资料

1.30 - local_preload_libraries

local_preload_libraries 声明每个后端可由非特权用户预加载的共享库。
说明

Fact — 官方简述译文：列出每个后端可由非特权用户预加载的共享库。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

local_preload_libraries：列出每个后端可由非特权用户预加载的共享库。非特权用户只能指定安装在 PostgreSQL plugins 子目录中的库，因此软件包放置本身构成安全边界。

虽然 local_preload_libraries 无需重启服务器即可配置，但只有新后端启动时才处理库列表；在既有连接中修改不会卸载或追溯加载模块。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应通用调优 local_preload_libraries。只加载或暴露经过评审的功能所需模块，验证二进制兼容性，并在上线前演练故障恢复。
OLAP 只有扩展或 JIT 需求经过测量后才使用 local_preload_libraries，并计入后端启动、常驻内存与连接池下的行为。
小规格 尽量精简 local_preload_libraries。模块缺失或不兼容可能拒绝连接或阻止启动，每个预加载库也会占用稀缺地址空间或内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 local_preload_libraries，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 local_preload_libraries。

关联参数

shared_preload_libraries · session_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

参考资料

1.31 - lock_timeout

lock_timeout 定义每次等待锁所允许的最长时间。
说明

Fact — 官方简述译文：设置每次等待锁所允许的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 d43837d03067 — Add lock_timeout configuration parameter.
提交日期 2013-03-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 0 ms 0 ms

机制详解

lock_timeout：设置每次等待锁所允许的最长时间。计时对每次锁获取分别生效，而非限制语句总时长；相同或更短的 statement_timeout 会先触发。

lock_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 lock_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 lock_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 lock_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lock_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lock_timeout。

关联参数

statement_timeout · transaction_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

参考资料

1.32 - restrict_nonsystem_relation_kind

restrict_nonsystem_relation_kind 是 PostgreSQL 中用于禁止访问指定类别的非系统关系的参数。
说明

Fact — 官方简述译文：禁止访问指定类别的非系统关系。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 79c7a7e29695 — Restrict accesses to non-system views and foreign tables during pg_dump.
提交日期 2024-08-05
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

restrict_nonsystem_relation_kind：禁止访问指定类别的非系统关系。目前支持 view 与 foreign-table；PostgreSQL 将其用作特殊会话的安全边界，而不是通用 SQL 授权机制。

restrict_nonsystem_relation_kind 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应把 restrict_nonsystem_relation_kind 当作通用安全策略调优。除非 PostgreSQL 子系统或严格限定的维护流程明确需要，否则保持空值。
OLAP 不要用它沙箱化任意分析用户；应通过权限、模式与行级策略实施访问控制。
小规格 保持默认空值；启用关系类别禁令没有容量收益，却可能意外破坏普通查询。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 restrict_nonsystem_relation_kind，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 restrict_nonsystem_relation_kind。

关联参数

search_path · row_security · session_replication_role · event_triggers · createrole_self_grant

参考资料

1.33 - row_security

row_security 是控制是否启用行级安全的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用行级安全。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 491c029dbc42 — Row-Level Security Policies (RLS)
提交日期 2014-09-19
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 on — on

机制详解

row_security：启用行级安全。对普通角色而言，off 不会绕过策略，而会在本应应用策略时抛错，使 pg_dump 等工具避免悄然得到不完整结果。

row_security 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 row_security 当作正确性或安全控制，而非吞吐旋钮。严格限制 SET 权限，并由可信的角色或应用策略建立取值。
OLAP 若 row_security 必须不同，使用专用分析角色，并验证导出、触发器、策略与名称解析仍保持数据正确性。
小规格 除非有文档化的修复或兼容流程，否则保持 row_security 的安全默认值；临时变化应留痕并自动恢复。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 未修改；OLAP: PG9.5–19 Beta 3 未修改；CRIT: PG9.5–19 Beta 3 未修改；TINY: PG9.5–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 row_security，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 把 off 当作绕过策略，而普通角色在本应应用策略时会收到错误。

关联参数

search_path · session_replication_role · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

1.34 - search_path

search_path 定义解析未限定名称时的模式搜索顺序。
说明

Fact — 官方简述译文：设置解析未限定名称时的模式搜索顺序。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值"$user", public
“$user”, public

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.4 "$user",public — “$user”,public
PG9.5–19 Beta 3 "$user", public — “$user”, public

机制详解

search_path：设置解析未限定名称时的模式搜索顺序。它既控制名称查找，也决定未限定 CREATE 的目标模式；pg_catalog 与临时模式具有特殊的隐式搜索规则。

search_path 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 search_path 当作正确性或安全控制，而非吞吐旋钮。严格限制 SET 权限，并由可信的角色或应用策略建立取值。
OLAP 若 search_path 必须不同，使用专用分析角色，并验证导出、触发器、策略与名称解析仍保持数据正确性。
小规格 除非有文档化的修复或兼容流程，否则保持 search_path 的安全默认值；临时变化应留痕并自动恢复。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 search_path，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 把不受信角色可写的模式放在可信模式前，形成对象遮蔽攻击面。

关联参数

row_security · session_replication_role · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

1.35 - session_preload_libraries

session_preload_libraries 声明每个后端在会话开始时预加载的共享库。
说明

Fact — 官方简述译文：列出每个后端在会话开始时预加载的共享库。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 070518ddab2c — Add session_preload_libraries configuration parameter
提交日期 2013-06-12
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 "" — empty string

机制详解

session_preload_libraries：列出每个后端在会话开始时预加载的共享库。列表会加载到每个新的匹配后端中，且只能由超级用户或适当授权角色设置；库缺失会拒绝连接。

虽然 session_preload_libraries 无需重启服务器即可配置，但只有新后端启动时才处理库列表；在既有连接中修改不会卸载或追溯加载模块。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应通用调优 session_preload_libraries。只加载或暴露经过评审的功能所需模块，验证二进制兼容性，并在上线前演练故障恢复。
OLAP 只有扩展或 JIT 需求经过测量后才使用 session_preload_libraries，并计入后端启动、常驻内存与连接池下的行为。
小规格 尽量精简 session_preload_libraries。模块缺失或不兼容可能拒绝连接或阻止启动，每个预加载库也会占用稀缺地址空间或内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 session_preload_libraries，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 session_preload_libraries。

关联参数

shared_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

参考资料

1.36 - session_replication_role

session_replication_role 定义当前会话对触发器和重写规则的处理方式。
说明

Fact — 官方简述译文：设置当前会话对触发器和重写规则的处理方式。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值origin, replica, local
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值origin
origin

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 origin — origin

机制详解

session_replication_role：设置当前会话对触发器和重写规则的处理方式。replica 会抑制普通触发器和规则，包括外键检查；更改该值还会丢弃已缓存计划。

session_replication_role 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应调优 session_replication_role。只有受控复制或修复流程才可设为 replica，且必须独立保证约束并恢复 origin。
OLAP 分析会话保持 origin；抑制触发器不会加速读取，却会在会话写入时造成严重风险。
小规格 保持 origin；它不是小节点优化，并可能绕过外键。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 session_replication_role，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 忘记 replica 模式既抑制应用触发器，也抑制外键触发器。

关联参数

search_path · row_security · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

1.37 - shared_preload_libraries

shared_preload_libraries 声明服务器启动时预加载的共享库。
说明

Fact — 官方简述译文：列出服务器启动时预加载的共享库。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

shared_preload_libraries：列出服务器启动时预加载的共享库。库在共享内存定型前由 postmaster 一次性加载，可提供后续 LOAD 无法获得的钩子与共享状态；任一库缺失都会阻止服务器启动。

shared_preload_libraries 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应通用调优 shared_preload_libraries。只加载或暴露经过评审的功能所需模块，验证二进制兼容性，并在上线前演练故障恢复。
OLAP 只有扩展或 JIT 需求经过测量后才使用 shared_preload_libraries，并计入后端启动、常驻内存与连接池下的行为。
小规格 尽量精简 shared_preload_libraries。模块缺失或不兼容可能拒绝连接或阻止启动，每个预加载库也会占用稀缺地址空间或内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
OLAP pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
CRIT pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("$libdir/passwordcheck, pg_stat_statements, auto_explain") }}'
TINY pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)；OLAP: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)；CRIT: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)；TINY: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)。 建议（待人工复核）——编辑推断：pg_stat_statements 与 auto_explain 提供全局查询统计和定向慢计划证据，并接受启动加载及共享开销。

常见坑

  • 期待重新加载或 SET 激活 shared_preload_libraries，而它实际需要受控重启服务器。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 shared_preload_libraries。

关联参数

session_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

参考资料

1.38 - statement_timeout

statement_timeout 定义单条语句允许执行的最长时间。
说明

Fact — 官方简述译文：设置单条语句允许执行的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 ms 0 ms

机制详解

statement_timeout：设置单条语句允许执行的最长时间。计时从命令到达开始；现代版本会分别计算简单查询字符串中的各条语句，扩展协议则按 Parse/Bind/Execute 到 Sync 的消息周期计时。

statement_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 statement_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 statement_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 statement_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 statement_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 使用单一全局值，在终止失控请求的同时误杀合理维护与分析任务。

关联参数

lock_timeout · transaction_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

参考资料

1.39 - temp_tablespaces

temp_tablespaces 定义临时表和排序临时文件使用的表空间。
说明

Fact — 官方简述译文：设置临时表和排序临时文件使用的表空间。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

temp_tablespaces：设置临时表和排序临时文件使用的表空间。PostgreSQL 将该列表用于临时关系与执行器溢写文件，并在多个条目间分配工作；存在性和权限按设置上下文检查。

temp_tablespaces 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 temp_tablespaces 与模式管理策略一致，并在迁移中显式写出重要存储选择；任何物理布局变化都应用接近生产的写负载压测。
OLAP 为批量对象与高溢写作业有意识地使用 temp_tablespaces，采用前核对 I/O 放置、压缩支持与运维工具。
小规格 除非节点有经验证的替代存储路径或恢复需求，否则保留 temp_tablespaces 上游默认值；简单配置更少带来恢复意外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 temp_tablespaces，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 temp_tablespaces。

关联参数

default_table_access_method · default_tablespace · default_toast_compression · check_function_bodies · maintenance_work_mem

参考资料

1.40 - timezone_abbreviations

timezone_abbreviations 是 PostgreSQL 中用于选择时区缩写定义文件的参数。
说明

Fact — 官方简述译文：选择时区缩写定义文件。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 UNKNOWN — UNKNOWN
PG9.1–19 Beta 3 — — not set

机制详解

timezone_abbreviations：选择时区缩写定义文件。所选集合会改变可接受的日期时间输入记号，同一缩写在不同区域集合中可能解析为不同含义。

timezone_abbreviations 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 timezone_abbreviations 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 timezone_abbreviations；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 timezone_abbreviations 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 timezone_abbreviations，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 接受区域特定缩写集合，使熟悉记号解析到不同 UTC 偏移。

关联参数

DateStyle · IntervalStyle · TimeZone · lc_time · log_timezone

参考资料

1.41 - transaction_deferrable

transaction_deferrable 定义当前事务是否可延迟，供只读可串行化事务安全启动。
说明

Fact — 官方简述译文：设置当前事务是否可延迟，供只读可串行化事务安全启动。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 dafaa3efb75c — Implement genuine serializable isolation level.
提交日期 2011-02-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

transaction_deferrable：设置当前事务是否可延迟，供只读可串行化事务安全启动。它反映当前事务状态，且只有只读可串行化事务在取得快照前才有实际意义。

transaction_deferrable 可在会话中设置，但代表当前事务；事务取得快照或执行冲突操作后，PostgreSQL 会限制更改。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 transaction_deferrable。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 transaction_deferrable 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_deferrable，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 transaction_deferrable。

关联参数

default_transaction_isolation · transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable

参考资料

1.42 - transaction_isolation

transaction_isolation 定义当前事务的隔离级别。
说明

Fact — 官方简述译文：设置当前事务的隔离级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值serializable, repeatable read, read committed, read uncommitted
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值read committed
read committed

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 — — not set
PG9.1–11 default — default
PG12–19 Beta 3 read committed — read committed

机制详解

transaction_isolation：设置当前事务的隔离级别。它反映当前事务，初值来自 default_transaction_isolation；事务已经执行工作后不能任意提高隔离级别。

transaction_isolation 可在会话中设置，但代表当前事务；事务取得快照或执行冲突操作后，PostgreSQL 会限制更改。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 transaction_isolation。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 transaction_isolation 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_isolation，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 transaction_isolation。

关联参数

default_transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

1.43 - transaction_read_only

transaction_read_only 定义当前事务是否只读。
说明

Fact — 官方简述译文：设置当前事务是否只读。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

transaction_read_only：设置当前事务是否只读。它反映当前事务，初值来自 default_transaction_read_only；必须在执行与只读模式冲突的操作前设置。

transaction_read_only 可在会话中设置，但代表当前事务；事务取得快照或执行冲突操作后，PostgreSQL 会限制更改。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 transaction_read_only。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 transaction_read_only 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_read_only，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 transaction_read_only。

关联参数

default_transaction_isolation · transaction_isolation · default_transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

1.44 - transaction_timeout

transaction_timeout 定义会话中任一非预备事务允许持续的最长时间。
说明

Fact — 官方简述译文：设置会话中任一非预备事务允许持续的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 51efe38cb92f — Introduce transaction_timeout
提交日期 2024-02-15
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 0 ms 0 ms

机制详解

transaction_timeout：设置会话中任一非预备事务允许持续的最长时间。它会终止会话而不仅取消一条语句，不适用于预备事务；当其更短时，更长的事务内空闲或语句超时将失去作用。

transaction_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 transaction_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 transaction_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 transaction_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 期待它处理预备事务，而预备事务被明确排除。

关联参数

statement_timeout · lock_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

参考资料

1.45 - vacuum_cleanup_index_scale_factor

vacuum_cleanup_index_scale_factor 定义触发索引清理前允许新增元组数占 reltuples 的比例。
说明

Fact — 官方简述译文：设置触发索引清理前允许新增元组数占 reltuples 的比例。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1e+10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0.1
0.1

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–13
移除版本 PG14
引入提交 857f9c36cda5 — Skip full index scan during cleanup of B-tree indexes when possible
提交日期 2018-04-04
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–13 0.1 — 0.1

机制详解

vacuum_cleanup_index_scale_factor：设置触发索引清理前允许新增元组数占 reltuples 的比例。这一 PostgreSQL 11–13 参数按插入量延后索引清理；PostgreSQL 14 调整索引清理决策模型后将其移除。

vacuum_cleanup_index_scale_factor 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

这一遗留决策作用于 B-tree 清理扫描，并与 VACUUM 统计、新增元组、可复用索引页及 autovacuum 调度联动；它不是 GIN 控制项。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前服务器不应调优 vacuum_cleanup_index_scale_factor：PostgreSQL 14 已移除它。在 11–13 上也只应针对实测索引清理问题修改，并规划升级行为。
OLAP 遗留批量装载系统应测量真实索引维护，而不是把已移除参数作为配置传说继续携带。
小规格 保留遗留默认值并升级；已移除参数不是管理小节点 vacuum 成本的长期办法。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG13 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–13 未修改；OLAP: PG11–13 未修改；CRIT: PG11–13 未修改；TINY: PG11–13 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 vacuum_cleanup_index_scale_factor，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 未在对应版本测量索引扫描、可复用页与 VACUUM 行为，就采用旧式 B-tree 清理启发式。
  • 把已移除的会话默认参数与当前 autovacuum 阈值或表级存储参数混淆。
  • 升级到 PostgreSQL 14+ 时仍保留这一未知参数配置行。

关联参数

autovacuum · autovacuum_vacuum_scale_factor · vacuum_cost_limit · vacuum_cost_delay · maintenance_work_mem · autovacuum_work_mem

参考资料

1.46 - xmlbinary

xmlbinary 定义二进制值在 XML 中的编码方式。
说明

Fact — 官方简述译文：设置二进制值在 XML 中的编码方式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值base64, hex
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值base64
base64

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 base64 — base64

机制详解

xmlbinary：设置二进制值在 XML 中的编码方式。它影响 XML 构造函数中的 bytea 到 XML 转换；base64 与 hex 都能保留全部字节，但 hex 输出更大。

xmlbinary 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 xmlbinary 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 xmlbinary；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 xmlbinary 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 xmlbinary，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 xmlbinary。

关联参数

bytea_output · extra_float_digits · xmloption · client_encoding · DateStyle

参考资料

1.47 - xmloption

xmloption 定义隐式解析和序列化 XML 数据时将其视为文档还是内容片段。
说明

Fact — 官方简述译文：设置隐式解析和序列化 XML 数据时将其视为文档还是内容片段。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值content, document
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值content
content

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 content — content

机制详解

xmloption：设置隐式解析和序列化 XML 数据时将其视为文档还是内容片段。CONTENT 允许 XML 片段，而 DOCUMENT 要求单个格式良好的 XML 文档，因此会改变隐式转换与序列化行为。

xmloption 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 xmloption 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 xmloption；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 xmloption 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 xmloption，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 xmloption。

关联参数

bytea_output · extra_float_digits · xmlbinary · client_encoding · DateStyle

参考资料

2 - 连接与认证

Connections and Authentication 分类下的 45 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

2.1 - authentication_timeout

authentication_timeout 定义完成客户端认证所允许的最长时间。
说明

Fact — 官方简述译文：设置完成客户端认证所允许的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值1 – 600
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值60
1 min

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 60 s 1 min

机制详解

authentication_timeout：设置完成客户端认证所允许的最长时间。计时覆盖普通后端会话建立前的认证交互，用于限制停滞或恶意握手长期占用连接资源。

authentication_timeout 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按认证架构与安全策略设置 authentication_timeout，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP 分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格 优先保留 authentication_timeout 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 authentication_timeout 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
  • 为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 authentication_timeout。

关联参数

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval

参考资料

2.2 - bonjour

bonjour 是控制是否启用通过 Bonjour 广播服务器的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用通过 Bonjour 广播服务器。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

bonjour：启用通过 Bonjour 广播服务器。它只在具备 Bonjour 支持的平台与构建上通过 mDNS 发布可发现服务；不会自行打开监听地址，也不会修改 pg_hba.conf。

bonjour 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

Bonjour 广播依赖平台支持，只把监听器作为元数据发布；实际可达性与信任仍由 listen_addresses、port、pg_hba.conf、TLS 和防火墙决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有客户端明确在可信本地网络使用 Bonjour/mDNS 时才启用 bonjour。它只是发现元数据，不能替代认证或高可用服务注册。
OLAP 分析负载形态不构成改变 bonjour 的理由；应采用同一套经评审发现策略与稳定服务身份。
小规格 除非明确需要本地零配置发现，否则保持 bonjour 关闭或为空；它不会提升数据库容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 bonjour，而它实际需要受控重启服务器。
  • 把 mDNS 广播当作访问控制、认证或高可用机制。
  • 在不受信广播域发布意外的服务名称或端点。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 bonjour。

关联参数

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

2.3 - bonjour_name

bonjour_name 定义 Bonjour 服务名称。
说明

Fact — 官方简述译文：设置 Bonjour 服务名称。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

bonjour_name：设置 Bonjour 服务名称。空值会从计算机名派生广播服务名，而且只有启用 Bonjour 广播时该参数才有作用。

bonjour_name 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

Bonjour 广播依赖平台支持，只把监听器作为元数据发布；实际可达性与信任仍由 listen_addresses、port、pg_hba.conf、TLS 和防火墙决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有客户端明确在可信本地网络使用 Bonjour/mDNS 时才启用 bonjour_name。它只是发现元数据，不能替代认证或高可用服务注册。
OLAP 分析负载形态不构成改变 bonjour_name 的理由；应采用同一套经评审发现策略与稳定服务身份。
小规格 除非明确需要本地零配置发现，否则保持 bonjour_name 关闭或为空；它不会提升数据库容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 bonjour_name，而它实际需要受控重启服务器。
  • 把 mDNS 广播当作访问控制、认证或高可用机制。
  • 在不受信广播域发布意外的服务名称或端点。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 bonjour_name。

关联参数

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

2.4 - client_connection_check_interval

client_connection_check_interval 定义查询运行期间检查客户端断连的时间间隔。
说明

Fact — 官方简述译文：设置查询运行期间检查客户端断连的时间间隔。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / TCP Settings
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 c30f54ad732c — Detect POLLHUP/POLLRDHUP while running queries.
提交日期 2021-04-03
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 0 ms 0 ms

机制详解

client_connection_check_interval：设置查询运行期间检查客户端断连的时间间隔。非零间隔让长查询在下一次套接字写入前发现客户端已断开；检查是否有效取决于操作系统支持。

client_connection_check_interval 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有客户端丢失后放弃工作能显著节省容量且平台支持检查时，才为 client_connection_check_interval 使用非零值；应测量所选间隔的轮询开销。
OLAP 长分析查询可从周期断连检测获益，避免客户端消失后继续运行；该间隔并不限制健康查询的执行时长。
小规格 除非观察到孤儿长查询，否则保持零；启用时选择既能发现浪费又不过度检查活动查询的间隔。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 client_connection_check_interval，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 client_connection_check_interval。

关联参数

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · authentication_timeout

参考资料

2.5 - db_user_namespace

db_user_namespace 是控制是否启用按数据库划分的用户名空间的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用按数据库划分的用户名空间。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–16
移除版本 PG17
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–16 off — off

机制详解

db_user_namespace：启用按数据库划分的用户名空间。这一遗留功能在内部用 user@database 表示用户，并已于 PostgreSQL 17 移除；它不是现代的租户隔离机制。

db_user_namespace 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应采用或调优 db_user_namespace：它是遗留兼容功能，并已从 PostgreSQL 17 起移除。应迁移到普通集群级角色与显式授权。
OLAP 不要基于 db_user_namespace 构建分析租户隔离；应按边界要求使用角色、模式、数据库与行级安全。
小规格 旧版本中保持 db_user_namespace 关闭，并在升级前移除依赖；它没有小节点优化价值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG16 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–16 未修改；OLAP: PG9.0–16 未修改；CRIT: PG9.0–16 未修改；TINY: PG9.0–16 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 db_user_namespace 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
  • 为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 db_user_namespace。

关联参数

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

2.6 - gss_accept_delegation

gss_accept_delegation 定义是否接受客户端的 GSSAPI 凭据委派。
说明

Fact — 官方简述译文：设置是否接受客户端的 GSSAPI 凭据委派。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 9c0a0e2ed92a — rename “gss_accept_deleg” to “gss_accept_delegation”.
提交日期 2023-05-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 off — off

机制详解

gss_accept_delegation：设置是否接受客户端的 GSSAPI 凭据委派。接受委派凭据后，服务器端代码可代表客户端的 GSS 身份行动，因此信任范围超出普通认证。

gss_accept_delegation 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按认证架构与安全策略设置 gss_accept_delegation，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP 分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格 优先保留 gss_accept_delegation 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 gss_accept_delegation 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
  • 为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 gss_accept_delegation。

关联参数

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

2.7 - krb_caseins_users

krb_caseins_users 定义 Kerberos 和 GSSAPI 用户名是否按大小写不敏感方式处理。
说明

Fact — 官方简述译文：设置 Kerberos 和 GSSAPI 用户名是否按大小写不敏感方式处理。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

krb_caseins_users：设置 Kerberos 和 GSSAPI 用户名是否按大小写不敏感方式处理。它影响已认证 Kerberos/GSS 名称与数据库角色名的比较；大小写折叠可能合并现有映射中原本不同的身份。

krb_caseins_users 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按认证架构与安全策略设置 krb_caseins_users，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP 分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格 优先保留 krb_caseins_users 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 krb_caseins_users 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
  • 为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 krb_caseins_users。

关联参数

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

2.8 - krb_server_keyfile

krb_server_keyfile 定义 Kerberos 服务器密钥文件的位置。
说明

Fact — 官方简述译文：设置 Kerberos 服务器密钥文件的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值FILE:/etc/postgresql-common/krb5.keytab
FILE:/etc/postgresql-common/krb5.keytab

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 "" — empty string
PG9.1–19 Beta 3 FILE:/etc/postgresql-common/krb5.keytab — FILE:/etc/postgresql-common/krb5.keytab

机制详解

krb_server_keyfile：设置 Kerberos 服务器密钥文件的位置。该文件包含 GSSAPI 认证使用的服务密钥；操作系统所有权与 keytab 轮换也是有效配置的一部分。

krb_server_keyfile 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按认证架构与安全策略设置 krb_server_keyfile，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP 分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格 优先保留 krb_server_keyfile 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 krb_server_keyfile 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
  • 为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 krb_server_keyfile。

关联参数

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries

参考资料

2.9 - krb_srvname

krb_srvname：设置 Kerberos 服务名称。实测在档范围为 PG9.0–9.3；最后在档的 PG9.3 启动默认值为 postgres，context 为 sighup。它在 PG9.4 被移除。
说明

Fact — 官方简述译文：设置 Kerberos 服务名称。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Security and Authentication
上游分类
最后 boot 值 值postgres
postgres

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.3
移除版本 PG9.4
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.3 postgres — postgres

机制详解

krb_srvname：设置 Kerberos 服务名称。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG9.0–9.3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这个历史认证参数选择服务器使用的 Kerberos 服务主体名称，PG9.3 后退出。现代部署应从 pg_hba.conf、krb_server_keyfile 指定的 keytab、DNS 与客户端服务名选项共同设计 GSS/Kerberos，而不是继续携带这个旧 GUC。

应与 krb_server_keyfile、hba_file、ssl、password_encryption 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.3 未修改；OLAP: PG9.0–9.3 未修改；CRIT: PG9.0–9.3 未修改；TINY: PG9.0–9.3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 krb_srvname 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

krb_server_keyfile · hba_file · ssl · password_encryption

参考资料

2.10 - listen_addresses

listen_addresses 定义服务器监听的主机名或 IP 地址。
说明

Fact — 官方简述译文：设置服务器监听的主机名或 IP 地址。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值localhost
localhost

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 localhost — localhost

机制详解

listen_addresses：设置服务器监听的主机名或 IP 地址。服务器启动时绑定所列接口；是否可达仍取决于 port、pg_hba.conf、主机防火墙与网络路由。

listen_addresses 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

监听端点在启动时由 listen_addresses 与 port 组合，而 pg_hba.conf、TLS、防火墙、路由与服务发现决定哪些客户端能够使用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务拓扑设置 listen_addresses，只暴露必要接口或端口，并联合验证连接池、健康检查、pg_hba.conf、防火墙、故障转移与重启顺序。
OLAP 需要隔离时使用明确的分析端点或网络，但在各故障转移目标间保持连接信息一致。
小规格 除非需要远程访问，否则优先仅本地暴露；修改 listen_addresses 并重启前保留经过测试的管理路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 listen_addresses，而它实际需要受控重启服务器。
  • 误以为绑定地址或端口会授予访问权限；pg_hba.conf 与操作系统或网络控制仍然生效。
  • 修改仅启动时生效的端点，却未同步服务发现、健康检查、防火墙、客户端与管理恢复路径。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 listen_addresses。

关联参数

port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

2.11 - max_connections

PostgreSQL 客户端并发连接的启动时上限，也是多项共享资源的尺寸输入。
说明

Fact — 官方简述译文：设置数据库并发连接的最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值1 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值100
100

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 100 — 100

机制详解

max_connections 限制数据库服务器的并发连接数，只能在服务器启动时修改。PostgreSQL 会直接按该值确定部分资源规模，因此即使连接槽未全部使用，调高上限也会增加包括共享内存在内的分配。

reserved_connections 与 superuser_reserved_connections 从同一个总上限中划出应急或特权容量，因此普通应用通常不能占满所有配置槽位。

备用库的取值必须不低于主库。连接池可以把大量客户端连接与较少、受控的 PostgreSQL 后端连接解耦。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 面对大量客户端时优先使用事务池，按峰值活跃数据库工作量，加上监控、维护和故障转移余量来确定后端数；不要默认把每个客户端连接映射为一个服务器槽位。
OLAP 分析会话通常更少但更重，应把后端上限控制在能约束 work_mem 与并行工作进程总需求的范围，并为 ETL 与管理预留明确容量。
小规格 使用较低上限配合连接池并保留应急槽位。验证启动所需共享内存，不要通过不断提高上限掩盖连接泄漏。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 500 不同于 boot 值 {{ pg_max_connections }}
OLAP 500 不同于 boot 值 {{ pg_max_connections }}
CRIT 500 不同于 boot 值 {{ pg_max_connections }}
TINY 250 不同于 boot 值 {{ pg_max_connections }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 500 (dcs)；OLAP: PG9.0–19 Beta 3 = 500 (dcs)；CRIT: PG9.0–19 Beta 3 = 500 (dcs)；TINY: PG9.0–19 Beta 3 = 250 (dcs)。 建议（待人工复核）——编辑推断：模板在连接池后提供较宽松的兼容性上限，并为小节点降低上限，但实际活跃后端数与内存边界仍需按负载复核。

常见坑

  • 修改后没有安排重启，也没有保证备用库取值至少与主库相同。
  • 忽略更高连接上限带来的共享内存与每后端开销。
  • 计算应用容量时忘记预留连接与超级用户预留槽。
  • 同时使用很高的连接上限和宽松的单操作内存，却认为二者不会相乘。

关联参数

reserved_connections · superuser_reserved_connections · work_mem · max_worker_processes · max_prepared_transactions · max_wal_senders

参考资料

2.12 - md5_password_warnings

md5_password_warnings 是控制是否启用关于 MD5 密码的弃用警告的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用关于 MD5 密码的弃用警告。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 db6a4a985bc0 — Deprecate MD5 passwords.
提交日期 2024-12-02
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 on — on

机制详解

md5_password_warnings 控制 PostgreSQL 18 的弃用 WARNING：只有 CREATE ROLE 或 ALTER ROLE 设置 MD5 密码密文时才产生。它不会报告使用既有 MD5 密文进行的认证，因此不能作为活跃 MD5 客户端或角色的完整清单。

它属于 USER 上下文，获授权角色可在当前会话中修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。只有会话既执行设置密码语句又启用本参数时，才可能产生警告。

password_encryption 控制以明文设置密码时生成的格式，而既有 pg_authid 密文只有重置密码后才会改变。因此迁移除警告外，还需要受保护的密文类型清点、客户端兼容测试与凭据轮换。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 md5_password_warnings 为 on，但每条警告只能证明某个设置密码语句创建或提交了 MD5 密文。另行清点既有密文类型，并在强制仅 SCRAM 访问前测试所有认证路径。
OLAP 分析角色采用同一规则：遗留驱动可能继续用旧 MD5 密文认证而不产生本警告，因此必须显式测试并轮换这些凭据。
小规格 保持警告启用，其开销可忽略。不要把没有警告误当成不存在 MD5 密文或仅支持 MD5 客户端的证据。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为使用既有 MD5 密文认证时会告警；它只在 CREATE ROLE 或 ALTER ROLE 设置 MD5 密文时触发。
  • 把没有警告当成集群中不存在 MD5 密文或仅支持 MD5 客户端的证明。
  • 在创建或轮换角色的部署会话中关闭警告，从而隐藏新 MD5 密文的产生。
  • 修改 password_encryption 却不轮换既有角色密码，使其存储密文格式保持不变。

关联参数

password_encryption · scram_iterations · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

2.13 - oauth_validator_libraries

oauth_validator_libraries 声明可用于验证 OAuth 2.0 Bearer Token 的库。
说明

Fact — 官方简述译文：列出可用于验证 OAuth 2.0 Bearer Token 的库。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 b3f0be788afc — Add support for OAUTHBEARER SASL mechanism
提交日期 2025-02-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 "" — empty string

机制详解

oauth_validator_libraries 列出可验证 OAuth 2.0 Bearer Token 的受信服务器模块。PostgreSQL 18 不附带任何验证器实现，默认空值会拒绝所有 OAuth 连接；可用部署必须安装并列出至少一个兼容模块。

列表只有一个库时，PostgreSQL 默认将其用于 OAuth 连接；存在多个库时，pg_hba.conf 中每条 oauth 记录都必须从列表中显式指定 validator。该参数属于 SIGHUP 上下文，更改允许列表需要重新加载配置，并影响后续认证尝试。

验证器在服务器认证路径内执行受信本地代码。其令牌颁发者、受众、声明到角色映射、失败行为、依赖、软件包版本，以及在所有主库和故障转移节点上的可用性，都必须与 pg_hba.conf 和身份提供方一致。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先安装一个经过评审的验证器，在所有故障转移目标固定其软件包与版本，并在启用 oauth HBA 记录前测试颁发者、受众、过期、吊销、角色映射、畸形令牌和身份提供方故障。
OLAP 分析访问采用同一验证器信任策略。若需要不同颁发者或声明映射，应显式列出经评审模块，并在每条匹配 HBA 记录中选择预期 validator。
小规格 空值会安全地禁用 OAuth，但不是可工作的 OAuth 配置。小节点优先使用一个充分测试的验证器，并预算其令牌验证延迟，而不是削弱检查。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 列表为空时创建 oauth HBA 规则；PostgreSQL 会拒绝所有 OAuth 连接。
  • 误以为 PostgreSQL 提供内置验证器实现。
  • 列出多个库，却未在每条 oauth HBA 记录中选择 validator。
  • 只在主库安装验证器而未覆盖故障转移目标，或信任未经颁发者、受众与角色映射评审的本地代码。

关联参数

password_encryption · scram_iterations · md5_password_warnings · authentication_timeout · krb_server_keyfile

参考资料

2.14 - password_encryption

password_encryption 是 PostgreSQL 中用于选择生成密码密文时使用的算法的参数。
说明

Fact — 官方简述译文：选择生成密码密文时使用的算法。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值md5, scram-sha-256
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值scram-sha-256
scram-sha-256

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 on — on
PG10–13 md5 — md5
PG14–19 Beta 3 scram-sha-256 — scram-sha-256

机制详解

password_encryption：选择生成密码密文时使用的算法。它影响 CREATE ROLE、ALTER ROLE 等设置密码命令新生成的密文；既有密文不会自动重新哈希。

password_encryption 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

最终认证路径由该参数与 pg_hba.conf、角色属性、凭据材料、客户端能力，以及某些情况下的操作系统身份服务共同决定。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按认证架构与安全策略设置 password_encryption，而非按工作负载吞吐量。测试所有驱动、身份映射、故障转移路径与凭据轮换流程。
OLAP 分析访问也应采用同一安全基线；任何遗留客户端例外都应隔离到专用角色，并附带有期限的迁移计划。
小规格 优先保留 password_encryption 当前的安全默认值。不要为节省小节点上的少量 CPU 而削弱认证，应通过连接池降低连接抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP scram-sha-256 等于 boot 值 {{ pg_pwd_enc|default('scram-sha-256') }}
OLAP scram-sha-256 等于 boot 值 {{ pg_pwd_enc|default('scram-sha-256') }}
CRIT scram-sha-256 等于 boot 值 {{ pg_pwd_enc|default('scram-sha-256') }}
TINY scram-sha-256 等于 boot 值 {{ pg_pwd_enc|default('scram-sha-256') }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = scram-sha-256 (dcs)；OLAP: PG9.0–19 Beta 3 = scram-sha-256 (dcs)；CRIT: PG9.0–19 Beta 3 = scram-sha-256 (dcs)；TINY: PG9.0–19 Beta 3 = scram-sha-256 (dcs)。 建议（待人工复核）——编辑推断：SCRAM-SHA-256 在各模板与受支持 PostgreSQL 版本上建立一致的现代密码密文基线。

常见坑

  • 只在一个会话中修改 password_encryption，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 修改单个认证参数，却未测试 pg_hba.conf 顺序、既有密文、映射与所有客户端库。
  • 为解决应由连接池和容量规划处理的连接抖动或 CPU 成本而削弱身份策略。
  • 更改算法后误以为既有角色密文会自动转换。

关联参数

scram_iterations · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

2.15 - password_expiration_warning_threshold

password_expiration_warning_threshold：设置密码到期告警的提前时间阈值。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 7 d，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置密码到期告警的提前时间阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值604800
7 d

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 1d92e0c2cc47 — Add password expiration warnings.
提交日期 2026-02-11
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 604800 s 7 d

机制详解

password_expiration_warning_threshold：设置密码到期告警的提前时间阈值。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

密码认证成功后，如果带 VALID UNTIL 的角色剩余有效期小于该区间，PostgreSQL 会发出警告。0 禁用告警；默认七天窗口只负责提醒，不会创建、轮换或延长凭据，使用非密码认证也不会让密码生命周期自动化。

应与 password_encryption、authentication_timeout、md5_password_warnings、hba_file 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 通过分批客户端上线，验证证书选择与到期告警，并监控认证失败。保留测试过的回退方案，把文件权限和密钥轮换作为同一变更的一部分。
OLAP 批处理驱动与长连接 ETL 也应采用同一安全策略；测试不发送 SNI 的客户端、凭据到期自动化、reload 行为和证书链兼容性。
小规格 优先保持简单且有文档的 TLS 与凭据策略。没有覆盖每个主机名和回退路径的测试就不要启用多证书路由，更不能降低验证强度来掩盖配置错误。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 password_expiration_warning_threshold 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

password_encryption · authentication_timeout · md5_password_warnings · hba_file

参考资料

2.16 - port

port 定义服务器监听的 TCP 端口。
说明

Fact — 官方简述译文：设置服务器监听的 TCP 端口。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值1 – 65535
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值5432
5432

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 5432 — 5432

机制详解

port：设置服务器监听的 TCP 端口。所有 TCP 监听地址共用一个端口，它会进入客户端连接串、服务发现、防火墙规则与健康检查。

port 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

监听端点在启动时由 listen_addresses 与 port 组合，而 pg_hba.conf、TLS、防火墙、路由与服务发现决定哪些客户端能够使用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务拓扑设置 port，只暴露必要接口或端口，并联合验证连接池、健康检查、pg_hba.conf、防火墙、故障转移与重启顺序。
OLAP 需要隔离时使用明确的分析端点或网络，但在各故障转移目标间保持连接信息一致。
小规格 除非需要远程访问，否则优先仅本地暴露；修改 port 并重启前保留经过测试的管理路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 port，而它实际需要受控重启服务器。
  • 误以为绑定地址或端口会授予访问权限；pg_hba.conf 与操作系统或网络控制仍然生效。
  • 修改仅启动时生效的端点，却未同步服务发现、健康检查、防火墙、客户端与管理恢复路径。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 port。

关联参数

listen_addresses · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

2.17 - reserved_connections

reserved_connections 定义为具有 pg_use_reserved_connections 权限的角色保留的连接槽数量。
说明

Fact — 官方简述译文：设置为具有 pg_use_reserved_connections 权限的角色保留的连接槽数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 6e2775e4d4e4 — Add new GUC reserved_connections.
提交日期 2023-01-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 0 — 0

机制详解

reserved_connections：设置为具有 pg_use_reserved_connections 权限的角色保留的连接槽数量。这些槽位只向获授 pg_use_reserved_connections 的角色开放，位于普通容量之上、超级用户专用预留之下。

reserved_connections 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

reserved_connections 与 superuser_reserved_connections 从 max_connections 中划出特权层；连接池、监控、复制、维护与故障转移必须共同纳入同一后端总预算。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在 max_connections 总量内，按独立应急主体数量、连接池行为与故障转移操作确定 reserved_connections；测试普通连接饱和后管理入口仍可用。
OLAP 为重型分析会话之外的控制、监控与取消预留足够槽位，但不要让预留吞噬本就较小后端池的过高比例。
小规格 让 reserved_connections 相对 max_connections 保持适度，同时至少保留一条经过测试的应急路径；饱和时预留槽不会供普通客户端使用。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 reserved_connections，而它实际需要受控重启服务器。
  • 把预留槽计算在 max_connections 之外，而所有层级实际共享同一总上限。
  • 应急响应预留过少，或预留过多以致饱和时普通应用容量骤降。
  • 规划普通、预留与超级用户预留槽时，没有确保总量纳入 max_connections。

关联参数

listen_addresses · port · max_connections · superuser_reserved_connections · unix_socket_directories

参考资料

2.18 - scram_iterations

scram_iterations 定义生成 SCRAM 密文时使用的迭代次数。
说明

Fact — 官方简述译文：设置生成 SCRAM 密文时使用的迭代次数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Authentication
上游分类
最后 boot 值 值4096
4096

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 b577743000cd — Make SCRAM iteration count configurable
提交日期 2023-03-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 4096 — 4096

机制详解

scram_iterations 会写入每个新生成的 SCRAM-SHA-256 密文。提高它会增加离线猜测成本，也会增加正常设置密码与认证工作；既有密文会保留创建时的迭代次数，直至重置密码。

它属于 USER 上下文，因此执行 CREATE ROLE 或 ALTER ROLE 的会话决定写入新密文的次数。即使 postgresql.conf 只有一个值，角色、数据库或应用级覆盖也可能造成多种次数并存。

PostgreSQL 警告：当角色存储次数不同于服务器配置值时，未认证观察者可能通过响应行为差异推断角色存在。因此改变次数需要统一会话策略并轮换所有 SCRAM 密文，而不只是修改 GUC。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 通过安全与认证延迟压测选择唯一次数，在所有密码管理会话中强制使用，并轮换全部角色密码使存储密文收敛。提高前应压测重连风暴与故障转移。
OLAP 分析角色使用相同次数；负载类型不是暴露不同密文次数的理由。安排凭据轮换，避免长期服务账号保留旧次数。
小规格 除非测试证明需要改变，否则保留上游次数。小服务器可通过连接池降低连接抖动，但仍必须让所有新密文使用一致次数。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 GUC 却不重置既有密码；其密文仍保留旧次数。
  • 允许角色或数据库会话默认值生成不同于 postgresql.conf 的密文次数，从而形成角色存在性侧信道。
  • 提高次数却未压测认证风暴、故障转移、连接池重连与密码轮换作业。
  • 误以为更高次数能修复弱密码或弥补已泄漏密文材料。

关联参数

password_encryption · md5_password_warnings · authentication_timeout · oauth_validator_libraries · krb_server_keyfile

参考资料

2.19 - ssl

ssl 是控制是否启用 SSL/TLS 连接的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用 SSL/TLS 连接。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

ssl：启用 SSL/TLS 连接。开启后，在证书与私钥有效时提供 TLS 监听能力；真正要求特定客户端使用 TLS 的是 pg_hba.conf hostssl 规则。

ssl 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断：所有模板启用 TLS，使基于证书的加密传输成为统一基线；策略要求处仍需由 pg_hba.conf 强制使用。

常见坑

  • 编辑 ssl 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl。

关联参数

ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.20 - ssl_ca_file

ssl_ca_file 定义 SSL 证书颁发机构文件的位置。
说明

Fact — 官方简述译文：设置 SSL 证书颁发机构文件的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
提交日期 2012-02-22
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 "" — empty string

机制详解

ssl_ca_file：设置 SSL 证书颁发机构文件的位置。PEM CA 包定义客户端证书验证的信任根，以及 TLS 协商期间发送的可接受颁发机构列表。

ssl_ca_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有经评审且用于验证客户端证书的 CA 包才写入 ssl_ca_file。CA 轮换期间规划新旧信任根重叠，限制文件写权限，并在重载后测试每条 cert/clientcert HBA 路径。
OLAP 除非分析访问属于刻意分离的 PKI 域，否则使用相同信任根。不要为解决客户端部署问题而扩大 CA 包。
小规格 不使用客户端证书验证时保持空值。启用后让 CA 包尽量精简，监控到期，并在故障转移节点保持一致。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP /pg/cert/ca.crt 不同于 boot 值 '/pg/cert/ca.crt'
OLAP /pg/cert/ca.crt 不同于 boot 值 '/pg/cert/ca.crt'
CRIT /pg/cert/ca.crt 不同于 boot 值 '/pg/cert/ca.crt'
TINY /pg/cert/ca.crt 不同于 boot 值 '/pg/cert/ca.crt'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)；OLAP: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)；CRIT: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)；TINY: PG9.2–19 Beta 3 = /pg/cert/ca.crt (dcs)。 建议（待人工复核）——编辑推断：统一托管 CA 路径让各模板的信任材料保持一致，并支持可重复证书部署。

常见坑

  • 编辑 ssl_ca_file 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_ca_file。

关联参数

ssl · ssl_cert_file · ssl_key_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.21 - ssl_cert_file

ssl_cert_file 定义 SSL 服务器证书文件的位置。
说明

Fact — 官方简述译文：设置 SSL 服务器证书文件的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值server.crt
server.crt

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
提交日期 2012-02-22
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 server.crt — server.crt

机制详解

ssl_cert_file：设置 SSL 服务器证书文件的位置。PEM 文件提供服务器叶证书，也可包含向客户端呈现完整链所需的中间证书。

ssl_cert_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 部署的证书应在密钥用途、SAN、有效期和证书链上匹配所有对外数据库端点。删除旧证书前，测试重载和新的客户端握手。
OLAP 分析端点需要相同身份保证；若使用独立名称，应签发正确 SAN，而不是复用名称不匹配的证书。
小规格 自动化续期与到期告警。小节点不会因缩短到客户端无法建立信任的链获益，只保留必要叶证书与中间证书。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP /pg/cert/server.crt 不同于 boot 值 '/pg/cert/server.crt'
OLAP /pg/cert/server.crt 不同于 boot 值 '/pg/cert/server.crt'
CRIT /pg/cert/server.crt 不同于 boot 值 '/pg/cert/server.crt'
TINY /pg/cert/server.crt 不同于 boot 值 '/pg/cert/server.crt'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)；OLAP: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)；CRIT: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)；TINY: PG9.2–19 Beta 3 = /pg/cert/server.crt (dcs)。 建议（待人工复核）——编辑推断：统一托管服务器证书路径让所有模板遵循同一证书生命周期布局。

常见坑

  • 编辑 ssl_cert_file 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_cert_file。

关联参数

ssl · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.22 - ssl_ciphers

ssl_ciphers 定义 TLS 1.2 及更低版本允许使用的密码套件列表。
说明

Fact — 官方简述译文：设置 TLS 1.2 及更低版本允许使用的密码套件列表。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值HIGH:MEDIUM:+3DES:!aNULL
HIGH:MEDIUM:+3DES:!aNULL

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 不作断言：名称在 2008 Git 历史边界已经存在
提交日期 ≤ 2008-01-01
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–9.2 ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH — ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
PG9.3 DEFAULT:!LOW:!EXP:!MD5:@STRENGTH — DEFAULT:!LOW:!EXP:!MD5:@STRENGTH
PG9.4–19 Beta 3 HIGH:MEDIUM:+3DES:!aNULL — HIGH:MEDIUM:+3DES:!aNULL

机制详解

ssl_ciphers 名称在本项目 2008 年历史边界以及 PG9.0 的 GUC 源码中已经存在，但只在定义 USE_SSL 时编译。本项目可审计的 PG9.0 备用构建没有启用 OpenSSL，因此该名称首次出现在 PG9.1 官方镜像快照；这个矩阵边界反映构建能力，而不是功能最初发明时间。

该 OpenSSL 密码字符串控制 TLS 1.2 及更低版本握手；PG18+ 的 TLS 1.3 套件由 ssl_tls13_ciphers 单独配置。SIGHUP reload 会改变新 TLS 上下文和新连接使用的策略，但不会重新协商已经建立的会话。

应把 ssl_ciphers 视为完整传输策略的一部分，与 ssl、pg_hba.conf、证书和私钥、CA 与吊销设置、协议上下限、ssl_groups 及客户端能力联合验证。必须针对实际安装的 OpenSSL 构建测试，因为可接受的密码名称与安全级别依赖库版本。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_ciphers 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl_ciphers 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_ciphers 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_ciphers。

关联参数

ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

2.23 - ssl_crl_dir

ssl_crl_dir 定义 SSL 证书吊销列表目录的位置。
说明

Fact — 官方简述译文：设置 SSL 证书吊销列表目录的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 f5465fade908 — Allow specifying CRL directory
提交日期 2021-02-18
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 "" — empty string

机制详解

ssl_crl_dir 指定客户端证书吊销列表目录。OpenSSL 需要哈希查找链接，因此每次新增或替换 CRL 后都必须再次运行 openssl rehash 或 c_rehash。它补充 ssl_crl_file，两种来源可以同时启用。

更改目录路径属于 SIGHUP 上下文配置变化，但配置目录中的 CRL 文件会在连接时按需加载。因此新安装且正确 rehash 的 CRL 可由新连接立即使用，无需重载 PostgreSQL。

这不同于 ssl_crl_file：后者的文件内容在服务器启动或配置重载时加载。两者都不会追溯吊销既有 TLS 会话；应使用新的客户端证书握手测试吊销，并监控 CRL 的颁发者、签名与到期。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_crl_dir 作为按颁发者索引的 CRL 仓库管理：加入最新 CRL，运行 openssl rehash 或 c_rehash，并用新连接验证吊销。只有能运维按需多颁发者更新时才使用。
OLAP 分析证书使用同一吊销仓库；不能仅因这些客户端连接较少就建立独立且陈旧的目录。
小规格 除非已具备自动 CRL 获取、rehash、到期监控与故障转移同步，否则保持空目录；无人维护的目录会造成虚假安全感。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 新增或替换 CRL 后没有运行 openssl rehash 或 c_rehash，导致 OpenSSL 无法发现。
  • 只重载 PostgreSQL 却不刷新过期 CRL，或误以为目录变化会追溯影响既有 TLS 会话。
  • 把 ssl_crl_dir 当成 ssl_crl_file，忽略目录 CRL 会为新连接按需加载。
  • 只同步目录路径，却未把 CRL 与哈希链接同步到所有故障转移节点。

关联参数

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.24 - ssl_crl_file

ssl_crl_file 定义 SSL 证书吊销列表文件的位置。
说明

Fact — 官方简述译文：设置 SSL 证书吊销列表文件的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
提交日期 2012-02-22
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 "" — empty string

机制详解

ssl_crl_file：设置 SSL 证书吊销列表文件的位置。验证客户端证书时会读取该 PEM 吊销列表，并应随颁发机构发布的新吊销状态更新。

ssl_crl_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在颁发 CA 的 next-update 截止前刷新 ssl_crl_file，验证签名与颁发者覆盖，重载 PostgreSQL，并证明新吊销客户端证书会被拒绝。
OLAP 分析客户端遵循相同吊销策略；不能因会话更长或频率更低而延后 CRL 刷新。
小规格 若没有受管 CRL 源，应明确记录客户端证书吊销状态不再新鲜，而不是依赖过期文件；在每个故障转移节点监控文件与重载流程。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 未修改；OLAP: PG9.2–19 Beta 3 未修改；CRIT: PG9.2–19 Beta 3 未修改；TINY: PG9.2–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_crl_file 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_crl_file。

关联参数

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_min_protocol_version

参考资料

2.25 - ssl_dh_params_file

ssl_dh_params_file 定义 SSL DH 参数文件的位置。
说明

Fact — 官方简述译文：设置 SSL DH 参数文件的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 c0a15e07cd71 — Always use 2048 bit DH parameters for OpenSSL ephemeral DH ciphers.
提交日期 2017-07-31
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 "" — empty string

机制详解

ssl_dh_params_file：设置 SSL DH 参数文件的位置。空值使用 PostgreSQL 编译内置的 DH 参数；该文件只影响采用有限域 Diffie-Hellman 交换的密码套件。

ssl_dh_params_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有有意支持有限域临时 DH 密码套件，且参数由当前获批流程生成时才使用自定义 ssl_dh_params_file。上线前测试 OpenSSL 接受与重载。
OLAP 分析吞吐量不是削弱 DH 参数的理由。采用相同的经评审密钥交换策略，并只在证明客户端兼容后测量性能。
小规格 除非策略要求受管自定义参数，否则保持空值使用 PostgreSQL 编译内置参数；生成或加载自定义参数不会提升容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_dh_params_file 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_dh_params_file。

关联参数

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

2.26 - ssl_ecdh_curve

ssl_ecdh_curve 定义 ECDH 使用的椭圆曲线。
说明

Fact — 官方简述译文：设置 ECDH 使用的椭圆曲线。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值prime256v1
prime256v1

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–17
移除版本 PG18
引入提交 3164721462d5 — SSL: Support ECDH key exchange
提交日期 2013-12-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–17 prime256v1 — prime256v1

机制详解

ssl_ecdh_curve：设置 ECDH 使用的椭圆曲线。这一单曲线控制项存在至 PostgreSQL 17，并在 PostgreSQL 18 被支持多组的 ssl_groups 取代。

ssl_ecdh_curve 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP PostgreSQL 18+ 不应调优 ssl_ecdh_curve，应把经评审策略迁移到 ssl_groups。旧版本也只能在完成 TLS 库兼容测试后修改。
OLAP 采用与 OLTP 相同的经评审密钥交换策略；分析吞吐量不是保留已移除单曲线控制项的理由。
小规格 PostgreSQL 17 及更早版本保留受支持的安全默认值，升级时验证 ssl_groups 替代配置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG17 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–17 未修改；OLAP: PG9.4–17 未修改；CRIT: PG9.4–17 未修改；TINY: PG9.4–17 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_ecdh_curve 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 在 PostgreSQL 18 配置中保留已移除名称，而未迁移到 ssl_groups。

关联参数

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

2.27 - ssl_groups

ssl_groups 定义 Diffie-Hellman 密钥交换使用的组。
说明

Fact — 官方简述译文：设置 Diffie-Hellman 密钥交换使用的组。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值X25519:prime256v1
X25519:prime256v1

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 3d1ef3a15c3e — Support configuring multiple ECDH curves
提交日期 2024-10-24
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 X25519:prime256v1 — X25519:prime256v1

机制详解

ssl_groups：设置 Diffie-Hellman 密钥交换使用的组。PostgreSQL 18 接受按优先顺序排列、以冒号分隔的列表，取代原先单一的 ssl_ecdh_curve，并覆盖支持的密钥交换组。

ssl_groups 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_groups 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl_groups 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_groups 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_groups。

关联参数

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers

参考资料

2.28 - ssl_key_file

ssl_key_file 定义 SSL 服务器私钥文件的位置。
说明

Fact — 官方简述译文：设置 SSL 服务器私钥文件的位置。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值server.key
server.key

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 a445cb92ef5b — Add parameters for controlling locations of server-side SSL files
提交日期 2012-02-22
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 server.key — server.key

机制详解

ssl_key_file：设置 SSL 服务器私钥文件的位置。该文件包含与 ssl_cert_file 匹配的私钥；PostgreSQL 会先强制检查严格的所有权与权限。

ssl_key_file 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 ssl_key_file 由 PostgreSQL 服务账号拥有，使用 PostgreSQL 接受的严格权限，确认与 ssl_cert_file 匹配，并通过可审计秘密交付路径轮换。
OLAP 分析节点采用相同私钥控制；负载类型绝不构成共享、组可写或脱离受管 PKI 流程复制私钥的理由。
小规格 优先使用一个受管私钥并测试到期/续期与受保护备份。私钥加密时，在无人值守重启前测试 ssl_passphrase_command 与重载行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP /pg/cert/server.key 不同于 boot 值 '/pg/cert/server.key'
OLAP /pg/cert/server.key 不同于 boot 值 '/pg/cert/server.key'
CRIT /pg/cert/server.key 不同于 boot 值 '/pg/cert/server.key'
TINY /pg/cert/server.key 不同于 boot 值 '/pg/cert/server.key'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)；OLAP: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)；CRIT: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)；TINY: PG9.2–19 Beta 3 = /pg/cert/server.key (dcs)。 建议（待人工复核）——编辑推断：统一托管私钥路径与服务器证书配对，并集中所有权与续期约定。

常见坑

  • 编辑 ssl_key_file 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 私钥所有权或权限被 PostgreSQL 拒绝，或意外向可读组泄漏。

关联参数

ssl · ssl_cert_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.29 - ssl_max_protocol_version

ssl_max_protocol_version 定义允许使用的最高 SSL/TLS 协议版本。
说明

Fact — 官方简述译文：设置允许使用的最高 SSL/TLS 协议版本。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值"", TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 e73e67c71959 — Add settings to control SSL/TLS protocol version
提交日期 2018-11-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

ssl_max_protocol_version：设置允许使用的最高 SSL/TLS 协议版本。空值不在 SSL 库之外施加 PostgreSQL 专属上限；指定版本可为兼容测试有意阻止更新协议。

ssl_max_protocol_version 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_max_protocol_version 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl_max_protocol_version 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_max_protocol_version 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_max_protocol_version。

关联参数

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

2.30 - ssl_min_protocol_version

ssl_min_protocol_version 定义允许使用的最低 SSL/TLS 协议版本。
说明

Fact — 官方简述译文：设置允许使用的最低 SSL/TLS 协议版本。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值TLSv1.2
TLSv1.2

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 e73e67c71959 — Add settings to control SSL/TLS protocol version
提交日期 2018-11-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12 TLSv1 — TLSv1
PG13–19 Beta 3 TLSv1.2 — TLSv1.2

机制详解

ssl_min_protocol_version：设置允许使用的最低 SSL/TLS 协议版本。协商版本低于下限的连接会被拒绝；上游默认值从 PostgreSQL 12 的 TLSv1 提升为 PostgreSQL 13 的 TLSv1.2。

ssl_min_protocol_version 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_min_protocol_version 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl_min_protocol_version 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_min_protocol_version 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 ssl_min_protocol_version。

关联参数

ssl_ciphers · ssl_tls13_ciphers · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

2.31 - ssl_passphrase_command

ssl_passphrase_command 定义用于获取 SSL 私钥口令的命令。
说明

Fact — 官方简述译文：设置用于获取 SSL 私钥口令的命令。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 8a3d9425290f — Add ssl_passphrase_command setting
提交日期 2018-02-26
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 "" — empty string

机制详解

ssl_passphrase_command 是 PostgreSQL 需要解密加密私钥等 SSL 文件时调用的外部助手。助手必须把口令写到标准输出并以状态零退出；PostgreSQL 会去掉输出末尾的一个换行。

配置命令中的 %p 会替换为可能包含空白的提示字符串，因此必须安全引用；%% 输出字面百分号。命令以 PostgreSQL 服务账号运行，其环境、路径、参数、输出与错误日志都不得泄漏秘密。

它属于 SIGHUP 上下文，但重载时能否替换加密私钥还取决于 ssl_passphrase_command_supports_reload。非交互 keychain/文件助手可支持重载；TTY 提示通常只适合受控启动，Windows 另有重载要求。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 使用绝对路径、最小化、非交互助手，并由受保护 keychain 或文件描述符提供秘密。测试精确标准输出、退出状态、%p 引用、超时/失败、启动、重载和故障节点可用性，且不得记录口令。
OLAP 分析节点使用相同助手与秘密源；负载类型不会改变私钥信任要求。安排证书轮换前测试无人值守重启。
小规格 优先使用最简单且可审计、能无人值守重启的助手。若保留 TTY 提示，应记录：除非安全启用 supports_reload，否则重载无法替换加密私钥。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在标准输出中写入口令以外内容，或返回非零状态。
  • 没有引用 %p，而替换后的提示可能含空白；或忘记字面百分号需要写成 %%。
  • 通过命令参数、进程列表、环境变量、shell 跟踪、标准错误或服务器日志泄漏口令。
  • 部署只在一个主库交互运行成功，却在无人值守重启、重载或故障转移时失败的助手。

关联参数

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.32 - ssl_passphrase_command_supports_reload

ssl_passphrase_command_supports_reload 是 PostgreSQL 中用于控制重新加载服务器配置时是否调用 ssl_passphrase_command的参数。
说明

Fact — 官方简述译文：控制重新加载服务器配置时是否调用 ssl_passphrase_command。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 8a3d9425290f — Add ssl_passphrase_command setting
提交日期 2018-02-26
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 off — off

机制详解

ssl_passphrase_command_supports_reload 决定重新加载配置时，如替换 SSL 私钥需要口令，是否可以调用 ssl_passphrase_command。设为 off 时，重载会忽略该命令；若私钥需要口令，PostgreSQL 将不重载 SSL 配置。

该参数属于 SIGHUP 上下文，影响新握手使用的替换 TLS 材料；既有 TLS 会话不会重新协商。只有助手无需交互、可靠可用且能在运行中的服务器环境安全调用时才应开启。

Windows 上该参数必须为 on，因为 Windows 进程模型会使每个连接执行配置重载。这一平台要求优先于 Unix 环境中把依赖 TTY 的助手限制在启动阶段的通常选择。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有 ssl_passphrase_command 已证明无需交互、幂等、快速且重新加载时可用，才启用本项；否则证书刷新可能在运维上失败。
OLAP 各负载类型采用相同重载能力，使每个节点的证书轮换行为可预测。
小规格 Windows 上必须设为 on。Unix 上只有在完全不需要重载时取口令时才保持 off；若需要无人值守轮换，应先在服务器运行环境中验证助手再开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • Windows 上设为 off；该平台因每个连接都会执行配置重载而强制要求 on。
  • 助手仍需交互、执行缓慢、不可用或无法安全重复调用，却开启重载支持。
  • 误以为重新加载会重新协商既有会话；替换后的 TLS 材料只影响新握手。
  • 重载后未检查服务器日志；若口令获取失败，PostgreSQL 会继续使用旧 SSL 配置。

关联参数

ssl · ssl_cert_file · ssl_key_file · ssl_ca_file · ssl_crl_file · ssl_min_protocol_version

参考资料

2.33 - ssl_prefer_server_ciphers

ssl_prefer_server_ciphers 是 PostgreSQL 中用于优先采用服务器端的密码套件顺序的参数。
说明

Fact — 官方简述译文：优先采用服务器端的密码套件顺序。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 ef3267523d1e — SSL: Add configuration option to prefer server cipher order
提交日期 2013-12-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 on — on

机制详解

ssl_prefer_server_ciphers：优先采用服务器端的密码套件顺序。它只影响 TLS 1.2 及更低版本采用服务器还是客户端顺序；TLS 1.3 协商不使用该开关。

ssl_prefer_server_ciphers 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_prefer_server_ciphers 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl_prefer_server_ciphers 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_prefer_server_ciphers 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 误以为它控制 TLS 1.3 密码套件顺序。

关联参数

ssl_ciphers · ssl_tls13_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_groups

参考资料

2.34 - ssl_renegotiation_limit

ssl_renegotiation_limit：设置重新协商加密密钥前允许收发的流量。实测在档范围为 PG9.0–9.4；最后在档的 PG9.4 启动默认值为 0 B，context 为 user。它在 PG9.5 被移除。
说明

Fact — 官方简述译文：设置重新协商加密密钥前允许收发的流量。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Security and Authentication
上游分类
最后 boot 值 值0
0 B

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.4
移除版本 PG9.5
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.4 0 kB 0 B

机制详解

ssl_renegotiation_limit：设置重新协商加密密钥前允许收发的流量。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG9.0–9.4 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

该参数在 TLS 流量达到阈值后发起密钥重新协商。随着协议、库行为和安全建议转向避免 renegotiation，PostgreSQL 在 PG9.5 移除了它；现代 TLS 策略应管理协议版本、密码套件、证书与连接轮换。

应与 ssl_min_protocol_version、ssl_max_protocol_version、ssl_ciphers、ssl 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.4 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.4 未修改；OLAP: PG9.0–9.4 未修改；CRIT: PG9.0–9.4 未修改；TINY: PG9.0–9.4 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 ssl_renegotiation_limit 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

ssl_min_protocol_version · ssl_max_protocol_version · ssl_ciphers · ssl

参考资料

2.35 - ssl_sni

ssl_sni：设置是否解释 SSL 连接中的 SNI 扩展。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置是否解释 SSL 连接中的 SNI 扩展。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 4f433025f666 — ssl: Serverside SNI support for libpq
提交日期 2026-03-18
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 off — off

机制详解

ssl_sni：设置是否解释 SSL 连接中的 SNI 扩展。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

在 TLS 下启用后，PostgreSQL 读取客户端的 Server Name Indication，并通过 hosts_file 选择凭据。主机名不区分大小写匹配，/no_sni/ 与 * 提供明确的回退行为；证书身份、客户端校验、CRL、文件权限和 reload 失败仍需独立验证。

应与 hosts_file、ssl、ssl_cert_file、ssl_key_file 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 通过分批客户端上线，验证证书选择与到期告警，并监控认证失败。保留测试过的回退方案，把文件权限和密钥轮换作为同一变更的一部分。
OLAP 批处理驱动与长连接 ETL 也应采用同一安全策略；测试不发送 SNI 的客户端、凭据到期自动化、reload 行为和证书链兼容性。
小规格 优先保持简单且有文档的 TLS 与凭据策略。没有覆盖每个主机名和回退路径的测试就不要启用多证书路由，更不能降低验证强度来掩盖配置错误。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 ssl_sni 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

hosts_file · ssl · ssl_cert_file · ssl_key_file · ssl_ca_file

参考资料

2.36 - ssl_tls13_ciphers

ssl_tls13_ciphers 定义 TLS 1.3 允许使用的密码套件列表。
说明

Fact — 官方简述译文：设置 TLS 1.3 允许使用的密码套件列表。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / SSL
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 45188c2ea239 — Support configuring TLSv1.3 cipher suites
提交日期 2024-10-24
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 "" — empty string

机制详解

ssl_tls13_ciphers：设置 TLS 1.3 允许使用的密码套件列表。空值把 TLS 1.3 套件选择交给 SSL 库默认值，其语法也不同于 ssl_ciphers。

ssl_tls13_ciphers 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。既有 TLS 会话不会重新协商。

它参与新握手使用的 TLS 上下文。ssl 启用传输，pg_hba.conf 决定哪些连接类别必须使用它，而证书、私钥、CA、吊销、协议与密码参数必须组成一套有效策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 ssl_tls13_ciphers 作为传输安全策略而非性能旋钮。遵循组织 TLS 基线，并测试证书轮换、重新加载及每类客户端。
OLAP 分析流量应采用相同 TLS 下限；大流量可能暴露 CPU 成本，但只能在正确性之后压测，不能据此接受过时协议。
小规格 保持 ssl_tls13_ciphers 简单且安全，使用托管证书与针对当前 OpenSSL 版本评审过的库默认值，并在到期前演练续期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 ssl_tls13_ciphers 后没有重新加载配置，也没有核对有效值与后续行为。
  • 只更新一个 TLS 文件或策略参数，留下无效证书链、不可读私钥或不兼容协议集合。
  • 误以为重新加载会重新协商既有会话；TLS 策略变化只影响新握手。
  • 对 TLS 1.3 使用 ssl_ciphers 的语法或名称，意外拒绝所有预期套件。

关联参数

ssl_ciphers · ssl_min_protocol_version · ssl_max_protocol_version · ssl_prefer_server_ciphers · ssl_groups

参考资料

2.37 - superuser_reserved_connections

superuser_reserved_connections 定义为超级用户保留的连接槽数量。
说明

Fact — 官方简述译文：设置为超级用户保留的连接槽数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值3
3

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 3 — 3

机制详解

superuser_reserved_connections：设置为超级用户保留的连接槽数量。普通槽位与 reserved_connections 容量耗尽后，只有超级用户能使用这些槽位，从而保留应急入口。

superuser_reserved_connections 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

reserved_connections 与 superuser_reserved_connections 从 max_connections 中划出特权层；连接池、监控、复制、维护与故障转移必须共同纳入同一后端总预算。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在 max_connections 总量内，按独立应急主体数量、连接池行为与故障转移操作确定 superuser_reserved_connections；测试普通连接饱和后管理入口仍可用。
OLAP 为重型分析会话之外的控制、监控与取消预留足够槽位，但不要让预留吞噬本就较小后端池的过高比例。
小规格 让 superuser_reserved_connections 相对 max_connections 保持适度，同时至少保留一条经过测试的应急路径；饱和时预留槽不会供普通客户端使用。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 10 不同于 boot 值 10
OLAP 10 不同于 boot 值 10
CRIT 10 不同于 boot 值 10
TINY 10 不同于 boot 值 10
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 10 (dcs)；OLAP: PG9.0–19 Beta 3 = 10 (dcs)；CRIT: PG9.0–19 Beta 3 = 10 (dcs)；TINY: PG9.0–19 Beta 3 = 10 (dcs)。 建议（待人工复核）——编辑推断：十个应急槽在连接池前置服务中提供高于上游的监控、修复与故障转移操作余量。

常见坑

  • 期待重新加载或 SET 激活 superuser_reserved_connections，而它实际需要受控重启服务器。
  • 把预留槽计算在 max_connections 之外，而所有层级实际共享同一总上限。
  • 应急响应预留过少，或预留过多以致饱和时普通应用容量骤降。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 superuser_reserved_connections。

关联参数

listen_addresses · port · max_connections · reserved_connections · unix_socket_directories

参考资料

2.38 - tcp_keepalives_count

tcp_keepalives_count 定义 TCP keepalive 的最大重传次数。
说明

Fact — 官方简述译文：设置 TCP keepalive 的最大重传次数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / TCP Settings
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

tcp_keepalives_count：设置 TCP keepalive 的最大重传次数。它与 idle、interval 一起决定多少次未响应探测后判定故障；在支持的平台上，零选择操作系统默认值。

tcp_keepalives_count 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

有效故障发现窗口由 tcp_keepalives_idle、tcp_keepalives_interval 与 tcp_keepalives_count 共同推导，并受操作系统支持及更短网络设备超时约束。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 tcp_keepalives_count 与其他 keepalive 控制联合选择，使总故障发现时间符合负载均衡、故障转移与重试预算，并确认操作系统实现对应套接字选项。
OLAP 长分析连接的 keepalive 应短于中间网络设备的空闲过期时间，但不能激进到因短暂丢包终止健康作业。
小规格 除非实测网络故障模式要求覆盖，否则使用操作系统默认值；应整体调节 idle/interval/count，而不是只调 tcp_keepalives_count。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 tcp_keepalives_count，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 只调一个 keepalive 组成项，却未计算完整空闲加重传故障窗口。
  • 误以为 PostgreSQL 请求值能覆盖不支持的平台，或更短的防火墙与负载均衡空闲策略。
  • 误以为零表示不探测，而它实际选择操作系统默认值。

关联参数

tcp_keepalives_idle · tcp_keepalives_interval · tcp_user_timeout · client_connection_check_interval · authentication_timeout

参考资料

2.39 - tcp_keepalives_idle

tcp_keepalives_idle 定义开始发送 TCP keepalive 前的空闲时间。
说明

Fact — 官方简述译文：设置开始发送 TCP keepalive 前的空闲时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值s
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / TCP Settings
上游分类
最后 boot 值 值0
0 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 s 0 s

机制详解

tcp_keepalives_idle：设置开始发送 TCP keepalive 前的空闲时间。它决定空闲 TCP 连接在首次 keepalive 探测前等待多久；零选择操作系统默认值。

tcp_keepalives_idle 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

有效故障发现窗口由 tcp_keepalives_idle、tcp_keepalives_interval 与 tcp_keepalives_count 共同推导，并受操作系统支持及更短网络设备超时约束。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 tcp_keepalives_idle 与其他 keepalive 控制联合选择，使总故障发现时间符合负载均衡、故障转移与重试预算，并确认操作系统实现对应套接字选项。
OLAP 长分析连接的 keepalive 应短于中间网络设备的空闲过期时间，但不能激进到因短暂丢包终止健康作业。
小规格 除非实测网络故障模式要求覆盖，否则使用操作系统默认值；应整体调节 idle/interval/count，而不是只调 tcp_keepalives_idle。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 tcp_keepalives_idle，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 只调一个 keepalive 组成项，却未计算完整空闲加重传故障窗口。
  • 误以为 PostgreSQL 请求值能覆盖不支持的平台，或更短的防火墙与负载均衡空闲策略。
  • 取值长于网络设备空闲超时，导致 keepalive 尚未探测连接就已被设备丢弃。

关联参数

tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout

参考资料

2.40 - tcp_keepalives_interval

tcp_keepalives_interval 定义 TCP keepalive 重传之间的间隔。
说明

Fact — 官方简述译文：设置 TCP keepalive 重传之间的间隔。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值s
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / TCP Settings
上游分类
最后 boot 值 值0
0 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 s 0 s

机制详解

tcp_keepalives_interval：设置 TCP keepalive 重传之间的间隔。探测开始后，它规定重传间隔，并与 tcp_keepalives_count 共同决定总故障发现时间。

tcp_keepalives_interval 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

有效故障发现窗口由 tcp_keepalives_idle、tcp_keepalives_interval 与 tcp_keepalives_count 共同推导，并受操作系统支持及更短网络设备超时约束。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 tcp_keepalives_interval 与其他 keepalive 控制联合选择，使总故障发现时间符合负载均衡、故障转移与重试预算，并确认操作系统实现对应套接字选项。
OLAP 长分析连接的 keepalive 应短于中间网络设备的空闲过期时间，但不能激进到因短暂丢包终止健康作业。
小规格 除非实测网络故障模式要求覆盖，否则使用操作系统默认值；应整体调节 idle/interval/count，而不是只调 tcp_keepalives_interval。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 tcp_keepalives_interval，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 只调一个 keepalive 组成项，却未计算完整空闲加重传故障窗口。
  • 误以为 PostgreSQL 请求值能覆盖不支持的平台，或更短的防火墙与负载均衡空闲策略。
  • 只调重传间隔，却未结合 tcp_keepalives_count 与总故障发现时间。

关联参数

tcp_keepalives_idle · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout

参考资料

2.41 - tcp_user_timeout

tcp_user_timeout 定义 TCP 用户超时。
说明

Fact — 官方简述译文：设置 TCP 用户超时。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / TCP Settings
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 249d64999615 — Add support TCP user timeout in libpq and the backend server
提交日期 2019-04-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 0 ms 0 ms

机制详解

tcp_user_timeout：设置 TCP 用户超时。在操作系统支持时，它限制已发送数据保持未确认状态的时长；这不同于对空闲连接进行探测的 keepalive。

tcp_user_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按可接受的未确认数据停滞上限设置 tcp_user_timeout，使其短于服务故障转移预算，并测试客户端重试行为。
OLAP 为大结果传输的暂时拥塞留出空间，但应短于不可达对端占用工作进程直至作业窗口结束的时长。
小规格 除非实测半开连接需要边界，否则使用操作系统默认值；依赖前先确认平台支持。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 tcp_user_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 把未确认数据超时与空闲套接字的 keepalive 探测混为一谈。

关联参数

tcp_keepalives_idle · tcp_keepalives_interval · tcp_keepalives_count · client_connection_check_interval · authentication_timeout

参考资料

2.42 - unix_socket_directories

unix_socket_directories 定义创建 Unix 域套接字的目录。
说明

Fact — 官方简述译文：设置创建 Unix 域套接字的目录。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值/var/run/postgresql
/var/run/postgresql

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 c9b0cbe98bd7 — Support having multiple Unix-domain sockets per postmaster.
提交日期 2012-08-10
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 /var/run/postgresql — /var/run/postgresql

机制详解

unix_socket_directories：设置创建 Unix 域套接字的目录。PostgreSQL 启动时在每个所列目录创建套接字与锁文件；在支持的系统上，以 @ 开头的值选择抽象命名空间。

unix_socket_directories 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

Unix 套接字可达性由目录存在性与遍历权限、套接字组和模式、服务器账号及客户端搜索路径共同决定；pg_hba.conf 的 local 记录仍负责认证。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 unix_socket_directories 纳入同一套 Unix 套接字访问策略：选择可信目录、所有者、组成员与权限，并测试本地连接池、监控、备份和管理工具。
OLAP 分析工具采用同一套经评审本地访问边界；只有客户端与操作系统生命周期受管时才新增目录或组。
小规格 保持 unix_socket_directories 简单且最小权限。本地套接字只带来很小的 TCP 开销差异，不应为方便而开放给所有用户。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP /var/run/postgresql, /tmp 不同于 boot 值 '/var/run/postgresql, /tmp'
OLAP /var/run/postgresql, /tmp 不同于 boot 值 '/var/run/postgresql, /tmp'
CRIT /var/run/postgresql, /tmp 不同于 boot 值 '/var/run/postgresql, /tmp'
TINY /var/run/postgresql, /tmp 不同于 boot 值 '/var/run/postgresql, /tmp'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)；OLAP: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)；CRIT: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)；TINY: PG9.3–19 Beta 3 = /var/run/postgresql, /tmp (local)。 建议（待人工复核）——编辑推断：同时提供发行版运行目录与 /tmp，可兼容本地工具，并保留常规托管套接字路径。

常见坑

  • 期待重新加载或 SET 激活 unix_socket_directories，而它实际需要受控重启服务器。
  • 放宽套接字模式，却忽略目录遍历、组成员与 pg_hba.conf local 认证。
  • 加入易失或不存在目录，导致重启后服务器无法启动或本地客户端找错位置。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 unix_socket_directories。

关联参数

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections

参考资料

2.43 - unix_socket_directory

unix_socket_directory：设置创建 Unix 域套接字的目录。实测在档范围为 PG9.0–9.2；最后在档的 PG9.2 启动默认值为 empty string，context 为 postmaster。它在 PG9.3 被移除。
说明

Fact — 官方简述译文：设置创建 Unix 域套接字的目录。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.2
移除版本 PG9.3
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.2 "" — empty string

机制详解

unix_socket_directory：设置创建 Unix 域套接字的目录。该值在服务器启动时固定，修改后必须安排受控重启。 本站在 PG9.0–9.2 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这个单数路径参数指定 Unix 域套接字目录。PG9.3 用 unix_socket_directories 取代它，新参数可用逗号分隔多个位置；套接字所属组与权限仍由其他参数控制。

应与 unix_socket_directories、unix_socket_group、unix_socket_permissions、listen_addresses 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.2 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.2 未修改；OLAP: PG9.0–9.2 未修改；CRIT: PG9.0–9.2 未修改；TINY: PG9.0–9.2 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 unix_socket_directory 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 postmaster context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

unix_socket_directories · unix_socket_group · unix_socket_permissions · listen_addresses

参考资料

2.44 - unix_socket_group

unix_socket_group 定义 Unix 域套接字的所属组。
说明

Fact — 官方简述译文：设置 Unix 域套接字的所属组。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

unix_socket_group 设置文件系统 Unix 域套接字的所属组；所有者仍是 PostgreSQL 服务器账号。空字符串使用该账号默认组，unix_socket_permissions 决定哪些组访问位有效。

它属于 POSTMASTER 上下文，更改需要重启，并作用于启动时重建的套接字。目录所有权与遍历权限、组成员以及 pg_hba.conf local 记录仍是独立访问层。

Windows 不支持并会忽略该参数。对 unix_socket_directories 中以 @ 开头的 Linux 抽象命名空间套接字也会忽略，因为它们没有文件系统所有者或组。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有本地工具确需套接字可达时才选择专用操作系统组，审计组成员，并与 0770 类套接字及目录权限配合；另行测试 pg_hba.conf 认证。
OLAP 分析工具应加入同一经评审本地访问组或使用 TCP/TLS；不要为了方便创建宽泛组。
小规格 除非受管本地客户端需要其他组，否则使用服务器账号默认组。Windows 或抽象套接字会忽略本 GUC，应改为配置实际生效的访问边界。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重载改变套接字所有权；只有服务器重启时才重建套接字。
  • 在 Windows 或抽象命名空间套接字上依赖本参数，而它会被忽略。
  • 授予套接字组成员资格，却未另行实施 pg_hba.conf 认证与数据库权限。
  • 更改套接字组，但目录遍历权限仍阻止预期客户端访问。

关联参数

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

2.45 - unix_socket_permissions

unix_socket_permissions 定义 Unix 域套接字的访问权限。
说明

Fact — 官方简述译文：设置 Unix 域套接字的访问权限。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 511
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Connections and Authentication / Connection Settings
上游分类
最后 boot 值 值511
511

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 511 — 511

机制详解

unix_socket_permissions 设置文件系统 Unix 域套接字的 chmod 风格模式，八进制写法需要前导零。对套接字而言，只有写权限位控制能否连接；读与执行位不会提供有意义的额外套接字访问。

它属于 POSTMASTER 上下文，只有服务器重启重建套接字时模式才改变。目录遍历权限与 unix_socket_group 可形成额外本地边界，而 pg_hba.conf local 记录仍独立认证数据库用户。

抽象命名空间套接字没有文件系统权限，因此以 @ 开头的套接字条目会忽略本参数。某些操作系统也完全忽略套接字模式；不能把该模式描述成目录权限或 pg_hba.conf 的可移植替代。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有本地操作系统成员资格是有意的第一道边界时才使用 0770 或 0700，并验证目录权限与 pg_hba.conf 仍实施预期策略。pg_hba.conf 为权威时，可移植默认 0777 也可能合理。
OLAP 分析工具采用同一本地策略。不要为解决缺失组或目录部署而放宽模式，应修复操作系统身份路径。
小规格 选择平台支持的最简单模式，并在重启后测试。对抽象套接字或忽略套接字模式的系统，应在适用时通过目录选择与 pg_hba.conf 实施访问。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 写成十进制 770 而非八进制 0770，得到意外的数字模式。
  • 期待读或执行位控制套接字连接访问；只有写权限位有意义。
  • 在抽象命名空间套接字或忽略套接字权限的操作系统上依赖该模式。
  • 把严格套接字模式当作 pg_hba.conf 认证、角色权限或目录遍历控制的替代品。

关联参数

listen_addresses · port · max_connections · reserved_connections · superuser_reserved_connections · unix_socket_directories

参考资料

3 - 自定义选项

Customized Options 分类下的 1 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

3.1 - custom_variable_classes

custom_variable_classes：设置已知自定义变量类别的列表。实测在档范围为 PG9.0–9.1；最后在档的 PG9.1 启动默认值为 not set，context 为 sighup。它在 PG9.2 被移除。
说明

Fact — 官方简述译文：设置已知自定义变量类别的列表。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Customized Options
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.1
移除版本 PG9.2
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.1 — — not set

机制详解

custom_variable_classes：设置已知自定义变量类别的列表。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG9.0–9.1 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

旧版本要求扩展或应用预先声明允许使用的自定义 GUC 前缀。PG9.2 移除了这套注册机制；现代服务器接受任意两段式自定义名称，并可在定义它的扩展加载前保留尚未识别的占位值。

应与 shared_preload_libraries、session_preload_libraries、config_file、allow_alter_system 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.1 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.1 未修改；OLAP: PG9.0–9.1 未修改；CRIT: PG9.0–9.1 未修改；TINY: PG9.0–9.1 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 custom_variable_classes 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

shared_preload_libraries · session_preload_libraries · config_file · allow_alter_system

参考资料

4 - 开发者选项

Developer Options 分类下的 27 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

4.1 - allow_in_place_tablespaces

allow_in_place_tablespaces：允许在 pg_tblspc 内直接创建 tablespace，用于测试。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许在 pg_tblspc 内直接创建 tablespace，用于测试。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 7bdbbb87340f — Allow “in place” tablespaces.
提交日期 2022-07-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 off — off

机制详解

allow_in_place_tablespaces 允许超级用户用空 location 把 tablespace 直接建在 pg_tblspc 下，而不是使用指向外部位置的正常符号链接；它用于同机测试主备实例。

这种目录布局违反备份与 tablespace 管理工具的常规假设，因为工具通常期望 pg_tblspc 条目是链接；它也不会让同位置 tablespace 成为独立存储。

该开关在特权 CREATE TABLESPACE 操作时读取，不是性能参数。关闭后，以这种方式创建的对象仍可能留存。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 allow_in_place_tablespaces 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 allow_in_place_tablespaces 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 allow_in_place_tablespaces 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 allow_in_place_tablespaces 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

data_directory · wal_level · hot_standby · archive_mode

参考资料

4.2 - allow_system_table_mods

allow_system_table_mods：允许修改系统表的结构。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许修改系统表的结构。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

allow_system_table_mods 解除系统目录结构修改保护，并允许其他通常禁止的目录操作；仅有超级用户身份通常也不能执行这些动作。

目录定义与 PostgreSQL 代码、缓存描述、bootstrap 数据、WAL 和升级假设紧密耦合；表面合法的 ALTER 也可能造成不可逆损坏或数据丢失。

该参数用于 PostgreSQL 开发、bootstrap 与严格受控工具，不是受支持的扩展机制；扩展应使用公开目录与 hook 接口。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 绝不能用 allow_system_table_mods 做性能调优。只限 PostgreSQL 开发或有已验证备份与精确回滚路径的可丢弃维护流程。
OLAP 负载类型不会降低 allow_system_table_mods 的目录损坏风险；分析系统同样必须关闭。
小规格 保持 allow_system_table_mods=off。没有预备环境不等于可以在唯一数据副本上实验。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 allow_system_table_mods 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

allow_in_place_tablespaces · ignore_system_indexes · zero_damaged_pages · wal_consistency_checking

参考资料

4.3 - backtrace_functions

backtrace_functions：当指定函数中发生错误时记录调用栈。实测在档范围为 PG13–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 empty string，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：当指定函数中发生错误时记录调用栈。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 71a8a4f6e365 — Add backtrace support for error reporting
提交日期 2019-11-08
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 "" — empty string

机制详解

backtrace_functions 是内部 C 函数名的逗号分隔列表。错误起源函数命中列表时，PostgreSQL 会在服务器日志中的错误后附加原生调用栈。

它匹配 C 符号而非 SQL 函数名。是否可用以及符号质量取决于平台、编译器、构建参数、调试信息与函数内联。

该设置可只针对狭窄故障路径，而无需为所有错误记录栈。调用栈会暴露实现细节并增加日志量，因此应限定范围并保护日志。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 backtrace_functions 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 backtrace_functions 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 backtrace_functions 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 backtrace_functions 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

log_error_verbosity · log_min_error_statement · compute_query_id · log_line_prefix

参考资料

4.4 - debug_discard_caches

debug_discard_caches：为调试而激进地使系统目录缓存失效。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：为调试而激进地使系统目录缓存失效。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值0 – 0
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 6201fa3c166f — Rename debug_invalidate_system_caches_always to debug_discard_caches.
提交日期 2021-07-13
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 0 — 0

机制详解

debug_discard_caches 在最早时机使系统目录缓存条目失效；更高值会递归执行。非零值会让服务器极慢，用于暴露缓存失效 bug。

只有以 DISCARD_CACHES_ENABLED 构建时才支持，通常随 –enable-cassert 自动启用；生产构建保持零并拒绝修改。

该参数测试病态缓存抖动下的正确性，不会刷新 shared_buffers、操作系统页缓存或普通查询结果缓存。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 debug_discard_caches 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 debug_discard_caches 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 debug_discard_caches 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 debug_discard_caches 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

ignore_system_indexes · shared_buffers · debug_parallel_query · allow_system_table_mods

参考资料

4.5 - debug_io_direct

debug_io_direct：为指定文件访问使用直接 I/O。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 empty string，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：为指定文件访问使用直接 I/O。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 319bae9a8da6 — Rename io_direct to debug_io_direct.
提交日期 2023-05-15
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 "" — empty string

机制详解

debug_io_direct 为选定操作请求绕过缓存的文件访问，可选 data、wal 与 wal_init；PostgreSQL 依平台映射到 O_DIRECT、F_NOCACHE 或 FILE_FLAG_NO_BUFFERING。

空字符串关闭直接 I/O。不支持的内核或文件系统可能拒绝启动或在操作时失败，且对齐要求依平台不同。

PostgreSQL 文档明确把当前非默认用法描述为会降低性能的开发测试。它不同于 PG18 异步 I/O 方法，不应作为生产缓存策略。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 debug_io_direct 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 debug_io_direct 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 debug_io_direct 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 debug_io_direct 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

io_method · io_max_concurrency · wal_sync_method · shared_buffers · backend_flush_after

参考资料

4.6 - debug_logical_replication_streaming

debug_logical_replication_streaming：强制大型事务立即流式发送或序列化变更。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 buffered，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：强制大型事务立即流式发送或序列化变更。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值buffered, immediate
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值buffered
buffered

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 39d4207e876f — Rename logical_replication_mode to debug_logical_replication_streaming
提交日期 2023-08-29
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 buffered — buffered

机制详解

debug_logical_replication_streaming 强制大型事务逻辑复制路径立即流式发送或序列化，而不是等待正常缓冲阈值；buffered 是生产行为。

发布端 immediate 会在订阅启用 streaming 时逐项流出，否则逐项序列化，从而绕过 logical_decoding_work_mem 触发；并行订阅端则强制写文件，而不是正常共享内存队列。

因此发布端与订阅端会覆盖不同代码路径。它是回归与故障复现控制，不是延迟或内存调优捷径。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 debug_logical_replication_streaming 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 debug_logical_replication_streaming 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 debug_logical_replication_streaming 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 debug_logical_replication_streaming 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

logical_decoding_work_mem · max_logical_replication_workers · max_sync_workers_per_subscription · wal_level

参考资料

4.7 - debug_parallel_query

debug_parallel_query：为测试而强制规划器使用并行查询节点。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：为测试而强制规划器使用并行查询节点。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值off, on, regress
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 5352ca22e001 — Rename force_parallel_mode to debug_parallel_query
提交日期 2023-02-15
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 off — off

机制详解

debug_parallel_query 即使预计没有性能收益，也会强制安全查询进入并行模式。on 会在安全时添加顶层 Gather；regress 还会隐藏测试专用输出差异。

并行安全限制仍然适用。强制上下文可暴露被错误标为 parallel safe 的函数；即便最终没有可用 worker，也可能禁止子事务等操作。

它在 PG16 取代旧名称 force_parallel_mode，用于回归测试，不是让生产查询变快或绕过所有并行成本决策。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 debug_parallel_query 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 debug_parallel_query 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 debug_parallel_query 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 debug_parallel_query 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

force_parallel_mode · max_parallel_workers_per_gather · max_parallel_workers · parallel_setup_cost · parallel_leader_participation

参考资料

4.8 - force_parallel_mode

force_parallel_mode：强制使用并行查询设施。实测在档范围为 PG9.6–15；最后在档的 PG15 启动默认值为 off，context 为 user。它在 PG16 被移除。
说明

Fact — 官方简述译文：强制使用并行查询设施。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值off, on, regress
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–15
移除版本 PG16
引入提交 7c944bd90339 — Introduce a new GUC force_parallel_mode for testing purposes.
提交日期 2016-02-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–15 off — off

机制详解

PG15 及以前，force_parallel_mode 会让原本安全的查询在 Gather 下运行，以便即使没有预期加速也测试并行模式行为；regress 会抑制回归测试输出差异。

它不会让不安全查询变安全，并且即使没有 worker 实际运行，也可能施加并行上下文限制；顶层 Gather 是诊断开销，不是计划 hint。

PostgreSQL 16 移除该 GUC，并以 debug_parallel_query 承担测试用途。升级配置必须删除旧名称，也不应在生产中自动开启替代项。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前 PostgreSQL 不应配置 force_parallel_mode。升级时删除；即使存在后继参数，也只能用于同类受控开发测试，不能成为生产默认。
OLAP 分析负载不能成为保留已移除 force_parallel_mode 的理由；当前版本应使用受支持 EXPLAIN、日志或文档化替代项诊断。
小规格 现代配置中删除 force_parallel_mode。未知参数导致的启动失败与诊断开销远大于历史用途。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG15 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–15 未修改；OLAP: PG9.6–15 未修改；CRIT: PG9.6–15 未修改；TINY: PG9.6–15 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 force_parallel_mode 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

debug_parallel_query · max_parallel_workers_per_gather · max_parallel_workers · parallel_setup_cost

参考资料

4.9 - ignore_checksum_failure

ignore_checksum_failure：校验和失败后仍继续处理。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：校验和失败后仍继续处理。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 96ef3b8ff1cf — Allow I/O reliability checks using 16-bit checksums
提交日期 2013-03-22
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 off — off

机制详解

启用数据校验和时，页面校验和不匹配通常会中止当前事务；ignore_checksum_failure 改为警告，并在页面头仍合理时尝试继续。

它不会修复页面，也不能证明剩余元组有效。继续处理可能崩溃、隐藏或传播损坏；页面头损坏仍会阻止访问。

唯一可辩护用途是在存储与备份恢复手段耗尽后，从不可变副本中受控抢救数据。该模式下每次读取都是可疑证据，不代表完整性已恢复。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 绝不能把 ignore_checksum_failure 当作调优或常态可用性设置。应停止写入、保全不可变副本、用尽备份/存储修复、记录预期数据损失、窄范围抢救、重建并验证后才可恢复服务。
OLAP 只读分析也不会让 ignore_checksum_failure 安全：损坏页面仍会污染结果或结构。只能在可丢弃抢救副本上使用，并明确接受数据丢失。
小规格 不能因为没有副本就直接启用 ignore_checksum_failure。先保全原件并寻找干净备份；该开关可能把可见损坏变成静默丢失。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 ignore_checksum_failure 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

zero_damaged_pages · ignore_invalid_pages · data_checksums · wal_consistency_checking

参考资料

4.10 - ignore_invalid_pages

ignore_invalid_pages：恢复遇到无效页面引用后仍继续。实测在档范围为 PG13–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：恢复遇到无效页面引用后仍继续。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 41c184bc642b — Add GUC ignore_invalid_pages.
提交日期 2020-01-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 off — off

机制详解

恢复期间，WAL 引用无效页面通常会触发 PANIC 并停止恢复；ignore_invalid_pages 改为记录警告并跳过该引用继续。

这是仅启动时设置，只在恢复或备库模式有效。跳过 redo 会丢数据、传播损坏，并可能让结构内部不一致，即使服务器最终能启动。

它是在保全证据并用尽正确恢复路径后的紧急抢救机制。通过它启动的服务器不能视为健康，也不能直接提升投入正常服务。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 绝不能把 ignore_invalid_pages 当作调优或常态可用性设置。应停止写入、保全不可变副本、用尽备份/存储修复、记录预期数据损失、窄范围抢救、重建并验证后才可恢复服务。
OLAP 只读分析也不会让 ignore_invalid_pages 安全：损坏页面仍会污染结果或结构。只能在可丢弃抢救副本上使用，并明确接受数据丢失。
小规格 不能因为没有副本就直接启用 ignore_invalid_pages。先保全原件并寻找干净备份；该开关可能把可见损坏变成静默丢失。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 ignore_invalid_pages 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

ignore_checksum_failure · zero_damaged_pages · restore_command · wal_consistency_checking

参考资料

4.11 - ignore_system_indexes

ignore_system_indexes：读取系统表时忽略系统索引。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 backend。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：读取系统表时忽略系统索引。

身份

类型 值bool
上游 pg_settings 类型
Context 值backend
后端启动时固定
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

ignore_system_indexes 让新启动后端读取系统目录时不使用系统索引，但修改目录时仍更新索引；用于从损坏的系统索引中恢复。

其 backend 上下文在会话启动时固定，因此在现有会话内修改无效；目录扫描可能变得很慢。

该模式不会修复索引，只是提供检查数据并 REINDEX 损坏系统索引的路径。长期启用会掩盖症状并造成广泛目录开销。其 backend 上下文在连接启动时固定，现有会话不能修改。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 绝不能把 ignore_system_indexes 当作调优或常态可用性设置。应停止写入、保全不可变副本、用尽备份/存储修复、记录预期数据损失、窄范围抢救、重建并验证后才可恢复服务。
OLAP 只读分析也不会让 ignore_system_indexes 安全：损坏页面仍会污染结果或结构。只能在可丢弃抢救副本上使用，并明确接受数据丢失。
小规格 不能因为没有副本就直接启用 ignore_system_indexes。先保全原件并寻找干净备份；该开关可能把可见损坏变成静默丢失。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 ignore_system_indexes 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

allow_system_table_mods · ignore_checksum_failure · zero_damaged_pages · shared_buffers

参考资料

4.12 - jit_debugging_support

jit_debugging_support：向调试器注册 JIT 生成的函数。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser-backend。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：向调试器注册 JIT 生成的函数。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser-backend
超级用户后端启动时固定
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 250bca7fc145 — Debugging and profiling support for LLVM JIT provider.
提交日期 2018-03-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 off — off

机制详解

jit_debugging_support 在 LLVM 与平台具备所需 listener 接口时，把 JIT 生成函数注册给 GDB，以改善调试器中的符号可见性。

该值在后端启动时固定，并不会开启 JIT；查询仍需 jit、可用 provider 与成本阈值才会生成代码。

注册会增加开发插桩，只在调试 JIT 内部或生成代码时有用，不是查询性能功能。其 superuser-backend 上下文在连接启动时固定，并限制可设置角色。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 jit_debugging_support 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 jit_debugging_support 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 jit_debugging_support 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 jit_debugging_support 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

jit · jit_above_cost · jit_dump_bitcode · jit_profiling_support · jit_expressions

参考资料

4.13 - jit_dump_bitcode

jit_dump_bitcode：将 LLVM 位码写盘以便调试 JIT。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：将 LLVM 位码写盘以便调试 JIT。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 b96d550eb03c — Support for optimizing and emitting code in LLVM JIT provider.
提交日期 2018-03-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 off — off

机制详解

jit_dump_bitcode 会把实际执行 JIT 的查询所生成 LLVM IR/位码写到 data_directory，用于检查和复现 JIT 编译器行为。

它不会开启 JIT；没有查询越过 JIT 门槛时不会产生文件。生成物会累积、消耗磁盘，并可能包含来自执行表达式的细节。

只有严格受控的调试会话才应启用；文件需要显式收集与清理。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 jit_dump_bitcode 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 jit_dump_bitcode 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 jit_dump_bitcode 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 jit_dump_bitcode 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

jit · jit_above_cost · jit_debugging_support · jit_profiling_support · data_directory

参考资料

4.14 - jit_expressions

jit_expressions：允许 JIT 编译表达式。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许 JIT 编译表达式。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 2a0faed9d702 — Add expression compilation support to LLVM JIT provider.
提交日期 2018-03-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 on — on

机制详解

jit_expressions 控制查询已经越过顶层 JIT 成本门槛后，表达式求值是否进行 JIT 编译；它本身不会激活 JIT。

关闭后表达式保持解释执行，其他符合条件的 JIT 工作仍可能发生，可用于隔离表达式代码生成的正确性或编译开销。

该设置是开发诊断项，不是常规 JIT 调优方式；生产选择应由 jit_above_cost 与顶层 jit 开关控制。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 jit_expressions 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 jit_expressions 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 jit_expressions 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 jit_expressions 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

jit · jit_above_cost · jit_tuple_deforming · jit_inline_above_cost · jit_optimize_above_cost

参考资料

4.15 - jit_profiling_support

jit_profiling_support：向 perf 分析器注册 JIT 生成的函数。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser-backend。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：向 perf 分析器注册 JIT 生成的函数。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser-backend
超级用户后端启动时固定
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 250bca7fc145 — Debugging and profiling support for LLVM JIT provider.
提交日期 2018-03-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 off — off

机制详解

jit_profiling_support 在 LLVM 支持可用时输出注册数据，让 Linux perf 能把采样归因到 JIT 生成函数；文件写在服务器用户的 ~/.debug/jit 目录。

该值在后端启动时固定，并不会开启 JIT；只有越过正常门槛并生成代码的查询才受影响。

PostgreSQL 不会自动清理 profiling 文件。长时间或繁忙系统会累积可能敏感的生成物并消耗磁盘。其 superuser-backend 上下文在连接启动时固定，并限制可设置角色。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 jit_profiling_support 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 jit_profiling_support 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 jit_profiling_support 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 jit_profiling_support 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

jit · jit_above_cost · jit_debugging_support · jit_dump_bitcode · data_directory

参考资料

4.16 - jit_tuple_deforming

jit_tuple_deforming：允许 JIT 编译元组拆解。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许 JIT 编译元组拆解。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 32af96b2b118 — JIT tuple deforming in LLVM JIT provider.
提交日期 2018-03-26
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 on — on

机制详解

jit_tuple_deforming 控制查询越过主 JIT 门槛后，是否 JIT 编译从 PostgreSQL 堆元组提取属性的代码。

关闭后元组拆解保持解释执行，表达式 JIT 与其他编译仍可活动，可用于隔离该编译路径的正确性与开销。

它不是适用于每次扫描的独立性能开关；元组布局、所选列、行数、jit_above_cost 与总编译时间共同决定效果。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 jit_tuple_deforming 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 jit_tuple_deforming 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 jit_tuple_deforming 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 jit_tuple_deforming 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

jit · jit_above_cost · jit_expressions · jit_inline_above_cost · cpu_tuple_cost

参考资料

4.17 - post_auth_delay

post_auth_delay：设置连接认证完成后的调试等待时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 s，context 为 backend。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置连接认证完成后的调试等待时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值backend
后端启动时固定
单位 值s
原始单位
范围 值0 – 2147
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值0
0 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 s 0 s

机制详解

post_auth_delay 在认证成功后暂停新后端，让开发者有时间附加调试器；零关闭等待。

该 backend 上下文值在会话启动时固定。此时认证已完成，所以休眠期间会话与服务器资源已经分配。

它会有意增加连接延迟，并在连接风暴时占用后端名额；不是节流、安全或连接池控制。其 backend 上下文在连接启动时固定，现有会话不能修改。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 post_auth_delay 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 post_auth_delay 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 post_auth_delay 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 post_auth_delay 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

pre_auth_delay · authentication_timeout · max_connections · log_connections

参考资料

4.18 - pre_auth_delay

pre_auth_delay：设置连接认证开始前的调试等待时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置连接认证开始前的调试等待时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值0 – 60
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值0
0 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 s 0 s

机制详解

pre_auth_delay 在新服务器进程 fork 后、认证前暂停，让开发者附加调试器检查握手与认证代码；零关闭。

该 SIGHUP 设置作用于之后的新连接。进程休眠时客户端尚未认证，但服务器进程与连接名额可能已被占用。

它会有意延迟所有受影响连接，并可能放大拒绝服务风险；不能替代 authentication_timeout 或网络限流。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 pre_auth_delay 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 pre_auth_delay 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 pre_auth_delay 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 pre_auth_delay 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

post_auth_delay · authentication_timeout · max_connections · trace_connection_negotiation

参考资料

4.19 - remove_temp_files_after_crash

remove_temp_files_after_crash：控制后端崩溃后是否删除临时文件。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：控制后端崩溃后是否删除临时文件。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 cd91de0d1795 — Remove temporary files after backend crash
提交日期 2021-03-18
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 on — on

机制详解

后端崩溃后，remove_temp_files_after_crash 控制 PostgreSQL 是否删除失败进程遗留的临时文件；on 是正常清理行为。

关闭可保留取证材料，但反复故障会累积无用文件并写满临时文件所在文件系统。

该设置不会防止崩溃、恢复查询状态，也不会让普通临时表可重用。任何取证保留都需要显式空间监控与后续清理。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 remove_temp_files_after_crash 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 remove_temp_files_after_crash 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 remove_temp_files_after_crash 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 remove_temp_files_after_crash 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

temp_file_limit · temp_tablespaces · log_temp_files · send_abort_for_crash

参考资料

4.20 - send_abort_for_crash

send_abort_for_crash：后端崩溃后向其他子进程发送 SIGABRT 而非 SIGQUIT。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：后端崩溃后向其他子进程发送 SIGABRT 而非 SIGQUIT。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 51b5834cd53f — Provide options for postmaster to kill child processes with SIGABRT.
提交日期 2022-11-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 off — off

机制详解

一个后端崩溃后，postmaster 通常用 SIGQUIT 要求其他子进程退出；send_abort_for_crash 改发 SIGABRT，使这些同伴进程通常生成 core dump。

dump 捕获事故附近的同伴状态，不只是最初崩溃进程；反复崩溃可能因此产生大量大型 core 文件。

PostgreSQL 不自动清理 core。启用前必须配置 OS core 限制、存储容量、隐私保护与收集流程。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 send_abort_for_crash 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 send_abort_for_crash 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 send_abort_for_crash 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 send_abort_for_crash 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

send_abort_for_kill · remove_temp_files_after_crash · log_error_verbosity · data_directory

参考资料

4.21 - send_abort_for_kill

send_abort_for_kill：终止卡住的子进程时发送 SIGABRT 而非 SIGKILL。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：终止卡住的子进程时发送 SIGABRT 而非 SIGKILL。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 51b5834cd53f — Provide options for postmaster to kill child processes with SIGABRT.
提交日期 2022-11-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 off — off

机制详解

子进程收到 SIGQUIT 五秒后仍未退出时，postmaster 通常升级为 SIGKILL；send_abort_for_kill 改用 SIGABRT，使卡住进程通常写 core dump。

SIGABRT 提供取证状态，但会消耗时间与磁盘，可能延迟崩溃恢复；在所有故障模式下也不保证像 SIGKILL 一样迅速终止。

PostgreSQL 不清理生成的 core；OS 策略与监控必须防止反复卡死进程写满存储。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 send_abort_for_kill 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 send_abort_for_kill 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 send_abort_for_kill 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 send_abort_for_kill 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

send_abort_for_crash · remove_temp_files_after_crash · log_error_verbosity · data_directory

参考资料

4.22 - trace_connection_negotiation

trace_connection_negotiation：记录认证前连接握手的详细信息。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：记录认证前连接握手的详细信息。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 705843d294d5 — Enhance libpq encryption negotiation tests with new GUC
提交日期 2024-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 off — off

机制详解

trace_connection_negotiation 记录认证前连接协商路径的细节，可在普通认证日志尚不可用时为协议、加密与握手调试提供证据。

它是服务器启动参数，启用后会在下次重启前影响全集群后续连接握手；不会改变认证规则，也不会让失败协商自动成功。

握手日志可能量大，并暴露网络或客户端能力细节。应在受控复现中使用并保护生成的服务器日志。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 trace_connection_negotiation 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 trace_connection_negotiation 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 trace_connection_negotiation 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 trace_connection_negotiation 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

log_connections · authentication_timeout · ssl · pre_auth_delay · log_error_verbosity

参考资料

4.23 - trace_notify

trace_notify：为 LISTEN 和 NOTIFY 生成调试输出。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：为 LISTEN 和 NOTIFY 生成调试输出。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

trace_notify 为 LISTEN 与 NOTIFY 输出大量内部调试消息；只有 client_min_messages 或 log_min_messages 包含 DEBUG1 或更低级别时才可见。

它追踪实现活动，并不是通知 payload 的持久审计；额外消息量可能远大于应用通知流。

应只在受控会话中复现队列与投递 bug。队列容量与清理由 max_notify_queue_pages 和监听者事务行为另行控制。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 trace_notify 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 trace_notify 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 trace_notify 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 trace_notify 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

max_notify_queue_pages · notify_buffers · client_min_messages · log_min_messages · track_activities

参考资料

4.24 - trace_recovery_messages

trace_recovery_messages：控制恢复相关调试消息的日志级别。实测在档范围为 PG9.0–16；最后在档的 PG16 启动默认值为 log，context 为 sighup。它在 PG17 被移除。
说明

Fact — 官方简述译文：控制恢复相关调试消息的日志级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值log
log

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–16
移除版本 PG17
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–16 log — log

机制详解

PG16 及以前，trace_recovery_messages 会把达到所选严重级别的恢复 DEBUG 消息重新映射为 LOG，使通常隐藏的恢复内部信息在测试时可见。

它只改变消息可见性，不改变恢复决策、WAL 重放顺序或持久性；详细恢复日志可能极大并影响时序。

PostgreSQL 17 移除该参数。升级配置必须删除；当前恢复诊断应使用受支持日志、进度与 WAL 检查工具。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前 PostgreSQL 不应配置 trace_recovery_messages。升级时删除；即使存在后继参数，也只能用于同类受控开发测试，不能成为生产默认。
OLAP 分析负载不能成为保留已移除 trace_recovery_messages 的理由；当前版本应使用受支持 EXPLAIN、日志或文档化替代项诊断。
小规格 现代配置中删除 trace_recovery_messages。未知参数导致的启动失败与诊断开销远大于历史用途。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG16 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–16 未修改；OLAP: PG9.0–16 未修改；CRIT: PG9.0–16 未修改；TINY: PG9.0–16 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 trace_recovery_messages 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

log_min_messages · restore_command · recovery_min_apply_delay · wal_consistency_checking

参考资料

4.25 - trace_sort

trace_sort：输出排序操作的资源使用信息。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：输出排序操作的资源使用信息。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

trace_sort 为排序操作输出内部资源消息，包括内存、run 生成、归并轮次与计时细节，主要供 PostgreSQL 开发者使用。

它是诊断日志，不等同于 EXPLAIN 的 Sort Method 或 log_temp_files；在排序密集负载上会产生大量消息。

该开关不会改变 work_mem、排序算法或落盘阈值。应限定在复现场景，并配合能够实际捕获输出的日志级别。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 trace_sort 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 trace_sort 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 trace_sort 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 trace_sort 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

work_mem · log_temp_files · enable_sort · temp_file_limit · log_min_messages

参考资料

4.26 - wal_consistency_checking

wal_consistency_checking：设置要执行 WAL 一致性检查的资源管理器。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 empty string，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置要执行 WAL 一致性检查的资源管理器。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 a507b86900f6 — Add WAL consistency checking facility.
提交日期 2017-02-08
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 "" — empty string

机制详解

wal_consistency_checking 指定要验证 redo 例程的 WAL 资源管理器。对选中记录，PostgreSQL 会加入完整页面镜像，并在重放后把结果缓冲区与镜像比较。

意外差异会以致命错误终止恢复；hint bit 等已知非确定差异会特殊处理。all 会启用所有受支持资源管理器。

附加完整页面镜像会大幅增加 WAL 量与重放工作。该功能查找 redo 实现 bug，不是通用磁盘校验和、备份验证或损坏修复工具。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要用 wal_consistency_checking 调优生产 OLTP。只在有负责人、日志/磁盘预算、回滚条件与取证计划的限时复现中启用，完成后立即恢复默认。
OLAP 长分析任务会放大 wal_consistency_checking 的调试开销与生成物。应优先使用标准 EXPLAIN 与统计，并把开发实验与普通用户隔离。
小规格 让 wal_consistency_checking 保持上游默认。小主机没有足够 CPU、磁盘、连接与日志余量承担开发插桩，更不适合长时间开启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 wal_consistency_checking 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

full_page_writes · wal_log_hints · ignore_invalid_pages · ignore_checksum_failure · wal_level

参考资料

4.27 - zero_damaged_pages

zero_damaged_pages：遇到损坏页面头时把内存中的页面清零后继续。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：遇到损坏页面头时把内存中的页面清零后继续。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Developer Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

PostgreSQL 检测到损坏页面头时，zero_damaged_pages 会在内存中替换为全零页、发出警告并继续；原页面上的每一行都会从抢救读取中丢失。

零页不会自动强制写盘，因此继续使用该关系会产生不一致行为；抢救后必须重建表或索引。

这是备份与存储恢复手段耗尽后的最后数据提取开关。必须在已保全副本上窄范围使用，并在完成后立即关闭。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 绝不能把 zero_damaged_pages 当作调优或常态可用性设置。应停止写入、保全不可变副本、用尽备份/存储修复、记录预期数据损失、窄范围抢救、重建并验证后才可恢复服务。
OLAP 只读分析也不会让 zero_damaged_pages 安全：损坏页面仍会污染结果或结构。只能在可丢弃抢救副本上使用，并明确接受数据丢失。
小规格 不能因为没有副本就直接启用 zero_damaged_pages。先保全原件并寻找干净备份；该开关可能把可见损坏变成静默丢失。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 限时诊断或恢复任务结束后仍让 zero_damaged_pages 保持启用。
  • 在生产数据的唯一副本上进行实验。
  • 低估日志、core、临时文件、WAL、CPU 或连接名额放大。
  • 把服务器能启动或查询能完成误当作数据与行为正确的证明。

关联参数

ignore_checksum_failure · ignore_invalid_pages · data_checksums · wal_consistency_checking

参考资料

5 - 错误处理

Error Handling 分类下的 4 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

5.1 - data_sync_retry

data_sync_retry：设置数据文件同步失败后是否继续运行。实测在档范围为 PG9.4–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置数据文件同步失败后是否继续运行。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Error Handling
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 f1ff5f51d249 — PANIC on fsync() failure.
提交日期 2018-11-19
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 off — off

机制详解

设置数据文件同步失败后是否继续运行。该值在服务器启动时固定，修改后必须重启。

数据文件 fsync 失败后，默认认为 shared buffers 可能已经不一致并触发 PANIC，让崩溃恢复重建状态。继续运行可能丢失对脏页的认知，只适合内核同步语义能保证安全重试的特定平台。

应把 data_sync_retry 与 restart_after_crash、recovery_init_sync_method、fsync 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据故障模型与实际观测决定是否修改 data_sync_retry；先做会话/测试环境验证，再按 context 安全部署并保留回滚值。
OLAP 在长查询、批任务和峰值并发下单独验证，避免把 OLTP 经验直接套用到分析节点。
小规格 没有明确问题就保持默认；小规格环境更应避免以全局兼容性或故障策略换取微小收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在 fsync 失败会丢失脏页认知的平台上开启。
  • 不隔离坏存储就把 I/O 错误当成暂时故障。
  • 为表面可用性牺牲数据正确性。
  • 把 data_sync_retry 的启动默认值误当成当前有效值。
  • 忽略 postmaster context 对生效时机的约束。

关联参数

restart_after_crash · recovery_init_sync_method · fsync · full_page_writes · exit_on_error

参考资料

5.2 - exit_on_error

exit_on_error：发生任何错误后终止会话。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：发生任何错误后终止会话。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Error Handling
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 不作断言：名称在 2008 Git 历史边界已经存在
提交日期 ≤ 2008-01-01
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

exit_on_error 这个名称在本项目 2008 年 Git 历史边界以及 PG9.0 源码的 GUC 表中已经存在。PG9.0 为它设置 GUC_NO_SHOW_ALL，因此该版 pg_settings 快照看不到它；PG9.1 的首次观测表示可见性变化，并不声称底层行为发明于 PG9.1。

启用后，任何错误都会在正常错误处理后终止整个后端会话，而不只是当前事务。它不同于 psql ON_ERROR_STOP 等客户端侧遇错停止行为，可能意外丢失会话状态、预备语句、临时对象以及应用连接。

它具有 user context，可用受控会话测试而无需改变全部连接。应与 restart_after_crash、事务错误处理、连接池重试、statement_timeout 和 idle_in_transaction_session_timeout 联合评估；终止服务器会话不能替代正确的事务恢复。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据故障模型与实际观测决定是否修改 exit_on_error；先做会话/测试环境验证，再按 context 安全部署并保留回滚值。
OLAP 在长查询、批任务和峰值并发下单独验证，避免把 OLTP 经验直接套用到分析节点。
小规格 没有明确问题就保持默认；小规格环境更应避免以全局兼容性或故障策略换取微小收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 exit_on_error 的启动默认值误当成当前有效值。
  • 忽略 user context 对生效时机的约束。
  • 一次改变多个联动参数，无法归因结果。
  • 未在真实故障或负载边界上验证就全局发布。

关联参数

restart_after_crash · statement_timeout · idle_in_transaction_session_timeout · data_sync_retry · recovery_init_sync_method

参考资料

5.3 - recovery_init_sync_method

recovery_init_sync_method：设置崩溃恢复前同步数据目录的方法。它是 PG14–18 的 sighup 参数；最新实测启动默认值为 fsync。
说明

Fact — 官方简述译文：设置崩溃恢复前同步数据目录的方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值fsync, syncfs
非枚举类型记为 —
分类 值Error Handling
上游分类
最后 boot 值 值fsync
fsync

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 61752afb2640 — Provide recovery_init_sync_method=syncfs.
提交日期 2021-03-20
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 fsync — fsync

机制详解

设置崩溃恢复前同步数据目录的方法。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它定义故障发生后的服务器策略；选择会影响可用性与正确性边界。外部 supervisor、存储错误语义和恢复演练必须与该策略一致。

应把 recovery_init_sync_method 与 data_sync_retry、restart_after_crash、fsync 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据故障模型与实际观测决定是否修改 recovery_init_sync_method；先做会话/测试环境验证，再按 context 安全部署并保留回滚值。
OLAP 在长查询、批任务和峰值并发下单独验证，避免把 OLTP 经验直接套用到分析节点。
小规格 没有明确问题就保持默认；小规格环境更应避免以全局兼容性或故障策略换取微小收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 recovery_init_sync_method 的启动默认值误当成当前有效值。
  • 忽略 sighup context 对生效时机的约束。
  • 一次改变多个联动参数，无法归因结果。
  • 未在真实故障或负载边界上验证就全局发布。

关联参数

data_sync_retry · restart_after_crash · fsync · full_page_writes · exit_on_error

参考资料

5.4 - restart_after_crash

restart_after_crash：后端崩溃后重新初始化服务器。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：后端崩溃后重新初始化服务器。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Error Handling
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 5ffaa9005c45 — Add restart_after_crash GUC.
提交日期 2010-07-20
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 on — on

机制详解

后端崩溃后重新初始化服务器。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它定义故障发生后的服务器策略；选择会影响可用性与正确性边界。外部 supervisor、存储错误语义和恢复演练必须与该策略一致。

应把 restart_after_crash 与 data_sync_retry、recovery_init_sync_method、fsync 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据故障模型与实际观测决定是否修改 restart_after_crash；先做会话/测试环境验证，再按 context 安全部署并保留回滚值。
OLAP 在长查询、批任务和峰值并发下单独验证，避免把 OLTP 经验直接套用到分析节点。
小规格 没有明确问题就保持默认；小规格环境更应避免以全局兼容性或故障策略换取微小收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 restart_after_crash 的启动默认值误当成当前有效值。
  • 忽略 sighup context 对生效时机的约束。
  • 一次改变多个联动参数，无法归因结果。
  • 未在真实故障或负载边界上验证就全局发布。

关联参数

data_sync_retry · recovery_init_sync_method · fsync · full_page_writes · exit_on_error · statement_timeout

参考资料

6 - 文件位置

File Locations 分类下的 7 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

6.1 - config_file

config_file：设置服务器主配置文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器主配置文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 — — not set

机制详解

设置服务器主配置文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 config_file 与 allow_alter_system、data_directory、hba_file 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP config_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · data_directory · hba_file · ident_file · external_pid_file · extension_destdir

参考资料

6.2 - data_directory

data_directory：设置服务器数据目录。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器数据目录。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 — — not set

机制详解

设置服务器数据目录。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 data_directory 与 allow_alter_system、config_file、hba_file 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP data_directory 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · hba_file · ident_file · external_pid_file · extension_destdir

参考资料

6.3 - extension_destdir

extension_destdir 是 Debian/PGDG 下游提供的扩展暂存前缀 GUC，实测存在于打包版 PostgreSQL 9.5–17；它从未进入 PostgreSQL 上游，并从 PG18 实测包中消失。
说明

Fact — 实测 pg_settings 简述译文：设置加载扩展时要加在路径前的目录。（实测下游 pg_settings 简述。）

身份

类型 值string
实测下游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
实测下游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–17
移除版本 PG18
引入提交 Debian/PGDG 下游补丁 — Debian-specific extension_destdir patch used for extension build-time testing
提交日期 —
Discussion 下游文档

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–17 "" — empty string

机制详解

版本矩阵证明，Debian/PGDG 二进制从 PG9.5 到 PG17 暴露 extension_destdir。穷尽 PostgreSQL 上游 GUC 源码的 pickaxe 也找不到引入提交，因为该名称来自 Debian 的 extension_destdir 打包补丁，而不是 PostgreSQL 上游源码树。

该补丁在服务器寻找扩展 control/SQL 文件以及函数背后的动态库时，加上类似 DESTDIR 的暂存根目录。Debian 的 pg_virtualenv 用它在文件安装到最终系统路径前测试软件包；它明确服务于打包与构建测试，并不是通用生产扩展搜索路径。

从 PG18 起，应使用上游 extension_control_path 管理 control/SQL 文件，并用 dynamic_library_path 管理共享库，或把扩展安装到标准位置。启动新版本前，要从配置文件、ALTER SYSTEM、角色/数据库设置和生成模板中彻底删除 extension_destdir。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把它视为下游迁移债务，而不是调优项。应以受支持路径打包扩展，用数据库服务账号测试 extension_control_path 与 dynamic_library_path，并在升级 PG18 前删除旧键。
OLAP ETL 与分析扩展栈同样要迁移，包括 worker 和备用库；应按最终文件布局演练 CREATE EXTENSION、ALTER EXTENSION UPDATE、恢复与故障转移。
小规格 优先使用标准软件包位置。单节点几乎不会从重建 Debian 构建暂存机制中获益，而未知 GUC 足以阻止现代服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG17 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–17 未修改；OLAP: PG9.5–17 未修改；CRIT: PG9.5–17 未修改；TINY: PG9.5–17 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 extension_destdir 写成 PostgreSQL 上游参数，或为它伪造上游引入提交。
  • 在 PG18+ 继续下发该下游名称，而实测包已经不再识别它。
  • 只迁移扩展 control 文件，却忘记路径设计中的共享库部分。
  • 只用构建用户测试，数据库服务账号却无法读取最终目录、文件或父路径。

关联参数

extension_control_path · dynamic_library_path · shared_preload_libraries · session_preload_libraries · config_file

参考资料

6.4 - external_pid_file

external_pid_file：将 postmaster PID 写入指定文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：将 postmaster PID 写入指定文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 — — not set

机制详解

将 postmaster PID 写入指定文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 external_pid_file 与 allow_alter_system、config_file、data_directory 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP external_pid_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · data_directory · hba_file · ident_file · extension_destdir

参考资料

6.5 - hba_file

hba_file：设置服务器的 HBA 配置文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器的 HBA 配置文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 — — not set

机制详解

设置服务器的 HBA 配置文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 hba_file 与 allow_alter_system、config_file、data_directory 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP hba_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · data_directory · ident_file · external_pid_file · extension_destdir

参考资料

6.6 - hosts_file

hosts_file：设置服务器的 hosts 配置文件路径。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器的 hosts 配置文件路径。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 4f433025f666 — ssl: Serverside SNI support for libpq
提交日期 2026-03-18
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 — — not set

机制详解

hosts_file：设置服务器的 hosts 配置文件路径。该值在服务器启动时固定，修改后必须安排受控重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

该路径指向 PG19 新增的服务器端 SNI 映射文件 pg_hosts.conf。启用 ssl_sni 后，hostname、/no_sni/ 与通配条目可选择证书、私钥、可选 CA 和口令命令；文件为空或不存在时回退到 postgresql.conf 中的普通 TLS 文件。

应与 ssl_sni、ssl_cert_file、ssl_key_file、ssl_ca_file 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 通过分批客户端上线，验证证书选择与到期告警，并监控认证失败。保留测试过的回退方案，把文件权限和密钥轮换作为同一变更的一部分。
OLAP 批处理驱动与长连接 ETL 也应采用同一安全策略；测试不发送 SNI 的客户端、凭据到期自动化、reload 行为和证书链兼容性。
小规格 优先保持简单且有文档的 TLS 与凭据策略。没有覆盖每个主机名和回退路径的测试就不要启用多证书路由，更不能降低验证强度来掩盖配置错误。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 hosts_file 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 postmaster context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

ssl_sni · ssl_cert_file · ssl_key_file · ssl_ca_file · hba_file

参考资料

6.7 - ident_file

ident_file：设置服务器的 ident 配置文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器的 ident 配置文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 — — not set

机制详解

设置服务器的 ident 配置文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 ident_file 与 allow_alter_system、config_file、data_directory 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP ident_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · data_directory · hba_file · external_pid_file · extension_destdir

参考资料

7 - 锁管理

Lock Management 分类下的 5 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

7.1 - deadlock_timeout

deadlock_timeout：设置等待锁多久后开始检查死锁。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 s，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置等待锁多久后开始检查死锁。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值ms
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Lock Management
上游分类
最后 boot 值 值1000
1 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 1000 ms 1 s

机制详解

设置等待锁多久后开始检查死锁。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

PostgreSQL 等待到该时长才运行成本较高的死锁检测器。启用 log_lock_waits 时，同一时长也决定锁等待日志，因此调低会加快诊断与死锁响应，但普通争用中会增加检测次数。

应把 deadlock_timeout 与 log_lock_waits、lock_timeout、max_locks_per_transaction 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从锁等待日志、涉及对象数量和并发上界校准 deadlock_timeout；先修复过长事务与访问顺序，再增加共享内存或改变检测粒度。
OLAP 分区查询、批量 DDL 与 SERIALIZABLE 报表可能触及大量对象；用最坏计划验证，而不是只看平均事务。
小规格 保持默认通常足够。若提高启动时锁表参数，要同时核算 max_connections、prepared transactions 与备库一致性。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 50ms 不同于 boot 值 50ms
OLAP 50ms 不同于 boot 值 50ms
CRIT 50ms 不同于 boot 值 50ms
TINY 50ms 不同于 boot 值 50ms
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 50ms (dcs)；OLAP: PG9.0–19 Beta 3 = 50ms (dcs)；CRIT: PG9.0–19 Beta 3 = 50ms (dcs)；TINY: PG9.0–19 Beta 3 = 50ms (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在比上游更快发现真实死锁并产出锁等待诊断；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把平均共享内存规划值当成单事务硬上限。
  • 提高参数却不核算连接数与预备事务带来的乘数。
  • 只扩容锁表，不修复长事务、对象访问顺序或分区爆炸。
  • 忽略备库必须具备兼容的启动时锁容量。

关联参数

log_lock_waits · lock_timeout · max_locks_per_transaction · max_pred_locks_per_transaction · max_pred_locks_per_page · max_pred_locks_per_relation

参考资料

7.2 - max_locks_per_transaction

max_locks_per_transaction：设置每个事务的锁数量上限。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 128，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置每个事务的锁数量上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值10 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Lock Management
上游分类
最后 boot 值 值128
128

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–18 64 — 64
PG19 Beta 3 128 — 128

机制详解

设置每个事务的锁数量上限。该值在服务器启动时固定，修改后必须重启。

共享锁表按每个后端或预备事务平均这么多个不同对象来分配。只要全局仍有空间，单个事务可超过该数；它不限制行锁，而且备库的值不得低于主库。

应把 max_locks_per_transaction 与 deadlock_timeout、log_lock_waits、lock_timeout 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从锁等待日志、涉及对象数量和并发上界校准 max_locks_per_transaction；先修复过长事务与访问顺序，再增加共享内存或改变检测粒度。
OLAP 分区查询、批量 DDL 与 SERIALIZABLE 报表可能触及大量对象；用最坏计划验证，而不是只看平均事务。
小规格 保持默认通常足够。若提高启动时锁表参数，要同时核算 max_connections、prepared transactions 与备库一致性。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 500 不同于 boot 值 {{ pg_max_locks_per_transaction }}
OLAP 1000 不同于 boot 值 {{ pg_max_locks_per_transaction }}
CRIT 500 不同于 boot 值 {{ pg_max_locks_per_transaction }}
TINY 250 不同于 boot 值 {{ pg_max_locks_per_transaction }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 500 (dcs)；OLAP: PG9.0–19 Beta 3 = 1000 (dcs)；CRIT: PG9.0–19 Beta 3 = 500 (dcs)；TINY: PG9.0–19 Beta 3 = 250 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在为分区多、对象多的工作负载预留共享锁表容量；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把它理解成行锁上限或单事务硬上限。
  • 提高时不核算 max_connections 与预备事务。
  • 备库设置低于主库导致无法查询。
  • 把平均共享内存规划值当成单事务硬上限。
  • 提高参数却不核算连接数与预备事务带来的乘数。

关联参数

deadlock_timeout · log_lock_waits · lock_timeout · max_pred_locks_per_transaction · max_pred_locks_per_relation · max_pred_locks_per_page

参考资料

7.3 - max_pred_locks_per_page

max_pred_locks_per_page：设置每页可保留的元组级谓词锁最大数量。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置每页可保留的元组级谓词锁最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Lock Management
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 c63172d60f24 — Add GUCs for predicate lock promotion thresholds.
提交日期 2017-04-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 2 — 2

机制详解

设置每页可保留的元组级谓词锁最大数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

Serializable Snapshot Isolation 在同一页的元组级谓词锁达到该数后提升为页级锁。提升可节省共享内存，却可能让无关写入看似冲突并增加 serialization failure。

应把 max_pred_locks_per_page 与 max_pred_locks_per_transaction、max_pred_locks_per_relation、default_transaction_isolation 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从锁等待日志、涉及对象数量和并发上界校准 max_pred_locks_per_page；先修复过长事务与访问顺序，再增加共享内存或改变检测粒度。
OLAP 分区查询、批量 DDL 与 SERIALIZABLE 报表可能触及大量对象；用最坏计划验证，而不是只看平均事务。
小规格 保持默认通常足够。若提高启动时锁表参数，要同时核算 max_connections、prepared transactions 与备库一致性。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把平均共享内存规划值当成单事务硬上限。
  • 提高参数却不核算连接数与预备事务带来的乘数。
  • 只扩容锁表，不修复长事务、对象访问顺序或分区爆炸。
  • 忽略备库必须具备兼容的启动时锁容量。

关联参数

max_pred_locks_per_transaction · max_pred_locks_per_relation · default_transaction_isolation · max_locks_per_transaction · deadlock_timeout

参考资料

7.4 - max_pred_locks_per_relation

max_pred_locks_per_relation：设置每个关系可保留的页级和元组级谓词锁最大数量。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 -2，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置每个关系可保留的页级和元组级谓词锁最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值-2147483648 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Lock Management
上游分类
最后 boot 值 值-2
-2

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 c63172d60f24 — Add GUCs for predicate lock promotion thresholds.
提交日期 2017-04-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 -2 — -2

机制详解

设置每个关系可保留的页级和元组级谓词锁最大数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

SSI 达到阈值后把页级/元组级谓词锁提升为一个关系级锁。负值表示 max_pred_locks_per_transaction 除以其绝对值；提升改变粒度，不改变 SQL 锁强度。

应把 max_pred_locks_per_relation 与 max_pred_locks_per_transaction、max_pred_locks_per_page、default_transaction_isolation 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从锁等待日志、涉及对象数量和并发上界校准 max_pred_locks_per_relation；先修复过长事务与访问顺序，再增加共享内存或改变检测粒度。
OLAP 分区查询、批量 DDL 与 SERIALIZABLE 报表可能触及大量对象；用最坏计划验证，而不是只看平均事务。
小规格 保持默认通常足够。若提高启动时锁表参数，要同时核算 max_connections、prepared transactions 与备库一致性。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把平均共享内存规划值当成单事务硬上限。
  • 提高参数却不核算连接数与预备事务带来的乘数。
  • 只扩容锁表，不修复长事务、对象访问顺序或分区爆炸。
  • 忽略备库必须具备兼容的启动时锁容量。

关联参数

max_pred_locks_per_transaction · max_pred_locks_per_page · default_transaction_isolation · max_locks_per_transaction · deadlock_timeout

参考资料

7.5 - max_pred_locks_per_transaction

max_pred_locks_per_transaction：设置每个事务的谓词锁最大数量。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 64，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置每个事务的谓词锁最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值10 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Lock Management
上游分类
最后 boot 值 值64
64

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 6a77e9385eb4 — Rename max_predicate_locks_per_transaction.
提交日期 2011-02-15
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 64 — 64

机制详解

设置每个事务的谓词锁最大数量。该值在服务器启动时固定，修改后必须重启。

它按每个后端或预备事务为 SERIALIZABLE 冲突跟踪规划共享谓词锁表。这是平均共享内存额度，不是单事务硬上限，也与普通行锁数量无关。

应把 max_pred_locks_per_transaction 与 deadlock_timeout、log_lock_waits、lock_timeout 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从锁等待日志、涉及对象数量和并发上界校准 max_pred_locks_per_transaction；先修复过长事务与访问顺序，再增加共享内存或改变检测粒度。
OLAP 分区查询、批量 DDL 与 SERIALIZABLE 报表可能触及大量对象；用最坏计划验证，而不是只看平均事务。
小规格 保持默认通常足够。若提高启动时锁表参数，要同时核算 max_connections、prepared transactions 与备库一致性。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把平均共享内存规划值当成单事务硬上限。
  • 提高参数却不核算连接数与预备事务带来的乘数。
  • 只扩容锁表，不修复长事务、对象访问顺序或分区爆炸。
  • 忽略备库必须具备兼容的启动时锁容量。

关联参数

deadlock_timeout · log_lock_waits · lock_timeout · max_locks_per_transaction · max_pred_locks_per_relation · max_pred_locks_per_page

参考资料

8 - 预设选项

Preset Options 分类下的 24 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

8.1 - block_size

block_size：显示磁盘页块大小。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8192，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示磁盘页块大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值8192 – 8192
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值8192
8192

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 8192 — 8192

机制详解

显示磁盘页块大小。它是只读状态，不能通过 SET 或修改配置文件来改变。

它反映构建 PostgreSQL 时选定的 BLCKSZ（通常为 8 KiB）；所有堆表与索引页布局都依赖该值。

联动解读应同时查看 wal_block_size、wal_segment_size、segment_size。应用与运维工具可读取 block_size 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 block_size 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 block_size 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 block_size。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

wal_block_size · wal_segment_size · segment_size · data_checksums · server_version_num · max_function_args

参考资料

8.2 - data_checksums

data_checksums：显示该集群是否启用了数据校验和。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示该集群是否启用了数据校验和。

身份

类型 值enum
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值""
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 5a7e75849cb5 — Add a GUC to report whether data page checksums are enabled.
提交日期 2013-09-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 off — off

机制详解

报告控制文件记录的集群级数据校验和状态。它在 SQL 中是 internal/只读值，不能通过 SET 修改。

校验和可由 initdb 选定，也可在服务器停止后通过 pg_checksums 修改。PostgreSQL 从存储读取页时验证校验和，写页时计算校验和。

校验和能发现撕裂或损坏页，但不能修复，也不能证明 WAL、备份、内存与所有存储层都健康。变更需要离线流程、全集群扫描容量和已验证备份。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把该值视作完整性能力，而非性能旋钮。持久集群优先使用校验和并监控失败；既有集群应通过计划好的离线 pg_checksums 流程变更。
OLAP 按真实数据集预算校验和 CPU 与启停所需的全集群扫描；离线转换前验证备份与副本兼容性。
小规格 尽量在 initdb 时启用。既有小集群通常用 pg_checksums 比重建简单，但仍需停机与可恢复备份。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试通过 SET 或 ALTER SYSTEM 修改只读报告。
  • 服务器未干净停机时运行 pg_checksums。
  • 误以为忽略校验和错误就能修复损坏。
  • 误以为校验和本身能验证 WAL 记录、逻辑正确性或备份。
  • 启用后未监控校验和失败与存储健康。

关联参数

ignore_checksum_failure · zero_damaged_pages · wal_log_hints · full_page_writes · data_directory · block_size

参考资料

8.3 - data_directory_mode

data_directory_mode：显示数据目录的权限模式。它是 PG11–18 的只读元数据，不是运行时调优旋钮。
说明

Fact — 官方简述译文：显示数据目录的权限模式。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值0 – 511
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值448
448

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 c37b3d08ca68 — Allow group access on PGDATA
提交日期 2018-04-07
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 448 — 448

机制详解

显示数据目录的权限模式。它是只读状态，不能通过 SET 或修改配置文件来改变。

它以 pg_settings 的十进制表示报告数据目录的有效 Unix 权限，常见值对应 0700 或允许同组读取的 0750。

联动解读应同时查看 block_size、data_checksums、debug_assertions。应用与运维工具可读取 data_directory_mode 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 data_directory_mode 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 data_directory_mode 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 data_directory_mode。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

block_size · data_checksums · debug_assertions · huge_pages_status · in_hot_standby · integer_datetimes

参考资料

8.4 - debug_assertions

debug_assertions：显示运行中的服务器是否启用了断言检查。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示运行中的服务器是否启用了断言检查。

身份

类型 值bool
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

显示运行中的服务器是否启用了断言检查。它是只读状态，不能通过 SET 或修改配置文件来改变。

它反映服务器二进制是否带断言检查构建；这是会增加开销、并可能在违反内部不变量时中止的开发诊断功能。

联动解读应同时查看 server_version、server_version_num、server_encoding。应用与运维工具可读取 debug_assertions 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 debug_assertions 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 debug_assertions 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 debug_assertions。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

server_version · server_version_num · server_encoding · ssl_library · integer_datetimes · block_size

参考资料

8.5 - debug_exec_backend

debug_exec_backend：显示运行中的服务器是否启用了 EXEC_BACKEND 构建选项。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示运行中的服务器是否启用了 EXEC_BACKEND 构建选项。

身份

类型 值bool
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 b3fe098d330f — Add GUC to show EXEC_BACKEND state
提交日期 2025-11-26
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 off — off

机制详解

debug_exec_backend：显示运行中的服务器是否启用了 EXEC_BACKEND 构建选项。它是 PostgreSQL 报告的只读状态，不是操作员可设置的调优旋钮。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

EXEC_BACKEND 通过执行新的服务器进程创建后端，而不只依赖 fork 后继承地址空间。该只读值由平台或构建选项决定，在 Windows 上通常为 true；它可用于解释参数传递方式和平台相关的后端启动行为。

应与 debug_assertions、server_version、server_version_num、dynamic_shared_memory_type 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在出现可复现的运维需求前保持上游默认；应在代表性并发下测试，并在全局修改前检查日志、延迟与关联参数。
OLAP 结合有代表性的长查询和批处理评估，比较整个任务的总耗时、资源、日志量与失败行为，而不是孤立操作。
小规格 尽量减少覆盖并记录回滚。小系统容纳额外日志、worker、内存或保留 WAL 的余量更小，必须用明确资源上限验证。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 debug_exec_backend 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 internal context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

debug_assertions · server_version · server_version_num · dynamic_shared_memory_type

参考资料

8.6 - effective_wal_level

effective_wal_level：显示系统当前实际生效的 WAL 级别。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 replica，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示系统当前实际生效的 WAL 级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值minimal, replica, logical
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值replica
replica

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 67c20979ce72 — Toggle logical decoding dynamically based on logical slot presence.
提交日期 2025-12-23
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 replica — replica

机制详解

effective_wal_level：显示系统当前实际生效的 WAL 级别。它是 PostgreSQL 报告的只读状态，不是操作员可设置的调优旋钮。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

它不同于配置项 wal_level，是系统实际 WAL 记录级别的只读报告。PG19 在 wal_level=replica 但逻辑槽需要时仍可维持等价于 logical 的 WAL；备用库则继承复制链最上游服务器的有效级别。

应与 wal_level、max_replication_slots、max_wal_senders、track_commit_timestamp 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在出现可复现的运维需求前保持上游默认；应在代表性并发下测试，并在全局修改前检查日志、延迟与关联参数。
OLAP 结合有代表性的长查询和批处理评估，比较整个任务的总耗时、资源、日志量与失败行为，而不是孤立操作。
小规格 尽量减少覆盖并记录回滚。小系统容纳额外日志、worker、内存或保留 WAL 的余量更小，必须用明确资源上限验证。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 effective_wal_level 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 internal context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

wal_level · max_replication_slots · max_wal_senders · track_commit_timestamp

参考资料

8.7 - huge_pages_status

huge_pages_status：显示大页的使用状态。它是 PG17–18 的只读元数据，不是运行时调优旋钮。
说明

Fact — 官方简述译文：显示大页的使用状态。

身份

类型 值enum
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值off, on, unknown
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值unknown
unknown

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 a14354cac0e3 — Add GUC parameter “huge_pages_status”
提交日期 2023-07-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 unknown — unknown

机制详解

报告主共享内存区是否实际使用显式大页。它是 internal、只读的启动结果，取值为 off、on 或 unknown。

PostgreSQL 应用 huge_pages 后，根据操作系统支持与可用大页池尝试启动分配，再得出该状态；它不由 PostgreSQL 二进制或 initdb 固定。

用 shared_memory_size_in_huge_pages 估算所需池，并在每次重启后把 huge_pages_status 与请求的 huge_pages 策略对照。Transparent Huge Pages 是另一套操作系统机制。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不能直接调该状态。请求 on 却显示 off 时，检查 huge_pages 策略、OS 支持、池大小、权限与启动日志；调整 OS 池后重启。
OLAP 大型共享内存可能需要大量大页；按真实 shared_memory_size 预留余量，并在每个节点验证 NUMA 放置与重启行为。
小规格 平台策略无特殊要求时保持 huge_pages=try。不要只为让小共享内存显示 on 就预留过大的 OS 大页池。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试 SET 一个只读启动结果。
  • 混淆 huge_pages_status 与配置请求 huge_pages。
  • 忽略操作系统大页池过小或启动分配失败。
  • 混淆 PostgreSQL 显式大页与 Transparent Huge Pages。
  • 误以为一个节点的状态适用于 OS 配置不同的故障切换节点。

关联参数

huge_pages · shared_memory_size_in_huge_pages · shared_memory_size · shared_buffers · min_dynamic_shared_memory · dynamic_shared_memory_type

参考资料

8.8 - in_hot_standby

in_hot_standby：显示当前是否处于 hot standby 状态。它是 PG14–18 的只读元数据，不是运行时调优旋钮。
说明

Fact — 官方简述译文：显示当前是否处于 hot standby 状态。

身份

类型 值bool
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 bf8a662c9afa — Introduce a new GUC_REPORT setting “in_hot_standby”.
提交日期 2021-01-05
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 off — off

机制详解

显示当前是否处于 hot standby 状态。它是只读状态，不能通过 SET 或修改配置文件来改变。

它会随恢复进入或退出 hot standby 而变化，供 SQL 代码进行能力探测。

联动解读应同时查看 hot_standby、max_standby_streaming_delay、hot_standby_feedback。应用与运维工具可读取 in_hot_standby 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 in_hot_standby 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 in_hot_standby 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 in_hot_standby。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

hot_standby · max_standby_streaming_delay · hot_standby_feedback · primary_conninfo · block_size · data_checksums

参考资料

8.9 - integer_datetimes

integer_datetimes：显示日期时间是否采用整数表示。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示日期时间是否采用整数表示。

身份

类型 值bool
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

显示日期时间是否采用整数表示。它是只读状态，不能通过 SET 或修改配置文件来改变。

它报告服务器的日期时间表示。全部实测 PG9.0–19 Beta 3 构建都使用整数日期时间，应用应把它视作兼容元数据。

联动解读应同时查看 server_version、server_version_num、server_encoding。应用与运维工具可读取 integer_datetimes 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 integer_datetimes 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 integer_datetimes 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 integer_datetimes。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

server_version · server_version_num · server_encoding · ssl_library · debug_assertions · block_size

参考资料

8.10 - lc_collate

lc_collate：显示排序规则所使用的区域设置。实测在档范围为 PG9.0–15；最后在档的 PG15 启动默认值为 C，context 为 internal。它在 PG16 被移除。
说明

Fact — 官方简述译文：显示排序规则所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–15
移除版本 PG16
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–15 C — C

机制详解

在 PG15 及更早版本通过只读值报告当前数据库的排序 locale。它是 internal 状态而非可配置 GUC，PostgreSQL 16 将其从 pg_settings 移除。

排序 locale 在建库时选定，同一集群不同数据库可以不同。它影响排序与比较语义；修改服务器配置不能重写既有索引或数据库 locale 元数据。

PG16 及以后，监控与应用应读取 pg_database 中当前数据库及对应 locale provider 元数据，并通过 pg_collation 查看具体 collation 对象。collation 版本变化应独立验证，不能依赖已移除 reporter。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 SHOW/current_setting 读取改为版本感知的 pg_database 查询；跨 locale provider 或版本迁移时回归测试索引排序与唯一性。
OLAP 在分析导出旁记录每个数据库的 provider 与 locale。改变排序规则需要有计划的数据库/对象迁移，并可能需要 REINDEX，而不是改 GUC。
小规格 只有明确接受时才使用建库默认 locale。应在清单与备份中保留 locale 元数据，避免重建时悄然采用不同排序规则。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG15 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–15 未修改；OLAP: PG9.0–15 未修改；CRIT: PG9.0–15 未修改；TINY: PG9.0–15 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试在配置中删除或设置 lc_collate，尽管它一直是 internal/只读值。
  • 误以为一个集群级值适用于所有数据库。
  • 操作系统或 ICU locale 数据变化后，未检查 collation 版本并重建受影响索引。
  • 只凭 locale 名称就比较不同 provider 的文本行为。

关联参数

lc_ctype · server_encoding · client_encoding · icu_validation_level · default_text_search_config · server_version_num

参考资料

8.11 - lc_ctype

lc_ctype：显示字符分类与大小写转换所使用的区域设置。实测在档范围为 PG9.0–15；最后在档的 PG15 启动默认值为 C，context 为 internal。它在 PG16 被移除。
说明

Fact — 官方简述译文：显示字符分类与大小写转换所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–15
移除版本 PG16
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–15 C — C

机制详解

在 PG15 及更早版本报告当前数据库的字符分类与大小写转换 locale。它是 internal/只读值，PostgreSQL 16 将其从 pg_settings 移除。

该 locale 在建库时固定，并可因数据库而异。它影响 locale 感知的字符分类与大小写转换，但不是会话开关，也不能通过 ALTER SYSTEM 修改。

PG16 及以后，应把 SHOW/current_setting 消费者迁移到 pg_database 的 locale provider 元数据，并通过 pg_collation 检查对象级行为；应用测试应覆盖大小写转换及模式/字符类假设。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把读取迁移到 pg_database，并在 locale/provider 升级前测试大小写折叠、upper/lower 行为与表达式索引。
OLAP 若 ETL 分类或规范化依赖该属性，应随输出记录 locale 元数据。改变 locale 需要有计划迁移，而不是运行时设置。
小规格 在建库与重建自动化中显式指定 locale；不要假定主机默认值在镜像或操作系统升级后保持稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG15 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–15 未修改；OLAP: PG9.0–15 未修改；CRIT: PG9.0–15 未修改；TINY: PG9.0–15 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试配置一个一直是 internal/只读的值。
  • 误以为不同数据库或 locale provider 的字符分类完全相同。
  • locale 库变化后未测试表达式索引与大小写转换结果。
  • 只迁移监控文案，却让应用继续依赖 SHOW lc_ctype。

关联参数

lc_collate · server_encoding · client_encoding · icu_validation_level · default_text_search_config · server_version_num

参考资料

8.12 - max_function_args

max_function_args：显示函数参数数量上限。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 100，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示函数参数数量上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值100 – 100
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值100
100

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 100 — 100

机制详解

显示函数参数数量上限。它是只读状态，不能通过 SET 或修改配置文件来改变。

它暴露 FUNC_MAX_ARGS 构建常量；修改需要兼容的自定义构建，而不是改配置。

联动解读应同时查看 max_identifier_length、max_index_keys、block_size。应用与运维工具可读取 max_function_args 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 max_function_args 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 max_function_args 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 max_function_args。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

max_identifier_length · max_index_keys · block_size · server_version_num · data_checksums · data_directory_mode

参考资料

8.13 - max_identifier_length

max_identifier_length：显示标识符长度上限。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 63，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示标识符长度上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值63 – 63
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值63
63

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 63 — 63

机制详解

显示标识符长度上限。它是只读状态，不能通过 SET 或修改配置文件来改变。

它暴露 NAMEDATALEN 减一的结果；创建对象时，超过长度的标识符会被截断。

联动解读应同时查看 max_function_args、max_index_keys、block_size。应用与运维工具可读取 max_identifier_length 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 max_identifier_length 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 max_identifier_length 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 max_identifier_length。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

max_function_args · max_index_keys · block_size · server_version_num · data_checksums · data_directory_mode

参考资料

8.14 - max_index_keys

max_index_keys：显示索引键数量上限。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 32，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示索引键数量上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值32 – 32
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值32
32

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 32 — 32

机制详解

显示索引键数量上限。它是只读状态，不能通过 SET 或修改配置文件来改变。

它暴露 INDEX_MAX_KEYS 构建上限，约束索引属性数量（适用时也包括 INCLUDE 列）。

联动解读应同时查看 max_function_args、max_identifier_length、block_size。应用与运维工具可读取 max_index_keys 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 max_index_keys 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 max_index_keys 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 max_index_keys。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

max_function_args · max_identifier_length · block_size · server_version_num · data_checksums · data_directory_mode

参考资料

8.15 - num_os_semaphores

num_os_semaphores：显示服务器所需的操作系统信号量数量。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示服务器所需的操作系统信号量数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 0dcaea569034 — Introduce num_os_semaphores GUC.
提交日期 2024-07-26
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 0 — 0

机制详解

显示服务器所需的操作系统信号量数量。它是只读状态，不能通过 SET 或修改配置文件来改变。

它根据启动时的进程与连接配置计算，供管理员规划 System V 信号量容量。

联动解读应同时查看 shared_memory_size、shared_memory_size_in_huge_pages、huge_pages。应用与运维工具可读取 num_os_semaphores 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 num_os_semaphores 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 num_os_semaphores 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 num_os_semaphores。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

shared_memory_size · shared_memory_size_in_huge_pages · huge_pages · huge_pages_status · max_connections · block_size

参考资料

8.16 - segment_size

segment_size：显示每个磁盘文件所含的页数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 GiB (131072 × 8kB)，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示每个磁盘文件所含的页数。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值8kB
原始单位
范围 值131072 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值131072
1 GiB (131072 × 8kB)

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 131072 8kB 1 GiB (131072 × 8kB)

机制详解

显示每个磁盘文件所含的页数。它是只读状态，不能通过 SET 或修改配置文件来改变。

它报告每个关系段文件包含的数据库页数；与 block_size 一起决定文件分段边界。

联动解读应同时查看 block_size、wal_block_size、wal_segment_size。应用与运维工具可读取 segment_size 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 segment_size 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 segment_size 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 segment_size。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

block_size · wal_block_size · wal_segment_size · data_checksums · server_version_num · data_directory_mode

参考资料

8.17 - server_encoding

server_encoding：显示服务器（数据库）字符集编码。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 SQL_ASCII，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示服务器（数据库）字符集编码。

身份

类型 值string
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值SQL_ASCII
SQL_ASCII

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 SQL_ASCII — SQL_ASCII

机制详解

显示服务器（数据库）字符集编码。它是只读状态，不能通过 SET 或修改配置文件来改变。

它报告当前数据库编码；编码在建库时选定，同一集群的不同数据库可以不同。

联动解读应同时查看 lc_collate、lc_ctype、client_encoding。应用与运维工具可读取 server_encoding 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 server_encoding 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 server_encoding 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 server_encoding。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

lc_collate · lc_ctype · client_encoding · default_text_search_config · icu_validation_level · server_version

参考资料

8.18 - server_version

server_version：显示服务器版本。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 19beta3 (Debian 19~beta3-1.pgdg13+1)，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示服务器版本。

身份

类型 值string
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值19beta3 (Debian 19~beta3-1.pgdg13+1)
19beta3 (Debian 19~beta3-1.pgdg13+1)

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 9.0.23 — 9.0.23
PG9.1 9.1.24 — 9.1.24
PG9.2 9.2.23 — 9.2.23
PG9.3 9.3.25 — 9.3.25
PG9.4 9.4.26 — 9.4.26
PG9.5 9.5.25 — 9.5.25
PG9.6 9.6.24 — 9.6.24
PG10 10.23 (Debian 10.23-1.pgdg110+1) — 10.23 (Debian 10.23-1.pgdg110+1)
PG11 11.22 (Debian 11.22-1.pgdg120+1) — 11.22 (Debian 11.22-1.pgdg120+1)
PG12 12.22 (Debian 12.22-1.pgdg120+1) — 12.22 (Debian 12.22-1.pgdg120+1)
PG13 13.23 (Debian 13.23-1.pgdg13+1) — 13.23 (Debian 13.23-1.pgdg13+1)
PG14 14.24 (Debian 14.24-1.pgdg13+2) — 14.24 (Debian 14.24-1.pgdg13+2)
PG15 15.19 (Debian 15.19-1.pgdg13+2) — 15.19 (Debian 15.19-1.pgdg13+2)
PG16 16.15 (Debian 16.15-1.pgdg13+2) — 16.15 (Debian 16.15-1.pgdg13+2)
PG17 17.11 (Debian 17.11-1.pgdg13+2) — 17.11 (Debian 17.11-1.pgdg13+2)
PG18 18.6 (Debian 18.6-1.pgdg13+2) — 18.6 (Debian 18.6-1.pgdg13+2)
PG19 Beta 3 19beta3 (Debian 19~beta3-1.pgdg13+1) — 19beta3 (Debian 19~beta3-1.pgdg13+1)

机制详解

显示服务器版本。它是只读状态，不能通过 SET 或修改配置文件来改变。

它是人类可读的服务器构建/版本字符串，可能包含发行商文字，不适合做数值排序。

联动解读应同时查看 server_version_num、server_encoding、ssl_library。应用与运维工具可读取 server_version 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 server_version 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 server_version 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 server_version。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

server_version_num · server_encoding · ssl_library · integer_datetimes · debug_assertions · block_size

参考资料

8.19 - server_version_num

server_version_num：以整数形式显示服务器版本。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 190000，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：以整数形式显示服务器版本。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值190000 – 190000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值190000
190000

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 90023 — 90023
PG9.1 90124 — 90124
PG9.2 90223 — 90223
PG9.3 90325 — 90325
PG9.4 90426 — 90426
PG9.5 90525 — 90525
PG9.6 90624 — 90624
PG10 100023 — 100023
PG11 110022 — 110022
PG12 120022 — 120022
PG13 130023 — 130023
PG14 140024 — 140024
PG15 150019 — 150019
PG16 160015 — 160015
PG17 170011 — 170011
PG18 180006 — 180006
PG19 Beta 3 190000 — 190000

机制详解

以整数报告当前服务器二进制版本。它是 internal/只读值，由二进制决定，与 initdb 或建库无关。

在本项目实测的 PG9.0–19 Beta 3 中，该整数编码大版本与小版本更新，软件可据此做数值比较，无需解析 server_version 的发行商文字。

只有无法直接探测服务端能力时才用它做兼容 gating。扩展与客户端仍需考虑不改变上游版本号的发行商 backport。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。升级后记录每个服务器的值，并在部署检查中做数值比较；改变它意味着运行不同 PostgreSQL 二进制。
OLAP 启用版本专属 SQL 或优化器功能前，核对协调节点、worker、副本与扩展构建对应的真实服务器版本。
小规格 可用该值做简单兼容检查，但优先直接探测所需能力；不要尝试通过配置或 initdb 修改。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把整数当字符串比较。
  • 尝试通过配置或重建数据库修改。
  • 误以为该数值包含发行商 backport 与下游补丁信息。
  • 用客户端库版本替代所连接服务器版本。

关联参数

server_version · server_encoding · integer_datetimes · ssl_library · max_identifier_length · block_size

参考资料

8.20 - shared_memory_size

shared_memory_size：显示服务器主共享内存区的大小（向上取整到 MB）。它是 PG15–18 的只读元数据，不是运行时调优旋钮。
说明

Fact — 官方简述译文：显示服务器主共享内存区的大小（向上取整到 MB）。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值MB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值0
0 B

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 bd1788051b02 — Introduce GUC shared_memory_size
提交日期 2021-09-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 0 MB 0 B

机制详解

显示服务器主共享内存区的大小（向上取整到 MB）。它是只读状态，不能通过 SET 或修改配置文件来改变。

它报告 PostgreSQL 完成启动尺寸计算后、按 MB 向上取整的主共享内存段大小。

联动解读应同时查看 shared_memory_size_in_huge_pages、huge_pages、huge_pages_status。应用与运维工具可读取 shared_memory_size 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 shared_memory_size 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 shared_memory_size 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 shared_memory_size。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

shared_memory_size_in_huge_pages · huge_pages · huge_pages_status · num_os_semaphores · max_connections · block_size

参考资料

8.21 - shared_memory_size_in_huge_pages

shared_memory_size_in_huge_pages：显示主共享内存区所需的大页数量。它是 PG15–18 的只读元数据，不是运行时调优旋钮。
说明

Fact — 官方简述译文：显示主共享内存区所需的大页数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值-1
-1

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 43c1c4f65eab — Introduce GUC shared_memory_size_in_huge_pages
提交日期 2021-09-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 -1 — -1

机制详解

显示主共享内存区所需的大页数量。它是只读状态，不能通过 SET 或修改配置文件来改变。

它估算主共享内存段所需的大页数量；平台无法给出估算时返回 -1。

联动解读应同时查看 shared_memory_size、huge_pages、huge_pages_status。应用与运维工具可读取 shared_memory_size_in_huge_pages 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 shared_memory_size_in_huge_pages 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 shared_memory_size_in_huge_pages 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 shared_memory_size_in_huge_pages。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

shared_memory_size · huge_pages · huge_pages_status · num_os_semaphores · max_connections · block_size

参考资料

8.22 - ssl_library

ssl_library：显示 SSL 库的名称。它是 PG12–18 的只读元数据，不是运行时调优旋钮。
说明

Fact — 官方简述译文：显示 SSL 库的名称。

身份

类型 值string
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值OpenSSL
OpenSSL

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 98efa76fe313 — Add ssl_library preset parameter
提交日期 2018-06-26
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 OpenSSL — OpenSSL

机制详解

显示 SSL 库的名称。它是只读状态，不能通过 SET 或修改配置文件来改变。

它报告服务器链接的 SSL 实现，可用于诊断 TLS provider 特有行为。

联动解读应同时查看 server_version、server_version_num、server_encoding。应用与运维工具可读取 ssl_library 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 ssl_library 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 ssl_library 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 ssl_library。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

server_version · server_version_num · server_encoding · integer_datetimes · debug_assertions · block_size

参考资料

8.23 - wal_block_size

wal_block_size：显示预写日志块大小。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8192，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示预写日志块大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值—
原始单位
范围 值8192 – 8192
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值8192
8192

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 8192 — 8192

机制详解

显示预写日志块大小。它是只读状态，不能通过 SET 或修改配置文件来改变。

它反映构建时选定的 XLOG_BLCKSZ（通常为 8 KiB），用于 WAL I/O 缓冲。

联动解读应同时查看 block_size、wal_segment_size、segment_size。应用与运维工具可读取 wal_block_size 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 wal_block_size 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 wal_block_size 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 wal_block_size。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

block_size · wal_segment_size · segment_size · data_checksums · server_version_num · data_directory_mode

参考资料

8.24 - wal_segment_size

wal_segment_size：显示预写日志段文件大小。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 16 MiB，context 为 internal。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：显示预写日志段文件大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值internal
内部或预设值，用户不可修改
单位 值B
原始单位
范围 值1048576 – 1073741824
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Preset Options
上游分类
最后 boot 值 值16777216
16 MiB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–10 2048 8kB 16 MiB (2048 × 8kB)
PG11–19 Beta 3 16777216 B 16 MiB

机制详解

显示预写日志段文件大小。它是只读状态，不能通过 SET 或修改配置文件来改变。

它报告 WAL 段大小。PostgreSQL 11 及以后在 initdb 时选择该值；更早集群通常使用构建时数值。

联动解读应同时查看 min_wal_size、max_wal_size、wal_keep_size。应用与运维工具可读取 wal_segment_size 做能力或环境判断，但不能依靠 SET 改变它；跨集群比较时还要考虑构建、initdb 与当前数据库差异。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不可调。把 wal_segment_size 当作部署与能力事实记录；若与预期不符，应修正二进制、initdb 或数据库创建流程，而不是 SET。
OLAP 不可调。用 wal_segment_size 校验分析节点的格式、构建或资源假设，并确保所有读写节点兼容。
小规格 不可调。只需在清单与故障报告中保留该值；不要为改变它而做不必要的自定义构建或重建。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 尝试用 SET 或配置文件改变只读的 wal_segment_size。
  • 假定所有集群、数据库或发行包的报告值相同。
  • 在文件格式或功能兼容性检查中忽略该值。
  • 把显示值当作性能目标，而不是环境事实。

关联参数

min_wal_size · max_wal_size · wal_keep_size · checkpoint_timeout · checkpoint_completion_target · wal_keep_segments

参考资料

9 - 查询调优

Query Tuning 分类下的 55 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

9.1 - constraint_exclusion

constraint_exclusion：允许规划器利用约束排除不可能匹配的表。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 partition，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器利用约束排除不可能匹配的表。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值partition, on, off
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值partition
partition

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 partition — partition

机制详解

constraint_exclusion 允许规划器把查询谓词与 CHECK 约束比较，并排除约束可证明不可能匹配的关系。partition 只对传统继承子表和 UNION ALL 分支执行该工作；它与声明式分区裁剪不同。

证明发生在规划阶段，因此更广泛地开启会增加规划工作，即使最终没有关系可排除。它依赖规划器可见且与查询条件逻辑矛盾的约束。

对声明式分区表，enable_partition_pruning 才是主要开关。constraint_exclusion 仍适用于继承式分区以及精心构造、由约束支撑的 UNION ALL 视图。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性计划显示可重复的全负载问题，否则保留 constraint_exclusion 上游默认值。先测试局部覆盖，并同时计入规划延迟与执行延迟。
OLAP 分析 SQL 的连接、游标或递归规模更大，constraint_exclusion 的影响可能更明显。应测试完整语句族并检查估算，不要照搬一次成功的取值。
小规格 小主机上不要在无实测收益时通过 constraint_exclusion 增加规划搜索或内存压力。优先调整查询结构或使用限定角色设置，而不是集群级覆盖。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 constraint_exclusion 当作执行器资源上限，而不是规划假设或策略。
  • 只测试一组参数值或一种数据分布。
  • 期待已经缓存的计划自动重写。
  • 用全局覆盖掩盖陈旧统计信息或脆弱 SQL 结构。

关联参数

enable_partition_pruning · from_collapse_limit · join_collapse_limit · default_statistics_target

参考资料

9.2 - cpu_index_tuple_cost

cpu_index_tuple_cost：设置规划器处理每个索引条目的成本估计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.005，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置规划器处理每个索引条目的成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值0.005
0.005

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0.005 — 0.005

机制详解

cpu_index_tuple_cost 用于刻画索引扫描处理一个索引条目的 CPU 工作量。它只是路径估算成本的一项，不会直接分配资源或改变执行器行为。

规划器成本单位是任意尺度，只有比例有意义。把所有成本常量同比例缩放不会改变路径排序；只改一项则会改变 I/O、行处理、操作符与并行开销之间的权衡。

生成计划时才会读取该值。统计信息、行数估计、缓存假设、tablespace 覆盖以及可用计划方法，都可能比小幅调整这个常量影响更大。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应依据代表性负载校准 cpu_index_tuple_cost，不能依据单个计划。先修复陈旧统计，并用 EXPLAIN (ANALYZE, BUFFERS) 比较估算与实际；能按角色或 tablespace 限定时不要全局修改。
OLAP 分析负载可能需要不同的 CPU 与 I/O 权衡，但应把 cpu_index_tuple_cost 与相关成本模型一起调整，并验证完整的扫描、连接与聚合组合。
小规格 除非反复证据表明存在系统性建模偏差，否则保留上游值。小系统上并发与缓存驻留通常比细调 cpu_index_tuple_cost 更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把数值解释为实际耗时或硬资源上限。
  • 为修复单条查询而调整，导致更广泛负载回归。
  • 在修正统计信息与基数估计之前先改成本常量。
  • 忘记只有各成本项的相对值会影响路径选择。

关联参数

cpu_tuple_cost · cpu_operator_cost · random_page_cost · seq_page_cost · enable_indexscan

参考资料

9.3 - cpu_operator_cost

cpu_operator_cost：设置规划器执行每个操作符或函数调用的成本估计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.0025，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置规划器执行每个操作符或函数调用的成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值0.0025
0.0025

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0.0025 — 0.0025

机制详解

cpu_operator_cost 用于刻画每次操作符或函数调用的 CPU 工作量。它只是路径估算成本的一项，不会直接分配资源或改变执行器行为。

规划器成本单位是任意尺度，只有比例有意义。把所有成本常量同比例缩放不会改变路径排序；只改一项则会改变 I/O、行处理、操作符与并行开销之间的权衡。

生成计划时才会读取该值。统计信息、行数估计、缓存假设、tablespace 覆盖以及可用计划方法，都可能比小幅调整这个常量影响更大。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应依据代表性负载校准 cpu_operator_cost，不能依据单个计划。先修复陈旧统计，并用 EXPLAIN (ANALYZE, BUFFERS) 比较估算与实际；能按角色或 tablespace 限定时不要全局修改。
OLAP 分析负载可能需要不同的 CPU 与 I/O 权衡，但应把 cpu_operator_cost 与相关成本模型一起调整，并验证完整的扫描、连接与聚合组合。
小规格 除非反复证据表明存在系统性建模偏差，否则保留上游值。小系统上并发与缓存驻留通常比细调 cpu_operator_cost 更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把数值解释为实际耗时或硬资源上限。
  • 为修复单条查询而调整，导致更广泛负载回归。
  • 在修正统计信息与基数估计之前先改成本常量。
  • 忘记只有各成本项的相对值会影响路径选择。

关联参数

cpu_tuple_cost · cpu_index_tuple_cost · jit_above_cost · seq_page_cost

参考资料

9.4 - cpu_tuple_cost

cpu_tuple_cost：设置规划器处理每个元组（行）的成本估计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.01，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置规划器处理每个元组（行）的成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值0.01
0.01

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0.01 — 0.01

机制详解

cpu_tuple_cost 用于刻画处理一行的 CPU 工作量。它只是路径估算成本的一项，不会直接分配资源或改变执行器行为。

规划器成本单位是任意尺度，只有比例有意义。把所有成本常量同比例缩放不会改变路径排序；只改一项则会改变 I/O、行处理、操作符与并行开销之间的权衡。

生成计划时才会读取该值。统计信息、行数估计、缓存假设、tablespace 覆盖以及可用计划方法，都可能比小幅调整这个常量影响更大。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应依据代表性负载校准 cpu_tuple_cost，不能依据单个计划。先修复陈旧统计，并用 EXPLAIN (ANALYZE, BUFFERS) 比较估算与实际；能按角色或 tablespace 限定时不要全局修改。
OLAP 分析负载可能需要不同的 CPU 与 I/O 权衡，但应把 cpu_tuple_cost 与相关成本模型一起调整，并验证完整的扫描、连接与聚合组合。
小规格 除非反复证据表明存在系统性建模偏差，否则保留上游值。小系统上并发与缓存驻留通常比细调 cpu_tuple_cost 更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把数值解释为实际耗时或硬资源上限。
  • 为修复单条查询而调整，导致更广泛负载回归。
  • 在修正统计信息与基数估计之前先改成本常量。
  • 忘记只有各成本项的相对值会影响路径选择。

关联参数

cpu_index_tuple_cost · cpu_operator_cost · seq_page_cost · random_page_cost · enable_seqscan

参考资料

9.5 - cursor_tuple_fraction

cursor_tuple_fraction：设置规划器对游标实际取回行比例的估计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.1，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置规划器对游标实际取回行比例的估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值0.1
0.1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0.1 — 0.1

机制详解

cursor_tuple_fraction 告诉规划器预计会取回游标结果的多大比例。比例越小越重视启动成本；1.0 则像会消费全部结果的普通查询一样规划。

该估计可通过偏好更快的首行来改变连接顺序与访问路径，即使总执行时间更慢。它不会在达到该比例后停止 FETCH，也不是行数限制。

该值在规划游标时读取。应用行为至关重要：分页、提前退出与完整导出使用游标时，合适比例完全不同。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性计划显示可重复的全负载问题，否则保留 cursor_tuple_fraction 上游默认值。先测试局部覆盖，并同时计入规划延迟与执行延迟。
OLAP 分析 SQL 的连接、游标或递归规模更大，cursor_tuple_fraction 的影响可能更明显。应测试完整语句族并检查估算，不要照搬一次成功的取值。
小规格 小主机上不要在无实测收益时通过 cursor_tuple_fraction 增加规划搜索或内存压力。优先调整查询结构或使用限定角色设置，而不是集群级覆盖。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 cursor_tuple_fraction 当作执行器资源上限，而不是规划假设或策略。
  • 只测试一组参数值或一种数据分布。
  • 期待已经缓存的计划自动重写。
  • 用全局覆盖掩盖陈旧统计信息或脆弱 SQL 结构。

关联参数

plan_cache_mode · random_page_cost · enable_nestloop · enable_indexscan

参考资料

9.6 - default_statistics_target

为没有单独目标值的列设置 ANALYZE 默认统计细节级别。更多细节可能改善基数估算，但会增加统计收集时间和系统目录空间。
说明

Fact — 官方简述译文：设置未单独指定目标值的列所使用的默认统计目标。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值100
100

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 100 — 100

机制详解

该目标限制列的最常见值列表条目数和直方图桶数。规划器用这些统计估算行数，进而选择访问路径、连接顺序与连接算法。

ANALYZE 对大表采用抽样而不是读取全部行。抽样规模由本次分析列中的最大统计目标驱动，因此提高目标会大致按比例增加分析时间和空间。

ALTER TABLE … ALTER COLUMN … SET STATISTICS 可按列覆盖全局默认值。多列相关性是另一类问题，通常应使用 CREATE STATISTICS，而不是仅提高本参数。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持适中的全局目标，只对确实产生行数误估的倾斜列提高；重新运行 ANALYZE，并比较调整前后的估算行数与实际行数。
OLAP 较高基线有助于复杂过滤和连接，但相关谓词应使用扩展统计；批量装载后还要为增加的 ANALYZE 时间留预算。
小规格 适度提高全局值通常成本不高，但按列调优更精确；从不参与过滤、分组或排序的列不需要深直方图。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 400 不同于 boot 值 400
OLAP 1000 不同于 boot 值 1000
CRIT 400 不同于 boot 值 400
TINY 200 不同于 boot 值 200
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 400 (dcs)；OLAP: PG9.0–19 Beta 3 = 1000 (dcs)；CRIT: PG9.0–19 Beta 3 = 400 (dcs)；TINY: PG9.0–19 Beta 3 = 200 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：各模板以更多 ANALYZE 成本换取更好的估算，其中 OLAP 最重视计划质量，TINY 则限制收集开销。

常见坑

  • 修改参数不会刷新已有统计，之后必须运行 ANALYZE。
  • 提高单列目标本身无法描述跨列相关性。
  • 过高的全局值会让不重要列也承担额外 ANALYZE 工作。
  • 分区子表变化不会触发父表分析，父表可能需要手工 ANALYZE。
  • 抽样仍是近似过程，可能出现估算误差与计划波动。

关联参数

autovacuum_analyze_scale_factor · autovacuum_analyze_threshold · enable_partitionwise_join · plan_cache_mode · random_page_cost · effective_cache_size

参考资料

9.7 - effective_cache_size

规划器对单条查询可用 PostgreSQL 数据缓存规模的估计；它影响成本计算，但不会分配内存。
说明

Fact — 官方简述译文：设置规划器对有效数据缓存总规模的假设。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值524288
4 GiB (524288 × 8kB)

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.3 16384 8kB 128 MiB (16384 × 8kB)
PG9.4–19 Beta 3 524288 8kB 4 GiB (524288 × 8kB)

机制详解

effective_cache_size 是成本模型输入。数值越高，索引扫描看起来越有吸引力；数值越低，顺序扫描越有吸引力。

估算时应同时考虑 shared_buffers 与操作系统页缓存中可能用于 PostgreSQL 数据的部分，也要考虑二者内容重叠，以及多个并发查询共同争用缓存容量。

修改此参数不会改变 PostgreSQL 共享内存大小、不会预留内核缓存，也不保证页面在查询之间持续驻留；它只通过执行计划选择间接生效。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 估算扣除操作系统和同机服务后 PostgreSQL 实际可用的缓存，再用 EXPLAIN 验证索引密集型计划。不要照搬并发与工作集完全不同的主机百分比。
OLAP 大扫描会驱逐或争用缓存，因此不能把已安装内存直接等同于单条分析查询可用缓存；应结合代表性的混合负载与冷缓存测试校准。
小规格 为操作系统与其他服务留出空间；共享的小主机若把它设置为接近总内存，通常会高估缓存。始终把它当规划器估计值，而不是内存目标。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 24576MB 不同于 boot 值 {{ pg_effective_cache_size }}MB
OLAP 24576MB 不同于 boot 值 {{ pg_effective_cache_size }}MB
CRIT 24576MB 不同于 boot 值 {{ pg_effective_cache_size }}MB
TINY 24576MB 不同于 boot 值 {{ pg_effective_cache_size }}MB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 24576MB (dcs)；OLAP: PG9.0–19 Beta 3 = 24576MB (dcs)；CRIT: PG9.0–19 Beta 3 = 24576MB (dcs)；TINY: PG9.0–19 Beta 3 = 24576MB (dcs)。 建议（待人工复核）——编辑推断：把该余量作为规划器有效缓存估计是一项简化，需要结合实际 OS 缓存、内容重叠、同机服务与查询并发复核。

常见坑

  • 期待该设置实际分配或预留内存。
  • 不扣除 PostgreSQL 缓存无法使用的内存，直接设置为整机 RAM。
  • 忽略访问不同数据集的并发查询会共享有效缓存。
  • 高估取值后，把过度偏向索引的计划误归因于其他成本参数。

关联参数

shared_buffers · random_page_cost · seq_page_cost · effective_io_concurrency · max_connections

参考资料

9.8 - enable_async_append

enable_async_append：允许规划器使用异步 Append 计划。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用异步 Append 计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 27e1f14563cf — Add support for asynchronous execution.
提交日期 2021-03-31
Discussion 讨论 1 · 讨论 2 · 讨论 3

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 on — on

机制详解

enable_async_append 控制规划器是否可以选择异步感知 Append；它可在多个支持异步访问的子计划之间重叠等待。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断异步感知 Append；它可在多个支持异步访问的子计划之间重叠等待是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_async_append，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_async_append 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_async_append 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_parallel_append · effective_io_concurrency · io_method · enable_partition_pruning

参考资料

9.9 - enable_bitmapscan

enable_bitmapscan：允许规划器使用位图扫描计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用位图扫描计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_bitmapscan 控制规划器是否可以选择位图索引与位图堆扫描；它先合并元组位置，再访问堆页面。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断位图索引与位图堆扫描；它先合并元组位置，再访问堆页面是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_bitmapscan，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_bitmapscan 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_bitmapscan 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_indexscan · enable_seqscan · random_page_cost · work_mem · effective_io_concurrency

参考资料

9.10 - enable_distinct_reordering

enable_distinct_reordering：允许规划器重排 DISTINCT 键。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器重排 DISTINCT 键。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 a8ccf4e93a7e — Reordering DISTINCT keys to match input path’s pathkeys
提交日期 2024-11-26
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 on — on

机制详解

enable_distinct_reordering 控制规划器是否可以选择重排 DISTINCT 键以匹配有用的输入排序键，从而避免或缩小排序。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保留 PG18 默认 on。怀疑回归时比较会话级计划，并验证重排后的 DISTINCT 键是真正匹配有用输入 pathkeys，还是只把一种排序换成另一种。
OLAP 大型 DISTINCT 在重排可利用索引、归并或已有顺序时可能获益。应测排序内存、落盘量、规划时间与总执行，不能因一个计划就全局关闭优化。
小规格 除非证明存在可复现计划回归，否则保持 on。若排序落盘，应先修正 work_mem 与计划输入，而不是把该规划器开关当作永久 hint。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_distinct_reordering 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_sort · enable_incremental_sort · enable_presorted_aggregate · work_mem

参考资料

9.11 - enable_eager_aggregate

enable_eager_aggregate：允许规划器把部分聚合提前推过连接。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器把部分聚合提前推过连接。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 8e11859102f9 — Implement Eager Aggregation
提交日期 2025-10-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 on — on

机制详解

enable_eager_aggregate：允许规划器把部分聚合提前推过连接。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

提前聚合会把部分聚合下推到连接之前，从而减少穿过连接的行数，再在全部关系连接后完成最终聚合。只有估算平均分组尺寸达到 min_eager_agg_group_size 才会考虑；基数估算、分组语义、内存和其他连接路径仍决定规划器是否采用。

应与 min_eager_agg_group_size、enable_hashagg、enable_partitionwise_aggregate、work_mem 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先按会话使用 EXPLAIN (ANALYZE, BUFFERS) 和有代表性的参数分布实验。只有提前聚合能稳定减少行数和延迟、且不引入计划抖动时才偏离默认值。
OLAP 测试确有预聚合机会的连接，并覆盖新旧统计信息与落盘压力；比较总 CPU、峰值内存、中间行数和并行计划，而不只看一次耗时。
小规格 在定位出可复现回归前保持规划器开关与阈值默认。先修复基数统计；全局强制路径常会用一个查询的收益换来更多回归。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_eager_aggregate 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

min_eager_agg_group_size · enable_hashagg · enable_partitionwise_aggregate · work_mem · hash_mem_multiplier

参考资料

9.12 - enable_gathermerge

enable_gathermerge：允许规划器使用 Gather Merge 计划。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用 Gather Merge 计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 355d3993c53e — Add a Gather Merge executor node.
提交日期 2017-03-09
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 on — on

机制详解

enable_gathermerge 控制规划器是否可以选择Gather Merge；它在合并并行 worker 输出时保留顺序。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断Gather Merge；它在合并并行 worker 输出时保留顺序是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_gathermerge，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_gathermerge 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 未修改；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 未修改；TINY: PG10–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_gathermerge 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

max_parallel_workers_per_gather · enable_sort · enable_incremental_sort · parallel_leader_participation

参考资料

9.13 - enable_group_by_reordering

enable_group_by_reordering：允许规划器重排 GROUP BY 键。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器重排 GROUP BY 键。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 db0d67db2401 — Optimize order of GROUP BY keys
提交日期 2022-03-31
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 on — on

机制详解

enable_group_by_reordering 控制规划器是否可以选择重排 GROUP BY 键以匹配子节点路径键并利用已有顺序。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保留默认 on。计划回归时在会话内比较 on/off，并检查重排 GROUP BY 键是否利用子节点已有 pathkeys，还是增加规划工作却没有避免排序。
OLAP 大型分组可能利用索引或预排序输入。为报表角色修改前，应评估排序与聚合节点、落盘、规划时间及结果顺序要求。
小规格 除非隔离出可重复回归，否则保持 on。把 off 当作局部绕行前，先解决陈旧统计、缺失排序路径与 work_mem 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_group_by_reordering 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_sort · enable_incremental_sort · enable_hashagg · enable_presorted_aggregate

参考资料

9.14 - enable_hashagg

enable_hashagg：允许规划器使用哈希聚合计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用哈希聚合计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_hashagg 控制规划器是否可以选择哈希聚合；它在哈希表中分组，而不是依赖已排序的输入流。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断哈希聚合；它在哈希表中分组，而不是依赖已排序的输入流是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_hashagg，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_hashagg 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_hashagg 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

work_mem · hash_mem_multiplier · enable_sort · enable_partitionwise_aggregate

参考资料

9.15 - enable_hashjoin

enable_hashjoin：允许规划器使用哈希连接计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用哈希连接计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_hashjoin 控制规划器是否可以选择哈希连接；它为一侧输入建立哈希表，再用另一侧探测。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断哈希连接；它为一侧输入建立哈希表，再用另一侧探测是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_hashjoin，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_hashjoin 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_hashjoin 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

work_mem · hash_mem_multiplier · enable_parallel_hash · enable_mergejoin · enable_nestloop

参考资料

9.16 - enable_incremental_sort

enable_incremental_sort：允许规划器使用增量排序步骤。实测在档范围为 PG13–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用增量排序步骤。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 94e454cddfba — Rename enable_incrementalsort for clarity
提交日期 2020-07-05
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 on — on

机制详解

enable_incremental_sort 控制规划器是否可以选择增量排序；它利用输入已按目标键前缀有序，只在各组内部继续排序。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断增量排序；它利用输入已按目标键前缀有序，只在各组内部继续排序是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_incremental_sort，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_incremental_sort 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_incremental_sort 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_sort · enable_gathermerge · work_mem · enable_presorted_aggregate

参考资料

9.17 - enable_indexonlyscan

enable_indexonlyscan：允许规划器使用仅索引扫描计划。实测在档范围为 PG9.2–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用仅索引扫描计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 a2822fb9337a — Support index-only scans using the visibility map to avoid heap fetches.
提交日期 2011-10-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 on — on

机制详解

enable_indexonlyscan 控制规划器是否可以选择仅索引扫描；当可见性信息允许时，它可直接返回索引元组而不读堆。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

只有 enable_indexscan 同时开启时它才有效；未标记 all-visible 的堆页面仍需回表。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断仅索引扫描；当可见性信息允许时，它可直接返回索引元组而不读堆是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_indexonlyscan，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_indexonlyscan 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 未修改；OLAP: PG9.2–19 Beta 3 未修改；CRIT: PG9.2–19 Beta 3 未修改；TINY: PG9.2–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_indexonlyscan 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 只有 enable_indexscan 同时开启时它才有效；未标记 all-visible 的堆页面仍需回表。

关联参数

enable_indexscan · enable_bitmapscan · enable_seqscan · random_page_cost · track_counts

参考资料

9.18 - enable_indexscan

enable_indexscan：允许规划器使用索引扫描计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用索引扫描计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_indexscan 控制规划器是否可以选择普通索引扫描；该开关同时是考虑仅索引扫描的前置条件。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断普通索引扫描；该开关同时是考虑仅索引扫描的前置条件是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_indexscan，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_indexscan 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_indexscan 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_indexonlyscan · enable_bitmapscan · enable_seqscan · random_page_cost · effective_cache_size

参考资料

9.19 - enable_material

enable_material：允许规划器插入物化节点。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器插入物化节点。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_material 控制规划器是否可以选择规划器插入的 Materialize 节点；它保存输入以供重复扫描或隔离执行属性。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

关闭它也不能删除正确性所必需的物化，只会阻止规划器插入可选物化。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断规划器插入的 Materialize 节点；它保存输入以供重复扫描或隔离执行属性是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_material，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_material 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_material 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 关闭它也不能删除正确性所必需的物化，只会阻止规划器插入可选物化。

关联参数

work_mem · temp_file_limit · enable_memoize · enable_nestloop

参考资料

9.20 - enable_memoize

enable_memoize：允许规划器使用 Memoize 缓存节点。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用 Memoize 缓存节点。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 47ca4836441d — Change the name of the Result Cache node to Memoize
提交日期 2021-07-14
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 on — on

机制详解

enable_memoize 控制规划器是否可以选择Memoize 节点；它在嵌套循环连接中缓存参数化内侧扫描的结果。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断Memoize 节点；它在嵌套循环连接中缓存参数化内侧扫描的结果是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_memoize，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_memoize 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_memoize 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_nestloop · work_mem · enable_material · cpu_operator_cost

参考资料

9.21 - enable_mergejoin

enable_mergejoin：允许规划器使用归并连接计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用归并连接计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_mergejoin 控制规划器是否可以选择归并连接；它消费按兼容连接键排序的两侧输入。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断归并连接；它消费按兼容连接键排序的两侧输入是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_mergejoin，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_mergejoin 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_mergejoin 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_hashjoin · enable_nestloop · enable_sort · enable_indexscan · work_mem

参考资料

9.22 - enable_nestloop

enable_nestloop：允许规划器使用嵌套循环连接计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用嵌套循环连接计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_nestloop 控制规划器是否可以选择嵌套循环连接，包括外侧很小时可能最优的参数化内侧扫描。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

关闭只会抑制嵌套循环，因为有些连接没有其他正确实现。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断嵌套循环连接，包括外侧很小时可能最优的参数化内侧扫描是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_nestloop，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_nestloop 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_nestloop 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 关闭只会抑制嵌套循环，因为有些连接没有其他正确实现。

关联参数

enable_hashjoin · enable_mergejoin · enable_memoize · random_page_cost · work_mem

参考资料

9.23 - enable_parallel_append

enable_parallel_append：允许规划器使用并行感知的 Append 计划。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用并行感知的 Append 计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 ab7271677812 — Support Parallel Append plan nodes.
提交日期 2017-12-05
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 on — on

机制详解

enable_parallel_append 控制规划器是否可以选择并行感知 Append；它让 worker 在多个子计划之间分配工作。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断并行感知 Append；它让 worker 在多个子计划之间分配工作是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_parallel_append，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_parallel_append 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_parallel_append 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_async_append · max_parallel_workers_per_gather · enable_partition_pruning · parallel_leader_participation

参考资料

9.24 - enable_parallel_hash

enable_parallel_hash：允许规划器使用并行哈希计划。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用并行哈希计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 1804284042e6 — Add parallel-aware hash joins.
提交日期 2017-12-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 on — on

机制详解

enable_parallel_hash 控制规划器是否可以选择并行哈希；多个 worker 协同建立并探测共享哈希表。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

enable_hashjoin 关闭时它无效，并且还依赖并行安全计划和可用 worker。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断并行哈希；多个 worker 协同建立并探测共享哈希表是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_parallel_hash，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_parallel_hash 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_parallel_hash 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • enable_hashjoin 关闭时它无效，并且还依赖并行安全计划和可用 worker。

关联参数

enable_hashjoin · max_parallel_workers_per_gather · work_mem · hash_mem_multiplier

参考资料

9.25 - enable_partition_pruning

enable_partition_pruning：允许在规划和执行阶段裁剪分区。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许在规划和执行阶段裁剪分区。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 055fb8d33da6 — Add GUC enable_partition_pruning
提交日期 2018-04-23
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 on — on

机制详解

enable_partition_pruning 控制规划器是否可以选择在规划和执行阶段排除与查询条件矛盾的分区。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断在规划和执行阶段排除与查询条件矛盾的分区是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_partition_pruning，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_partition_pruning 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_partition_pruning 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

constraint_exclusion · enable_partitionwise_join · enable_partitionwise_aggregate · plan_cache_mode

参考资料

9.26 - enable_partitionwise_aggregate

enable_partitionwise_aggregate：允许按分区执行聚合与分组。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许按分区执行聚合与分组。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 e2f1eb0ee30d — Implement partition-wise grouping/aggregation.
提交日期 2018-03-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 off — off

机制详解

enable_partitionwise_aggregate 控制规划器是否可以选择按分区分组或聚合；分组键不含分区键时再执行最终汇总。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

参与分区增多时，它可能近似线性地增加受 work_mem 限制的节点和规划成本。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断按分区分组或聚合；分组键不含分区键时再执行最终汇总是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_partitionwise_aggregate，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_partitionwise_aggregate 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP on 不同于 boot 值 'on'
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 = on (dcs)；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：仅 OLAP 覆盖意在分析型分区模型上利用分区内聚合，同时避免其他模板承担规划与内存放大。

常见坑

  • 把 enable_partitionwise_aggregate 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 参与分区增多时，它可能近似线性地增加受 work_mem 限制的节点和规划成本。

关联参数

enable_partitionwise_join · enable_partition_pruning · work_mem · enable_hashagg · max_parallel_workers_per_gather

参考资料

9.27 - enable_partitionwise_join

enable_partitionwise_join：允许按匹配分区执行连接。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许按匹配分区执行连接。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 2fb1abaeb016 — Rename enable_partition_wise_join to enable_partitionwise_join
提交日期 2018-02-16
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 off — off

机制详解

enable_partitionwise_join 控制规划器是否可以选择当连接键包含兼容分区键时，对一一匹配的分区分别执行连接。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

参与分区增多时，它可能近似线性地增加受 work_mem 限制的节点和规划成本。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 保持上游默认 off。只有两侧是一一兼容分区布局且连接包含全部分区键时，才在会话范围测试 on；同时预算每分区产生的规划 CPU 与受 work_mem 限制节点。
OLAP 分区对齐的分析连接可能从 on 获益，这也是当前 Pigsty OLAP 模板启用它的背景。应比较规划内存、规划时间、总执行内存与分区数，不能只看执行时间。
小规格 除非特定分区对齐连接反复获益，否则保持 off。分区很多时，即使每个局部连接高效，规划与每节点内存也可能在小主机上失衡。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP on 不同于 boot 值 'on'
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 = on (dcs)；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：仅 OLAP 覆盖意在分析型连接中利用匹配分区布局，同时避免其他模板承担更广泛的规划与内存成本。

常见坑

  • 把 enable_partitionwise_join 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 参与分区增多时，它可能近似线性地增加受 work_mem 限制的节点和规划成本。

关联参数

enable_partitionwise_aggregate · enable_partition_pruning · work_mem · join_collapse_limit · max_parallel_workers_per_gather

参考资料

9.28 - enable_presorted_aggregate

enable_presorted_aggregate：允许规划器为带 ORDER BY 或 DISTINCT 的聚合提供预排序输入。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器为带 ORDER BY 或 DISTINCT 的聚合提供预排序输入。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 3226f47282a0 — Add enable_presorted_aggregate GUC
提交日期 2022-12-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 on — on

机制详解

enable_presorted_aggregate 控制规划器是否可以选择为聚合函数的 ORDER BY 或 DISTINCT 子句直接提供已排序输入的计划。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断为聚合函数的 ORDER BY 或 DISTINCT 子句直接提供已排序输入的计划是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_presorted_aggregate，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_presorted_aggregate 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_presorted_aggregate 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_sort · enable_incremental_sort · enable_group_by_reordering · work_mem

参考资料

9.29 - enable_self_join_elimination

enable_self_join_elimination：允许消除可证明冗余的唯一自连接。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许消除可证明冗余的唯一自连接。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 fc069a3a6319 — Implement Self-Join Elimination
提交日期 2025-02-13
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 on — on

机制详解

enable_self_join_elimination 控制规划器是否可以选择在唯一性与谓词能保持语义时，删除普通表上可证明冗余的自连接。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该优化仅适用于普通表，并要求能证明删除重复关系不改变结果。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保留 PG18 默认 on。怀疑回归时只在单个会话比较 on/off，并检查唯一性证明与谓词是否允许删除普通表冗余自连接；不要通过全局关闭掩盖估算问题。
OLAP 自连接消除可减少生成式分析 SQL 的扫描与连接工作。应在代表性语句上验证计划形态与结果等价，并记住它仅适用于普通表和可证明唯一的情况。
小规格 除非隔离出可复现的 PG18 规划器回归，否则保持 on。该开关不会删除任意自连接；缺少证明条件时仍需正确查询与索引设计。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_self_join_elimination 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该优化仅适用于普通表，并要求能证明删除重复关系不改变结果。

关联参数

join_collapse_limit · from_collapse_limit · enable_nestloop · enable_hashjoin

参考资料

9.30 - enable_seqscan

enable_seqscan：允许规划器使用顺序扫描计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用顺序扫描计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_seqscan 控制规划器是否可以选择顺序扫描；它按物理页面次序读取关系。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

关闭只会抑制顺序扫描，因为有些查询仍没有可用替代路径。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断顺序扫描；它按物理页面次序读取关系是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_seqscan，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_seqscan 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_seqscan 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 关闭只会抑制顺序扫描，因为有些查询仍没有可用替代路径。

关联参数

enable_indexscan · enable_bitmapscan · seq_page_cost · random_page_cost · effective_cache_size

参考资料

9.31 - enable_sort

enable_sort：允许规划器使用显式排序步骤。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用显式排序步骤。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_sort 控制规划器是否可以选择在没有可用输入顺序满足目标路径键时插入显式 Sort 节点。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

关闭只会抑制显式排序，因为正确性仍可能要求排序。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断在没有可用输入顺序满足目标路径键时插入显式 Sort 节点是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_sort，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_sort 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_sort 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 关闭只会抑制显式排序，因为正确性仍可能要求排序。

关联参数

work_mem · temp_file_limit · enable_incremental_sort · enable_gathermerge · trace_sort

参考资料

9.32 - enable_tidscan

enable_tidscan：允许规划器使用 TID 扫描计划。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许规划器使用 TID 扫描计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Method Configuration
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

enable_tidscan 控制规划器是否可以选择针对 ctid 等物理元组位置谓词的 TID 扫描。

该值在生成计划时读取。会话级修改适合比较不同 EXPLAIN 方案，但不会追溯改写已缓存计划；必须触发失效或重新规划才能观察到不同选择。

该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 应保留上游默认值。可在事务或会话内临时修改以诊断针对 ctid 等物理元组位置谓词的 TID 扫描是否导致回归，随后修复统计信息、索引、估算或查询形态，不要留下集群级方法禁令。
OLAP 应对代表性分析计划分别测试开启与关闭 enable_tidscan，同时评估规划时间、内存、落盘和执行时间；单份报表获益不能证明适合全局修改。
小规格 不要把 enable_tidscan 当作小主机上的永久 hint。资源压力会改变最佳方法，应使用 EXPLAIN (ANALYZE, BUFFERS) 验证；确有需要也应把范围限制到相关负载。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 enable_tidscan 当成单条查询 hint，却忽略它会影响作用域内生成的所有计划。
  • 用已经缓存的预备计划测试，然后误判该参数没有效果。
  • 通过全局禁用计划方法来掩盖统计信息陈旧或基数估算错误。
  • 该开关改变规划器可以计价的候选路径，并不会让已选中的方法本身变快。

关联参数

enable_indexscan · enable_seqscan · random_page_cost · cpu_tuple_cost

参考资料

9.33 - from_collapse_limit

from_collapse_limit：设置不再折叠子查询的 FROM 列表规模阈值。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置不再折叠子查询的 FROM 列表规模阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值8
8

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 8 — 8

机制详解

from_collapse_limit 限制规划器把可折叠子查询合并到上层 FROM 列表的程度。展平会暴露更多连接顺序与谓词移动机会，也会扩大搜索空间。

若展平会产生超过阈值的 FROM 项，子查询边界就会保留。较小值可缩短规划时间，但可能隐藏更好的全局连接顺序。

最终关系数会与 join_collapse_limit 和 geqo_threshold 联动；提高本值可能让查询意外从穷举规划切换到 GEQO。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性计划显示可重复的全负载问题，否则保留 from_collapse_limit 上游默认值。先测试局部覆盖，并同时计入规划延迟与执行延迟。
OLAP 分析 SQL 的连接、游标或递归规模更大，from_collapse_limit 的影响可能更明显。应测试完整语句族并检查估算，不要照搬一次成功的取值。
小规格 小主机上不要在无实测收益时通过 from_collapse_limit 增加规划搜索或内存压力。优先调整查询结构或使用限定角色设置，而不是集群级覆盖。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 from_collapse_limit 当作执行器资源上限，而不是规划假设或策略。
  • 只测试一组参数值或一种数据分布。
  • 期待已经缓存的计划自动重写。
  • 用全局覆盖掩盖陈旧统计信息或脆弱 SQL 结构。

关联参数

join_collapse_limit · geqo_threshold · geqo · plan_cache_mode

参考资料

9.34 - geqo

geqo：启用遗传查询优化。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：启用遗传查询优化。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

对足够大的连接问题，它选择启发式 GEQO 连接顺序搜索，而不是穷举式动态规划。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo_threshold · geqo_effort · geqo_pool_size · geqo_generations · join_collapse_limit

参考资料

9.35 - geqo_effort

geqo_effort：设置 GEQO 用于推导其他参数默认值的工作强度。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 5，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 GEQO 用于推导其他参数默认值的工作强度。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值5
5

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 5 — 5

机制详解

它是 1 到 10 的便捷旋钮，用于推导种群规模与代数默认值；它不直接参与遗传算法步骤。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo_effort 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo_effort，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo_effort 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo · geqo_pool_size · geqo_generations · geqo_selection_bias · geqo_threshold

参考资料

9.36 - geqo_generations

geqo_generations：设置 GEQO 算法迭代代数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 GEQO 算法迭代代数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

它设置进化迭代代数；零表示根据所选种群规模推导。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo_generations 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo_generations，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo_generations 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo · geqo_pool_size · geqo_effort · geqo_seed · geqo_selection_bias

参考资料

9.37 - geqo_pool_size

geqo_pool_size：设置 GEQO 种群中的个体数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 GEQO 种群中的个体数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

它设置遗传种群中的候选连接顺序数；零表示让 PostgreSQL 根据 effort 与查询规模推导。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo_pool_size 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo_pool_size，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo_pool_size 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo · geqo_effort · geqo_generations · geqo_selection_bias · geqo_seed

参考资料

9.38 - geqo_seed

geqo_seed：设置 GEQO 随机路径选择的种子。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 GEQO 随机路径选择的种子。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

它为 GEQO 随机路径选择设种。修改它会探索不同的连接顺序子集，不会改变表数据或统计信息。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo_seed 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo_seed，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo_seed 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo · geqo_pool_size · geqo_generations · geqo_selection_bias · geqo_threshold

参考资料

9.39 - geqo_selection_bias

geqo_selection_bias：设置 GEQO 种群内的选择压力。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 GEQO 种群内的选择压力。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1.5 – 2
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 2 — 2

机制详解

它控制选择压力：较高值更强地偏好高适应度候选，但也会降低种群多样性。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo_selection_bias 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo_selection_bias，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo_selection_bias 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo · geqo_pool_size · geqo_generations · geqo_seed · geqo_effort

参考资料

9.40 - geqo_threshold

geqo_threshold：设置 FROM 项达到多少时改用 GEQO。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 12，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 FROM 项达到多少时改用 GEQO。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值2 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Genetic Query Optimizer
上游分类
最后 boot 值 值12
12

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 12 — 12

机制详解

它统计 FROM 项，在达到阈值时把符合条件的连接问题切换到 GEQO；一个 FULL OUTER JOIN 构造只算一项。

GEQO 以可能错过最佳连接顺序为代价，把规划时间控制在启发式搜索范围内。构造候选之后，它仍使用普通规划器成本模型为扫描与连接路径计价。

该值在规划阶段读取；GEQO 的随机搜索意味着计划质量会随种子与搜索预算变化。折叠阈值会改变暴露给连接搜索的关系数，因此也会影响是否越过 GEQO 阈值。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测多表连接规划时间有问题，否则保留 geqo_threshold 上游默认值。全局扩大随机搜索预算前，应先简化生成 SQL 或修复连接估算。
OLAP 对反复执行的多表报表，应在多个 geqo_seed 下测试 geqo_threshold，同时比较规划与执行时间。偶然命中的好种子不是稳定生产策略。
小规格 小主机上不要通过调整 geqo_threshold 消耗不成比例的规划 CPU。默认自适应取值通常比照搬大系统搜索预算更安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只根据一次随机 GEQO 运行判断计划质量。
  • 调整 GEQO 旋钮却没有考虑 geqo_threshold 与折叠阈值。
  • 为微小或不稳定的执行收益付出大幅规划 CPU。
  • 误以为 GEQO 保证找到全局最佳连接顺序。

关联参数

geqo · geqo_effort · join_collapse_limit · from_collapse_limit · geqo_seed

参考资料

9.41 - jit

当构建包含可用的 JIT 实现且计划估算成本越过阈值时，允许 PostgreSQL 使用即时编译。开启并不意味着每条查询都会执行 JIT。
说明

Fact — 官方简述译文：在 JIT 可用且成本规则选中查询时允许即时编译。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 432bb9e04da4 — Basic JIT provider and error handling infrastructure.
提交日期 2018-03-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11 off — off
PG12–18 on — on
PG19 Beta 3 off — off

机制详解

jit 是总开关。开启后，jit_above_cost 决定是否开始编译，jit_inline_above_cost 与 jit_optimize_above_cost 控制额外且成本更高的内联和优化工作。

JIT 主要有利于运行时间长、CPU 密集的查询，常见于分析负载。编译本身增加延迟，因此过度降低阈值可能让短语句更慢。

决策发生在规划阶段。使用通用计划的预备语句由生成该计划时的配置决定；EXPLAIN ANALYZE 会显示 JIT 是否执行以及各阶段耗时。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持较高默认阈值；若短请求尾延迟中出现编译开销，可关闭 JIT。应先按语句或角色测试，再考虑全局修改。
OLAP 保持可用，并针对 CPU 密集的聚合、表达式和扫描做基准；评估总执行时间时必须包含生成、内联、优化和代码发射开销。
小规格 小型且 CPU 受限系统上的普通查询通常获益有限。保持开启并使用保守阈值，与降低阈值强制编译是两回事。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 若 PostgreSQL 构建没有可用 JIT 实现，jit=on 也不会生效。
  • 开启不等于每条查询都编译，成本阈值仍会筛选。
  • 降低阈值可能让短查询比解释执行更慢。
  • 通用预备计划采用生成计划时的配置。
  • 估算成本不是执行时间，必须用代表性计划实测阈值效果。

关联参数

jit_above_cost · jit_inline_above_cost · jit_optimize_above_cost · jit_provider · plan_cache_mode · jit_expressions

参考资料

9.42 - jit_above_cost

jit_above_cost：设置启用 JIT 编译的查询成本阈值。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 100000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置启用 JIT 编译的查询成本阈值。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值-1 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值100000
100000

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 cc415a56d09a — Basic planner and executor integration for JIT.
提交日期 2018-03-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 100000 — 100000

机制详解

jit_above_cost 把最终计划的估算成本与阈值比较，决定 PostgreSQL 是否可以开始 JIT 编译。这里的成本是规划器任意单位的估计，并非毫秒。

决策发生在规划阶段，且只有 jit 已开启并存在可用 provider 时才有意义。通用预备计划会保留生成该通用计划时作出的决定。

设置为 -1 会关闭该阶段。jit_inline_above_cost 与 jit_optimize_above_cost 是越过 jit_above_cost 后的附加门槛，因此把它们设得低于基础编译阈值没有意义。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要为一条 CPU 密集语句全局降低 jit_above_cost。短查询尾延迟会直接承受编译开销；应按语句或角色测试，并把 JIT 生成时间计入结果。
OLAP 对长时间 CPU 密集查询，应在 jit_above_cost 阈值两侧比较总耗时。只有节省的执行 CPU 能稳定覆盖编译开销时，降低阈值才有价值。
小规格 保持默认值；当 LLVM 工作会争抢有限 CPU 时可用 -1 关闭相应阶段。估算成本高并不能证明 JIT 一定收回启动成本。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把阈值误读为毫秒，而不是规划器任意成本单位。
  • 基准测试时忽略 JIT 生成、内联、优化和代码发射时间。
  • 期望修改该值后已生成的通用计划会自动改变。
  • 把附加阶段阈值设得低于 jit_above_cost，并误以为该阶段能独立运行。

关联参数

jit · jit_inline_above_cost · jit_optimize_above_cost · jit_expressions

参考资料

9.43 - jit_inline_above_cost

jit_inline_above_cost：设置 JIT 尝试内联的查询成本阈值。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 500000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 JIT 尝试内联的查询成本阈值。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值-1 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值500000
500000

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 9370462e9a79 — Add inlining support to LLVM JIT provider.
提交日期 2018-03-28
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 500000 — 500000

机制详解

jit_inline_above_cost 把最终计划的估算成本与阈值比较，决定 PostgreSQL 是否可以执行 JIT 内联。这里的成本是规划器任意单位的估计，并非毫秒。

决策发生在规划阶段，且只有 jit 已开启并存在可用 provider 时才有意义。通用预备计划会保留生成该通用计划时作出的决定。

设置为 -1 会关闭该阶段。jit_inline_above_cost 与 jit_optimize_above_cost 是越过 jit_above_cost 后的附加门槛，因此把它们设得低于基础编译阈值没有意义。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要为一条 CPU 密集语句全局降低 jit_inline_above_cost。短查询尾延迟会直接承受编译开销；应按语句或角色测试，并把 JIT 生成时间计入结果。
OLAP 对长时间 CPU 密集查询，应在 jit_inline_above_cost 阈值两侧比较总耗时。只有节省的执行 CPU 能稳定覆盖编译开销时，降低阈值才有价值。
小规格 保持默认值；当 LLVM 工作会争抢有限 CPU 时可用 -1 关闭相应阶段。估算成本高并不能证明 JIT 一定收回启动成本。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把阈值误读为毫秒，而不是规划器任意成本单位。
  • 基准测试时忽略 JIT 生成、内联、优化和代码发射时间。
  • 期望修改该值后已生成的通用计划会自动改变。
  • 把附加阶段阈值设得低于 jit_above_cost，并误以为该阶段能独立运行。

关联参数

jit · jit_above_cost · jit_optimize_above_cost · jit_expressions

参考资料

9.44 - jit_optimize_above_cost

jit_optimize_above_cost：设置 JIT 执行昂贵优化的查询成本阈值。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 500000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 JIT 执行昂贵优化的查询成本阈值。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值-1 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值500000
500000

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 cc415a56d09a — Basic planner and executor integration for JIT.
提交日期 2018-03-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 500000 — 500000

机制详解

jit_optimize_above_cost 把最终计划的估算成本与阈值比较，决定 PostgreSQL 是否可以执行昂贵的 JIT 优化过程。这里的成本是规划器任意单位的估计，并非毫秒。

决策发生在规划阶段，且只有 jit 已开启并存在可用 provider 时才有意义。通用预备计划会保留生成该通用计划时作出的决定。

设置为 -1 会关闭该阶段。jit_inline_above_cost 与 jit_optimize_above_cost 是越过 jit_above_cost 后的附加门槛，因此把它们设得低于基础编译阈值没有意义。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要为一条 CPU 密集语句全局降低 jit_optimize_above_cost。短查询尾延迟会直接承受编译开销；应按语句或角色测试，并把 JIT 生成时间计入结果。
OLAP 对长时间 CPU 密集查询，应在 jit_optimize_above_cost 阈值两侧比较总耗时。只有节省的执行 CPU 能稳定覆盖编译开销时，降低阈值才有价值。
小规格 保持默认值；当 LLVM 工作会争抢有限 CPU 时可用 -1 关闭相应阶段。估算成本高并不能证明 JIT 一定收回启动成本。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把阈值误读为毫秒，而不是规划器任意成本单位。
  • 基准测试时忽略 JIT 生成、内联、优化和代码发射时间。
  • 期望修改该值后已生成的通用计划会自动改变。
  • 把附加阶段阈值设得低于 jit_above_cost，并误以为该阶段能独立运行。

关联参数

jit · jit_above_cost · jit_inline_above_cost · jit_expressions

参考资料

9.45 - join_collapse_limit

join_collapse_limit：设置不再展平 JOIN 构造的 FROM 列表规模阈值。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置不再展平 JOIN 构造的 FROM 列表规模阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值8
8

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 8 — 8

机制详解

join_collapse_limit 控制何时把显式 JOIN 构造（FULL JOIN 除外）展平为可重排的 FROM 列表。设置为 1 会保留 SQL 写出的显式连接顺序。

展平扩大规划器可探索的连接顺序集合，可能改善计划，但会消耗更多规划 CPU 与内存；外连接语义仍会限制合法重排。

暴露的项数会与 from_collapse_limit 和 geqo_threshold 联动。把 1 当作手工连接顺序工具会把责任转给 SQL 作者，并不构成通用计划稳定性保证。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性计划显示可重复的全负载问题，否则保留 join_collapse_limit 上游默认值。先测试局部覆盖，并同时计入规划延迟与执行延迟。
OLAP 分析 SQL 的连接、游标或递归规模更大，join_collapse_limit 的影响可能更明显。应测试完整语句族并检查估算，不要照搬一次成功的取值。
小规格 小主机上不要在无实测收益时通过 join_collapse_limit 增加规划搜索或内存压力。优先调整查询结构或使用限定角色设置，而不是集群级覆盖。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 join_collapse_limit 当作执行器资源上限，而不是规划假设或策略。
  • 只测试一组参数值或一种数据分布。
  • 期待已经缓存的计划自动重写。
  • 用全局覆盖掩盖陈旧统计信息或脆弱 SQL 结构。

关联参数

from_collapse_limit · geqo_threshold · geqo · enable_hashjoin · enable_nestloop

参考资料

9.46 - min_eager_agg_group_size

min_eager_agg_group_size：设置考虑提前聚合所需的最小平均分组大小。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置考虑提前聚合所需的最小平均分组大小。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值8
8

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 8e11859102f9 — Implement Eager Aggregation
提交日期 2025-10-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 8 — 8

机制详解

min_eager_agg_group_size：设置考虑提前聚合所需的最小平均分组大小。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这个成本阈值表示：估算每组平均至少有多少输入行，提前聚合才值得考虑。提高它会要求更明显的行数缩减；降低它会探索更多提前聚合路径，但可能把规划与执行开销花在几乎不能缩小连接输入的分组上。

应与 enable_eager_aggregate、enable_hashagg、enable_partitionwise_aggregate、work_mem 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先按会话使用 EXPLAIN (ANALYZE, BUFFERS) 和有代表性的参数分布实验。只有提前聚合能稳定减少行数和延迟、且不引入计划抖动时才偏离默认值。
OLAP 测试确有预聚合机会的连接，并覆盖新旧统计信息与落盘压力；比较总 CPU、峰值内存、中间行数和并行计划，而不只看一次耗时。
小规格 在定位出可复现回归前保持规划器开关与阈值默认。先修复基数统计；全局强制路径常会用一个查询的收益换来更多回归。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 min_eager_agg_group_size 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

enable_eager_aggregate · enable_hashagg · enable_partitionwise_aggregate · work_mem · hash_mem_multiplier

参考资料

9.47 - min_parallel_index_scan_size

min_parallel_index_scan_size：设置考虑并行索引扫描所需的最小索引数据量。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 512 KiB (64 × 8kB)，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置考虑并行索引扫描所需的最小索引数据量。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值0 – 715827882
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值64
512 KiB (64 × 8kB)

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 51ee6f3160d2 — Replace min_parallel_relation_size with two new GUCs.
提交日期 2017-02-15
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 64 8kB 512 KiB (64 × 8kB)

机制详解

min_parallel_index_scan_size 是规划器的候选资格下限：只有预计会访问的索引页面量达到配置规模时，才会考虑并行扫描路径。

越过该下限并不保证产生并行计划。规划器仍会比较成本、检查并行安全性，并受 max_parallel_workers_per_gather 与集群 worker 池约束。

索引阈值还参与判断索引能否并行 vacuum。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 提高 min_parallel_index_scan_size 可减少短 OLTP 扫描启动并行，但要确认报表与维护任务没有回归。Pigsty 的 OLTP/crit 取值是规划策略偏好，并非资源上限。
OLAP 除非较小但昂贵的扫描被错误排除，否则保留上游阈值。降低 min_parallel_index_scan_size 会在大量并发查询时增加规划与 worker 开销。
小规格 小主机上 worker 启动与内存竞争更突出，宜采用保守或更高阈值，并与 max_parallel_workers_per_gather 联动，而不是单独调整。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 2MB 不同于 boot 值 2MB
OLAP 未修改 — —
CRIT 2MB 不同于 boot 值 2MB
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 = 2MB (dcs)；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 = 2MB (dcs)；TINY: PG10–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：OLTP/crit 取值提高索引并行候选下限以降低并行倾向，OLAP 与 tiny 保留上游行为。

常见坑

  • 误以为阈值限制实际读取字节；它只控制规划器候选资格。
  • 认为规模估计一越过阈值就必然产生并行计划。
  • 降低阈值却没有为并发下的 worker 与节点内存做预算。
  • 比较裸数值时忘记应用 8kB 块单位。

关联参数

max_parallel_workers_per_gather · parallel_setup_cost · parallel_tuple_cost · max_parallel_workers · enable_indexscan

参考资料

9.48 - min_parallel_relation_size

min_parallel_relation_size：设置可考虑并行扫描的关系最小尺寸。实测在档范围为 PG9.6；最后在档的 PG9.6 启动默认值为 8 MiB (1024 × 8kB)，context 为 user。它在 PG10 被移除。
说明

Fact — 官方简述译文：设置可考虑并行扫描的关系最小尺寸。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值0 – 715827882
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值1024
8 MiB (1024 × 8kB)

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6
移除版本 PG10
引入提交 75be66464cb1 — Invent min_parallel_relation_size GUC to replace a hard-wired constant.
提交日期 2016-06-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6 1024 8kB 8 MiB (1024 × 8kB)

机制详解

min_parallel_relation_size：设置可考虑并行扫描的关系最小尺寸。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG9.6 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PG9.6 使用单一关系尺寸阈值判断是否值得考虑并行扫描。PG10 将它拆成 min_parallel_table_scan_size 与 min_parallel_index_scan_size，让 heap 与索引访问路径拥有不同的盈亏平衡点。

应与 min_parallel_table_scan_size、min_parallel_index_scan_size、max_parallel_workers_per_gather、enable_parallel_append 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.6 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6 未修改；OLAP: PG9.6 未修改；CRIT: PG9.6 未修改；TINY: PG9.6 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 min_parallel_relation_size 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

min_parallel_table_scan_size · min_parallel_index_scan_size · max_parallel_workers_per_gather · enable_parallel_append

参考资料

9.49 - min_parallel_table_scan_size

min_parallel_table_scan_size：设置考虑并行表扫描所需的最小表数据量。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8 MiB (1024 × 8kB)，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置考虑并行表扫描所需的最小表数据量。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值0 – 715827882
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值1024
8 MiB (1024 × 8kB)

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 51ee6f3160d2 — Replace min_parallel_relation_size with two new GUCs.
提交日期 2017-02-15
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 1024 8kB 8 MiB (1024 × 8kB)

机制详解

min_parallel_table_scan_size 是规划器的候选资格下限：只有预计会扫描的表数据量达到配置规模时，才会考虑并行扫描路径。

越过该下限并不保证产生并行计划。规划器仍会比较成本、检查并行安全性，并受 max_parallel_workers_per_gather 与集群 worker 池约束。

对并行顺序扫描，估算量通常是整个关系大小。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 提高 min_parallel_table_scan_size 可减少短 OLTP 扫描启动并行，但要确认报表与维护任务没有回归。Pigsty 的 OLTP/crit 取值是规划策略偏好，并非资源上限。
OLAP 除非较小但昂贵的扫描被错误排除，否则保留上游阈值。降低 min_parallel_table_scan_size 会在大量并发查询时增加规划与 worker 开销。
小规格 小主机上 worker 启动与内存竞争更突出，宜采用保守或更高阈值，并与 max_parallel_workers_per_gather 联动，而不是单独调整。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 32MB 不同于 boot 值 32MB
OLAP 未修改 — —
CRIT 32MB 不同于 boot 值 32MB
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 = 32MB (dcs)；OLAP: PG10–19 Beta 3 未修改；CRIT: PG10–19 Beta 3 = 32MB (dcs)；TINY: PG10–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：OLTP/crit 取值提高表扫描并行候选下限以降低并行倾向，OLAP 与 tiny 保留上游行为。

常见坑

  • 误以为阈值限制实际读取字节；它只控制规划器候选资格。
  • 认为规模估计一越过阈值就必然产生并行计划。
  • 降低阈值却没有为并发下的 worker 与节点内存做预算。
  • 比较裸数值时忘记应用 8kB 块单位。

关联参数

max_parallel_workers_per_gather · parallel_setup_cost · parallel_tuple_cost · max_parallel_workers · enable_seqscan

参考资料

9.50 - parallel_setup_cost

parallel_setup_cost：设置规划器启动并行工作进程的成本估计。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置规划器启动并行工作进程的成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值1000
1000

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 3bd909b22093 — Add a Gather executor node.
提交日期 2015-09-30
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 1000 — 1000

机制详解

parallel_setup_cost 用于刻画为计划启动并行 worker 的固定开销。它只是路径估算成本的一项，不会直接分配资源或改变执行器行为。

规划器成本单位是任意尺度，只有比例有意义。把所有成本常量同比例缩放不会改变路径排序；只改一项则会改变 I/O、行处理、操作符与并行开销之间的权衡。

生成计划时才会读取该值。统计信息、行数估计、缓存假设、tablespace 覆盖以及可用计划方法，都可能比小幅调整这个常量影响更大。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应依据代表性负载校准 parallel_setup_cost，不能依据单个计划。先修复陈旧统计，并用 EXPLAIN (ANALYZE, BUFFERS) 比较估算与实际；能按角色或 tablespace 限定时不要全局修改。
OLAP 分析负载可能需要不同的 CPU 与 I/O 权衡，但应把 parallel_setup_cost 与相关成本模型一起调整，并验证完整的扫描、连接与聚合组合。
小规格 除非反复证据表明存在系统性建模偏差，否则保留上游值。小系统上并发与缓存驻留通常比细调 parallel_setup_cost 更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 2000 不同于 boot 值 2000
OLAP 未修改 — —
CRIT 2000 不同于 boot 值 2000
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 2000 (dcs)；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 = 2000 (dcs)；TINY: PG9.6–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：OLTP/crit 把启动估算翻倍，意在不完全禁用的前提下降低并行计划倾向；OLAP 与 tiny 保留上游行为。

常见坑

  • 把数值解释为实际耗时或硬资源上限。
  • 为修复单条查询而调整，导致更广泛负载回归。
  • 在修正统计信息与基数估计之前先改成本常量。
  • 忘记只有各成本项的相对值会影响路径选择。

关联参数

parallel_tuple_cost · max_parallel_workers_per_gather · min_parallel_table_scan_size · max_parallel_workers

参考资料

9.51 - parallel_tuple_cost

parallel_tuple_cost：设置把每行从并行 worker 传给 leader 的成本估计。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.1，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置把每行从并行 worker 传给 leader 的成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值0.1
0.1

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 3bd909b22093 — Add a Gather executor node.
提交日期 2015-09-30
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 0.1 — 0.1

机制详解

parallel_tuple_cost 用于刻画把每行从并行 worker 传给另一个进程的开销。它只是路径估算成本的一项，不会直接分配资源或改变执行器行为。

规划器成本单位是任意尺度，只有比例有意义。把所有成本常量同比例缩放不会改变路径排序；只改一项则会改变 I/O、行处理、操作符与并行开销之间的权衡。

生成计划时才会读取该值。统计信息、行数估计、缓存假设、tablespace 覆盖以及可用计划方法，都可能比小幅调整这个常量影响更大。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应依据代表性负载校准 parallel_tuple_cost，不能依据单个计划。先修复陈旧统计，并用 EXPLAIN (ANALYZE, BUFFERS) 比较估算与实际；能按角色或 tablespace 限定时不要全局修改。
OLAP 分析负载可能需要不同的 CPU 与 I/O 权衡，但应把 parallel_tuple_cost 与相关成本模型一起调整，并验证完整的扫描、连接与聚合组合。
小规格 除非反复证据表明存在系统性建模偏差，否则保留上游值。小系统上并发与缓存驻留通常比细调 parallel_tuple_cost 更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0.2 不同于 boot 值 0.2
OLAP 未修改 — —
CRIT 0.2 不同于 boot 值 0.2
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 0.2 (dcs)；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 = 0.2 (dcs)；TINY: PG9.6–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：OLTP/crit 把元组传输估算翻倍，意在降低元组量大路径的并行计划倾向；OLAP 与 tiny 保留上游行为。

常见坑

  • 把数值解释为实际耗时或硬资源上限。
  • 为修复单条查询而调整，导致更广泛负载回归。
  • 在修正统计信息与基数估计之前先改成本常量。
  • 忘记只有各成本项的相对值会影响路径选择。

关联参数

parallel_setup_cost · max_parallel_workers_per_gather · parallel_leader_participation · enable_gathermerge

参考资料

9.52 - plan_cache_mode

plan_cache_mode：控制规划器选择自定义计划还是通用计划。实测在档范围为 PG12–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 auto，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：控制规划器选择自定义计划还是通用计划。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值auto, force_generic_plan, force_custom_plan
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值auto
auto

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 f7cb2842bf47 — Add plan_cache_mode setting
提交日期 2018-07-16
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 auto — auto

机制详解

预备语句可以使用根据当前参数值生成的自定义计划，也可以使用与参数值无关的通用计划。plan_cache_mode 以 auto、force_custom_plan 或 force_generic_plan 覆盖 PostgreSQL 的正常成本选择。

该设置在执行缓存语句时检查，而不是在 PREPARE 时检查。自定义计划反复支付规划成本但能适应数据倾斜；通用计划节省规划工作，却可能不适合参数敏感谓词。

PL/pgSQL 和协议层预备语句都会受影响。强制模式是诊断或特定负载策略，不是修复统计信息不准或索引缺失的方法。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性计划显示可重复的全负载问题，否则保留 plan_cache_mode 上游默认值。先测试局部覆盖，并同时计入规划延迟与执行延迟。
OLAP 分析 SQL 的连接、游标或递归规模更大，plan_cache_mode 的影响可能更明显。应测试完整语句族并检查估算，不要照搬一次成功的取值。
小规格 小主机上不要在无实测收益时通过 plan_cache_mode 增加规划搜索或内存压力。优先调整查询结构或使用限定角色设置，而不是集群级覆盖。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 plan_cache_mode 当作执行器资源上限，而不是规划假设或策略。
  • 只测试一组参数值或一种数据分布。
  • 期待已经缓存的计划自动重写。
  • 用全局覆盖掩盖陈旧统计信息或脆弱 SQL 结构。

关联参数

default_statistics_target · cursor_tuple_fraction · join_collapse_limit · compute_query_id · jit_above_cost

参考资料

9.53 - random_page_cost

这是描述非顺序页面访问相对顺序访问成本的规划器常量。降低它会让索引和位图访问路径显得更便宜，但不会改变存储系统本身的行为。
说明

Fact — 官方简述译文：设置规划器对非顺序读取页面的相对成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值4
4

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 4 — 4

机制详解

规划器成本单位是任意尺度，主要看各成本常量之间的相对关系。seq_page_cost 通常约定为 1.0，random_page_cost 则在考虑缓存命中与存储特性后描述随机访问的平均惩罚。

相对 seq_page_cost 降低本值会偏向索引扫描，提高则会让索引扫描显得更贵。两者都可按 tablespace 覆盖，适合一个集群存在多种存储层级的情况。

官方建议把这些常量视为整个查询组合的平均模型，并警告不要根据少量实验贸然修改。执行计划还受统计信息、effective_cache_size、数据相关性和查询形态影响。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 低延迟 SSD 且缓存命中率高时，1.1 可作为试验起点而非普遍真理；上线前比较代表性 EXPLAIN (ANALYZE, BUFFERS) 与尾延迟。
OLAP 不要仅因使用 SSD 就降低它；分析查询仍可能适合顺序扫描。应依据完整的扫描与索引访问组合校准，并考虑 tablespace 级设置。
小规格 若数据库通常完全驻留缓存，可考虑接近 seq_page_cost 的值；不要设得更低，并应先排除统计信息陈旧造成的错误计划。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1.1 不同于 boot 值 1.1
OLAP 1.1 不同于 boot 值 1.1
CRIT 1.1 不同于 boot 值 1.1
TINY 1.1 不同于 boot 值 1.1
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 1.1 (dcs)；OLAP: PG9.0–19 Beta 3 = 1.1 (dcs)；CRIT: PG9.0–19 Beta 3 = 1.1 (dcs)；TINY: PG9.0–19 Beta 3 = 1.1 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：1.1 用于刻画 SSD 与高缓存命中环境中随机访问更接近顺序访问的成本。

常见坑

  • 该数值是相对规划成本，不是毫秒或设备实测延迟。
  • 为修复单条查询而降低它可能伤害整体负载。
  • 基数估算错误常被误认为存储成本参数错误。
  • 低于 seq_page_cost 通常不符合物理直觉。
  • 全局值可能无法表示 SSD、HDD、网络存储混合的 tablespace。

关联参数

seq_page_cost · effective_cache_size · effective_io_concurrency · default_statistics_target · enable_indexscan · enable_bitmapscan

参考资料

9.54 - recursive_worktable_factor

recursive_worktable_factor：设置递归查询工作表平均大小的规划器估计倍数。实测在档范围为 PG15–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 10，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置递归查询工作表平均大小的规划器估计倍数。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0.001 – 1e+06
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Other Planner Options
上游分类
最后 boot 值 值10
10

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 0bd7af082ace — Invent recursive_worktable_factor GUC to replace hard-wired constant.
提交日期 2022-03-24
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 10 — 10

机制详解

recursive_worktable_factor 把递归工作表的平均规模估计为非递归种子项的倍数。该估计参与工作表与其他关系连接的成本计算。

它不限制递归、内存、行数或迭代次数。低扇出的遍历可用更小值建模，高扇出的图扩展则可能需要更大估计。

该值在规划阶段使用；实际递归增长仍取决于数据与终止谓词。估计错误可能让递归项内部选择不合适的连接方法。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性计划显示可重复的全负载问题，否则保留 recursive_worktable_factor 上游默认值。先测试局部覆盖，并同时计入规划延迟与执行延迟。
OLAP 分析 SQL 的连接、游标或递归规模更大，recursive_worktable_factor 的影响可能更明显。应测试完整语句族并检查估算，不要照搬一次成功的取值。
小规格 小主机上不要在无实测收益时通过 recursive_worktable_factor 增加规划搜索或内存压力。优先调整查询结构或使用限定角色设置，而不是集群级覆盖。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 recursive_worktable_factor 当作执行器资源上限，而不是规划假设或策略。
  • 只测试一组参数值或一种数据分布。
  • 期待已经缓存的计划自动重写。
  • 用全局覆盖掩盖陈旧统计信息或脆弱 SQL 结构。

关联参数

work_mem · enable_nestloop · enable_hashjoin · default_statistics_target

参考资料

9.55 - seq_page_cost

seq_page_cost：设置规划器顺序读取磁盘页面的成本估计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置规划器顺序读取磁盘页面的成本估计。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1.79769e+308
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Query Tuning / Planner Cost Constants
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 1 — 1

机制详解

seq_page_cost 用于刻画顺序页面读取，也是规划器任意成本尺度的约定基准。它只是路径估算成本的一项，不会直接分配资源或改变执行器行为。

规划器成本单位是任意尺度，只有比例有意义。把所有成本常量同比例缩放不会改变路径排序；只改一项则会改变 I/O、行处理、操作符与并行开销之间的权衡。

生成计划时才会读取该值。统计信息、行数估计、缓存假设、tablespace 覆盖以及可用计划方法，都可能比小幅调整这个常量影响更大。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应依据代表性负载校准 seq_page_cost，不能依据单个计划。先修复陈旧统计，并用 EXPLAIN (ANALYZE, BUFFERS) 比较估算与实际；能按角色或 tablespace 限定时不要全局修改。
OLAP 分析负载可能需要不同的 CPU 与 I/O 权衡，但应把 seq_page_cost 与相关成本模型一起调整，并验证完整的扫描、连接与聚合组合。
小规格 除非反复证据表明存在系统性建模偏差，否则保留上游值。小系统上并发与缓存驻留通常比细调 seq_page_cost 更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把数值解释为实际耗时或硬资源上限。
  • 为修复单条查询而调整，导致更广泛负载回归。
  • 在修正统计信息与基数估计之前先改成本常量。
  • 忘记只有各成本项的相对值会影响路径选择。

关联参数

random_page_cost · cpu_tuple_cost · effective_cache_size · enable_seqscan · effective_io_concurrency

参考资料

10 - 复制

Replication 分类下的 33 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

10.1 - hot_standby

hot_standby：允许在恢复期间连接并执行查询。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许在恢复期间连接并执行查询。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 off — off
PG10–19 Beta 3 on — on

机制详解

允许在恢复期间连接并执行查询。该值在服务器启动时固定，修改后必须重启。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 hot_standby 与 primary_conninfo、primary_slot_name、restore_command 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 hot_standby；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

primary_conninfo · primary_slot_name · restore_command · wal_receiver_timeout · wal_retrieve_retry_interval · max_standby_archive_delay

参考资料

10.2 - hot_standby_feedback

hot_standby_feedback：允许热备库向主库反馈信息，以避免查询冲突。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许热备库向主库反馈信息，以避免查询冲突。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 bca8b7f16a3e — Hot Standby feedback for avoidance of cleanup conflicts on standby. Standby optionally sends back information about oldestXmin of queries which is then checked and applied to the WALSender’s proc->xmin. GetOldestXmin() is modified slightly to agree with GetSnapshotData(), so that all backends on primary include WALSender within their snapshots. Note this does nothing to change the snapshot xmin on either master or standby. Feedback piggybacks on the standby reply message. vacuum_defer_cleanup_age is no longer used on standby, though parameter still exists on primary, since some use cases still exist.
提交日期 2011-02-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

启用后，备库会向主库或上游备库报告当前查询快照仍需要的可见性信息，使上游避免清理由这些查询仍可见的旧行版本。反馈发送频率不会高于 wal_receiver_status_interval。

避免清理冲突会把代价转移到主库：死亡行版本存活更久，表与索引膨胀以及后续 VACUUM 工作都会增加。在级联复制中反馈会继续向上传递，因此很下游的一个旧快照也可能影响主库。

该机制只缓解清理记录冲突，并不能消除全部热备冲突。DDL 锁、删除对象、表空间操作和某些页面级冲突仍会取消查询。无槽备库断开时反馈会中断，时钟跳变也可能影响发送时序。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有减少备库查询取消的收益高于主库膨胀风险时才启用。限制备库查询时长，监控事务年龄、死亡元组、表增长、VACUUM 进度和 pg_stat_database_conflicts；纯 HA 备库通常更重视及时重放。
OLAP 对长查询报表备库很有价值，但必须搭配工作负载超时和主库膨胀预算。如果分析快照经常阻止清理数小时，应考虑独立报表拓扑。
小规格 除非已证明查询取消是问题，否则从 off 开始。有限存储使主库膨胀风险更高；启用后应使用较短查询上限和积极监控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 = on (dcs)；OLAP: PG9.1–19 Beta 3 = on (dcs)；CRIT: PG9.1–19 Beta 3 = on (dcs)；TINY: PG9.1–19 Beta 3 = on (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 启用后忽略主库表或索引膨胀。
  • 期待它阻止 DDL、锁、删除数据库或表空间冲突。
  • 允许下游备库无限长查询长期阻止上游清理。
  • 认为无槽备库断开期间反馈仍然有效。
  • 分析反馈时序时忽略时钟跳变和 wal_receiver_status_interval。

关联参数

max_standby_streaming_delay · max_standby_archive_delay · wal_receiver_status_interval · primary_slot_name · autovacuum_vacuum_scale_factor · log_recovery_conflict_waits

参考资料

10.3 - idle_replication_slot_timeout

idle_replication_slot_timeout：设置复制槽保持空闲多久后失效。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置复制槽保持空闲多久后失效。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值0
0 s

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 ac0e33136abc — Invalidate inactive replication slots.
提交日期 2025-02-19
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 0 s 0 s

机制详解

设置复制槽保持空闲多久后失效。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

PostgreSQL 18 从 pg_replication_slots.inactive_since 计算空闲时间，并在超过阈值后的检查点使合格槽失效。零禁用策略；不保留 WAL 的槽与从主库同步来的备库槽不适用。

应把 idle_replication_slot_timeout 与 max_replication_slots、max_slot_wal_keep_size、primary_slot_name 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 idle_replication_slot_timeout；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 7d 不同于 boot 值 7d
OLAP 7d 不同于 boot 值 7d
CRIT 3d 不同于 boot 值 3d
TINY 7d 不同于 boot 值 7d
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 = 7d (dcs)；OLAP: PG18–19 Beta 3 = 7d (dcs)；CRIT: PG18–19 Beta 3 = 3d (dcs)；TINY: PG18–19 Beta 3 = 7d (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在使遗忘的 PG18 复制槽失效，并给 CRIT 更严格的窗口；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 期待时长一到立刻失效，而不是等后续检查点。
  • 误以为同步来的备库槽也适用。
  • 自动失效前没有订阅者重建 runbook。
  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。

关联参数

max_replication_slots · max_slot_wal_keep_size · primary_slot_name · wal_keep_size · checkpoint_timeout · max_wal_senders

参考资料

10.4 - max_active_replication_origins

max_active_replication_origins：设置可同时活动的复制源最大数量。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 10，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置可同时活动的复制源最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Subscribers
上游分类
最后 boot 值 值10
10

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 04ff636cbce4 — Add GUC option to control maximum active replication origins.
提交日期 2025-03-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 10 — 10

机制详解

设置可同时活动的复制源最大数量。该值在服务器启动时固定，修改后必须重启。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 max_active_replication_origins 与 max_logical_replication_workers、max_replication_slots、track_commit_timestamp 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_active_replication_origins；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_logical_replication_workers · max_replication_slots · track_commit_timestamp · max_parallel_apply_workers_per_subscription · max_sync_workers_per_subscription · hot_standby

参考资料

10.5 - max_logical_replication_workers

max_logical_replication_workers：设置逻辑复制 worker 进程的最大数量。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 4，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置逻辑复制 worker 进程的最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Subscribers
上游分类
最后 boot 值 值4
4

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 665d1fad99e7 — Logical replication
提交日期 2017-01-19
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 4 — 4

机制详解

设置逻辑复制 worker 进程的最大数量。该值在服务器启动时固定，修改后必须重启。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 max_logical_replication_workers 与 max_parallel_apply_workers_per_subscription、max_sync_workers_per_subscription、max_worker_processes 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_logical_replication_workers；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 8 不同于 boot 值 8
OLAP 8 不同于 boot 值 8
CRIT 8 不同于 boot 值 8
TINY 8 不同于 boot 值 8
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 = 8 (dcs)；OLAP: PG10–19 Beta 3 = 8 (dcs)；CRIT: PG10–19 Beta 3 = 8 (dcs)；TINY: PG10–19 Beta 3 = 8 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在为多个逻辑订阅与表同步任务留出 worker 余量；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_parallel_apply_workers_per_subscription · max_sync_workers_per_subscription · max_worker_processes · max_replication_slots · max_active_replication_origins · track_commit_timestamp

参考资料

10.6 - max_parallel_apply_workers_per_subscription

max_parallel_apply_workers_per_subscription：设置每个订阅的并行应用 worker 最大数量。它是 PG16–18 的 sighup 参数；最新实测启动默认值为 2。
说明

Fact — 官方简述译文：设置每个订阅的并行应用 worker 最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 1024
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Subscribers
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 216a784829c2 — Perform apply of large transactions by parallel workers.
提交日期 2023-01-09
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 2 — 2

机制详解

设置每个订阅的并行应用 worker 最大数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 max_parallel_apply_workers_per_subscription 与 max_logical_replication_workers、max_sync_workers_per_subscription、max_worker_processes 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_parallel_apply_workers_per_subscription；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_logical_replication_workers · max_sync_workers_per_subscription · max_worker_processes · max_replication_slots · max_active_replication_origins · hot_standby

参考资料

10.7 - max_repack_replication_slots

max_repack_replication_slots：设置 REPACK 命令可使用的最大复制槽数量。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 5，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 REPACK 命令可使用的最大复制槽数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值5
5

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 e76d8c749c31 — Reserve replication slots specifically for REPACK
提交日期 2026-04-07
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 5 — 5

机制详解

max_repack_replication_slots：设置 REPACK 命令可使用的最大复制槽数量。该值在服务器启动时固定，修改后必须安排受控重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PG19 的 REPACK 命令可使用专用复制槽，在跟踪并发变更的同时重组关系。这个启动上限决定服务器最多支持多少此类槽；它与复制槽总预算、WAL sender 预算以及 WAL 保留造成的磁盘风险联动。

应与 max_replication_slots、max_wal_senders、wal_level、max_slot_wal_keep_size 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 设定边界前要模拟正常故障转移与最坏复制延迟，并观察 sender 状态、保留 WAL、关机耗时和接收端追赶；为监控与计划切换保留足够容量。
OLAP 应计入大事务、批量装载、慢 apply 与远距离链路。较短超时虽能加快关机，却可能把恢复工作和不一致风险转移到下次启动。
小规格 限制槽和 sender 数量，监控 pg_wal 磁盘占用，并明确超时语义；分别在接收端健康与不可用时测试关机和重启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 max_repack_replication_slots 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 postmaster context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

max_replication_slots · max_wal_senders · wal_level · max_slot_wal_keep_size · wal_sender_shutdown_timeout

参考资料

10.8 - max_replication_slots

max_replication_slots：设置可同时定义的复制槽最大数量。实测在档范围为 PG9.4–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 10，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置可同时定义的复制槽最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值10
10

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 858ec11858a9 — Introduce replication slots.
提交日期 2014-01-31
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–9.6 0 — 0
PG10–19 Beta 3 10 — 10

机制详解

PostgreSQL 在服务器启动时分配复制槽控制容量。物理槽可以为备库保留 WAL；逻辑槽还会为解码消费者保留 WAL 和系统目录可见性信息。

该值限制复制槽对象数量，而不是活动 WAL 发送连接数；后者由 max_wal_senders 单独限制。使用复制槽还要求 wal_level 至少为 replica。若将该值降到现有槽数量以下，服务器将无法启动。

没有活动进程的槽也不一定无害。持久的非活动槽可能保留 WAL，逻辑槽还可能持有 catalog_xmin，因此消费者生命周期和槽清单治理与数字上限同样重要。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按具名物理备库、逻辑订阅、CDC 消费者、备份或迁移工具、故障转移槽及创建余量核算。可保留少量缓冲，但较大上限必须配套所有者、过期和延迟监控。
OLAP 为逻辑消费者和迁移任务预留空间，同时注意高 WAL 批处理会放大废弃槽的代价。批任务前后应检查 restart_lsn 与 confirmed_flush_lsn。
小规格 将上限保持在真实消费者数量加有限余量附近。大值本身不会保留 WAL，却更容易产生无人治理的槽，在小磁盘上迅速演变为故障。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 50 不同于 boot 值 50
OLAP 50 不同于 boot 值 50
CRIT 50 不同于 boot 值 50
TINY 50 不同于 boot 值 50
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 = 50 (dcs)；OLAP: PG9.4–19 Beta 3 = 50 (dcs)；CRIT: PG9.4–19 Beta 3 = 50 (dcs)；TINY: PG9.4–19 Beta 3 = 50 (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 把复制槽数量上限与限制并发发送进程的 max_wal_senders 混淆。
  • 将值降到现有复制槽数量以下，导致 PostgreSQL 无法启动。
  • 认为非活动槽不会保留 WAL 或系统目录旧行版本。
  • 提高上限却不监控 restart_lsn、catalog_xmin 和消费者健康。
  • 实验时创建永久复制槽，结束后从不删除。

关联参数

max_wal_senders · max_slot_wal_keep_size · wal_level · idle_replication_slot_timeout · max_logical_replication_workers · primary_slot_name

参考资料

10.9 - max_slot_wal_keep_size

在检查点时限制复制槽可保留 WAL 大小的可重载参数。本目录从 PG13 起收录，默认 -1（无限制）；Pigsty 使用有限的磁盘比例上限。
说明

Fact — 官方简述译文：设置复制槽可保留的 WAL 最大大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值MB
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值-1
-1 MB

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 c6550776394e — Allow users to limit storage reserved by replication slots
提交日期 2020-04-07
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 -1 MB -1 MB

机制详解

执行检查点时，PostgreSQL 会比较复制槽的 restart_lsn 与当前 WAL 位置。默认值 -1 表示参数不设上限，因此停滞消费者可能保留足以写满 pg_wal 的 WAL。

设置有限值后，复制槽落后过多时所需段可被释放。槽的 wal_status 可能从 unreserved 变为 lost，消费者可能需要重新做基础备份或逻辑同步。该上限通过牺牲无限期可续传保证来保护主库磁盘。

限制在检查点时执行，因此既不即时，也不是精确字节硬上限。pg_replication_slots 提供 restart_lsn、wal_status、invalidation_reason 和 safe_wal_size，应在触顶前使用这些信号预警。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在 pg_wal 应急预算内设置有限值，并按峰值 WAL 速率乘以最大修复窗口推导。safe_wal_size 仍为正时就应告警，并为每个消费者记录重新同步路径。
OLAP 为预期的批量 WAL 峰值留出空间，但不要让上限形同无限。协调消费者与批任务，验证归档可用性，并在落后消费者耗尽磁盘预算之前暂停或修复它。
小规格 采用更严格的有限上限和较短修复目标。小卷环境通常应优先保护主库，而不是永远保证陈旧备库或 CDC 槽可续传。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 30GB 不同于 boot 值 {{ ([pg_size_twentieth * 6, 3000])|min }}GB
OLAP 30GB 不同于 boot 值 {{ ([pg_size_twentieth * 6, 3000])|min }}GB
CRIT 30GB 不同于 boot 值 {{ ([pg_size_twentieth * 6, 3000])|min }}GB
TINY 30GB 不同于 boot 值 {{ ([pg_size_twentieth * 6, 3000])|min }}GB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 = 30GB (dcs)；OLAP: PG13–19 Beta 3 = 30GB (dcs)；CRIT: PG13–19 Beta 3 = 30GB (dcs)；TINY: PG13–19 Beta 3 = 30GB (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 保留 -1，却认为停滞复制槽不会写满磁盘。
  • 把有限值当作即时硬上限，忽略检查点执行时机。
  • 设置过小，在计划内批量任务期间使健康消费者失效。
  • 认为所需 WAL 删除后消费者仍必然可以续传。
  • 把该复制槽保留上限与 wal_keep_size 保留下限混淆。

关联参数

max_replication_slots · wal_keep_size · max_wal_size · idle_replication_slot_timeout · checkpoint_timeout · archive_mode

参考资料

10.10 - max_standby_archive_delay

max_standby_archive_delay：设置热备处理归档 WAL 时，取消冲突查询前允许的最大延迟。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 30 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置热备处理归档 WAL 时，取消冲突查询前允许的最大延迟。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值30000
30 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 30000 ms 30 s

机制详解

设置热备处理归档 WAL 时，取消冲突查询前允许的最大延迟。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

备库重放归档 WAL 时，恢复最多累计等待这么久再取消冲突查询。该预算针对重放进度，不会为每条查询重新发放；-1 可能让重放延迟无限增长。

应把 max_standby_archive_delay 与 max_standby_streaming_delay、hot_standby、hot_standby_feedback 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_standby_archive_delay；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 10min 不同于 boot 值 10min
OLAP 10min 不同于 boot 值 10min
CRIT 10min 不同于 boot 值 10min
TINY 10min 不同于 boot 值 10min
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 10min (dcs)；OLAP: PG9.0–19 Beta 3 = 10min (dcs)；CRIT: PG9.0–19 Beta 3 = 10min (dcs)；TINY: PG9.0–19 Beta 3 = 10min (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在备库从归档追赶时，在有界范围内偏向查询连续性；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_standby_streaming_delay · hot_standby · hot_standby_feedback · recovery_min_apply_delay · primary_conninfo · primary_slot_name

参考资料

10.11 - max_standby_streaming_delay

max_standby_streaming_delay：设置热备处理流式 WAL 时，取消冲突查询前允许的最大延迟。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 30 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置热备处理流式 WAL 时，取消冲突查询前允许的最大延迟。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值30000
30 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 30000 ms 30 s

机制详解

设置热备处理流式 WAL 时，取消冲突查询前允许的最大延迟。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

备库重放流式 WAL 时，恢复最多累计等待这么久再取消冲突查询。更大值偏向读连续性，却扩大复制延迟和恢复点暴露；hot_standby_feedback 可缓解部分快照冲突，但可能造成主库膨胀。

应把 max_standby_streaming_delay 与 max_standby_archive_delay、hot_standby、hot_standby_feedback 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_standby_streaming_delay；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 3min 不同于 boot 值 3min
OLAP 3min 不同于 boot 值 3min
CRIT 3min 不同于 boot 值 3min
TINY 3min 不同于 boot 值 3min
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 3min (dcs)；OLAP: PG9.0–19 Beta 3 = 3min (dcs)；CRIT: PG9.0–19 Beta 3 = 3min (dcs)；TINY: PG9.0–19 Beta 3 = 3min (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在允许流复制备库运行短分析查询，同时避免无限重放延迟；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_standby_archive_delay · hot_standby · hot_standby_feedback · recovery_min_apply_delay · in_hot_standby · primary_conninfo

参考资料

10.12 - max_sync_workers_per_subscription

max_sync_workers_per_subscription：设置每个订阅的表同步 worker 最大数量。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置每个订阅的表同步 worker 最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Subscribers
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 7c4f52409a8c — Logical replication support for initial data copy
提交日期 2017-03-23
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 2 — 2

机制详解

设置每个订阅的表同步 worker 最大数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 max_sync_workers_per_subscription 与 max_logical_replication_workers、max_parallel_apply_workers_per_subscription、max_worker_processes 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_sync_workers_per_subscription；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 6 不同于 boot 值 6
OLAP 6 不同于 boot 值 6
CRIT 6 不同于 boot 值 6
TINY 6 不同于 boot 值 6
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 = 6 (dcs)；OLAP: PG10–19 Beta 3 = 6 (dcs)；CRIT: PG10–19 Beta 3 = 6 (dcs)；TINY: PG10–19 Beta 3 = 6 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在全局 worker 预算内加速逻辑复制初始表复制；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_logical_replication_workers · max_parallel_apply_workers_per_subscription · max_worker_processes · max_replication_slots · max_active_replication_origins · hot_standby

参考资料

10.13 - max_wal_senders

max_wal_senders：设置可同时运行的 WAL sender 进程最大数量。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 10，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置可同时运行的 WAL sender 进程最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值10
10

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 0 — 0
PG10–19 Beta 3 10 — 10

机制详解

设置可同时运行的 WAL sender 进程最大数量。该值在服务器启动时固定，修改后必须重启。

每个流复制备库、流式基础备份或逻辑复制连接都可能占用 WAL sender。零会禁止发送；断开的客户端在超时前仍可能占槽，而且备库为支持查询应至少配置与主库相同的数量。

应把 max_wal_senders 与 wal_level、max_replication_slots、archive_mode 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 max_wal_senders；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 50 不同于 boot 值 50
OLAP 50 不同于 boot 值 50
CRIT 50 不同于 boot 值 50
TINY 50 不同于 boot 值 50
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 50 (dcs)；OLAP: PG9.0–19 Beta 3 = 50 (dcs)；CRIT: PG9.0–19 Beta 3 = 50 (dcs)；TINY: PG9.0–19 Beta 3 = 50 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在为备库、备份和逻辑客户端预留连接余量；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

wal_level · max_replication_slots · archive_mode · wal_log_hints · output_plugin_libraries · wal_sender_timeout

参考资料

10.14 - output_plugin_libraries

output_plugin_libraries：列出可作为逻辑解码输出插件指定的库。它是 PG14–18 的 superuser 参数；最新实测启动默认值为 pgoutput, test_decoding。
说明

Fact — 官方简述译文：列出可作为逻辑解码输出插件指定的库。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值pgoutput, test_decoding
pgoutput, test_decoding

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 bf3842a64f5d — Add an output_plugin_libraries GUC to bless trusted output plugins
提交日期 2026-08-10
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 pgoutput, test_decoding — pgoutput, test_decoding

机制详解

列出可作为逻辑解码输出插件指定的库。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

逻辑解码只接受该服务端白名单中的输出插件库名，按 LOAD 规则解释并要求插件名精确匹配。加入库是信任决策，因为插件代码在服务器进程内部执行。

应把 output_plugin_libraries 与 wal_level、max_wal_senders、max_replication_slots 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只列出已安装、已审计且确有消费者使用的输出插件；修改后用最低权限逻辑复制用户验证，并把插件升级纳入服务器发布。
OLAP ETL 解码插件同样是进程内代码，不要为方便使用通配或宽泛路径；验证大事务的内存、WAL 保留与插件输出。
小规格 不做逻辑解码就保留内置小白名单；增加 wal2json 等插件前确认包来源、版本兼容与维护责任。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP pgoutput, test_decoding, wal2json 不同于 boot 值 'pgoutput, test_decoding, wal2json'
OLAP pgoutput, test_decoding, wal2json 不同于 boot 值 'pgoutput, test_decoding, wal2json'
CRIT pgoutput, test_decoding, wal2json 不同于 boot 值 'pgoutput, test_decoding, wal2json'
TINY pgoutput, test_decoding, wal2json 不同于 boot 值 'pgoutput, test_decoding, wal2json'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs)；OLAP: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs)；CRIT: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs)；TINY: PG14–19 Beta 3 = pgoutput, test_decoding, wal2json (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在保持明确小型白名单的同时提供 wal2json；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

wal_level · max_wal_senders · max_replication_slots · archive_mode · wal_log_hints · shared_preload_libraries

参考资料

10.15 - primary_conninfo

primary_conninfo：设置连接发送端服务器时使用的连接字符串。它是 PG12–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置连接发送端服务器时使用的连接字符串。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置连接发送端服务器时使用的连接字符串。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

WAL receiver 用这条 libpq 连接串访问上游发送端。重载非空新值会重启 receiver；凭据应尽量放入受保护的 passfile，复制槽同步还要求提供 dbname。

应把 primary_conninfo 与 max_wal_senders、max_replication_slots、wal_level 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 primary_conninfo；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把明文密码写进可被广泛读取的配置或诊断。
  • 复制槽同步需要 dbname 时遗漏它。
  • 未协调时间线与槽状态就更换上游身份。
  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。

关联参数

max_wal_senders · max_replication_slots · wal_level · wal_sender_timeout · max_slot_wal_keep_size · primary_slot_name

参考资料

10.16 - primary_slot_name

primary_slot_name：设置连接发送端服务器时使用的复制槽名称。它是 PG12–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置连接发送端服务器时使用的复制槽名称。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置连接发送端服务器时使用的复制槽名称。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

Receiver 指定上游已有的物理槽，使发送端保留该备库所需 WAL。它提高断连后的连续性，却把磁盘保留风险转移到主库，故障切换时还必须协调槽生命周期。

应把 primary_slot_name 与 wal_keep_segments、wal_keep_size、wal_segment_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 primary_slot_name；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 创建槽却不监控 restart_lsn 与主库磁盘。
  • 故障切换时未证明消费者位置就删除或复用槽。
  • 误以为复制槽本身会归档或备份 WAL。
  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。

关联参数

wal_keep_segments · wal_keep_size · wal_segment_size · max_slot_wal_keep_size · max_wal_size · idle_replication_slot_timeout

参考资料

10.17 - promote_trigger_file

promote_trigger_file：指定一个文件，其出现会使备库结束恢复。它存在于 PG12–15 实测矩阵，并在 PG16 移除。PostgreSQL 16 移除了触发文件机制；应由 HA 控制器调用 pg_ctl promote 或 pg_promote()。
说明

Fact — 官方简述译文：指定一个文件，其出现会使备库结束恢复。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–15
移除版本 PG16
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–15 "" — empty string

机制详解

指定一个文件，其出现会使备库结束恢复。该参数在 PG15 仍存在，并从 PG16 起不再被识别。PostgreSQL 16 移除了触发文件机制；应由 HA 控制器调用 pg_ctl promote 或 pg_promote()。

该机制存在时，恢复进程监视指定路径并在文件出现后提升。残留文件、竞态与共享存储语义使编排脆弱；PostgreSQL 16 移除了这一设置。

升级前应联合检查 hot_standby、hot_standby_feedback、max_standby_archive_delay，从配置、ALTER SYSTEM、角色/数据库设置和自动化模板中删除旧名，并先验证替代机制再启动 PG16+。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要在 PG16+ 调优或继续下发 promote_trigger_file。PostgreSQL 16 移除了触发文件机制；应由 HA 控制器调用 pg_ctl promote 或 pg_promote()。升级前扫描所有配置层并做业务回归。
OLAP 迁移方案与 OLTP 相同；另外在长批处理、备库或大对象/扩展工作流中验证新机制，不要假定删除旧开关会保留旧行为。
小规格 直接删除旧配置并采用受支持替代项；若没有真实兼容需求，不要用脚本伪造旧行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG15 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–15 未修改；OLAP: PG12–15 未修改；CRIT: PG12–15 未修改；TINY: PG12–15 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在 PG16+ 配置中继续下发未知参数 promote_trigger_file。
  • 只删除参数名，却未迁移依赖它的应用行为。
  • 把历史默认值当作新版本替代机制的默认值。
  • 遗漏 ALTER SYSTEM、角色/数据库设置或自动化模板中的旧条目。

关联参数

hot_standby · hot_standby_feedback · max_standby_archive_delay · max_standby_streaming_delay · primary_conninfo · primary_slot_name

参考资料

10.18 - recovery_min_apply_delay

recovery_min_apply_delay：设置恢复期间应用变更的最小延迟。它是 PG12–18 的 sighup 参数；最新实测启动默认值为 0 ms。
说明

Fact — 官方简述译文：设置恢复期间应用变更的最小延迟。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 0 ms 0 ms

机制详解

设置恢复期间应用变更的最小延迟。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

备库会把每个事务 commit 的重放推迟到主库提交时间之后的指定时长。网络/级联延迟计入其中，时钟也会影响结果；synchronous_commit=remote_apply 会让主库提交一起等待这段人为延迟。

应把 recovery_min_apply_delay 与 max_standby_archive_delay、max_standby_streaming_delay、hot_standby 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 recovery_min_apply_delay；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_standby_archive_delay · max_standby_streaming_delay · hot_standby · hot_standby_feedback · primary_conninfo · primary_slot_name

参考资料

10.19 - replication_timeout

replication_timeout：设置等待 WAL 复制活动的最长时间。实测在档范围为 PG9.1–9.2；最后在档的 PG9.2 启动默认值为 1 min，context 为 sighup。它在 PG9.3 被移除。
说明

Fact — 官方简述译文：设置等待 WAL 复制活动的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值60000
1 min

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–9.2
移除版本 PG9.3
引入提交 754baa21f723 — Automatically terminate replication connections that are idle for more than replication_timeout (a new GUC) milliseconds. The TCP timeout is often too long, you want the master to notice a dead connection much sooner. People complained about that in 9.0 too, but with synchronous replication it’s even more important to notice dead connections promptly.
提交日期 2011-03-30
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–9.2 60000 ms 1 min

机制详解

replication_timeout：设置等待 WAL 复制活动的最长时间。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG9.1–9.2 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这是早期流复制中由发送端终止不活跃连接的超时。PG9.3 将其改名为 wal_sender_timeout；接收端故障检测由 wal_receiver_timeout 独立控制，迁移时必须分清计时器属于连接哪一端。

应与 wal_sender_timeout、wal_receiver_timeout、wal_receiver_status_interval、max_wal_senders 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.2 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–9.2 未修改；OLAP: PG9.1–9.2 未修改；CRIT: PG9.1–9.2 未修改；TINY: PG9.1–9.2 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 replication_timeout 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

wal_sender_timeout · wal_receiver_timeout · wal_receiver_status_interval · max_wal_senders

参考资料

10.20 - sync_replication_slots

sync_replication_slots：允许物理备库从主库同步逻辑故障转移复制槽。它是 PG17–18 的 sighup 参数；最新实测启动默认值为 off。
说明

Fact — 官方简述译文：允许物理备库从主库同步逻辑故障转移复制槽。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 93db6cbda037 — Add a new slot sync worker to synchronize logical slots.
提交日期 2024-02-22
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 off — off

机制详解

在物理备库启用 slotsync worker，从主库复制逻辑 failover slot 状态。重新加载配置即可应用新值。

同步要求主备之间存在物理复制槽（备库设置 primary_slot_name）、备库开启 hot_standby_feedback，并在 primary_conninfo 中提供有效 dbname；源逻辑槽还必须启用 failover。

槽状态是异步复制的。主库应把该备库的物理槽列入 synchronized_standby_slots，避免订阅者跑在故障转移备库之前；提升前必须验证每个必需槽已同步且可用于切换。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只在完整的逻辑故障转移设计中启用。自动检查所有前提，并在必需 failover slot 尚未同步或存在冲突时阻止计划提升。
OLAP 大事务与延迟备库会扩大同步滞后；应联合监控订阅者确认位置、备库重放、物理槽保留与 catalog horizon。
小规格 不要仅因开关存在就启用。小型部署同样需要永久物理槽、hot_standby_feedback、dbname、保留上限和经过验证的切换 runbook。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP true 不同于 boot 值 on
OLAP true 不同于 boot 值 on
CRIT true 不同于 boot 值 on
TINY true 不同于 boot 值 on
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 = True (dcs)；OLAP: PG17–19 Beta 3 = True (dcs)；CRIT: PG17–19 Beta 3 = True (dcs)；TINY: PG17–19 Beta 3 = True (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在物理备库准备逻辑故障转移槽，以支持受控切换；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 未设置 primary_slot_name、缺少强制物理槽时就启用。
  • hot_standby_feedback 仍为 off，无法为同步逻辑槽安全保留 catalog 行。
  • primary_conninfo 中遗漏 dbname。
  • 源逻辑槽未启用 failover，却期待它被同步。
  • 未确认每个必需槽已同步且没有落后于订阅者就提升。

关联参数

primary_slot_name · hot_standby_feedback · primary_conninfo · synchronized_standby_slots · max_replication_slots · max_slot_wal_keep_size

参考资料

10.21 - synchronized_standby_slots

synchronized_standby_slots：列出逻辑 WAL sender 必须等待的流复制备库槽。它是 PG17–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：列出逻辑 WAL sender 必须等待的流复制备库槽。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Primary Server
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 0f934b0739ad — Rename standby_slot_names to synchronized_standby_slots.
提交日期 2024-07-01
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 "" — empty string

机制详解

列出逻辑 WAL sender 必须等待的流复制备库槽。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

主库逻辑 sender 会等待列表中每个物理备库槽确认相关 WAL 后才发送解码变更。这保护 failover slot 连续性，但缺失、失效或停滞的槽会阻断逻辑复制与槽管理函数。

应把 synchronized_standby_slots 与 sync_replication_slots、primary_slot_name、max_replication_slots 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 synchronized_standby_slots；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 列入缺失或失效槽，阻塞逻辑 sender。
  • 混淆物理槽名与备库 application_name。
  • 对应备库没有开启 sync_replication_slots。
  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。

关联参数

sync_replication_slots · primary_slot_name · max_replication_slots · max_slot_wal_keep_size · synchronous_standby_names · vacuum_defer_cleanup_age

参考资料

10.22 - synchronous_standby_names

synchronous_standby_names：设置同步备库数量及候选备库名称列表。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 empty string，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置同步备库数量及候选备库名称列表。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Primary Server
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 a8a8a3e09652 — Efficient transaction-controlled synchronous replication. If a standby is broadcasting reply messages and we have named one or more standbys in synchronous_standby_names then allow users who set synchronous_replication to wait for commit, which then provides strict data integrity guarantees. Design avoids sending and receiving transaction state information so minimises bookkeeping overheads. We synchronize with the highest priority standby that is connected and ready to synchronize. Other standbys can be defined to takeover in case of standby failure.
提交日期 2011-03-06
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 "" — empty string

机制详解

设置同步备库数量及候选备库名称列表。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它按备库 application_name 解析优先级 FIRST 或仲裁 ANY 语法，只定义可用确认者；每个事务等待什么由 synchronous_commit 决定，重复名称或通配符可能使实际选择出乎预期。

应把 synchronous_standby_names 与 synchronous_commit、wal_sender_timeout、max_wal_senders 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 synchronous_standby_names；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为只配置列表就能让每个事务同步。
  • 重复 application_name 导致优先级选择不确定。
  • ANY/FIRST 数量在计划维护期间无法满足。
  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。

关联参数

synchronous_commit · wal_sender_timeout · max_wal_senders · application_name · synchronized_standby_slots · vacuum_defer_cleanup_age

参考资料

10.23 - track_commit_timestamp

track_commit_timestamp：记录事务提交时间。实测在档范围为 PG9.5–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：记录事务提交时间。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 73c986adde5d — Keep track of transaction commit timestamps
提交日期 2014-12-03
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 off — off

机制详解

记录事务提交时间。该值在服务器启动时固定，修改后必须重启。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 track_commit_timestamp 与 max_active_replication_origins、max_logical_replication_workers、max_replication_slots 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 track_commit_timestamp；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 = on (dcs)；OLAP: PG9.5–19 Beta 3 = on (dcs)；CRIT: PG9.5–19 Beta 3 = on (dcs)；TINY: PG9.5–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在为诊断和复制工作流提供提交时间元数据；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_active_replication_origins · max_logical_replication_workers · max_replication_slots · idle_replication_slot_timeout · max_slot_wal_keep_size · max_wal_senders

参考资料

10.24 - vacuum_defer_cleanup_age

vacuum_defer_cleanup_age：设置 VACUUM 与 HOT 清理要延后多少个事务。实测在档范围为 PG9.0–15；最后在档的 PG15 启动默认值为 0，context 为 sighup。它在 PG16 被移除。
说明

Fact — 官方简述译文：设置 VACUUM 与 HOT 清理要延后多少个事务。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 1000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Primary Server
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–15
移除版本 PG16
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–15 0 — 0

机制详解

设置 VACUUM 与 HOT 清理要延后多少个事务。该参数在 PG15 仍存在，并从 PG16 起不再被识别。PostgreSQL 16 移除了按事务数量延迟清理的机制；应根据真实需求组合 hot_standby_feedback、复制槽和有上界的备库冲突策略。

它曾让主库按固定事务数量延后删除近期死元组，是保护备库查询的粗略办法。它会保留膨胀却不能保证固定墙钟时间，并在 PostgreSQL 16 被移除。

升级前应联合检查 synchronized_standby_slots、synchronous_standby_names、hot_standby，从配置、ALTER SYSTEM、角色/数据库设置和自动化模板中删除旧名，并先验证替代机制再启动 PG16+。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要在 PG16+ 调优或继续下发 vacuum_defer_cleanup_age。PostgreSQL 16 移除了按事务数量延迟清理的机制；应根据真实需求组合 hot_standby_feedback、复制槽和有上界的备库冲突策略。升级前扫描所有配置层并做业务回归。
OLAP 迁移方案与 OLTP 相同；另外在长批处理、备库或大对象/扩展工作流中验证新机制，不要假定删除旧开关会保留旧行为。
小规格 直接删除旧配置并采用受支持替代项；若没有真实兼容需求，不要用脚本伪造旧行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG15 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 500000 不同于 boot 值 500000
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–15 未修改；OLAP: PG9.0–15 未修改；CRIT: PG9.0–15 = 500000 (dcs)；TINY: PG9.0–15 未修改。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在历史上通过延迟清理保护 CRIT 备库读，但这一策略现在必须迁移；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在 PG16+ 配置中继续下发未知参数 vacuum_defer_cleanup_age。
  • 只删除参数名，却未迁移依赖它的应用行为。
  • 把历史默认值当作新版本替代机制的默认值。
  • 遗漏 ALTER SYSTEM、角色/数据库设置或自动化模板中的旧条目。

关联参数

synchronized_standby_slots · synchronous_standby_names · hot_standby · hot_standby_feedback · idle_replication_slot_timeout · max_active_replication_origins

参考资料

10.25 - wal_keep_segments

wal_keep_segments：设置为备库保留的 WAL 文件数量。实测在档范围为 PG9.0–12；最后在档的 PG12 启动默认值为 0，context 为 sighup。它在 PG13 被移除。
说明

Fact — 官方简述译文：设置为备库保留的 WAL 文件数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–12
移除版本 PG13
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–12 0 — 0

机制详解

设置为备库保留的 WAL 文件数量。该参数在 PG12 仍存在，并从 PG13 起不再被识别。PostgreSQL 13 用 wal_keep_size 取代按段计数的接口；新参数用字节表示保留下限，不再隐含 WAL 段大小。

它至少为落后备库保留指定数量的旧 WAL 段，因此实际字节数取决于 wal_segment_size。它只是保留下限而非上限，也不能覆盖所有删除条件；PG13 改用 wal_keep_size。

升级前应联合检查 wal_keep_size、wal_segment_size、max_slot_wal_keep_size，从配置、ALTER SYSTEM、角色/数据库设置和自动化模板中删除旧名，并先验证替代机制再启动 PG13+。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要在 PG13+ 调优或继续下发 wal_keep_segments。PostgreSQL 13 用 wal_keep_size 取代按段计数的接口；新参数用字节表示保留下限，不再隐含 WAL 段大小。升级前扫描所有配置层并做业务回归。
OLAP 迁移方案与 OLTP 相同；另外在长批处理、备库或大对象/扩展工作流中验证新机制，不要假定删除旧开关会保留旧行为。
小规格 直接删除旧配置并采用受支持替代项；若没有真实兼容需求，不要用脚本伪造旧行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG12 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–12 未修改；OLAP: PG9.0–12 未修改；CRIT: PG9.0–12 未修改；TINY: PG9.0–12 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 没有乘以 wal_segment_size 就把旧整数直接复制到 wal_keep_size。
  • 把保留数量误当上限而非下限。
  • PG13+ 自动化中仍保留已移除名称。
  • 在 PG13+ 配置中继续下发未知参数 wal_keep_segments。
  • 只删除参数名，却未迁移依赖它的应用行为。

关联参数

wal_keep_size · wal_segment_size · max_slot_wal_keep_size · max_wal_size · primary_slot_name · idle_replication_slot_timeout

参考资料

10.26 - wal_keep_size

为可能落后的流复制备库额外保留旧 WAL 的可重载最小值。本目录从 PG13 起收录该参数，默认 0 MB，Pigsty 四个模板均未修改。
说明

Fact — 官方简述译文：设置为备库保留的 WAL 文件大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值MB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值0
0 B

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 f5dff45962ec — Rename wal_keep_segments to wal_keep_size.
提交日期 2020-07-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 0 MB 0 B

机制详解

发送端会在 pg_wal 中至少保留 wal_keep_size MB 的历史 WAL，使落后备库不会因旧段过早消失而中断流复制。如果落后距离超过现有文件，流连接会终止；若归档中存在缺失段，备库仍可从归档恢复。

它是保留下限，不是精确预留量，也不是上限。检查点恢复、归档、复制槽以及近期 WAL 用量估计都可能保留更多文件。值为 0 表示不专门为备库额外保留，并不表示 pg_wal 中没有旧 WAL。

复制槽依据各消费者确认位置精确保留 WAL，通常更可靠。wal_keep_size 仍可作为无槽备库或短暂重连的简单保险，但容量应按峰值 WAL 速率乘以预期中断窗口计算。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 优先使用受监控的复制槽和经过验证的归档。确需非零下限时，按峰值 WAL 字节速率与容忍断连时间计算，再增加余量并监控复制延迟。
OLAP 短时间批量导入就可能突破静态保留量。必须跨越此类峰值的消费者应使用复制槽或归档，wal_keep_size 也应按峰值而非平均速率定值。
小规格 复制槽和归档恢复可靠时保持 0。否则选择不会在归档或复制槽事故叠加时耗尽磁盘的适度、有界值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 wal_keep_size 当作 pg_wal 使用量上限。
  • 把 0 理解为“不保留 WAL”，而不是“不为备库额外保留”。
  • 按平均 WAL 速率定值，在批任务峰值时失效。
  • 认为备库超过保留窗口后仍保证可继续复制。
  • 比较 PG12 与 PG13 时漏掉前身参数 wal_keep_segments。

关联参数

wal_keep_segments · max_replication_slots · max_slot_wal_keep_size · archive_mode · max_wal_size · primary_slot_name

参考资料

10.27 - wal_receiver_create_temp_slot

wal_receiver_create_temp_slot：未配置永久槽时，设置 WAL receiver 是否创建临时复制槽。它是 PG13–18 的 sighup 参数；最新实测启动默认值为 off。
说明

Fact — 官方简述译文：未配置永久槽时，设置 WAL receiver 是否创建临时复制槽。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 329730827848 — walreceiver uses a temporary replication slot by default
提交日期 2020-01-14
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 off — off

机制详解

未配置永久槽时，设置 WAL receiver 是否创建临时复制槽。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

primary_slot_name 为空时，receiver 可为连接生命周期创建上游临时槽。它能防止连接期间删除 WAL，但断连即消失，无法保证长时间中断后的追赶。

应把 wal_receiver_create_temp_slot 与 primary_slot_name、max_replication_slots、max_slot_wal_keep_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 wal_receiver_create_temp_slot；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

primary_slot_name · max_replication_slots · max_slot_wal_keep_size · wal_keep_size · hot_standby · hot_standby_feedback

参考资料

10.28 - wal_receiver_status_interval

wal_receiver_status_interval：设置 WAL receiver 向发送端报告状态的最大间隔。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 10 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 WAL receiver 向发送端报告状态的最大间隔。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值0 – 2147483
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值10
10 s

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 b186523fd97c — Send status updates back from standby server to master, indicating how far the standby has written, flushed, and applied the WAL. At the moment, this is for informational purposes only, the values are only shown in pg_stat_replication system view, but in the future they will also be needed for synchronous replication.
提交日期 2011-02-10
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 10 s 10 s

机制详解

设置 WAL receiver 向发送端报告状态的最大间隔。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 wal_receiver_status_interval 与 wal_receiver_timeout、wal_sender_timeout、primary_conninfo 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 wal_receiver_status_interval；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1s 不同于 boot 值 1s
OLAP 1s 不同于 boot 值 1s
CRIT 1s 不同于 boot 值 1s
TINY 1s 不同于 boot 值 1s
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 = 1s (dcs)；OLAP: PG9.1–19 Beta 3 = 1s (dcs)；CRIT: PG9.1–19 Beta 3 = 1s (dcs)；TINY: PG9.1–19 Beta 3 = 1s (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在向发送端与监控提供更新鲜的重放/刷写反馈；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

wal_receiver_timeout · wal_sender_timeout · primary_conninfo · hot_standby_feedback · hot_standby · max_standby_archive_delay

参考资料

10.29 - wal_receiver_timeout

wal_receiver_timeout：设置等待发送端数据的最长时间。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 min，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置等待发送端数据的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值60000
1 min

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 6f60fdd7015b — Improve replication connection timeouts.
提交日期 2012-10-11
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 60000 ms 1 min

机制详解

设置等待发送端数据的最长时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 wal_receiver_timeout 与 primary_conninfo、primary_slot_name、restore_command 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 wal_receiver_timeout；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 60s 等于 boot 值 60s
OLAP 60s 等于 boot 值 60s
CRIT 60s 等于 boot 值 60s
TINY 60s 等于 boot 值 60s
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 = 60s (dcs)；OLAP: PG9.3–19 Beta 3 = 60s (dcs)；CRIT: PG9.3–19 Beta 3 = 60s (dcs)；TINY: PG9.3–19 Beta 3 = 60s (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在显式采用一分钟的 receiver 故障检测窗口；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

primary_conninfo · primary_slot_name · restore_command · wal_retrieve_retry_interval · hot_standby · wal_receiver_status_interval

参考资料

10.30 - wal_retrieve_retry_interval

wal_retrieve_retry_interval：设置 WAL 获取失败后的重试等待时间。实测在档范围为 PG9.5–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 5 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 WAL 获取失败后的重试等待时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Standby Servers
上游分类
最后 boot 值 值5000
5 s

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 5d2b45e3f78a — Add GUC to control the time to wait before retrieving WAL after failed attempt.
提交日期 2015-02-23
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 5000 ms 5 s

机制详解

设置 WAL 获取失败后的重试等待时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 wal_retrieve_retry_interval 与 primary_conninfo、primary_slot_name、restore_command 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 wal_retrieve_retry_interval；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 未修改；OLAP: PG9.5–19 Beta 3 未修改；CRIT: PG9.5–19 Beta 3 未修改；TINY: PG9.5–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

primary_conninfo · primary_slot_name · restore_command · wal_receiver_timeout · hot_standby · hot_standby_feedback

参考资料

10.31 - wal_sender_delay

wal_sender_delay：设置 WAL sender 两次复制动作之间的休眠时间。实测在档范围为 PG9.0–9.1；最后在档的 PG9.1 启动默认值为 1 s，context 为 sighup。它在 PG9.2 被移除。
说明

Fact — 官方简述译文：设置 WAL sender 两次复制动作之间的休眠时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值1 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Master Server
上游分类
最后 boot 值 值1000
1 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.1
移除版本 PG9.2
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 200 ms 200 ms
PG9.1 1000 ms 1 s

机制详解

wal_sender_delay：设置 WAL sender 两次复制动作之间的休眠时间。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG9.0–9.1 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

早期 WAL sender 每次尝试发送更多 WAL 之间按该值休眠。随着 sender 唤醒与流式行为演进，它在 PG9.1 后退出；现代延迟与存活控制使用 wal_sender_timeout、wal_receiver_status_interval 和 wal_receiver_timeout，而不是轮询延迟。

应与 wal_sender_timeout、wal_receiver_status_interval、wal_receiver_timeout、max_wal_senders 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.1 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.1 未修改；OLAP: PG9.0–9.1 未修改；CRIT: PG9.0–9.1 未修改；TINY: PG9.0–9.1 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 wal_sender_delay 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

wal_sender_timeout · wal_receiver_status_interval · wal_receiver_timeout · max_wal_senders

参考资料

10.32 - wal_sender_shutdown_timeout

wal_sender_shutdown_timeout：设置关机时等待 WAL 全部复制到接收端的最长时间。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 -1 ms，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置关机时等待 WAL 全部复制到接收端的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值-1
-1 ms

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 a8f45dee9176 — Add wal_sender_shutdown_timeout GUC to limit shutdown wait for replication
提交日期 2026-04-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 -1 ms -1 ms

机制详解

wal_sender_shutdown_timeout：设置关机时等待 WAL 全部复制到接收端的最长时间。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

关机时 WAL sender 通常等待未发送 WAL 到达接收端。默认 -1 无限等待，0 立即停止，正值限定等待时间但可能让两端暂时不一致；连接选项可为物理与逻辑复制链路设置不同策略。

应与 wal_sender_timeout、wal_receiver_timeout、synchronous_commit、synchronous_standby_names 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 设定边界前要模拟正常故障转移与最坏复制延迟，并观察 sender 状态、保留 WAL、关机耗时和接收端追赶；为监控与计划切换保留足够容量。
OLAP 应计入大事务、批量装载、慢 apply 与远距离链路。较短超时虽能加快关机，却可能把恢复工作和不一致风险转移到下次启动。
小规格 限制槽和 sender 数量，监控 pg_wal 磁盘占用，并明确超时语义；分别在接收端健康与不可用时测试关机和重启。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 wal_sender_shutdown_timeout 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

wal_sender_timeout · wal_receiver_timeout · synchronous_commit · synchronous_standby_names · max_wal_senders

参考资料

10.33 - wal_sender_timeout

wal_sender_timeout：设置等待 WAL 复制活动的最长时间。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 min，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置等待 WAL 复制活动的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Replication / Sending Servers
上游分类
最后 boot 值 值60000
1 min

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 6f60fdd7015b — Improve replication connection timeouts.
提交日期 2012-10-11
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 60000 ms 1 min

机制详解

设置等待 WAL 复制活动的最长时间。它可在会话级修改，因此不同会话可能采用不同的行为。

它只在对应的发送端、主库、备库或订阅端角色上生效；级联复制与故障切换会改变服务器角色，因此相关容量和依赖应在所有候选节点一致规划。

应把 wal_sender_timeout 与 max_wal_senders、max_replication_slots、wal_level 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按主备拓扑、故障切换角色、复制槽/订阅数量与断连余量规划 wal_sender_timeout；上线前验证主库写延迟、备库重放和磁盘保留的最坏情况。
OLAP 读备库与逻辑订阅常有长查询或大事务，应给重放/应用留明确上界，并监控延迟、worker 饱和、槽 restart_lsn 与冲突取消。
小规格 只配置真实需要的复制能力。少量节点也应设置有界超时与槽生命周期，不要用无限保留换取表面稳定。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在错误的主库、备库、发送端或订阅端角色上修改。
  • 只看字节/时间配置，不监控真实复制延迟、槽位置与 worker 状态。
  • 故障切换后新主库缺少与旧主库一致的容量或依赖。
  • 用无限等待或无限 WAL 保留掩盖失效消费者。

关联参数

max_wal_senders · max_replication_slots · wal_level · primary_conninfo · max_slot_wal_keep_size · wal_receiver_status_interval

参考资料

11 - 报告与日志

Reporting and Logging 分类下的 47 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

11.1 - application_name

application_name 定义在统计信息和日志中报告的应用名称。
说明

Fact — 官方简述译文：设置在统计信息和日志中报告的应用名称。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

application_name 是客户端提供的会话元数据，通常在启动包中设置，也可稍后用 SET 修改。它出现在 pg_stat_activity 与 CSV 日志中，并可通过 log_line_prefix 的 %a 写入文本日志。

该值短于 NAMEDATALEN 字节（标准构建为 64 个字符）。PostgreSQL 接受可打印 ASCII，其他字符显示为 C 风格十六进制转义。由于截断与转义，日志消费者不能假定显示值与应用原始字符串完全一致。

它属于 USER 上下文标签，不是经过认证的身份：任何获授权客户端都可声明误导值，池化会话也可能保留或覆盖它。应与已认证用户、数据库、会话 ID、远端点，以及受控连接池签出/重置行为关联。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 要求每个服务与连接池在签出时设置短小、稳定、无秘密的 application_name，并在复用前重置。使用受控命名约定，但绝不能只依据该值授权或审计。
OLAP 设置稳定的作业或工具族标签，把运行级高基数身份放到其他位置。用已认证角色与会话 ID 关联长分析会话。
小规格 标签保持简短有用，节点规格与此无关。不要把租户 ID、令牌、SQL 或无界请求标识塞入这一 64 字符且受客户端控制的字段。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 application_name 当作已认证身份，或单独用于授权、计费与审计归属。
  • 超过 NAMEDATALEN，因截断悄然丢失具有区分度的后缀。
  • 误以为任意 Unicode 会原样保留，而不是转义为可打印的 C 风格十六进制序列。
  • 在日志与 pg_stat_activity 中泄漏秘密或制造无界基数，或在连接池中未重置该值。

关联参数

cluster_name · update_process_title · log_line_prefix · log_timezone · log_hostname

参考资料

11.2 - cluster_name

cluster_name 定义显示在进程标题中的集群名称。
说明

Fact — 官方简述译文：设置显示在进程标题中的集群名称。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Process Title
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 51adcaa0df81 — Add cluster_name GUC which is included in process titles if set.
提交日期 2014-06-29
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 "" — empty string

机制详解

cluster_name：设置显示在进程标题中的集群名称。它是写入进程标题的运维标签，可区分同一主机上的多个集群，但不是数据库标识符。

cluster_name 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

进程标题与 application_name、cluster_name、pg_stat_activity、log_line_prefix 相互补充，使操作系统观察能够关联数据库活动。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非分析证明确有显著开销，否则保持 cluster_name 启用或有值以便运维识别；使用与监控清单一致、稳定且不含秘密的标签。
OLAP 保留 cluster_name，使长作业能从操作系统与 PostgreSQL 视图中归属；更细粒度作业身份应使用 application_name。
小规格 不要为容量而调节 cluster_name。其可观测性价值通常高于微小开销，但应避免高基数或敏感标签。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 未修改；OLAP: PG9.5–19 Beta 3 未修改；CRIT: PG9.5–19 Beta 3 未修改；TINY: PG9.5–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 cluster_name，而它实际需要受控重启服务器。
  • 把秘密或无界高基数数据放入运维可见的进程标签。
  • 集群、应用与进程标签不一致，无法在监控系统之间关联。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 cluster_name。

关联参数

application_name · update_process_title · log_line_prefix · log_timezone · log_hostname

参考资料

11.3 - debug_pretty_print

debug_pretty_print 是 PostgreSQL 中用于对解析树和计划树的显示进行缩进美化的参数。
说明

Fact — 官方简述译文：对解析树和计划树的显示进行缩进美化。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

debug_pretty_print：对解析树和计划树的显示进行缩进美化。它只改变 debug_print_* 开关所输出内部解析树与计划树的缩进格式。

debug_pretty_print 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

debug_print_* 开关沿普通服务器日志路径输出，因此 log_min_messages、log_destination 与收集器容量共同决定内容能否安全保留。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应在生产环境全局调优或启用 debug_pretty_print。若服务器开发级诊断确有需要，只在单一会话短时开启，并安全接收产生的日志。
OLAP 不要用 debug_pretty_print 替代分析 SQL 的 EXPLAIN；应定向抓取计划，而不是转储每一棵内部树。
小规格 保持 debug_pretty_print 的正常默认值。冗长内部树可能意外耗尽小节点的日志 I/O 与磁盘。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 debug_pretty_print，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 全局长期打开内部树转储，压垮日志 I/O、存储或摄取。
  • 把调试输出当作稳定公共格式，或用它替代定向 EXPLAIN 诊断。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 debug_pretty_print。

关联参数

debug_print_parse · debug_print_plan · debug_print_rewritten · log_min_messages · client_min_messages

参考资料

11.4 - debug_print_parse

debug_print_parse 决定 PostgreSQL 是否记录每个查询的解析树。
说明

Fact — 官方简述译文：记录每个查询的解析树。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

debug_print_parse：记录每个查询的解析树。输出是每条查询的 PostgreSQL 内部解析树表示，而不是规范化后的 SQL 文本。

debug_print_parse 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

debug_print_* 开关沿普通服务器日志路径输出，因此 log_min_messages、log_destination 与收集器容量共同决定内容能否安全保留。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应在生产环境全局调优或启用 debug_print_parse。若服务器开发级诊断确有需要，只在单一会话短时开启，并安全接收产生的日志。
OLAP 不要用 debug_print_parse 替代分析 SQL 的 EXPLAIN；应定向抓取计划，而不是转储每一棵内部树。
小规格 保持 debug_print_parse 的正常默认值。冗长内部树可能意外耗尽小节点的日志 I/O 与磁盘。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 debug_print_parse，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 全局长期打开内部树转储，压垮日志 I/O、存储或摄取。
  • 把调试输出当作稳定公共格式，或用它替代定向 EXPLAIN 诊断。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 debug_print_parse。

关联参数

debug_pretty_print · debug_print_plan · debug_print_rewritten · log_min_messages · client_min_messages

参考资料

11.5 - debug_print_plan

debug_print_plan 决定 PostgreSQL 是否记录每个查询的执行计划树。
说明

Fact — 官方简述译文：记录每个查询的执行计划树。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

debug_print_plan：记录每个查询的执行计划树。输出是每条查询的内部计划树，比定向执行 EXPLAIN 冗长得多，主要用于服务器调试。

debug_print_plan 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

debug_print_* 开关沿普通服务器日志路径输出，因此 log_min_messages、log_destination 与收集器容量共同决定内容能否安全保留。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应在生产环境全局调优或启用 debug_print_plan。若服务器开发级诊断确有需要，只在单一会话短时开启，并安全接收产生的日志。
OLAP 不要用 debug_print_plan 替代分析 SQL 的 EXPLAIN；应定向抓取计划，而不是转储每一棵内部树。
小规格 保持 debug_print_plan 的正常默认值。冗长内部树可能意外耗尽小节点的日志 I/O 与磁盘。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 debug_print_plan，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 全局长期打开内部树转储，压垮日志 I/O、存储或摄取。
  • 把调试输出当作稳定公共格式，或用它替代定向 EXPLAIN 诊断。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 debug_print_plan。

关联参数

debug_pretty_print · debug_print_parse · debug_print_rewritten · log_min_messages · client_min_messages

参考资料

11.6 - debug_print_raw_parse

debug_print_raw_parse：把每条查询的原始解析树写入日志。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：把每条查询的原始解析树写入日志。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 06473f5a344d — Allow to log raw parse tree.
提交日期 2025-09-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 off — off

机制详解

debug_print_raw_parse：把每条查询的原始解析树写入日志。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

原始解析树在语义分析、重写、规划与执行之前输出。消息级别为 LOG；debug_pretty_print 控制格式，而 client_min_messages 与 log_min_messages 决定输出位置。内容可能非常庞大，也可能暴露查询结构。

应与 debug_print_parse、debug_print_rewritten、debug_print_plan、debug_pretty_print 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在出现可复现的运维需求前保持上游默认；应在代表性并发下测试，并在全局修改前检查日志、延迟与关联参数。
OLAP 结合有代表性的长查询和批处理评估，比较整个任务的总耗时、资源、日志量与失败行为，而不是孤立操作。
小规格 尽量减少覆盖并记录回滚。小系统容纳额外日志、worker、内存或保留 WAL 的余量更小，必须用明确资源上限验证。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 debug_print_raw_parse 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

debug_print_parse · debug_print_rewritten · debug_print_plan · debug_pretty_print · log_min_messages

参考资料

11.7 - debug_print_rewritten

debug_print_rewritten 决定 PostgreSQL 是否记录每个查询重写后的解析树。
说明

Fact — 官方简述译文：记录每个查询重写后的解析树。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

debug_print_rewritten：记录每个查询重写后的解析树。它显示规则重写后的查询树，可诊断视图与规则问题，但可能产生非常庞大的日志。

debug_print_rewritten 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

debug_print_* 开关沿普通服务器日志路径输出，因此 log_min_messages、log_destination 与收集器容量共同决定内容能否安全保留。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应在生产环境全局调优或启用 debug_print_rewritten。若服务器开发级诊断确有需要，只在单一会话短时开启，并安全接收产生的日志。
OLAP 不要用 debug_print_rewritten 替代分析 SQL 的 EXPLAIN；应定向抓取计划，而不是转储每一棵内部树。
小规格 保持 debug_print_rewritten 的正常默认值。冗长内部树可能意外耗尽小节点的日志 I/O 与磁盘。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 debug_print_rewritten，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 全局长期打开内部树转储，压垮日志 I/O、存储或摄取。
  • 把调试输出当作稳定公共格式，或用它替代定向 EXPLAIN 诊断。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 debug_print_rewritten。

关联参数

debug_pretty_print · debug_print_parse · debug_print_plan · log_min_messages · client_min_messages

参考资料

11.8 - event_source

event_source 定义在 Windows 事件日志中标识 PostgreSQL 消息的应用名称。
说明

Fact — 官方简述译文：设置在 Windows 事件日志中标识 PostgreSQL 消息的应用名称。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值PostgreSQL
PostgreSQL

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 d8ea33f2c027 — Support configurable eventlog application names on Windows
提交日期 2011-10-25
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 PostgreSQL — PostgreSQL

机制详解

event_source：设置在 Windows 事件日志中标识 PostgreSQL 消息的应用名称。这是 Windows 事件日志标识符，只有 eventlog 是活动日志目标时才会生效。

event_source 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

只有 Windows 上的 log_destination 选择 eventlog 时才读取 event_source；其余管线由 Windows 事件日志注册、权限、路由与保留策略提供。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有 Windows eventlog 部署才设置 event_source，并使用由主机日志策略注册和路由的稳定、无秘密标识。
OLAP 各负载类型保持相同事件源，避免 Windows 收集规则与看板按模板碎片化。
小规格 除非选择 eventlog，否则保留 event_source 默认值；修改未启用路径上的标签没有容量或可观测性收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 未修改；OLAP: PG9.2–19 Beta 3 未修改；CRIT: PG9.2–19 Beta 3 未修改；TINY: PG9.2–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 event_source，而它实际需要受控重启服务器。
  • 更改来源名称，却未注册或更新 Windows 事件日志路由与访问策略。
  • 在 eventlog 未启用或平台不是 Windows 时期待 event_source 生效。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 event_source。

关联参数

logging_collector · log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

参考资料

11.9 - log_autoanalyze_min_duration

log_autoanalyze_min_duration：设置记录 autovacuum ANALYZE 动作的最短执行时间。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 10 min，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置记录 autovacuum ANALYZE 动作的最短执行时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值600000
10 min

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 dd3ae378301f — Add log_autoanalyze_min_duration
提交日期 2025-10-15
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 600000 ms 10 min

机制详解

log_autoanalyze_min_duration：设置记录 autovacuum ANALYZE 动作的最短执行时间。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

0 会记录每次自动 ANALYZE，-1 禁用这类耗时消息，正值则记录达到阈值的动作，以及因锁冲突或关系被删除而跳过的相关事件。表级存储参数可以覆盖它，并且它与记录 VACUUM 的 log_autovacuum_min_duration 相互独立。

应与 log_autovacuum_min_duration、autovacuum、autovacuum_analyze_threshold、autovacuum_analyze_scale_factor 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在出现可复现的运维需求前保持上游默认；应在代表性并发下测试，并在全局修改前检查日志、延迟与关联参数。
OLAP 结合有代表性的长查询和批处理评估，比较整个任务的总耗时、资源、日志量与失败行为，而不是孤立操作。
小规格 尽量减少覆盖并记录回滚。小系统容纳额外日志、worker、内存或保留 WAL 的余量更小，必须用明确资源上限验证。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 log_autoanalyze_min_duration 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

log_autovacuum_min_duration · autovacuum · autovacuum_analyze_threshold · autovacuum_analyze_scale_factor · log_min_messages

参考资料

11.10 - log_autovacuum_min_duration

log_autovacuum_min_duration 定义记录 autovacuum 操作所需达到的最短执行时间。
说明

Fact — 官方简述译文：设置记录 autovacuum 操作所需达到的最短执行时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值600000
10 min

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–14 -1 ms -1 ms
PG15–19 Beta 3 600000 ms 10 min

机制详解

log_autovacuum_min_duration：设置记录 autovacuum 操作所需达到的最短执行时间。每个达到阈值的自动 VACUUM 或 ANALYZE 会输出时长与工作详情；-1 关闭完成记录，零记录所有动作。

log_autovacuum_min_duration 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_autovacuum_min_duration；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_autovacuum_min_duration 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_autovacuum_min_duration 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1s 不同于 boot 值 1s
OLAP 1s 不同于 boot 值 1s
CRIT 1s 不同于 boot 值 1s
TINY 1s 不同于 boot 值 1s
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 1s (dcs)；OLAP: PG9.0–19 Beta 3 = 1s (dcs)；CRIT: PG9.0–19 Beta 3 = 1s (dcs)；TINY: PG9.0–19 Beta 3 = 1s (dcs)。 建议（待人工复核）——编辑推断：一秒阈值让各模板都能看到异常缓慢的 vacuum 维护，同时避免记录每个快速动作。

常见坑

  • 编辑 log_autovacuum_min_duration 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_autovacuum_min_duration。

关联参数

log_checkpoints · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

参考资料

11.11 - log_checkpoints

log_checkpoints 决定 PostgreSQL 是否记录每次检查点。
说明

Fact — 官方简述译文：记录每次检查点。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–14 off — off
PG15–19 Beta 3 on — on

机制详解

log_checkpoints：记录每次检查点。检查点记录包含各阶段耗时及缓冲区或 WAL 工作量，暴露检查点节奏与写压力，而不只是一个标记。

log_checkpoints 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_checkpoints；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_checkpoints 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_checkpoints 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 等于 boot 值 'on'
OLAP on 等于 boot 值 'on'
CRIT on 等于 boot 值 'on'
TINY on 等于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断：显式记录检查点可在各版本一致保留写入量与时序证据，包括上游默认曾为 off 的版本。

常见坑

  • 编辑 log_checkpoints 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_checkpoints。

关联参数

log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

参考资料

11.12 - log_connections

log_connections 决定 PostgreSQL 是否记录连接建立与初始化过程中的指定阶段。
说明

Fact — 官方简述译文：记录连接建立与初始化过程中的指定阶段。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser-backend
超级用户后端启动时固定
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–17 off — off
PG18–19 Beta 3 "" — empty string

机制详解

PostgreSQL 10–17 中，log_connections 是布尔参数，启用后记录成功连接。PostgreSQL 18 将其改为字符串列表，精确选项为 receipt、authentication、authorization、setup_durations 与 all；空字符串关闭连接日志。为兼容旧配置，on、true、yes、1 等价于 receipt,authentication,authorization，off、false、no、0 等价于空列表。认证失败无论本参数为何值都会记录。

log_connections 属于 SUPERUSER_BACKEND 上下文：超级用户或获授相应 SET 权限的角色可在会话启动时选择它，但后端会话启动后不能再修改。因此配置变化只影响新会话。

receipt 记录连接到达，authentication 记录认证方法提交的原始身份，authorization 记录带用户、数据库和应用上下文的成功授权，setup_durations 记录总初始化、后端 fork 与认证耗时。会话结束由 log_disconnections 单独控制；连接身份与拓扑仍属于敏感日志数据。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 只记录审计或延迟问题真正需要的阶段；authorization 以较低日志量保留成功连接轨迹，receipt 与 authentication 增加授权前证据。只有排查连接启动延迟时才加入 setup_durations。
OLAP 分析会话更少但更长，authorization 加 setup_durations 可用于归因昂贵的连接初始化；不要仅因查询量较低就使用 all。
小规格 列表保持最小，并继续监控不受本参数影响的认证失败。确认日志存储与脱敏能够安全保留原始身份和应用名称。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP authorization 不同于 boot 值 'authorization'
OLAP authorization 不同于 boot 值 'authorization'
CRIT receipt,authentication,authorization 不同于 boot 值 'receipt,authentication,authorization'
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–17 未修改, PG18–19 Beta 3 = authorization (dcs)；OLAP: PG9.0–17 未修改, PG18–19 Beta 3 = authorization (dcs)；CRIT: PG9.0–17 = on (dcs), PG18–19 Beta 3 = receipt,authentication,authorization (dcs)；TINY: PG9.0–19 Beta 3 未修改。 建议（待人工复核）——编辑推断：CRIT 捕获更完整的认证审计轨迹，而 PostgreSQL 18 的 OLTP 与 OLAP 以较低日志量保留成功授权事件；迁移语义仍需复核。

常见坑

  • 使用不存在的 setup，而不是 PostgreSQL 18 的有效选项 setup_durations。
  • 误以为兼容值 on 等于 all；它不含 setup_durations，只映射到 receipt、authentication、authorization。
  • 期待既有会话继承新值，而该参数在后端启动时已经固定。
  • 未考虑 psql 等客户端可能探测两次就把重复 receipt 当作攻击，或在没有访问控制策略时长期保留原始身份。

关联参数

log_statement · log_duration · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

参考资料

11.13 - log_destination

log_destination 定义服务器日志输出的目标。
说明

Fact — 官方简述译文：设置服务器日志输出的目标。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值stderr
stderr

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 stderr — stderr

机制详解

log_destination：设置服务器日志输出的目标。可同时启用多个目标；csvlog 与 jsonlog 需要 logging_collector，而 stderr、syslog 和 Windows eventlog 采用不同传输路径。

log_destination 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 log_destination 纳入端到端日志设计，联合验证收集器、轮转、所有权、转运、保留策略以及目标写满后的恢复。
OLAP 按分析日志突发为 log_destination 路径定容，并验证轮转或下游摄取不会阻塞数据库进程。
小规格 为 log_destination 使用有界且易轮转的配置并监控剩余空间；小节点不应保留重复格式或无限文件。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP csvlog 不同于 boot 值 csvlog
OLAP csvlog 不同于 boot 值 csvlog
CRIT csvlog 不同于 boot 值 csvlog
TINY csvlog 不同于 boot 值 csvlog
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = csvlog (dcs)；OLAP: PG9.0–19 Beta 3 = csvlog (dcs)；CRIT: PG9.0–19 Beta 3 = csvlog (dcs)；TINY: PG9.0–19 Beta 3 = csvlog (dcs)。 建议（待人工复核）——编辑推断：csvlog 为所有模板提供稳定的结构化记录，便于收集与面向 SQL 的分析。

常见坑

  • 编辑 log_destination 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_destination。

关联参数

logging_collector · log_directory · log_filename · log_rotation_age · log_rotation_size

参考资料

11.14 - log_directory

log_directory 定义日志文件的目标目录。
说明

Fact — 官方简述译文：设置日志文件的目标目录。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值log
log

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 pg_log — pg_log
PG10–19 Beta 3 log — log

机制详解

log_directory：设置日志文件的目标目录。相对路径在数据目录下解析，绝对路径则可把收集器管理的文件放到独立文件系统。

log_directory 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 log_directory 纳入端到端日志设计，联合验证收集器、轮转、所有权、转运、保留策略以及目标写满后的恢复。
OLAP 按分析日志突发为 log_directory 路径定容，并验证轮转或下游摄取不会阻塞数据库进程。
小规格 为 log_directory 使用有界且易轮转的配置并监控剩余空间；小节点不应保留重复格式或无限文件。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP /pg/log/postgres 不同于 boot 值 {{ pg_log_dir }}
OLAP /pg/log/postgres 不同于 boot 值 {{ pg_log_dir }}
CRIT /pg/log/postgres 不同于 boot 值 {{ pg_log_dir }}
TINY /pg/log/postgres 不同于 boot 值 {{ pg_log_dir }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = /pg/log/postgres (dcs)；OLAP: PG9.0–19 Beta 3 = /pg/log/postgres (dcs)；CRIT: PG9.0–19 Beta 3 = /pg/log/postgres (dcs)；TINY: PG9.0–19 Beta 3 = /pg/log/postgres (dcs)。 建议（待人工复核）——编辑推断：专用 /pg/log/postgres 路径把 PostgreSQL 日志与数据目录分离，并与托管文件系统布局一致。

常见坑

  • 编辑 log_directory 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_directory。

关联参数

logging_collector · log_destination · log_filename · log_rotation_age · log_rotation_size

参考资料

11.15 - log_disconnections

log_disconnections 决定 PostgreSQL 是否记录会话结束及其持续时间。
说明

Fact — 官方简述译文：记录会话结束及其持续时间。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser-backend
超级用户后端启动时固定
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_disconnections：记录会话结束及其持续时间。记录在会话结束时输出并包含会话时长，可与连接开始身份配对，但不能证明每次突发故障都到达日志器。

log_disconnections 属于 SUPERUSER_BACKEND 上下文：配置变化在新后端会话启动时生效，并需要超级用户级权限；既有会话保留启动值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_disconnections；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_disconnections 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_disconnections 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT on 不同于 boot 值 'on'
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 未修改。 建议（待人工复核）——编辑推断：CRIT 记录会话结束与持续时间以补全连接审计轨迹，并只在该模板承担额外日志量。

常见坑

  • 期待既有会话继承新的 log_disconnections 值，而它在每个后端启动时已经固定。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_disconnections。

关联参数

log_statement · log_duration · log_connections · log_parameter_max_length · log_parameter_max_length_on_error

参考资料

11.16 - log_duration

log_duration 决定 PostgreSQL 是否记录每条已完成 SQL 语句的执行时长。
说明

Fact — 官方简述译文：记录每条已完成 SQL 语句的执行时长。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_duration：记录每条已完成 SQL 语句的执行时长。它为每条完成语句输出时长，但自身不输出语句文本；需要文本时由 log_statement 或时长阈值提供。

log_duration 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_duration；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_duration 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_duration 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 log_duration，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 期待时长日志包含 SQL 文本，而实际上没有任何语句日志参数输出文本。

关联参数

log_statement · log_connections · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

参考资料

11.17 - log_error_verbosity

log_error_verbosity 定义日志消息的详细程度。
说明

Fact — 官方简述译文：设置日志消息的详细程度。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值terse, default, verbose
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值default
default

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 default — default

机制详解

log_error_verbosity：设置日志消息的详细程度。TERSE 抑制详情与提示，DEFAULT 保留常规诊断，VERBOSE 追加 SQLSTATE 以及源文件、函数与行号。

log_error_verbosity 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_error_verbosity；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_error_verbosity 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_error_verbosity 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 log_error_verbosity，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_error_verbosity。

关联参数

log_statement · log_duration · log_connections · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

参考资料

11.18 - log_file_mode

log_file_mode 定义日志文件的权限模式。
说明

Fact — 官方简述译文：设置日志文件的权限模式。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 511
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值384
384

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 3ec694e17bc0 — Add a log_file_mode GUC that allows control of the file permissions set on log files created by the syslogger process.
提交日期 2010-07-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 384 — 384

机制详解

log_file_mode 是 logging_collector 新建文件所用的 chmod 风格数字模式。常规八进制写法必须带前导零：0640 与十进制 640 不是同一个数值。它不作用于 syslog/eventlog 输出，也不会修改既有文件。

它属于 SIGHUP 上下文。重载后，logging_collector 下次创建文件时使用新模式；重载不会对当前打开文件或历史文件执行 chmod。

有效访问边界还包括 PostgreSQL 服务账号、文件组、log_directory 的所有权与遍历权限、转运代理组成员，以及外部保留副本。只有该组受到严格控制时，组可读模式才安全。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 选择既能让获准收集器或转运组读取新文件、又尽量小权限的模式。在真实轮转后核对所有权；策略变化时应显式修复既有文件。
OLAP 分析日志往往包含查询文本与身份信息，应采用相同或更严格模式；日志量更大不是扩大文件访问范围的理由。
小规格 除非受控本地组必须转运日志，否则保持 0600；使用 0640 时应审计组成员与目录权限，而不是向所有用户开放读取。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0640 不同于 boot 值 '0640'
OLAP 0640 不同于 boot 值 '0640'
CRIT 0640 不同于 boot 值 '0640'
TINY 0640 不同于 boot 值 '0640'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 = 0640 (dcs)；OLAP: PG9.1–19 Beta 3 = 0640 (dcs)；CRIT: PG9.1–19 Beta 3 = 0640 (dcs)；TINY: PG9.1–19 Beta 3 = 0640 (dcs)。 建议（待人工复核）——编辑推断：0640 阻止其他用户读取日志，同时允许运维组读取并转运。

常见坑

  • 编辑 log_file_mode 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 写成 640 而非八进制 0640，得到不同的数字权限模式。

关联参数

logging_collector · log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

参考资料

11.19 - log_filename

log_filename 定义日志文件名模式。
说明

Fact — 官方简述译文：设置日志文件名模式。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值postgresql-%Y-%m-%d_%H%M%S.log
postgresql-%Y-%m-%d_%H%M%S.log

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 postgresql-%Y-%m-%d_%H%M%S.log — postgresql-%Y-%m-%d_%H%M%S.log

机制详解

log_filename：设置日志文件名模式。logging_collector 每次打开新文件时按 log_timezone 展开 strftime 转义，因此重复名称必须与轮转和截断协调。

log_filename 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 使用与轮转策略唯一性相匹配的文件名模式。若名称会重复，应结合按时间轮转、log_truncate_on_rotation 与已确认的转运，避免复用名称混合周期或覆盖尚未收集的数据。
OLAP 为大型分析日志选择可预测的周期边界，并保证下游摄取在模式重复前关闭上一文件；不要把按大小轮转与非唯一名称组合。
小规格 星期或日期循环只有在保留策略与空间监控匹配时才有界。保留足够时间组成，避免重启或手工轮转后的意外冲突。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP postgresql-%a.log 不同于 boot 值 'postgresql-%a.log'
OLAP postgresql-%a.log 不同于 boot 值 'postgresql-%a.log'
CRIT postgresql-%a.log 不同于 boot 值 'postgresql-%a.log'
TINY postgresql-%a.log 不同于 boot 值 'postgresql-%a.log'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = postgresql-%a.log (dcs)；OLAP: PG9.0–19 Beta 3 = postgresql-%a.log (dcs)；CRIT: PG9.0–19 Beta 3 = postgresql-%a.log (dcs)；TINY: PG9.0–19 Beta 3 = postgresql-%a.log (dcs)。 建议（待人工复核）——编辑推断：按星期命名形成可预测的七文件循环，意在配合每日轮转与截断。

常见坑

  • 编辑 log_filename 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 使用重复的 strftime 文件名，却未匹配轮转与截断策略，造成持续追加或意外覆盖。

关联参数

logging_collector · log_destination · log_directory · log_rotation_age · log_rotation_size

参考资料

11.20 - log_hostname

log_hostname 是 PostgreSQL 中用于在连接日志中记录主机名的参数。
说明

Fact — 官方简述译文：在连接日志中记录主机名。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_hostname：在连接日志中记录主机名。为把客户端地址转换为名称会执行反向 DNS；名称服务缓慢时可能增加连接延迟甚至造成停顿。

log_hostname 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_hostname；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_hostname 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_hostname 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 log_hostname 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 在解析器延迟位于连接路径时启用反向 DNS。

关联参数

application_name · cluster_name · update_process_title · log_line_prefix · log_timezone

参考资料

11.21 - log_line_prefix

log_line_prefix 是 PostgreSQL 中用于控制每行日志前添加的信息的参数。
说明

Fact — 官方简述译文：控制每行日志前添加的信息。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值%m [%p]
%m [%p]

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 "" — empty string
PG10–19 Beta 3 %m [%p] — %m [%p]

机制详解

log_line_prefix：控制每行日志前添加的信息。百分号转义可加入会话、用户、数据库、进程、应用与时间上下文；csvlog 和 jsonlog 已单独携带结构化字段。

log_line_prefix 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_line_prefix；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_line_prefix 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_line_prefix 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 log_line_prefix 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 遗漏关联多行文本日志所需的进程、会话、数据库、用户或应用身份。

关联参数

application_name · cluster_name · update_process_title · log_timezone · log_hostname

参考资料

11.22 - log_lock_failures

log_lock_failures 决定 PostgreSQL 是否记录锁获取失败。
说明

Fact — 官方简述译文：记录锁获取失败。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 73bdcfab35ec — Rename log_lock_failure GUC to log_lock_failures for consistency.
提交日期 2025-06-03
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 off — off

机制详解

log_lock_failures 引入于 PostgreSQL 18，在受支持的锁获取失败时输出详细消息。PostgreSQL 18 当前支持范围明确只有 SELECT … NOWAIT 导致的锁失败；它不是所有 NOWAIT 类命令或所有锁错误的通用日志器。

它属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可按会话修改，因此角色/数据库默认值与连接池重置行为决定哪些会话产生记录。

它补充 log_lock_waits：后者记录超过 deadlock_timeout 的等待，而 SELECT … NOWAIT 会立即失败并可由本参数记录。详细消息可能暴露关系、锁与语句上下文，必须遵循常规日志访问策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在 SELECT … NOWAIT 失败能解释延迟或重试行为的会话中启用，并把记录与应用重试及锁持有者关联；不要期待它覆盖无关锁错误。
OLAP 使用 SELECT … NOWAIT 的分析读取可在争用调查期间启用；若没有这类命令则保持 off，因为它不提供更广泛等待遥测。
小规格 正常日志量较低，但启用前仍应验证日志访问与保留。与 log_lock_waits 和死锁诊断配合，而不是把它当作替代品。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP 未修改 — —
CRIT on 不同于 boot 值 'on'
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 = on (dcs)；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 = on (dcs)；TINY: PG18–19 Beta 3 未修改。 建议（待人工复核）——编辑推断：该覆盖似乎旨在为最需要立即锁失败重试或审计诊断的模板保留 SELECT … NOWAIT 失败详情；PostgreSQL 18 的该 GUC 不提供更广泛的锁失败覆盖。

常见坑

  • 误以为 PostgreSQL 18 会记录所有锁获取失败；当前只支持 SELECT … NOWAIT。
  • 用它替代 log_lock_waits，而立即失败与等待超过 deadlock_timeout 是不同事件。
  • 只在一个池化会话中启用，却认为其他会话继承了该值。
  • 在没有适当日志访问、脱敏与保留控制时保存详细锁和语句上下文。

关联参数

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_temp_files · log_replication_commands

参考资料

11.23 - log_lock_waits

log_lock_waits 决定 PostgreSQL 是否记录持续时间较长的锁等待。
说明

Fact — 官方简述译文：记录持续时间较长的锁等待。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–18 off — off
PG19 Beta 3 on — on

机制详解

log_lock_waits：记录持续时间较长的锁等待。锁等待超过 deadlock_timeout 后才记录，因此诊断阈值与死锁检测节奏相互耦合。

log_lock_waits 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_lock_waits；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_lock_waits 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_lock_waits 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 等于 boot 值 'on'
OLAP on 等于 boot 值 'on'
CRIT on 等于 boot 值 'on'
TINY on 等于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断：所有模板都保留长锁等待证据，因为它对诊断延迟与阻塞者价值高，而正常日志量较低。

常见坑

  • 只在一个会话中修改 log_lock_waits，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 修改 deadlock_timeout，却未意识到锁等待诊断出现时间也随之改变。

关联参数

log_checkpoints · log_autovacuum_min_duration · log_lock_failures · log_temp_files · log_replication_commands

参考资料

11.24 - log_min_duration_sample

log_min_duration_sample 定义进入语句抽样记录所需达到的最短执行时间，抽样由 log_statement_sample_rate 决定。
说明

Fact — 官方简述译文：设置进入语句抽样记录所需达到的最短执行时间，抽样由 log_statement_sample_rate 决定。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值-1
-1 ms

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 6e3e6cc0e884 — Allow sampling of statements depending on duration
提交日期 2019-11-04
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 -1 ms -1 ms

机制详解

log_min_duration_sample 让执行时长达到阈值的已完成语句进入由 log_statement_sample_rate 控制的随机日志路径。-1 关闭该路径，零让所有已完成语句进入，再由抽样率决定实际输出。

log_min_duration_statement 优先级更高。达到其阈值的语句始终记录且不参与抽样，即使同时超过 log_min_duration_sample。扩展查询协议下，Parse、Bind 与 Execute 的时长分别记录。

它属于 SUPERUSER 上下文的会话参数。抽样条目与 log_min_duration_statement 具有相同的语句文本、Bind 值、关联、开销和安全问题，因此 log_line_prefix 与 log_parameter_max_length 仍决定可用性与暴露范围。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先用 log_min_duration_statement 设置始终记录阈值，再用更低抽样阈值与实测概率覆盖高流量中间区间。在 OLTP 峰值下验证实际样本数与敏感数据处理。
OLAP 长分析查询往往超过始终记录阈值，因此抽样可能无法减少这些日志。应依据时长分布选择阈值，而不是照搬 OLTP 值。
小规格 使用保守抽样率与有界语句文本。除非明确需要每条语句时长记录，小节点不要组合零阈值与抽样率 1。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待抽样影响已被更高优先级 log_min_duration_statement 阈值捕获的语句。
  • 忘记扩展查询协议会分别计时并记录 Parse、Bind 与 Execute。
  • 把阈值设为零且 log_statement_sample_rate 为 1，意外记录每条已完成语句的时长。
  • 在没有关联标识、脱敏、访问控制与实测容量预算时抽样 SQL 和 Bind 值。

关联参数

log_min_messages · log_min_error_statement · log_min_duration_statement · log_statement_sample_rate · log_transaction_sample_rate

参考资料

11.25 - log_min_duration_statement

记录执行时间达到阈值的每条已完成语句。它是确定性的慢查询采集开关，与抽样日志和取消语句是不同机制。
说明

Fact — 官方简述译文：记录运行时间达到配置阈值的已完成语句。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值ms
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值-1
-1 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 -1 ms -1 ms

机制详解

未写单位时按毫秒解释。-1 关闭按时长记录，0 记录所有已完成语句，正数则记录达到或超过阈值的语句。

由本参数选中的语句会始终记录而不参与抽样，因此优先于 log_min_duration_sample。使用扩展查询协议时，Parse、Bind、Execute 阶段的时长可能分别出现。

该参数只观察并记录已经完成的工作，不会终止慢语句；取消执行应使用独立的 statement_timeout。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据应用延迟目标和可接受日志量选择阈值。高 QPS 场景可用有意义的硬阈值捕获真正慢查询，并对更快的语句采用抽样。
OLAP 采用更高阈值，避免正常的长分析查询淹没日志；结合 query identifier 和工作负载标签，让重复记录仍然可行动。
小规格 调优期可使用较低阈值，但要观察磁盘与轮转；一旦日志本身成为可测负载，应提高阈值或改用抽样。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 100 不同于 boot 值 100
OLAP 1000 不同于 boot 值 1000
CRIT 100 不同于 boot 值 100
TINY 100 不同于 boot 值 100
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 100 (dcs)；OLAP: PG9.0–19 Beta 3 = 1000 (dcs)；CRIT: PG9.0–19 Beta 3 = 100 (dcs)；TINY: PG9.0–19 Beta 3 = 100 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：Pigsty 主动保留确定性的慢查询证据，而 OLAP 用更宽松阈值适应天然更长的分析语句。

常见坑

  • 高吞吐系统上的低阈值可能制造巨量日志与 I/O。
  • SQL 文本可能含敏感字面量，日志应按应用数据同等级保护。
  • 它只记录慢语句而不取消；取消应使用 statement_timeout。
  • 扩展协议阶段可能分开记录，需要会话或 PID 关联。
  • 与 log_statement、抽样和 log_line_prefix 的组合可能造成重复或碎片化理解。

关联参数

log_min_duration_sample · log_statement_sample_rate · log_statement · log_duration · log_line_prefix · statement_timeout

参考资料

11.26 - log_min_error_statement

log_min_error_statement 决定 PostgreSQL 是否记录所有产生不低于指定级别错误的语句。
说明

Fact — 官方简述译文：记录所有产生不低于指定级别错误的语句。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值debug5, debug4, debug3, debug2, debug1, info, notice, warning, error, log, fatal, panic
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值error
error

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 error — error

机制详解

log_min_error_statement：记录所有产生不低于指定级别错误的语句。它控制是否附带产生错误级消息的 SQL 语句；消息本身是否输出则由 log_min_messages 分别决定。

log_min_error_statement 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_min_error_statement；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_min_error_statement 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_min_error_statement 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 log_min_error_statement，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_min_error_statement。

关联参数

log_min_messages · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

参考资料

11.27 - log_min_messages

log_min_messages 定义写入服务器日志的消息级别。
说明

Fact — 官方简述译文：设置写入服务器日志的消息级别。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值warning
warning

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 warning — warning

机制详解

log_min_messages：设置写入服务器日志的消息级别。服务器日志严重级别中 LOG 的位置特殊，且顺序不同于 client_min_messages，因此不能在二者之间盲目照搬阈值名。

log_min_messages 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_min_messages；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_min_messages 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_min_messages 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 log_min_messages，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_min_messages。

关联参数

log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

参考资料

11.28 - log_parameter_max_length

log_parameter_max_length 定义记录语句时绑定参数值可写入日志的最大字节数。
说明

Fact — 官方简述译文：设置记录语句时绑定参数值可写入日志的最大字节数。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值B
原始单位
范围 值-1 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值-1
-1 B

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 0b34e7d307e6 — Improve user control over truncation of logged bind-parameter values.
提交日期 2020-04-02
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 -1 B -1 B

机制详解

log_parameter_max_length 控制附加到非错误语句日志消息的 Bind 值。零不记录，-1 允许完整值，正字节数把每个文本值截断到该上限。

它作用于 log_statement、log_min_duration_statement 及相关语句日志产生的消息。任何非零值都会增加工作量；二进制参数必须先转换为文本才能记录。

它属于 SUPERUSER 上下文的会话参数，并与 log_parameter_max_length_on_error 相互独立。因此普通路径与错误路径需要分别决定保密性与开销。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP Bind 值可能包含凭据或受监管数据时保持零。诊断确需值时，选择最小有用正上限，并在 OLTP 峰值流量下测量二进制 Bind 转换成本。
OLAP 分析参数可能是大数组或谓词；短期诊断使用有界正上限，不要使用 -1，并验证截断后日志仍有用。
小规格 默认使用零。完整值会消耗小节点难以安全承受的磁盘与转换 CPU，而且截断不等于脱敏。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 使用 -1，在普通语句日志中暴露完整凭据、令牌或大载荷。
  • 把截断当作脱敏；敏感前缀仍可能完整可见。
  • 值非零时忽略二进制 Bind 参数的文本转换开销。
  • 误以为它也限制由 log_parameter_max_length_on_error 控制的错误路径参数。

关联参数

log_statement · log_duration · log_connections · log_disconnections · log_parameter_max_length_on_error

参考资料

11.29 - log_parameter_max_length_on_error

log_parameter_max_length_on_error 定义发生错误时绑定参数值可写入日志的最大字节数。
说明

Fact — 官方简述译文：设置发生错误时绑定参数值可写入日志的最大字节数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值B
原始单位
范围 值-1 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值0
0 B

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 0b34e7d307e6 — Improve user control over truncation of logged bind-parameter values.
提交日期 2020-04-02
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 0 B 0 B

机制详解

log_parameter_max_length_on_error 控制错误报告中包含的 Bind 值。默认零不记录，-1 允许完整值，正字节数把每个文本值截断到该上限。

只要值非零，PostgreSQL 就必须在每条语句开始时保留参数的文本表示，以备发生错误。即使语句成功也要支付该开销，二进制参数还需要转换而不只是复制文本。

它属于 USER 上下文的会话参数，并与 log_parameter_max_length 相互独立。因此即使普通语句日志不记录值，应用也可能在错误路径意外暴露。应联合评审错误详情、访问、脱敏与保留。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非错误诊断明确需要绑定值，否则保持 0。任何非零值都会让每条语句承担转换与保留内存开销，因此优先使用有界正值，并按角色、数据库或会话缩小范围。
OLAP 只在受控诊断参数化分析作业时使用有界正值；成功语句同样会保留参数文本，应同时预算转换成本与内存。
小规格 优先保持 0。若错误路径必须记录绑定值，应选短上限、缩小作用域，并在启用前验证内存开销与秘密脱敏策略。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为只有语句失败时才支付转换与内存成本；值非零时每条语句都会支付。
  • 使用 -1，把完整秘密或大载荷暴露在错误报告中。
  • 忽略二进制 Bind 值的文本转换成本，以及成功语句也会保留参数表示。
  • 误以为 log_parameter_max_length 会保护错误路径；两个上限彼此独立。

关联参数

log_statement · log_duration · log_connections · log_disconnections · log_parameter_max_length

参考资料

11.30 - log_recovery_conflict_waits

log_recovery_conflict_waits 决定 PostgreSQL 是否记录备用库恢复冲突等待。
说明

Fact — 官方简述译文：记录备用库恢复冲突等待。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 0650ff23038b — Add GUC to log long wait times on recovery conflicts.
提交日期 2021-01-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 off — off

机制详解

log_recovery_conflict_waits：记录备用库恢复冲突等待。在备用库上，恢复冲突等待超过 deadlock_timeout 后会被记录，可在尚未必须取消查询前暴露回放延迟。

log_recovery_conflict_waits 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_recovery_conflict_waits；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_recovery_conflict_waits 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_recovery_conflict_waits 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 log_recovery_conflict_waits 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_recovery_conflict_waits。

关联参数

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

参考资料

11.31 - log_replication_commands

log_replication_commands 决定 PostgreSQL 是否记录每条复制命令。
说明

Fact — 官方简述译文：记录每条复制命令。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 4ad2a548050f — Add GUC to enable logging of replication commands.
提交日期 2014-09-13
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 off — off

机制详解

log_replication_commands：记录每条复制命令。它既覆盖复制协议命令，也覆盖 SQL 复制命令，因此能够暴露复制拓扑与复制槽活动。

log_replication_commands 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_replication_commands；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_replication_commands 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_replication_commands 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 = on (dcs)；OLAP: PG9.5–19 Beta 3 = on (dcs)；CRIT: PG9.5–19 Beta 3 = on (dcs)；TINY: PG9.5–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断：复制命令历史有助于在托管集群中诊断复制槽、发送端、故障转移与拓扑变化。

常见坑

  • 只在一个会话中修改 log_replication_commands，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_replication_commands。

关联参数

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files

参考资料

11.32 - log_rotation_age

log_rotation_age 定义强制轮转日志文件前等待的时间。
说明

Fact — 官方简述译文：设置强制轮转日志文件前等待的时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值min
原始单位
范围 值0 – 35791394
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值1440
1 d

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 1440 min 1 d

机制详解

log_rotation_age：设置强制轮转日志文件前等待的时间。收集器在达到间隔后打开新文件；零关闭这一触发器，但仍可使用按大小或外部轮转。

log_rotation_age 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按文件允许保持打开的最长时间以及转运/保留边界设置 log_rotation_age，并确认文件名模式在该间隔生成不同名称或按预期复用。
OLAP 长分析突发本身不要求不同的时钟；选择能让下游可预测关闭和摄取文件、又不会生成过大对象的间隔。
小规格 优先使用简单的每日或更短间隔以限制故障影响。零会关闭按时间轮转，只有按大小或外部轮转已成为权威且经过测试时才安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1d 等于 boot 值 '1d'
OLAP 1d 等于 boot 值 '1d'
CRIT 1d 等于 boot 值 '1d'
TINY 1d 等于 boot 值 '1d'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 1d (dcs)；OLAP: PG9.0–19 Beta 3 = 1d (dcs)；CRIT: PG9.0–19 Beta 3 = 1d (dcs)；TINY: PG9.0–19 Beta 3 = 1d (dcs)。 建议（待人工复核）——编辑推断：每日轮转与星期文件名循环匹配，形成可预测的运维边界。

常见坑

  • 编辑 log_rotation_age 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_rotation_age。

关联参数

logging_collector · log_destination · log_directory · log_filename · log_rotation_size

参考资料

11.33 - log_rotation_size

log_rotation_size 定义触发轮转前单个日志文件可达到的最大大小。
说明

Fact — 官方简述译文：设置触发轮转前单个日志文件可达到的最大大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值kB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值10240
10 MiB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 10240 kB 10 MiB

机制详解

log_rotation_size：设置触发轮转前单个日志文件可达到的最大大小。当前文件约达到该大小时收集器轮转；零只关闭大小触发器，不关闭按时间轮转。

log_rotation_size 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 需要直接限制单文件大小时，为 log_rotation_size 使用非零值，并让文件名能够区分同一时间周期内的多次轮转。设为零时，应确认按时间轮转与磁盘告警提供替代边界。
OLAP 分析日志突发可能反复跨越大小阈值；应测试生成的文件名后缀、转运吞吐与最大单文件大小，而不是习惯性调大。
小规格 适度大小上限可限制日志突发损害，但文件过小会增加元数据与转运开销。只有按时间循环和剩余空间护栏已经验证时才使用零。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0 不同于 boot 值 '0'
OLAP 0 不同于 boot 值 '0'
CRIT 0 不同于 boot 值 '0'
TINY 0 不同于 boot 值 '0'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 0 (dcs)；OLAP: PG9.0–19 Beta 3 = 0 (dcs)；CRIT: PG9.0–19 Beta 3 = 0 (dcs)；TINY: PG9.0–19 Beta 3 = 0 (dcs)。 建议（待人工复核）——编辑推断：关闭按大小轮转似乎旨在让每日时间轮转成为唯一文件循环机制；磁盘护栏仍需独立复核。

常见坑

  • 编辑 log_rotation_size 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 设为零却没有有效的按时间或外部轮转策略，导致文件无界增长。

关联参数

logging_collector · log_destination · log_directory · log_filename · log_rotation_age

参考资料

11.34 - log_startup_progress_interval

log_startup_progress_interval 定义耗时启动操作的进度日志间隔。
说明

Fact — 官方简述译文：设置耗时启动操作的进度日志间隔。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值10000
10 s

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 9ce346eabf35 — Report progress of startup operations that take a long time.
提交日期 2021-10-25
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 10000 ms 10 s

机制详解

log_startup_progress_interval：设置耗时启动操作的进度日志间隔。启动进程在 WAL 回放等操作持续超过该间隔时周期性输出进度；零关闭这些更新。

log_startup_progress_interval 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_startup_progress_interval；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_startup_progress_interval 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_startup_progress_interval 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 log_startup_progress_interval 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_startup_progress_interval。

关联参数

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_temp_files · log_replication_commands

参考资料

11.35 - log_statement

log_statement 定义要记录的 SQL 语句类型。
说明

Fact — 官方简述译文：设置要记录的 SQL 语句类型。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值none, ddl, mod, all
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值none
none

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 none — none

机制详解

log_statement 可选 none、ddl、mod、all。ddl 记录数据定义命令，mod 再加入数据变更命令，all 记录所有到达日志点的语句；PREPARE、EXECUTE 与 EXPLAIN ANALYZE 按其包含命令分类。

使用扩展查询协议时，收到 Execute 才记录，并包含 Bind 参数值。即使设为 all，基本解析失败的简单语句，以及在 Execute 前的解析分析或规划阶段失败的扩展协议语句也不会记录；这些错误路径需要 log_min_error_statement。

它属于 SUPERUSER 上下文的会话参数。语句文本与 Bind 值可能暴露个人数据、令牌，甚至明文密码，因此范围选择、访问、脱敏、传输与保留必须同时作为安全控制和可观测性选择。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 常规 OLTP 以 none 或 ddl 为基线，查询性能使用时长阈值或抽样。启用 mod/all 前，测试日志量，并为 SQL 文本与 Bind 值建立具体脱敏和访问策略。
OLAP 分析排障使用角色或会话限定窗口，不要集群级 all。长生成 SQL 与大 Bind 值可能主导日志并暴露源数据。
小规格 优先使用 ddl 或定向阈值；即使节点安静，all 也可能压垮磁盘并泄漏秘密。保留 log_min_error_statement 以覆盖 log_statement 漏掉的语法/解析失败。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP ddl 不同于 boot 值 ddl
OLAP ddl 不同于 boot 值 ddl
CRIT ddl 不同于 boot 值 ddl
TINY ddl 不同于 boot 值 ddl
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = ddl (dcs)；OLAP: PG9.0–19 Beta 3 = ddl (dcs)；CRIT: PG9.0–19 Beta 3 = ddl (dcs)；TINY: PG9.0–19 Beta 3 = ddl (dcs)。 建议（待人工复核）——编辑推断：记录 DDL 让所有模板获得模式变更轨迹，同时避免记录全部语句带来的保密与容量成本。

常见坑

  • 误以为 all 会捕获语法错误或 Execute 前的扩展协议失败；这些路径应使用 log_min_error_statement。
  • 忘记扩展协议在 Execute 日志中包含 Bind 参数值。
  • 在没有脱敏与严格访问控制时记录含明文密码、Bearer Token、个人数据或应用秘密的 SQL。
  • 未限制日志吞吐、磁盘、转运与保留就集群级启用 mod 或 all。

关联参数

log_duration · log_connections · log_disconnections · log_parameter_max_length · log_parameter_max_length_on_error

参考资料

11.36 - log_statement_sample_rate

log_statement_sample_rate 定义超过 log_min_duration_sample 的语句被记录的比例。
说明

Fact — 官方简述译文：设置超过 log_min_duration_sample 的语句被记录的比例。

身份

类型 值real
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 88bdbd3f7460 — Add log_statement_sample_rate parameter
提交日期 2018-11-29
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 1 — 1

机制详解

log_statement_sample_rate：设置超过 log_min_duration_sample 的语句被记录的比例。该概率只对达到 log_min_duration_sample 的语句生效，不会抽样 log_statement 或 log_min_duration_statement 的输出。

log_statement_sample_rate 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_statement_sample_rate；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_statement_sample_rate 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_statement_sample_rate 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 log_statement_sample_rate，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 期待它抽样所有语句日志，而实际上只控制 log_min_duration_sample。

关联参数

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_transaction_sample_rate

参考资料

11.37 - log_temp_files

log_temp_files 决定 PostgreSQL 是否记录大于指定千字节数的临时文件使用。
说明

Fact — 官方简述译文：记录大于指定千字节数的临时文件使用。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值kB
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值-1
-1 kB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 -1 kB -1 kB

机制详解

log_temp_files：记录大于指定千字节数的临时文件使用。临时文件删除时会记录名称与大小；-1 关闭记录，零包含每个文件。

log_temp_files 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_temp_files；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_temp_files 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_temp_files 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1024 不同于 boot 值 1024
OLAP 1024 不同于 boot 值 1024
CRIT 1024 不同于 boot 值 1024
TINY 1024 不同于 boot 值 1024
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 1024 (dcs)；OLAP: PG9.0–19 Beta 3 = 1024 (dcs)；CRIT: PG9.0–19 Beta 3 = 1024 (dcs)；TINY: PG9.0–19 Beta 3 = 1024 (dcs)。 建议（待人工复核）——编辑推断：1 MiB 阈值暴露有意义的执行器溢写，同时过滤很小的临时文件。

常见坑

  • 只在一个会话中修改 log_temp_files，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_temp_files。

关联参数

log_checkpoints · log_autovacuum_min_duration · log_lock_waits · log_lock_failures · log_replication_commands

参考资料

11.38 - log_timezone

log_timezone 定义日志消息使用的时区。
说明

Fact — 官方简述译文：设置日志消息使用的时区。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / What to Log
上游分类
最后 boot 值 值GMT
GMT

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 UNKNOWN — UNKNOWN
PG9.1 — — not set
PG9.2–19 Beta 3 GMT — GMT

机制详解

log_timezone：设置日志消息使用的时区。它影响日志系统显示的时间戳，包括文件名展开上下文，但不改变会话 TimeZone 或已存储时间戳。

log_timezone 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 使用一个集群级时区，通常为 UTC，使所有会话的服务器日志时间戳能跨主机、副本、故障转移与集中摄取关联。修改前测试解析器与 log_filename 展开。
OLAP 分析负载类型不构成独立日志时区的理由。保持 UTC 或全局标准，只在报表工具中转换到本地民用时间，尤其要处理夏令时切换。
小规格 除非既有运维管线要求其他稳定时区，否则保持 UTC。修改 log_timezone 不会减少日志量，只会改变时间戳解释，并可能改变轮转文件名。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP UTC 不同于 boot 值 'UTC'
OLAP UTC 不同于 boot 值 'UTC'
CRIT UTC 不同于 boot 值 'UTC'
TINY UTC 不同于 boot 值 'UTC'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = UTC (dcs)；OLAP: PG9.0–19 Beta 3 = UTC (dcs)；CRIT: PG9.0–19 Beta 3 = UTC (dcs)；TINY: PG9.0–19 Beta 3 = UTC (dcs)。 建议（待人工复核）——编辑推断：UTC 让跨主机、区域、故障转移与集中日志系统的时间戳可以直接比较。

常见坑

  • 编辑 log_timezone 后没有重新加载配置，也没有核对有效值与后续行为。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 log_timezone。

关联参数

DateStyle · IntervalStyle · TimeZone · lc_time · timezone_abbreviations

参考资料

11.39 - log_transaction_sample_rate

log_transaction_sample_rate 定义抽取整笔事务并记录其中所有语句的比例。
说明

Fact — 官方简述译文：设置抽取整笔事务并记录其中所有语句的比例。

身份

类型 值real
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / When to Log
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 799e220346f1 — Log all statements from a sample of transactions
提交日期 2019-04-03
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 0 — 0

机制详解

log_transaction_sample_rate：设置抽取整笔事务并记录其中所有语句的比例。被抽中的事务会记录其中每条语句，能够保留事务上下文，但长事务或高频事务可能造成日志突发。

log_transaction_sample_rate 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变输出的诊断数据而非查询语义，但日志量、敏感内容、log_line_prefix、目标、收集器吞吐与保留策略共同决定运维成本和价值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 围绕明确的可观测性问题和实测日志容量预算调节 log_transaction_sample_rate；优先使用选择性阈值、抽样或角色级覆盖，而非无差别采集。
OLAP 分析作业可以需要更丰富的 log_transaction_sample_rate 遥测，但应把长语句、大绑定值与集中完成造成的日志突发计入管线容量。
小规格 让 log_transaction_sample_rate 保持有用且有界：提高详细度或频率前，先验证磁盘、收集器、保留与脱敏能力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 log_transaction_sample_rate，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 增加日志内容却未预算收集器吞吐、存储、保留与下游查询成本。
  • 记录 SQL 文本、绑定值、身份或主机数据，却没有脱敏与访问控制策略。
  • 低估高频事务被抽中后每条语句都记录所造成的突发。

关联参数

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate

参考资料

11.40 - log_truncate_on_rotation

log_truncate_on_rotation 是 PostgreSQL 中用于轮转时截断同名的既有日志文件的参数。
说明

Fact — 官方简述译文：轮转时截断同名的既有日志文件。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_truncate_on_rotation：轮转时截断同名的既有日志文件。只有按时间轮转复用既有文件名时才截断；按大小轮转等其他原因不采用同一覆盖规则。

log_truncate_on_rotation 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有按时间轮转有意复用文件名，且上一文件已经可靠转运或本就应被替换时，才启用 log_truncate_on_rotation；唯一时间戳名称应保持 off。
OLAP 分析日志应在重复名称被截断前确认长时间摄取已经完成；无法保证完成时使用唯一名称。
小规格 短循环可限制磁盘使用，但截断不是保留管理。监控转运与备份，避免下一次时间轮转删除唯一副本。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断：截断闭合星期文件名循环，使复用的每日名称替换上周文件，而不是无限追加。

常见坑

  • 编辑 log_truncate_on_rotation 后没有重新加载配置，也没有核对有效值与后续行为。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 期待所有轮转路径都截断文件；它只与按时间轮转时复用既有文件名相关。

关联参数

logging_collector · log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

参考资料

11.41 - logging_collector

logging_collector 是 PostgreSQL 中用于启动子进程，将 stderr、csvlog 和/或 jsonlog 捕获到日志文件的参数。
说明

Fact — 官方简述译文：启动子进程，将 stderr、csvlog 和/或 jsonlog 捕获到日志文件。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

logging_collector：启动子进程，将 stderr、csvlog 和/或 jsonlog 捕获到日志文件。收集器通过管道排空服务器 stderr 并写入所选文件格式；其设计目标是不丢消息，因此极端背压可能阻塞输出者。

logging_collector 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

实际路径由 log_destination、logging_collector 或 syslog/eventlog、文件命名与权限、轮转触发条件，以及外部转运或保留共同构成。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 需要 csvlog/jsonlog 或收集器管理的 stderr 文件时启用 logging_collector，并压测管道吞吐、轮转、磁盘写满、转运与重启。它属于 POSTMASTER 参数，需要受控重启。
OLAP 分析负载可能在查询结束时产生大规模日志突发；按该突发为收集器与目标 I/O 定容，并验证数据库进程不会因收集器背压停顿。
小规格 只保留必要格式并设置有界保留。小节点同样需要磁盘告警，因为收集器以不丢消息为目标，目标缓慢或写满时可能向数据库进程传递背压。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断：配置的 csvlog 文件管线需要收集器，它为所有模板提供受管本地日志文件。

常见坑

  • 期待重新加载或 SET 激活 logging_collector，而它实际需要受控重启服务器。
  • 组合互不兼容的目标、收集器、文件名与轮转假设，最终丢失或覆盖日志。
  • 未监控写满或不可写的日志目标；不同路径下它可能阻塞日志甚至数据库活动。
  • 在未启用收集器时配置文件型目标，或启用收集器却没有磁盘与保留计划。

关联参数

log_destination · log_directory · log_filename · log_rotation_age · log_rotation_size

参考资料

11.42 - silent_mode

silent_mode：让服务器以静默模式运行。实测在档范围为 PG9.0–9.1；最后在档的 PG9.1 启动默认值为 off，context 为 postmaster。它在 PG9.2 被移除。
说明

Fact — 官方简述译文：让服务器以静默模式运行。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.1
移除版本 PG9.2
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.1 off — off

机制详解

silent_mode：让服务器以静默模式运行。该值在服务器启动时固定，修改后必须安排受控重启。 本站在 PG9.0–9.1 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

静默模式是早期后台运行服务器时处理终端输出的便利开关。PG9.2 移除了它；现代环境应由服务管理器以及 logging_collector、log_destination、log_directory 明确管理进程和日志。

应与 logging_collector、log_destination、log_directory、log_filename 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.1 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.1 未修改；OLAP: PG9.0–9.1 未修改；CRIT: PG9.0–9.1 未修改；TINY: PG9.0–9.1 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 silent_mode 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 postmaster context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

logging_collector · log_destination · log_directory · log_filename

参考资料

11.43 - syslog_facility

syslog_facility 定义启用 syslog 时使用的 facility。
说明

Fact — 官方简述译文：设置启用 syslog 时使用的 facility。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值local0, local1, local2, local3, local4, local5, local6, local7
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值local0
local0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 local0 — local0

机制详解

syslog_facility：设置启用 syslog 时使用的 facility。只有 log_destination 包含 syslog 时它才选择路由 facility；系统日志器再把 facility 映射到存储或转发规则。

syslog_facility 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

只有 log_destination 包含 syslog 时它才生效；随后 facility、ident、序号、拆分、主机守护进程与远端接收器共同定义记录交付。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 syslog_facility 匹配接收端 syslog 守护进程的路由、分帧、去重与消息大小契约，并用真实收集器验证故障转移与背压。
OLAP 以分析日志突发和多行计划测试 syslog_facility，避免拆分或接收端限制破坏记录边界。
小规格 为 syslog_facility 沿用主机既有 syslog 约定；除非有明确目的与大小限制，否则不要并行保留本地重复文件。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 syslog_facility 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改 PostgreSQL 分帧或标识，却未把主机守护进程与远端接收器作为整体测试。
  • 默认假设 syslog 会保留无限消息长度、多行边界、顺序或重复记录。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 syslog_facility。

关联参数

log_destination · syslog_ident · syslog_sequence_numbers · syslog_split_messages · logging_collector

参考资料

11.44 - syslog_ident

syslog_ident 定义在 syslog 中标识 PostgreSQL 消息的程序名。
说明

Fact — 官方简述译文：设置在 syslog 中标识 PostgreSQL 消息的程序名。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值postgres
postgres

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 postgres — postgres

机制详解

syslog_ident：设置在 syslog 中标识 PostgreSQL 消息的程序名。ident 在 syslog 中标记 PostgreSQL 记录，并可结合 facility 或主机元数据区分集群。

syslog_ident 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

只有 log_destination 包含 syslog 时它才生效；随后 facility、ident、序号、拆分、主机守护进程与远端接收器共同定义记录交付。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 syslog_ident 匹配接收端 syslog 守护进程的路由、分帧、去重与消息大小契约，并用真实收集器验证故障转移与背压。
OLAP 以分析日志突发和多行计划测试 syslog_ident，避免拆分或接收端限制破坏记录边界。
小规格 为 syslog_ident 沿用主机既有 syslog 约定；除非有明确目的与大小限制，否则不要并行保留本地重复文件。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 syslog_ident 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改 PostgreSQL 分帧或标识，却未把主机守护进程与远端接收器作为整体测试。
  • 默认假设 syslog 会保留无限消息长度、多行边界、顺序或重复记录。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 syslog_ident。

关联参数

log_destination · syslog_facility · syslog_sequence_numbers · syslog_split_messages · logging_collector

参考资料

11.45 - syslog_sequence_numbers

syslog_sequence_numbers 是 PostgreSQL 中用于为 syslog 消息添加序号以避免重复消息被抑制的参数。
说明

Fact — 官方简述译文：为 syslog 消息添加序号以避免重复消息被抑制。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 f4c454e9ba52 — Add syslog_sequence_numbers parameter
提交日期 2016-02-26
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 on — on

机制详解

syslog_sequence_numbers：为 syslog 消息添加序号以避免重复消息被抑制。单调递增序号前缀可防止某些 syslog 实现合并重复消息，也有助于发现缺口。

syslog_sequence_numbers 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

只有 log_destination 包含 syslog 时它才生效；随后 facility、ident、序号、拆分、主机守护进程与远端接收器共同定义记录交付。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 syslog_sequence_numbers 匹配接收端 syslog 守护进程的路由、分帧、去重与消息大小契约，并用真实收集器验证故障转移与背压。
OLAP 以分析日志突发和多行计划测试 syslog_sequence_numbers，避免拆分或接收端限制破坏记录边界。
小规格 为 syslog_sequence_numbers 沿用主机既有 syslog 约定；除非有明确目的与大小限制，否则不要并行保留本地重复文件。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 未修改；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 未修改；TINY: PG9.6–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 syslog_sequence_numbers 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改 PostgreSQL 分帧或标识，却未把主机守护进程与远端接收器作为整体测试。
  • 默认假设 syslog 会保留无限消息长度、多行边界、顺序或重复记录。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 syslog_sequence_numbers。

关联参数

log_destination · syslog_facility · syslog_ident · syslog_split_messages · logging_collector

参考资料

11.46 - syslog_split_messages

syslog_split_messages 是 PostgreSQL 中用于按行并按 1024 字节限制拆分发送给 syslog 的消息的参数。
说明

Fact — 官方简述译文：按行并按 1024 字节限制拆分发送给 syslog 的消息。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Where to Log
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 fc201dfd9505 — Add syslog_split_messages parameter
提交日期 2016-03-15
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 on — on

机制详解

syslog_split_messages：按行并按 1024 字节限制拆分发送给 syslog 的消息。启用后 PostgreSQL 按行及传统 1024 字节限制拆分；关闭后则依赖接收端处理多行或长载荷。

syslog_split_messages 属于 SIGHUP 上下文：重新加载配置即可在不重启的情况下激活服务器新值，后续读取它的操作使用刷新值。

只有 log_destination 包含 syslog 时它才生效；随后 facility、ident、序号、拆分、主机守护进程与远端接收器共同定义记录交付。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 syslog_split_messages 匹配接收端 syslog 守护进程的路由、分帧、去重与消息大小契约，并用真实收集器验证故障转移与背压。
OLAP 以分析日志突发和多行计划测试 syslog_split_messages，避免拆分或接收端限制破坏记录边界。
小规格 为 syslog_split_messages 沿用主机既有 syslog 约定；除非有明确目的与大小限制，否则不要并行保留本地重复文件。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 未修改；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 未修改；TINY: PG9.6–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 编辑 syslog_split_messages 后没有重新加载配置，也没有核对有效值与后续行为。
  • 修改 PostgreSQL 分帧或标识，却未把主机守护进程与远端接收器作为整体测试。
  • 默认假设 syslog 会保留无限消息长度、多行边界、顺序或重复记录。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 syslog_split_messages。

关联参数

log_destination · syslog_facility · syslog_ident · syslog_sequence_numbers · logging_collector

参考资料

11.47 - update_process_title

update_process_title 是 PostgreSQL 中用于更新进程标题以显示当前 SQL 命令的参数。
说明

Fact — 官方简述译文：更新进程标题以显示当前 SQL 命令。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Reporting and Logging / Process Title
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

update_process_title：更新进程标题以显示当前 SQL 命令。操作系统支持时，PostgreSQL 会随命令变化重写每个后端的进程标题，使 ps 等工具可看到当前活动。

update_process_title 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

进程标题与 application_name、cluster_name、pg_stat_activity、log_line_prefix 相互补充，使操作系统观察能够关联数据库活动。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非分析证明确有显著开销，否则保持 update_process_title 启用或有值以便运维识别；使用与监控清单一致、稳定且不含秘密的标签。
OLAP 保留 update_process_title，使长作业能从操作系统与 PostgreSQL 视图中归属；更细粒度作业身份应使用 application_name。
小规格 不要为容量而调节 update_process_title。其可观测性价值通常高于微小开销，但应避免高基数或敏感标签。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 update_process_title，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把秘密或无界高基数数据放入运维可见的进程标签。
  • 集群、应用与进程标签不一致，无法在监控系统之间关联。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 update_process_title。

关联参数

application_name · cluster_name · log_line_prefix · log_timezone · log_hostname

参考资料

12 - 资源使用

Resource Usage 分类下的 51 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

12.1 - autovacuum_work_mem

每个 autovacuum 工作进程的内存上限；-1 表示继承 maintenance_work_mem。
说明

Fact — 官方简述译文：设置每个 autovacuum 工作进程可使用的最大内存。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值kB
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值-1
-1 kB

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 8693559cacf1 — New autovacuum_work_mem parameter
提交日期 2013-12-12
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 -1 kB -1 kB

机制详解

autovacuum_work_mem 分别作用于每个 autovacuum 工作进程。默认哨兵值 -1 表示使用 maintenance_work_mem，而不是负数内存。

该设置只影响 autovacuum 工作进程，不改变手工执行的 VACUUM。它属于 SIGHUP 上下文，因此是服务器级配置，而不是会话级调优旋钮。

多个工作进程可以并发运行，所以潜在总分配等于每进程取值乘以活跃 autovacuum worker 数。内存只是清理行为的一部分，I/O 节流、工作进程数、触发阈值与表活动同样重要。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当 maintenance_work_mem 很大时，除非并发工作进程预算明确可容纳，否则应为 autovacuum 单独设置更低上限。增加前后观察清理耗时、死元组积压与延迟。
OLAP 大表可能需要更多单 worker 内存，但调度与 worker 并发往往同样关键；应与 autovacuum_max_workers 和维护窗口一起调整。
小规格 只有 maintenance_work_mem 本身克制时才保留 -1；否则设置更小的显式值，避免多个工作进程耗尽主机内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 -1 当作负 1 kB，而不是继承哨兵。
  • 误以为该设置控制手工 VACUUM。
  • 只预算一个 worker，而多个 autovacuum worker 可以同时运行。
  • 用增加内存处理实际由 I/O 节流、触发阈值、锁或 worker 容量不足造成的问题。

关联参数

maintenance_work_mem · autovacuum_max_workers · autovacuum_worker_slots · vacuum_buffer_usage_limit · autovacuum_vacuum_cost_delay

参考资料

12.2 - backend_flush_after

backend_flush_after：设置单个后端写出多少页面后请求操作系统下刷。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 B (0 × 8kB)，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置单个后端写出多少页面后请求操作系统下刷。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值0 – 256
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值0
0 B (0 × 8kB)

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes.
提交日期 2016-02-19
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 0 8kB 0 B (0 × 8kB)

机制详解

单个后端写出超过 backend_flush_after 指定的数据量后，PostgreSQL 会请求操作系统开始把相应页缓存脏页写向存储。零会关闭这些回写提示。

这不是 fsync，也不会让事务更早持久化。目标是限制大批脏页与后续停顿；是否支持以及效果如何取决于操作系统。

阈值对每个后端分别计算，因此多个并发批量写入者都可能发起回写。它与面向其他写进程的 bgwriter_flush_after、checkpoint_flush_after 互补。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在并发下定位到对应资源瓶颈后才修改 backend_flush_after。应预算总内存、I/O、磁盘或内核容量，而不是孤立优化一个进程。
OLAP 使用代表性的批处理与扫描阶段测试 backend_flush_after，同时观察持续吞吐、落盘/回写及对其他会话的干扰，不能只看单次操作耗时。
小规格 小主机上应保守设置 backend_flush_after；证据不足时优先上游默认。照搬大服务器取值可能占用不成比例的资源。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 未修改；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 未修改；TINY: PG9.6–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 backend_flush_after 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

bgwriter_flush_after · checkpoint_flush_after · bgwriter_delay · shared_buffers · track_io_timing

参考资料

12.3 - bgwriter_delay

bgwriter_delay：设置后台写进程两轮工作之间的休眠时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 200 ms，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置后台写进程两轮工作之间的休眠时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值10 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Background Writer
上游分类
最后 boot 值 值200
200 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 200 ms 200 ms

机制详解

后台写进程完成一轮、写出选中的共享缓冲区脏页后，会休眠 bgwriter_delay。没有脏页时，无论本值如何，它都可能进入更长休眠。

较短间隔能更快响应缓冲区需求，但会更频繁唤醒进程。有些系统的有效定时精度约为 10 ms，因此更小值或非整十值实际可能向上取整。

每轮考虑的页面数由近期缓冲区分配需求、bgwriter_lru_multiplier 与 bgwriter_lru_maxpages 共同决定；checkpoint 由另一套机制处理。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应结合 bgwriter 与 checkpoint 指标调优 bgwriter_delay。目标是在不过度重复写的前提下减少后端自行写页并平滑延迟；每次只改一个维度。
OLAP 批量写入可能持续触及 bgwriter_delay 限制。应测总写入字节、checkpoint 与存储排队，不能只看前台查询延迟。
小规格 小主机通常需要保守的写平滑。激进 bgwriter_delay 会抢占前台 I/O；除非实测后端自行写页是问题，否则保留默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 10ms 不同于 boot 值 10ms
OLAP 10ms 不同于 boot 值 10ms
CRIT 10ms 不同于 boot 值 10ms
TINY 10ms 不同于 boot 值 10ms
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 10ms (dcs)；OLAP: PG9.0–19 Beta 3 = 10ms (dcs)；CRIT: PG9.0–19 Beta 3 = 10ms (dcs)；TINY: PG9.0–19 Beta 3 = 10ms (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：10ms 间隔意在让后台写进程比 PostgreSQL 启动默认更频繁地检查脏缓冲区需求。

常见坑

  • 修改 bgwriter_delay 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

bgwriter_lru_maxpages · bgwriter_lru_multiplier · bgwriter_flush_after · shared_buffers · checkpoint_completion_target

参考资料

12.4 - bgwriter_flush_after

bgwriter_flush_after：设置后台写进程写出多少页面后请求操作系统下刷。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 512 KiB (64 × 8kB)，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置后台写进程写出多少页面后请求操作系统下刷。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值8kB
原始单位
范围 值0 – 256
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Background Writer
上游分类
最后 boot 值 值64
512 KiB (64 × 8kB)

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes.
提交日期 2016-02-19
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 64 8kB 512 KiB (64 × 8kB)

机制详解

后台写进程写出超过 bgwriter_flush_after 指定的数据量后，PostgreSQL 会请求操作系统开始把这些页缓存页面写向存储。零会关闭该请求。

该请求用于平滑回写，并不是保证持久性的 fsync。它可能减少内核大批刷新造成的停顿，也可能伤害受益于 OS 脏页缓存的负载；不支持的平台上没有效果。

实测 Docker/Linux 启动值只代表 Linux 行为；PostgreSQL 文档说明 Linux 默认 512kB，其他平台默认零。后端与 checkpointer 有各自独立阈值。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应结合 bgwriter 与 checkpoint 指标调优 bgwriter_flush_after。目标是在不过度重复写的前提下减少后端自行写页并平滑延迟；每次只改一个维度。
OLAP 批量写入可能持续触及 bgwriter_flush_after 限制。应测总写入字节、checkpoint 与存储排队，不能只看前台查询延迟。
小规格 小主机通常需要保守的写平滑。激进 bgwriter_flush_after 会抢占前台 I/O；除非实测后端自行写页是问题，否则保留默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 未修改；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 未修改；TINY: PG9.6–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 bgwriter_flush_after 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

backend_flush_after · checkpoint_flush_after · bgwriter_delay · bgwriter_lru_maxpages · shared_buffers

参考资料

12.5 - bgwriter_lru_maxpages

bgwriter_lru_maxpages：设置后台写进程每轮最多刷新的 LRU 页面数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 100，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置后台写进程每轮最多刷新的 LRU 页面数。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Background Writer
上游分类
最后 boot 值 值100
100

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 100 — 100

机制详解

bgwriter_lru_maxpages 限制后台写进程每轮最多写出多少个按 LRU 选中的脏缓冲区。零会关闭这种后台写入，但不会关闭 checkpoint。

写进程尝试为预测需求准备足够的可复用清洁缓冲区，而本值限制每轮数量。若反复触顶，前台后端仍可能不得不自行写页。

预测量来自近期分配量乘以 bgwriter_lru_multiplier，各轮之间由 bgwriter_delay 间隔。提高上限可能平滑延迟，但会增加重复写放大。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应结合 bgwriter 与 checkpoint 指标调优 bgwriter_lru_maxpages。目标是在不过度重复写的前提下减少后端自行写页并平滑延迟；每次只改一个维度。
OLAP 批量写入可能持续触及 bgwriter_lru_maxpages 限制。应测总写入字节、checkpoint 与存储排队，不能只看前台查询延迟。
小规格 小主机通常需要保守的写平滑。激进 bgwriter_lru_maxpages 会抢占前台 I/O；除非实测后端自行写页是问题，否则保留默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 800 不同于 boot 值 800
OLAP 800 不同于 boot 值 800
CRIT 800 不同于 boot 值 800
TINY 800 不同于 boot 值 800
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 800 (dcs)；OLAP: PG9.0–19 Beta 3 = 800 (dcs)；CRIT: PG9.0–19 Beta 3 = 800 (dcs)；TINY: PG9.0–19 Beta 3 = 800 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：更高的每轮上限意在让频繁运行的后台写进程有足够能力准备清洁缓冲区，减少前台后端自行写页。

常见坑

  • 修改 bgwriter_lru_maxpages 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

bgwriter_lru_multiplier · bgwriter_delay · bgwriter_flush_after · shared_buffers · checkpoint_completion_target

参考资料

12.6 - bgwriter_lru_multiplier

bgwriter_lru_multiplier：设置为预计近期缓冲区需求预留清洁页面的倍数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置为预计近期缓冲区需求预留清洁页面的倍数。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Background Writer
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 2 — 2

机制详解

后台写进程对近期缓冲区分配量取平均，再乘以 bgwriter_lru_multiplier，得到应准备的可复用清洁缓冲区目标。大于 1 会为突发需求留余量。

它是预测倍数，不是直接页面数。实际写入仍受 bgwriter_lru_maxpages 限制，并按 bgwriter_delay 的轮次发生。

更多余量可减少前台后端自行写页与延迟尖峰，但 checkpoint 之间反复变脏的页面可能被多写几次，从而增加总 I/O。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只应结合 bgwriter 与 checkpoint 指标调优 bgwriter_lru_multiplier。目标是在不过度重复写的前提下减少后端自行写页并平滑延迟；每次只改一个维度。
OLAP 批量写入可能持续触及 bgwriter_lru_multiplier 限制。应测总写入字节、checkpoint 与存储排队，不能只看前台查询延迟。
小规格 小主机通常需要保守的写平滑。激进 bgwriter_lru_multiplier 会抢占前台 I/O；除非实测后端自行写页是问题，否则保留默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 5.0 不同于 boot 值 5.0
OLAP 5.0 不同于 boot 值 5.0
CRIT 5.0 不同于 boot 值 5.0
TINY 5.0 不同于 boot 值 5.0
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 5.0 (dcs)；OLAP: PG9.0–19 Beta 3 = 5.0 (dcs)；CRIT: PG9.0–19 Beta 3 = 5.0 (dcs)；TINY: PG9.0–19 Beta 3 = 5.0 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：更大的预测余量意在吸收缓冲区需求突发，同时接受可能增加的后台重复写。

常见坑

  • 修改 bgwriter_lru_multiplier 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

bgwriter_lru_maxpages · bgwriter_delay · bgwriter_flush_after · shared_buffers · checkpoint_completion_target

参考资料

12.7 - commit_timestamp_buffers

commit_timestamp_buffers：设置提交时间戳缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 B (0 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置提交时间戳缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值0 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值0
0 B (0 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 0 8kB 0 B (0 × 8kB)

机制详解

commit_timestamp_buffers 在启动时为 pg_commit_ts 页面分配专用共享缓冲池；启用提交时间戳跟踪时会使用这块 SLRU 区域。

配置为零表示自动计算，并非零内存：PostgreSQL 按 shared_buffers/512 推导，再限制在 16 到 1024 个块之间，并在服务器启动时实际分配。

缓存可减少 pg_commit_ts 读取，但不会开启提交时间戳收集；功能开关是另一个参数 track_commit_timestamp。提高本值会消耗真实共享内存。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 commit_timestamp_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 commit_timestamp_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 commit_timestamp_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 commit_timestamp_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

track_commit_timestamp · shared_buffers · transaction_buffers · subtransaction_buffers

参考资料

12.8 - dynamic_shared_memory_type

dynamic_shared_memory_type：选择动态共享内存实现。实测在档范围为 PG9.4–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 posix，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：选择动态共享内存实现。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值posix, sysv, mmap
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值posix
posix

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 0ac5e5a7e152 — Allow dynamic allocation of shared memory segments.
提交日期 2013-10-09
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 posix — posix

机制详解

dynamic_shared_memory_type 选择 PostgreSQL 创建动态共享内存段的方法，供并行查询与扩展使用；受支持实现包括 POSIX、System V、Windows 和文件后端 mmap。

可用枚举值与启动默认值依平台而定。Docker/Linux 目录实测为 posix，这不代表 Windows 或缺少 POSIX 共享内存的系统也相同。

mmap 实现把映射文件放在 pg_dynshmem，一般不推荐，因为脏页可能被反复写盘。min_dynamic_shared_memory 可在主共享区域预分配一部分并行查询内存。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保留平台第一个受支持默认实现；实测 Linux 镜像通常是 posix。只有解决 API 可用性或诊断需求时才修改，并在目标 OS 重启测试并行查询与扩展 worker。
OLAP 并行查询会大量使用动态段，但应按 OS 支持与分配行为选择实现，不能只看扫描吞吐。普通磁盘上避免 file-backed mmap，因为反复回写会增加 I/O；RAM disk 只是特殊诊断场景。
小规格 保留平台默认。sysv 可能需要内核调优，file-backed mmap 会把内存流量变成磁盘 I/O；两者都不是免费降低内存的方法。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 Linux-Docker 的 posix boot 值外推到不支持 POSIX 共享内存的平台。
  • 在普通存储上使用 file-backed mmap，造成脏页反复回写。
  • 选择 sysv 前没有检查 System V 段限制。
  • 把动态段与 shared_memory_type 选择的主共享区域混淆。
  • 修改启动设置后没有测试会分配 DSM 的并行查询与扩展。

关联参数

shared_memory_type · min_dynamic_shared_memory · max_parallel_workers · max_worker_processes · huge_pages

参考资料

12.9 - effective_io_concurrency

告诉 PostgreSQL 单个会话应能并发发起多少个存储 I/O。它影响异步读取，并在支持的平台上影响预取距离；它不是全局 I/O 上限。
说明

Fact — 官方简述译文：设置单个会话可高效利用的存储并发度。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值16
16

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–17 1 — 1
PG18–19 Beta 3 16 — 16

机制详解

effective_io_concurrency 告诉单个会话应尝试利用多少存储并发；它不是集群级队列上限。同名 tablespace 选项可针对该存储上的数据覆盖会话设置。

PG10–17 中它主要控制受支持路径与平台的预取距离。Linux-Docker 实测 boot 值为 1，但缺少有效 posix_fadvise、因而不受支持的平台上游默认是 0；任何历史默认值表述都必须带上该平台条件。

PostgreSQL 18 将该参数接入核心异步 I/O，boot 默认改为 16，并允许用 0 关闭由该目标控制的异步请求。io_max_concurrency 仍是独立的单进程执行上限，combine 参数则控制每次请求字节数。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从保守值开始并在并发下测量读取延迟。短小点查通常不如位图扫描或扫描型负载受益，而高连接数下过高的每会话值会放大队列深度。
OLAP 分析扫描与位图堆扫描更可能从高值受益。尤其在网络存储或高 IOPS 设备上，应同时测试持续吞吐与尾延迟。
小规格 除非测量确认存在 I/O 停顿，优先采用 PG18 默认或适中值。小主机不会仅因磁盘标注为 SSD 就自然适合 200。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 200 不同于 boot 值 200
OLAP 200 不同于 boot 值 200
CRIT 200 不同于 boot 值 200
TINY 200 不同于 boot 值 200
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 200 (dcs)；OLAP: PG9.0–19 Beta 3 = 200 (dcs)；CRIT: PG9.0–19 Beta 3 = 200 (dcs)；TINY: PG9.0–19 Beta 3 = 200 (dcs)。 建议（待人工复核）——编辑推断：Pigsty 的 SSD 分支假设较深的会话级读取并发与预取有益；该假设必须在设备层验证。

常见坑

  • 把该会话级目标误当成集群总上限；大量会话会放大未完成 I/O。
  • 把 1 称为 PG10–17 无条件上游默认，忽略不支持平台默认 0。
  • 把 PG18 AIO 行为套到主要用于预取建议的旧版本。
  • 混合存储 tablespace 仍使用单一全局值，不考虑 tablespace 覆盖。
  • 持续提高目标，直到设备排队拖慢所有会话。

关联参数

maintenance_io_concurrency · io_method · io_max_concurrency · io_combine_limit · random_page_cost · effective_cache_size

参考资料

12.10 - file_copy_method

file_copy_method：选择数据库文件的复制方法。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 copy，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：选择数据库文件的复制方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值copy, clone
非枚举类型记为 —
分类 值Resource Usage / Disk
上游分类
最后 boot 值 值copy
copy

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 f78ca6f3ebbb — Introduce file_copy_method setting.
提交日期 2025-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 copy — copy

机制详解

file_copy_method 为 CREATE DATABASE … STRATEGY=FILE_COPY 与 ALTER DATABASE … SET TABLESPACE 选择 COPY 或 CLONE。它不会改变 SQL COPY 或普通文件读取。

CLONE 在 Linux/FreeBSD 使用 copy_file_range()，在 macOS 使用 copyfile，使支持的文件系统可以共享数据块或下推操作。可用性与实际优化取决于操作系统和文件系统；选择 CLONE 并不能证明数据块已共享。

写时复制可让初始操作很快，但后续写入仍会分配私有块，克隆也共享故障域。备份、配额与空闲空间监控必须理解文件系统语义。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 以 COPY 作为兼容基线。只有在完全相同的内核与文件系统上测试 CREATE DATABASE … STRATEGY=FILE_COPY、ALTER DATABASE … SET TABLESPACE，并验证备份、配额与空闲空间监控后才选 CLONE。
OLAP 负载类型不决定方法；clone 支持与写时复制行为才决定。CLONE 可缩短大型数据库复制，但标准化前必须同时测试初始操作与后续写放大。
小规格 除非明确了解文件系统 clone 语义且运维工具能识别共享 extent，否则优先 COPY。快速初始克隆仍可能在小卷上造成后续空间压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP clone 不同于 boot 值 clone
OLAP clone 不同于 boot 值 clone
CRIT clone 不同于 boot 值 clone
TINY clone 不同于 boot 值 clone
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 = clone (dcs)；OLAP: PG18–19 Beta 3 = clone (dcs)；CRIT: PG18–19 Beta 3 = clone (dcs)；TINY: PG18–19 Beta 3 = clone (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：模板注释明确以写时复制文件系统上的近即时数据库克隆为目标；支持情况与空闲空间语义仍需部署验证。

常见坑

  • 认为 CLONE 保证写时复制共享数据块；实际优化由内核与文件系统决定。
  • 期待该参数影响 SQL COPY 或普通关系读取。
  • 忽略快速克隆后续的私有块分配与空闲空间压力。
  • 备份、配额和文件系统工具尚不能识别共享 extent 时就使用 CLONE。

关联参数

file_extend_method · data_directory · temp_tablespaces · shared_buffers

参考资料

12.11 - file_extend_method

file_extend_method：选择扩展数据文件的方法。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 posix_fallocate，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：选择扩展数据文件的方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值posix_fallocate, write_zeros
非枚举类型记为 —
分类 值Resource Usage / Disk
上游分类
最后 boot 值 值posix_fallocate
posix_fallocate

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 e37b59802846 — Add file_extend_method=posix_fallocate,write_zeros.
提交日期 2025-05-31
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 posix_fallocate — posix_fallocate

机制详解

file_extend_method 选择 PostgreSQL 批量扩展关系文件的方法：可用时使用 posix_fallocate，否则显式写零；扩展不超过八个块时仍使用写零。

第一个受支持方法依平台而定。posix_fallocate 可在不逐块写入时预留空间，但文件系统不支持时会静默回退；当前 BTRFS 上它可能关闭该文件的压缩。

它影响空间分配方式与批量写延迟，不改变 WAL 持久性。空间预留、稀疏文件、压缩与写时复制语义都依文件系统而异。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非操作系统支持与受控基准证明需要修改，否则让 file_extend_method 保持探测/默认值；必须在完全相同的内核与文件系统上验证启动和恢复。
OLAP 大分配或批量 I/O 可能放大 file_extend_method 的影响，但平台能力是第一道门槛。应在生产等价存储上测试，并包含失败与回退行为。
小规格 小型或异构机器群上，除非解决已验证的平台问题，否则避免非默认 file_extend_method；可移植性与可靠启动通常比推测收益更重要。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 file_extend_method 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

file_copy_method · backend_flush_after · checkpoint_flush_after · wal_sync_method

参考资料

12.12 - hash_mem_multiplier

让基于哈希的执行器操作可使用高于 work_mem 基础值的内存倍数。
说明

Fact — 官方简述译文：以 work_mem 的倍数确定哈希表内存上限。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 1000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 78530c8e7a5a — Add hash_mem_multiplier GUC.
提交日期 2020-07-29
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–14 1 — 1
PG15–19 Beta 3 2 — 2

机制详解

哈希表内存上限等于 work_mem 乘以 hash_mem_multiplier。它作用于哈希连接、哈希聚合、Memoize 节点及其他哈希执行工作，但不会扩大排序操作的上限。

在 PG9.0–19 Beta 3 实测清单中，该参数首次出现于 PostgreSQL 13。其启动默认值在 PostgreSQL 13–14 为 1.0，从 PostgreSQL 15 起为 2.0。

一条查询可以包含多个哈希操作，并行工作进程也可能分别执行自己的操作，因此这个乘积仍是单操作上限，而不是整条查询的总内存上限。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保留上游默认值，或仅在确认哈希操作持续落盘后小幅提高。必须结合 work_mem 与峰值活跃计划评估乘积，不能孤立调倍数。
OLAP 当内存确实充足时，较高取值可帮助大型哈希连接与聚合。应在受控并发上限下增加，并比较批次数、落盘量与端到端耗时。
小规格 保持接近默认值。很高的倍数会把看似克制的 work_mem 变成每个哈希操作数百 MiB。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 8.0 不同于 boot 值 8.0
OLAP 8.0 不同于 boot 值 8.0
CRIT 8.0 不同于 boot 值 8.0
TINY 8.0 不同于 boot 值 8.0
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 = 8.0 (dcs)；OLAP: PG13–19 Beta 3 = 8.0 (dcs)；CRIT: PG13–19 Beta 3 = 8.0 (dcs)；TINY: PG13–19 Beta 3 = 8.0 (dcs)。 建议（待人工复核）——编辑推断：Pigsty 先约束基础 work_mem，再给内存敏感的哈希操作更大空间；最终单操作乘积及并行并发风险必须人工复核。

常见坑

  • 把数值当绝对内存大小，而不是 work_mem 的倍数。
  • 忘记 PostgreSQL 13 之前没有该参数，且 PostgreSQL 15 修改了上游默认值。
  • 期待它改善排序；排序仍受 work_mem 控制。
  • 一条查询存在多个哈希节点或并行工作进程时，却只计算一次乘数。

关联参数

work_mem · temp_file_limit · enable_hashjoin · enable_hashagg · max_parallel_workers_per_gather

参考资料

12.13 - huge_page_size

huge_page_size：设置 PostgreSQL 请求的显式大页大小。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 B，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 PostgreSQL 请求的显式大页大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值kB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值0
0 B

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 d2bddc2500fb — Add huge_page_size setting for use on Linux.
提交日期 2020-07-17
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 0 kB 0 B

机制详解

huge_page_size 在启用 huge_pages 时选择 PostgreSQL 主共享内存区请求的显式大页尺寸。零表示使用操作系统默认大页尺寸。

这是启动时的分配粒度选择，不是内存总量。可用非零尺寸取决于架构与内核，PostgreSQL 目前仅在 Linux 支持选择非默认尺寸。

请求尺寸必须与操作系统预留的大页池及共享内存分配匹配。它只影响主共享区域，不影响 work_mem 等普通后端分配。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 0，让 PostgreSQL 使用系统默认显式大页尺寸。只有在 Linux 上预留匹配的大页池，并按目标共享内存验证启动与 huge_pages_status 后，才选择非零尺寸。
OLAP 很大的主共享内存区可能从页表节省中获益，但合适尺寸取决于架构、内核池、碎片与重启运维，而不是批量 I/O 吞吐。应在完全相同主机上测试，并为后端与 OS 保留普通内存。
小规格 保持 0。小型共享内存分配通常不足以抵消非默认尺寸带来的内核预留与启动失败风险。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 0 读成零字节大页，而不是“使用系统默认大页尺寸”。
  • 在非 Linux 平台选择非零尺寸；当前非默认尺寸只受 Linux 支持。
  • 请求内核尚未预留的页面尺寸，并在 huge_pages=on 时导致启动失败。
  • 把主共享内存的显式大页与透明大页或后端私有内存混为一谈。

关联参数

huge_pages · huge_pages_status · shared_buffers · shared_memory_type · min_dynamic_shared_memory

参考资料

12.14 - huge_pages

控制 PostgreSQL 在受支持操作系统上为主共享内存区域使用显式大页。
说明

Fact — 官方简述译文：控制在 Linux 或 Windows 上使用大页。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值off, on, try
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值try
try

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 f8ce16d0d264 — Rename huge_tlb_pages to huge_pages, and improve docs.
提交日期 2014-03-03
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 try — try

机制详解

huge_pages 只影响主共享内存区域，并仅在服务器启动时评估。try 会申请大页，失败后回退普通页；on 会让申请失败直接阻止启动；off 则不发起申请。

显式大页可以减小页表并减少内存管理消耗的 CPU 时间，对较大的连续共享内存尤其有意义。在 Linux 上，PostgreSQL 要求 shared_memory_type=mmap 且操作系统预留足够大页；huge_pages_status 显示实际结果。

显式 HugeTLB 大页不等于 Linux 透明大页（THP）。PostgreSQL 文档在说明显式大页可能有益的同时，仍指出某些 Linux 版本上的 THP 可能导致性能下降。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 验证操作系统预留和 huge_pages_status 期间使用 try。只有在大页申请失败本就应该阻止启动、且跨重启预留可靠时，才改为 on。
OLAP 较大的共享内存可能受益更多，但应先计算所需页数，并为后端、查询工作区与操作系统留出内存；不要把大页视作必然提高吞吐量。
小规格 保留 try，或在大页预留的运维复杂度高于收益时使用 off。没有完整内存预算时，不要在小主机上预留很大比例。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP try 等于 boot 值 try
OLAP try 等于 boot 值 try
CRIT try 等于 boot 值 try
TINY try 等于 boot 值 try
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 = try (dcs)；OLAP: PG9.4–19 Beta 3 = try (dcs)；CRIT: PG9.4–19 Beta 3 = try (dcs)；TINY: PG9.4–19 Beta 3 = try (dcs)。 建议（待人工复核）——编辑推断：这样在节点已预留大页时可机会性使用，在大页不可用时仍保证启动；操作系统层的大页预留策略需要另行复核。

常见坑

  • 把显式大页与透明大页 THP 混为一谈。
  • 没有预留足够大页就设置 on，导致 PostgreSQL 无法启动。
  • 误以为它覆盖 work_mem 或其他普通进程内存；它针对主共享内存区域。
  • 只检查配置值，却不检查运行时 huge_pages_status。

关联参数

huge_page_size · huge_pages_status · shared_buffers · shared_memory_type · min_dynamic_shared_memory

参考资料

12.15 - io_combine_limit

io_combine_limit：限制合并读写操作的最大数据量。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 128 KiB (16 × 8kB)，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：限制合并读写操作的最大数据量。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值1 – 128
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值16
128 KiB (16 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 210622c60e1a — Provide vectored variant of ReadBuffer().
提交日期 2024-04-03
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

机制详解

io_combine_limit 限制把相邻且符合条件的操作合并后形成的单次 I/O 请求字节数。它控制每次请求大小，不控制可同时执行的请求数量。

PostgreSQL 17 中它是独立的用户可设置合并尺寸上限，Linux-Docker 实测 boot 值为 128kB；该版本不存在 io_max_combine_limit。PostgreSQL 18 中，有效尺寸是 io_combine_limit 与新启动参数 io_max_combine_limit 的较小者。

没有足够相邻工作时，实际请求可以更小；操作系统与 BLCKSZ 还会限制可行最大值。其 user 上下文允许按会话或事务修改；改变它不会改变 io_max_concurrency 或 worker 数。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在基准证明瓶颈确实来自合并请求尺寸而非队列深度前，保留对应版本默认值。PG18 必须同时核对 io_combine_limit 与 io_max_combine_limit，并在真实并发下测量尾延迟。
OLAP 更大的合并请求可在符合条件的顺序工作中减少系统调用，但也可能增加单次服务时间并降低公平性。应比较吞吐、延迟与实际请求尺寸，不能只按设备队列深度推导取值。
小规格 除非相邻 I/O 的实测结果证明其他尺寸更好，否则保留 128kB。PG18 中只把 io_combine_limit 提高到 clamp 之上不会生效；PG17 则没有独立 clamp GUC。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 PG18 的 io_max_combine_limit clamp 套到不存在该 GUC 的 PostgreSQL 17。
  • 把字节尺寸上限误当成 I/O 并发度或队列深度。
  • 把 io_combine_limit 提高到 PG18 服务器 clamp 之上，并期待请求继续变大。
  • 认为每个符合条件的操作都一定达到配置尺寸，即使没有足够相邻 I/O。

关联参数

io_max_combine_limit · io_max_concurrency · io_method · effective_io_concurrency · maintenance_io_concurrency

参考资料

12.16 - io_max_combine_limit

io_max_combine_limit：设置钳制 io_combine_limit 的服务器级上限。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 128 KiB (16 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置钳制 io_combine_limit 的服务器级上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值1 – 128
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值16
128 KiB (16 × 8kB)

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 10f664684751 — Introduce io_max_combine_limit.
提交日期 2025-03-19
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

机制详解

io_max_combine_limit 是服务器启动时确定的上限，会静默钳制用户可设置的 io_combine_limit，用于阻止请求尺寸超过服务器策略。

它控制合并操作的字节数，不控制队列深度。可行最大值取决于操作系统与 BLCKSZ，通常 Unix 为 1MB、Windows 为 128kB。

只把 io_combine_limit 提高到本值之上不会生效，必须同时提高这个启动参数。即便如此，没有相邻工作时合并请求仍可能更小。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非实测证明更大的合并请求能改善符合条件 I/O 且不伤害延迟，否则保留 PG18 服务器 clamp 128kB。io_combine_limit 仍较低时只提高本值没有变化，修改后还必须重启。
OLAP 更大的 clamp 只允许用户 combine 上限变大；它不会创造相邻 I/O，也不会增加并发。应有意设置两个参数，并测试实际请求尺寸、顺序吞吐与混合负载公平性。
小规格 小型或混合用途存储保留 128kB。不能用提高启动级全局尺寸上限来修复队列深度问题；后者属于并发控制。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把服务器字节尺寸 clamp 误当成 I/O 并发上限。
  • io_combine_limit 仍较低时提高 io_max_combine_limit，并期待行为改变。
  • 没有相邻且符合条件的操作时仍期待更大的合并请求。
  • 忽略操作系统与 BLCKSZ 限制，尤其是 Windows 通常更小的最大值。
  • 忘记修改后必须重启服务器。

关联参数

io_combine_limit · io_max_concurrency · io_method · shared_buffers

参考资料

12.17 - io_max_concurrency

io_max_concurrency：设置单个进程可同时执行的最大 I/O 数。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 -1，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置单个进程可同时执行的最大 I/O 数。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值-1 – 1024
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值-1
-1

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 02844012b304 — aio: Basic subsystem initialization
提交日期 2025-03-17
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 -1 — -1

机制详解

io_max_concurrency 是 PostgreSQL 18 启动时确定的单进程同时执行 I/O 数量上限。它按进程生效，不预留容量，也不是集群总上限。

默认 -1 表示让 PostgreSQL 根据 shared_buffers 与已配置进程上限推导，且不超过 64。许多后端与 worker 都可能达到自己的上限，因此全集群潜在未完成 I/O 可以大得多。

effective_io_concurrency 与 maintenance_io_concurrency 是该上限之下的工作目标；io_method 选择执行机制，combine 参数控制每次请求字节数。修改 io_max_concurrency 必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在实测证明自动单进程上限限制了符合条件的 AIO 前，保留 -1。若显式设置，应把取值乘以并发活动进程数，并在重启后测试设备排队与尾延迟。
OLAP 只有单个扫描或维护进程无法喂满高 IOPS 存储、且目标并发参数已经合适时，才提高单进程上限。比较未完成操作数、吞吐与延迟；该参数不会改变请求尺寸。
小规格 优先使用 -1。显式高上限会乘以并发进程数，即使单个进程没有越界，也可能压垮小型设备。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把单进程上限误当成集群总 I/O 限制。
  • 把 -1 理解成无限，而不是最高 64 的自动计算。
  • 把上限称为已预留容量；它只允许并发，不预分配 I/O 名额。
  • 把操作数量与 io_combine_limit 的每次请求字节数混淆。
  • 修改后没有重启，或没有把暴露量乘以进程数。

关联参数

io_method · io_workers · effective_io_concurrency · maintenance_io_concurrency · io_combine_limit · max_connections

参考资料

12.18 - io_max_workers

io_max_workers：设置 io_method=worker 时 I/O worker 进程的最大数量。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 io_method=worker 时 I/O worker 进程的最大数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值1 – 32
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值8
8

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
提交日期 2026-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 8 — 8

机制详解

io_max_workers：设置 io_method=worker 时 I/O worker 进程的最大数量。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这组参数只管理 io_method=worker 时使用的弹性后台 worker 池。io_min_workers 保留热容量，io_max_workers 限制池上限，io_worker_launch_interval 抑制短暂突发造成的过度启动，io_worker_idle_timeout 回收空闲进程；它们不会提高单个后端独立的 io_max_concurrency 上限。

应与 io_min_workers、io_worker_idle_timeout、io_worker_launch_interval、io_method 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 必须在生产存储栈与真实并发下测试，优化尾延迟和队列深度，而不只看平均吞吐，并为 WAL、检查点与前台读取保留容量。
OLAP 使用有代表性的扫描、预取与落盘阶段；只有吞吐继续提升且 CPU、内存与存储没有不可接受的饱和时，才增加并发或 worker 容量。
小规格 优先采用 auto 或上游 worker 上限，并按场景使用 pg_test_timing 或 I/O 统计验证；小节点上的大进程池可能只增加上下文切换。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 io_max_workers 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

io_min_workers · io_worker_idle_timeout · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit

参考资料

12.19 - io_method

io_method：选择 PostgreSQL 执行异步 I/O 操作的方法。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 worker，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：选择 PostgreSQL 执行异步 I/O 操作的方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值sync, worker, io_uring
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值worker
worker

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 02844012b304 — aio: Basic subsystem initialization
提交日期 2025-03-17
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 worker — worker

机制详解

worker 把符合条件的 I/O 交给专用 I/O worker 进程；io_uring 使用 Linux io_uring，要求构建时包含 liburing 支持；sync 则同步执行原本可异步的操作。上游默认是 worker。

PG18 AIO 子系统允许后端排队多个读取请求，可改善顺序扫描、位图堆扫描、vacuum 等受支持操作；它不会让 PostgreSQL 的所有 I/O 路径都自动异步化。

io_workers 仅在选择 worker 时有效。io_max_concurrency 与 I/O combine limit 控制不同维度的队列深度和请求大小，因此方法选择必须结合这些参数及完整存储栈评估。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 worker 作为兼容性基线。只有在确认构建与内核支持后才测试 io_uring，并以代表性并发延迟改善且存储队列稳定作为保留依据。
OLAP 顺序扫描和位图访问较多的分析负载是 AIO 的有力候选；应在真实扫描并发下比较 worker 与 io_uring，而不是只看单次冷扫描。
小规格 worker 是安全默认值；当 worker 开销或平台限制成为问题时，sync 可作为诊断回退。不要让过多 io_workers 占用稀缺进程资源。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP worker 等于 boot 值 {{ pg_effective_io_method }}
OLAP worker 等于 boot 值 {{ pg_effective_io_method }}
CRIT worker 等于 boot 值 {{ pg_effective_io_method }}
TINY worker 等于 boot 值 {{ pg_effective_io_method }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 = worker (dcs)；OLAP: PG18–19 Beta 3 = worker (dcs)；CRIT: PG18–19 Beta 3 = worker (dcs)；TINY: PG18–19 Beta 3 = worker (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：Pigsty 选择可移植的 PG18 AIO 基线，并把 io_uring 保留为运维人员的显式选择。

常见坑

  • PostgreSQL 18 之前不存在该参数。
  • 修改后必须重启服务器。
  • io_uring 需要操作系统和构建支持，仅写入枚举值不能创造这些能力。
  • 除非 io_method=worker，否则 io_workers 不生效。
  • AIO 只改善符合条件的路径，无法弥补过载或配置不当的存储层。

关联参数

io_workers · io_max_concurrency · io_combine_limit · io_max_combine_limit · effective_io_concurrency · maintenance_io_concurrency

参考资料

12.20 - io_min_workers

io_min_workers：设置 io_method=worker 时 I/O worker 进程的最小数量。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 io_method=worker 时 I/O worker 进程的最小数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值1 – 32
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
提交日期 2026-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 2 — 2

机制详解

io_min_workers：设置 io_method=worker 时 I/O worker 进程的最小数量。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这组参数只管理 io_method=worker 时使用的弹性后台 worker 池。io_min_workers 保留热容量，io_max_workers 限制池上限，io_worker_launch_interval 抑制短暂突发造成的过度启动，io_worker_idle_timeout 回收空闲进程；它们不会提高单个后端独立的 io_max_concurrency 上限。

应与 io_max_workers、io_worker_idle_timeout、io_worker_launch_interval、io_method 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 必须在生产存储栈与真实并发下测试，优化尾延迟和队列深度，而不只看平均吞吐，并为 WAL、检查点与前台读取保留容量。
OLAP 使用有代表性的扫描、预取与落盘阶段；只有吞吐继续提升且 CPU、内存与存储没有不可接受的饱和时，才增加并发或 worker 容量。
小规格 优先采用 auto 或上游 worker 上限，并按场景使用 pg_test_timing 或 I/O 统计验证；小节点上的大进程池可能只增加上下文切换。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 io_min_workers 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

io_max_workers · io_worker_idle_timeout · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit

参考资料

12.21 - io_worker_idle_timeout

io_worker_idle_timeout：设置 io_method=worker 时空闲 I/O worker 退出前的最长等待时间。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 min，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 io_method=worker 时空闲 I/O worker 退出前的最长等待时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值60000
1 min

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
提交日期 2026-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 60000 ms 1 min

机制详解

io_worker_idle_timeout：设置 io_method=worker 时空闲 I/O worker 退出前的最长等待时间。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这组参数只管理 io_method=worker 时使用的弹性后台 worker 池。io_min_workers 保留热容量，io_max_workers 限制池上限，io_worker_launch_interval 抑制短暂突发造成的过度启动，io_worker_idle_timeout 回收空闲进程；它们不会提高单个后端独立的 io_max_concurrency 上限。

应与 io_min_workers、io_max_workers、io_worker_launch_interval、io_method 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 必须在生产存储栈与真实并发下测试，优化尾延迟和队列深度，而不只看平均吞吐，并为 WAL、检查点与前台读取保留容量。
OLAP 使用有代表性的扫描、预取与落盘阶段；只有吞吐继续提升且 CPU、内存与存储没有不可接受的饱和时，才增加并发或 worker 容量。
小规格 优先采用 auto 或上游 worker 上限，并按场景使用 pg_test_timing 或 I/O 统计验证；小节点上的大进程池可能只增加上下文切换。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 io_worker_idle_timeout 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

io_min_workers · io_max_workers · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit

参考资料

12.22 - io_worker_launch_interval

io_worker_launch_interval：设置 io_method=worker 时启动新 I/O worker 的最小间隔。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 100 ms，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 io_method=worker 时启动新 I/O worker 的最小间隔。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值100
100 ms

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d1c01b79d4ae — aio: Adjust I/O worker pool automatically.
提交日期 2026-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 100 ms 100 ms

机制详解

io_worker_launch_interval：设置 io_method=worker 时启动新 I/O worker 的最小间隔。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这组参数只管理 io_method=worker 时使用的弹性后台 worker 池。io_min_workers 保留热容量，io_max_workers 限制池上限，io_worker_launch_interval 抑制短暂突发造成的过度启动，io_worker_idle_timeout 回收空闲进程；它们不会提高单个后端独立的 io_max_concurrency 上限。

应与 io_min_workers、io_max_workers、io_worker_idle_timeout、io_method 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 必须在生产存储栈与真实并发下测试，优化尾延迟和队列深度，而不只看平均吞吐，并为 WAL、检查点与前台读取保留容量。
OLAP 使用有代表性的扫描、预取与落盘阶段；只有吞吐继续提升且 CPU、内存与存储没有不可接受的饱和时，才增加并发或 worker 容量。
小规格 优先采用 auto 或上游 worker 上限，并按场景使用 pg_test_timing 或 I/O 统计验证；小节点上的大进程池可能只增加上下文切换。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 io_worker_launch_interval 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

io_min_workers · io_max_workers · io_worker_idle_timeout · io_method · io_max_concurrency · io_combine_limit

参考资料

12.23 - io_workers

io_workers：设置 io_method=worker 时使用的 I/O 工作进程数。实测在档范围为 PG18；最后在档的 PG18 启动默认值为 3，context 为 sighup。它在 PG19 Beta 3 被移除。
说明

Fact — 官方简述译文：设置 io_method=worker 时使用的 I/O 工作进程数。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值1 – 32
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值3
3

生命周期

Fact 值
首次观测 PG18
在档版本 PG18
移除版本 PG19 Beta 3
引入提交 55b454d0e140 — aio: Infrastructure for io_method=worker
提交日期 2025-03-18
Discussion 讨论 1 · 讨论 2 · 讨论 3

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18 3 — 3

机制详解

io_workers 设置 PostgreSQL 18 在 io_method=worker 时使用的专用 I/O 工作进程数；对 io_uring 或 sync 无效。

I/O worker 代表数据库进程执行异步请求；这是执行池，与并行查询 worker 及通用后台 worker 名额不同。

数量可重载修改，但有效能力仍受 io_max_concurrency、负载队列深度、存储延迟与 CPU 限制。更多 worker 不保证设备吞吐更高。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有 io_method=worker 时才调 io_workers。从 PG18 默认 3 开始，测量 worker 饱和、CPU 与尾延迟；只有符合条件的 I/O 在等待 worker 执行而不是等待设备时才扩大池。
OLAP 持续的符合条件扫描需要足够 I/O worker 才能喂满存储，但额外进程会增加调度开销，也不能突破单进程或设备并发瓶颈。应比较吞吐与 worker 利用率；请求尺寸由其他参数控制。
小规格 进程与 CPU 预算紧张时保留 3，或使用实测更小值。io_uring、sync 下 io_workers 无效，因此确认 io_method=worker 前不要调它。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG18 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 4 不同于 boot 值 {{ pg_io_workers }}
OLAP 4 不同于 boot 值 {{ pg_io_workers }}
CRIT 4 不同于 boot 值 {{ pg_io_workers }}
TINY 3 等于 boot 值 {{ pg_io_workers }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18 = 4 (dcs)；OLAP: PG18 = 4 (dcs)；CRIT: PG18 = 4 (dcs)；TINY: PG18 = 3 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：该 worker 池解析值让 PG18 worker AIO 方法在非 tiny 模板拥有更多执行进程，同时 tiny 保持上游启动数量。

常见坑

  • io_method 为 io_uring 或 sync 时修改 io_workers，此时它没有效果。
  • 把 worker 进程数误当成每次请求字节数或单进程 I/O 上限。
  • 存储设备已经饱和时仍增加 worker。
  • 忘记可重载的 worker 池仍会消耗进程、CPU 与调度容量。

关联参数

io_method · io_max_concurrency · effective_io_concurrency · maintenance_io_concurrency · max_worker_processes

参考资料

12.24 - logical_decoding_work_mem

logical_decoding_work_mem：设置逻辑解码使用的最大内存。实测在档范围为 PG13–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 64 MiB，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置逻辑解码使用的最大内存。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值65536
64 MiB

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 cec2edfa7859 — Add logical_decoding_work_mem to limit ReorderBuffer memory usage.
提交日期 2019-11-16
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 65536 kB 64 MiB

机制详解

logical_decoding_work_mem 是单条逻辑解码流把变更写入本地临时文件之前可使用的真实内存阈值，与普通查询 work_mem 相互独立。

每个复制连接使用一个这样的缓冲区，并发由复制 sender 能力而不是普通客户端会话限制。大型进行中事务可能落盘并在以后重新读取。

提高阈值可减少逻辑复制序列化 I/O，但集群内存预算必须乘以并发解码流数，并计入此参数未覆盖的输出插件内存。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在并发下定位到对应资源瓶颈后才修改 logical_decoding_work_mem。应预算总内存、I/O、磁盘或内核容量，而不是孤立优化一个进程。
OLAP 使用代表性的批处理与扫描阶段测试 logical_decoding_work_mem，同时观察持续吞吐、落盘/回写及对其他会话的干扰，不能只看单次操作耗时。
小规格 小主机上应保守设置 logical_decoding_work_mem；证据不足时优先上游默认。照搬大服务器取值可能占用不成比例的资源。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 logical_decoding_work_mem 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

work_mem · max_wal_senders · max_replication_slots · debug_logical_replication_streaming · temp_file_limit

参考资料

12.25 - maintenance_io_concurrency

maintenance_io_concurrency：设置维护操作可利用的存储 I/O 并发度。实测在档范围为 PG13–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 16，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置维护操作可利用的存储 I/O 并发度。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / I/O
上游分类
最后 boot 值 值16
16

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 fc34b0d9de27 — Introduce a maintenance_io_concurrency setting.
提交日期 2020-03-16
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–17 10 — 10
PG18–19 Beta 3 16 — 16

机制详解

maintenance_io_concurrency 是代表许多客户端执行的维护工作所使用的单次维护操作存储并发目标。同名 tablespace 选项可针对该存储覆盖；它既不是集群级设备上限，也不是内存分配。

PG13–17 中它主要控制受支持系统上的维护预取。Linux-Docker 实测 boot 值为 10，缺少有效预取建议、因而不受支持的平台默认 0；这些版本没有 PG18 的核心 AIO 执行模型。

PostgreSQL 18 把该目标接入核心 AIO，boot 默认改为 16。io_max_concurrency 另行钳制单进程同时执行数量，io_method 选择执行机制，combine 参数控制每次请求字节数。其 user 上下文允许局部运行时修改。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP PG13–17 只应在受支持存储上把它作为维护预取目标调优；PG18 才把它作为 AIO 并发目标。VACUUM 等符合条件的维护运行时应测前台尾延迟，异构存储使用 tablespace 覆盖。
OLAP 高延迟、高 IOPS 存储上，提高维护并发可能缩短符合条件的扫描或 vacuum，也会加深分析查询看到的队列。应同时测试维护完成时间与混合负载延迟；它不会改变请求尺寸。
小规格 除非维护确实受 I/O 停顿限制，否则使用对应版本和平台的默认值。小主机很低的目标也可能打满存储，不能未经测量照搬 Pigsty SSD 值 100。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 100 不同于 boot 值 100
OLAP 100 不同于 boot 值 100
CRIT 100 不同于 boot 值 100
TINY 100 不同于 boot 值 100
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 = 100 (dcs)；OLAP: PG13–19 Beta 3 = 100 (dcs)；CRIT: PG13–19 Beta 3 = 100 (dcs)；TINY: PG13–19 Beta 3 = 100 (dcs)。 建议（待人工复核）——编辑推断：模板要求 SSD 维护利用更多预取/AIO 并发，但该值是每次维护操作的目标，必须结合前台延迟验证。

常见坑

  • 把 10 称为 PG13–17 无条件默认，忽略不支持平台使用 0。
  • 把 PG18 核心 AIO 语义反向套到 PG13–17 的预取行为。
  • 把单次操作目标误当成集群或设备总上限。
  • 把并发度与 io_combine_limit 的每次请求字节数混为一谈。
  • 对存储特性差异很大的 tablespace 使用同一取值。

关联参数

effective_io_concurrency · io_method · io_max_concurrency · io_combine_limit · vacuum_buffer_usage_limit

参考资料

12.26 - maintenance_work_mem

VACUUM、CREATE INDEX 与添加外键约束等维护命令的内存上限。
说明

Fact — 官方简述译文：设置维护操作可使用的最大内存。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值65536
64 MiB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.3 16384 kB 16 MiB
PG9.4–19 Beta 3 65536 kB 64 MiB

机制详解

maintenance_work_mem 用于 VACUUM、CREATE INDEX、ALTER TABLE ADD FOREIGN KEY 等维护操作。一个会话通常同一时间只执行一个此类操作，因此它一般可以显著高于 work_mem。

对于并行工具命令，PostgreSQL 将 maintenance_work_mem 视为整个工具命令的上限，而不是给每个并行维护工作进程完整分配一份；不过并行度仍可能显著增加 CPU 与 I/O 消耗。

Autovacuum 是另一项并发风险：当 autovacuum_work_mem 为 -1 时，每个 autovacuum 工作进程都会继承 maintenance_work_mem，多个工作进程的总预算会远高于单次维护操作的数值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 取值应足以让日常 vacuum 与索引维护高效完成，但必须显式预算多个 autovacuum worker 的并发。若交互延迟敏感且 maintenance_work_mem 很大，应为 autovacuum_work_mem 单独设置较低上限。
OLAP 较大取值通常有利于大表索引构建、清理与恢复。应安排重型维护窗口，并验证维护并发、查询内存和操作系统内存仍能共同容纳。
小规格 全局值保持克制，只在受控维护会话中临时调高；增加之前先检查 autovacuum 的继承关系。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 2048MB 不同于 boot 值 {{ pg_maintenance_mem }}MB
OLAP 4096MB 不同于 boot 值 {{ pg_maintenance_mem }}MB
CRIT 2048MB 不同于 boot 值 {{ pg_maintenance_mem }}MB
TINY 2048MB 不同于 boot 值 {{ pg_maintenance_mem }}MB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 2048MB (dcs)；OLAP: PG9.0–19 Beta 3 = 4096MB (dcs)；CRIT: PG9.0–19 Beta 3 = 2048MB (dcs)；TINY: PG9.0–19 Beta 3 = 2048MB (dcs)。 建议（待人工复核）——编辑推断：更高的 OLAP 比例意在加速批量维护，而被 autovacuum 继承后的并发风险需要单独复核。

常见坑

  • 因为维护操作不频繁就认为大值无害，却让 autovacuum_work_mem 保持 -1。
  • 把上限按并行维护工作进程数相乘；PostgreSQL 对整个工具命令应用该上限。
  • 为了单次恢复长期保留很大的集群全局值，而不是使用作用域内 SET。
  • 期望单纯增加内存解决由锁或存储 I/O 主导的维护瓶颈。

关联参数

autovacuum_work_mem · autovacuum_max_workers · max_parallel_maintenance_workers · vacuum_buffer_usage_limit · work_mem

参考资料

12.27 - max_files_per_process

max_files_per_process：设置每个服务器进程可同时打开的最大文件数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1000，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置每个服务器进程可同时打开的最大文件数。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Kernel Resources
上游分类
最后 boot 值 值1000
1000

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 1000 — 1000

机制详解

max_files_per_process 是 PostgreSQL 启动时对单个服务器子进程可保持打开文件数的预期，不含从 postmaster 继承且已打开的文件。

它不会提高内核文件描述符限制。PostgreSQL 用它管理资源；在会跨进程过度承诺描述符的内核上，较低值可避免系统级耗尽。

相关容量是每进程值乘以后端与 worker 数量。出现“Too many open files”还可能需要修复 OS 服务限制、连接数、分区扇出或扩展行为。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先把 PostgreSQL 取值与服务真实每进程 nofile 限制及已观测描述符用量比较。提高该 GUC 不会提高内核限制；会跨大量进程过度承诺描述符的系统上，降低 PostgreSQL 值反而更安全。
OLAP 大量分区或索引扇出会增加单后端描述符，但应按实测峰值打开数与后端/worker 总量规划。修改 PostgreSQL 上限前先解决泄漏与 OS 服务限制。
小规格 除非描述符证据表明需要修改，否则保留默认。即使每个进程都低于个体上限，小主机仍可能耗尽系统级文件表。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待该 GUC 提高 ulimit 或服务管理器的 nofile 限制。
  • 只规划每进程数量，忽略连接与 worker 汇总值。
  • 通过提高取值掩盖描述符泄漏或过高分区/索引扇出。
  • 忘记从 postmaster 继承且已打开的文件不计入本数值。

关联参数

max_connections · max_worker_processes · max_wal_senders · shared_preload_libraries

参考资料

12.28 - max_notify_queue_pages

max_notify_queue_pages：设置 LISTEN/NOTIFY 队列最多分配的页面数。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1048576，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 LISTEN/NOTIFY 队列最多分配的页面数。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Disk
上游分类
最后 boot 值 值1048576
1048576

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 2cdf131c46e6 — Use larger segment file names for pg_notify
提交日期 2023-11-29
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 1048576 — 1048576

机制详解

max_notify_queue_pages 限制磁盘后端 LISTEN/NOTIFY 队列最多分配的数据库页面数。按常见 8kB BLCKSZ，PG18 默认允许最多 8GB。

通知会保留到所有监听会话都已消费或不再需要。监听者长期停留在事务中会阻止清理并让队列增长。

它限制磁盘容量，不是 notify_buffers 内存，也不是单个 payload 上限。队列写满时，尝试 NOTIFY 的事务可能在提交阶段失败。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 提高容量前先监控 pg_notification_queue_usage()，并找出长期停留在事务中的 listener。应按可容忍通知积压与数据库卷可用空间规划磁盘队列，而不是按查询扫描吞吐。
OLAP OLAP 标签不能成为扩大队列的理由。监听会话中的长分析事务会延迟清理，因此应把 listener 与长事务分离，并测通知生产与消费速率。
小规格 除非应用有已验证的 LISTEN/NOTIFY 积压需求，否则保留默认。更多页面只会允许更多磁盘消耗并推迟失败，不能修复卡住的 listener。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 通过扩大队列代替修复长期停留在事务中的 listener。
  • 把 max_notify_queue_pages 磁盘容量与 notify_buffers 共享内存缓存混淆。
  • 忘记按 8kB 页面计算时，默认 1048576 页允许约 8GB。
  • 认为更大队列会改变单个 NOTIFY payload 上限或投递语义。

关联参数

notify_buffers · track_activities · max_connections · shared_buffers

参考资料

12.29 - max_parallel_maintenance_workers

max_parallel_maintenance_workers：设置单次维护操作最多使用的并行工作进程数。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置单次维护操作最多使用的并行工作进程数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1024
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Worker Processes
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 9da0cc35284b — Support parallel btree index builds.
提交日期 2018-02-02
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 2 — 2

机制详解

max_parallel_maintenance_workers 限制单条受支持维护命令（如并行 CREATE INDEX 或 VACUUM）请求的 worker 数；leader 另计且也可能参与工作。

该上限不会预留 worker，也不保证可获得。请求要在 max_parallel_workers 与 max_worker_processes 内竞争，具体操作规则还可能选择更少。

并行维护会放大 CPU 与 I/O 压力；CREATE INDEX 的内存采用维护专用计账方式，并非简单地给每个 worker 独立一份 maintenance_work_mem。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 应根据并发预算而非仅凭 CPU 核数设置 max_parallel_maintenance_workers。保护延迟敏感 OLTP 不受报表与维护突发影响，并检查实际 Workers Planned 与 Workers Launched。
OLAP 分析负载可使用更大的 max_parallel_maintenance_workers，但要把每节点内存与 I/O 乘以并发语句数；应在真实 worker 竞争下测吞吐，而不是只测一条孤立查询。
小规格 小主机上应保守设置 max_parallel_maintenance_workers。更多潜在 worker 可能因上下文切换与内存压力降低总吞吐，即使一条查询变快。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 3 不同于 boot 值 {{ pg_max_parallel_mt_workers }}
OLAP 3 不同于 boot 值 {{ pg_max_parallel_mt_workers }}
CRIT 3 不同于 boot 值 {{ pg_max_parallel_mt_workers }}
TINY 2 等于 boot 值 {{ pg_max_parallel_mt_workers }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 = 3 (dcs)；OLAP: PG11–19 Beta 3 = 3 (dcs)；CRIT: PG11–19 Beta 3 = 3 (dcs)；TINY: PG11–19 Beta 3 = 2 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：模板变量为并行维护分配适中容量，并让 tiny 夹具少一个 worker 以降低资源压力。

常见坑

  • 把 max_parallel_maintenance_workers 当作已预留容量，而不是与其他工作共享的上限。
  • 忽略并行计划会放大 CPU、I/O 与受 work_mem 限制的节点。
  • 只测一条查询，没有模拟并发 worker 竞争。
  • 认为规划的 worker 数在执行时总能全部启动。

关联参数

max_parallel_workers · max_worker_processes · maintenance_work_mem · maintenance_io_concurrency · max_parallel_workers_per_gather

参考资料

12.30 - max_parallel_workers

max_parallel_workers：设置集群内可同时活动的并行工作进程总数。实测在档范围为 PG10–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置集群内可同时活动的并行工作进程总数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1024
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Worker Processes
上游分类
最后 boot 值 值8
8

生命周期

Fact 值
首次观测 PG10
在档版本 PG10–19 Beta 3
移除版本 否
引入提交 b460f5d66931 — Add max_parallel_workers GUC.
提交日期 2016-12-02
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG10–19 Beta 3 8 — 8

机制详解

max_parallel_workers 限制全集群同时活动的并行查询与维护 worker 数，是 max_worker_processes 之下的池上限。

单次操作参数从该池请求 worker，但不会预留名额。计划可能以少于规划数量的 worker 启动，并发任务也会互相争抢。

提高它会扩大潜在 CPU、内存与 I/O 并发，却不会自行让计划并行；规划阈值、安全检查与 max_parallel_workers_per_gather 仍决定查询选择。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 应根据并发预算而非仅凭 CPU 核数设置 max_parallel_workers。保护延迟敏感 OLTP 不受报表与维护突发影响，并检查实际 Workers Planned 与 Workers Launched。
OLAP 分析负载可使用更大的 max_parallel_workers，但要把每节点内存与 I/O 乘以并发语句数；应在真实 worker 竞争下测吞吐，而不是只测一条孤立查询。
小规格 小主机上应保守设置 max_parallel_workers。更多潜在 worker 可能因上下文切换与内存压力降低总吞吐，即使一条查询变快。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 4 不同于 boot 值 {{ pg_max_parallel_workers }}
OLAP 7 不同于 boot 值 {{ pg_max_parallel_workers }}
CRIT 4 不同于 boot 值 {{ pg_max_parallel_workers }}
TINY 4 不同于 boot 值 {{ pg_max_parallel_workers }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG10–19 Beta 3 = 4 (dcs)；OLAP: PG10–19 Beta 3 = 7 (dcs)；CRIT: PG10–19 Beta 3 = 4 (dcs)；TINY: PG10–19 Beta 3 = 4 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：解析后的池让 OLAP 比 OLTP/crit/tiny 拥有更多全集群并行容量，符合吞吐导向模板。

常见坑

  • 把 max_parallel_workers 当作已预留容量，而不是与其他工作共享的上限。
  • 忽略并行计划会放大 CPU、I/O 与受 work_mem 限制的节点。
  • 只测一条查询，没有模拟并发 worker 竞争。
  • 认为规划的 worker 数在执行时总能全部启动。

关联参数

max_worker_processes · max_parallel_workers_per_gather · max_parallel_maintenance_workers · parallel_setup_cost · parallel_leader_participation

参考资料

12.31 - max_parallel_workers_per_gather

max_parallel_workers_per_gather：设置单个 Gather 节点最多请求的并行工作进程数。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置单个 Gather 节点最多请求的并行工作进程数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1024
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Worker Processes
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 c9ce4a1c61eb — Eliminate “parallel degree” terminology.
提交日期 2016-06-09
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6 0 — 0
PG10–19 Beta 3 2 — 2

机制详解

max_parallel_workers_per_gather 限制单个 Gather 或 Gather Merge 节点最多请求多少个 worker。零会阻止通过这些节点执行并行查询，但不禁用其他后台 worker。

worker 不会预留，执行时可能因 max_parallel_workers 与 max_worker_processes 共享池而不足；leader 进程不计入本数值。

每个并行计划都可能放大受 work_mem 限制的节点、CPU 与 I/O 需求。规划器还会考虑 parallel_setup_cost 与 parallel_tuple_cost 后才决定是否请求。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 应根据并发预算而非仅凭 CPU 核数设置 max_parallel_workers_per_gather。保护延迟敏感 OLTP 不受报表与维护突发影响，并检查实际 Workers Planned 与 Workers Launched。
OLAP 分析负载可使用更大的 max_parallel_workers_per_gather，但要把每节点内存与 I/O 乘以并发语句数；应在真实 worker 竞争下测吞吐，而不是只测一条孤立查询。
小规格 小主机上应保守设置 max_parallel_workers_per_gather。更多潜在 worker 可能因上下文切换与内存压力降低总吞吐，即使一条查询变快。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 2 等于 boot 值 {{ pg_max_parallel_workers_per_gather|int }}
OLAP 4 不同于 boot 值 {{ pg_max_parallel_workers_per_gather|int }}
CRIT 0 不同于 boot 值 {{ pg_max_parallel_workers_per_gather|int }}
TINY 0 不同于 boot 值 {{ pg_max_parallel_workers_per_gather|int }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 2 (dcs)；OLAP: PG9.6–19 Beta 3 = 4 (dcs)；CRIT: PG9.6–19 Beta 3 = 0 (dcs)；TINY: PG9.6–19 Beta 3 = 0 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：这些值允许适中的 OLTP 与更强的 OLAP 查询并行，同时在 crit 与 tiny 模板显式禁止 Gather worker。

常见坑

  • 把 max_parallel_workers_per_gather 当作已预留容量，而不是与其他工作共享的上限。
  • 忽略并行计划会放大 CPU、I/O 与受 work_mem 限制的节点。
  • 只测一条查询，没有模拟并发 worker 竞争。
  • 认为规划的 worker 数在执行时总能全部启动。

关联参数

max_parallel_workers · max_worker_processes · parallel_setup_cost · parallel_tuple_cost · parallel_leader_participation · work_mem

参考资料

12.32 - max_prepared_transactions

max_prepared_transactions：设置可同时处于 prepared 状态的事务上限。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置可同时处于 prepared 状态的事务上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

max_prepared_transactions 为 PREPARE TRANSACTION 留下的两阶段事务预留容量；零会禁止创建 prepared transaction。

prepared transaction 会在客户端断开或崩溃后继续保留锁与事务状态，直到 COMMIT PREPARED 或 ROLLBACK PREPARED；容量会消耗共享内存并保存持久状态。

备库取值必须不小于主库，否则可能拒绝只读查询。它与 SQL 预备语句无关；没有受管理的两阶段提交协调器时应保持零。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非真实两阶段提交协调器会监控并解决每个 prepared transaction，否则保持 max_prepared_transactions=0。启用后主备容量应一致，并监控事务年龄。
OLAP 分析负载本身不构成启用 max_prepared_transactions 的理由。只有应用协议需要持久 prepared transaction 时才启用，与 SQL 预备语句无关。
小规格 小部署应保持 max_prepared_transactions=0；只有两阶段提交不可缺少且恢复流程已有文档时才启用，遗留 prepared transaction 会阻塞集群。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0 等于 boot 值 {{ pg_max_prepared_transactions }}
OLAP 0 等于 boot 值 {{ pg_max_prepared_transactions }}
CRIT 0 等于 boot 值 {{ pg_max_prepared_transactions }}
TINY 0 等于 boot 值 {{ pg_max_prepared_transactions }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 0 (dcs)；OLAP: PG9.0–19 Beta 3 = 0 (dcs)；CRIT: PG9.0–19 Beta 3 = 0 (dcs)；TINY: PG9.0–19 Beta 3 = 0 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：显式零让两阶段 prepared transaction 保持关闭，除非用户主动修改模板变量并部署协调器。

常见坑

  • 修改 max_prepared_transactions 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

max_connections · max_locks_per_transaction · wal_level · max_wal_senders

参考资料

12.33 - max_stack_depth

max_stack_depth：设置 PostgreSQL 认为安全的最大执行栈深度。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 100 KiB，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 PostgreSQL 认为安全的最大执行栈深度。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值kB
原始单位
范围 值100 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值100
100 KiB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 100 kB 100 KiB

机制详解

max_stack_depth 是部分递归执行路径使用的保护阈值。它既不分配进程栈，也不改变操作系统栈限制；内核限制仍是最终边界。

所有实测 PG9.0–19 Beta 3 镜像的目录原始 boot_val 都是 100kB，但同一批新容器的 setting 为 2048kB，与配置/initdb 后文档所述 2MB 默认一致。不能把 100kB boot 回退值写成普通有效设置。

安全显式值应等于 ulimit -s 等内核栈限制减去约 1MB，因为不是每个 C 调用点都会检查深度。设置超过真实限制会让失控递归崩溃后端。其 superuser 上下文允许获授权用户运行时修改，无需重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非可复现的递归函数或表达式触及 PostgreSQL 保护阈值，否则保留有效默认 2MB。提高前必须记录服务真实内核栈限制，并保留约 1MB 安全余量。
OLAP 查询时长、表大小与批量 I/O 不能成为提高栈阈值的理由。只有确认深层表达式或函数递归后才修改，并使用与生产相同的 OS 服务限制测试后端稳定性。
小规格 不要为了“节省内存”而升降该值：它是安全检查，不是预留内存。除非内核栈与具体递归负载证明其他取值安全且必要，否则保留配置默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 boot_val=100kB 与实测及文档所述的有效 setting=2048kB 混为一谈。
  • 把 max_stack_depth 当作已分配内存或降低常驻内存的手段。
  • 设置超过内核栈限制，让递归代码崩溃后端。
  • 没有检查服务管理器与 ulimit 栈设置，就在不同主机间照搬取值。

关联参数

max_worker_processes · shared_buffers · work_mem · max_connections

参考资料

12.34 - max_worker_processes

max_worker_processes：设置并发后台工作进程的总上限。实测在档范围为 PG9.4–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 8，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置并发后台工作进程的总上限。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值0 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Worker Processes
上游分类
最后 boot 值 值8
8

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 6bc8ef0b7f1f — Add new GUC, max_worker_processes, limiting number of bgworkers.
提交日期 2013-07-04
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 8 — 8

机制详解

max_worker_processes 是并发后台 worker 的启动时总上限，包含并行 worker 与扩展管理的 worker，范围比 max_parallel_workers 更广。

该设置分配共享控制容量，但不会主动启动 worker。复制、扩展、逻辑 apply 与并行执行都可能依赖其下的名额。

备库通常应配置为不小于主库，因为 worker 需求可能在重放或提升后出现。没有 CPU 与内存预算时，提高它只会创造潜在并发。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 应根据并发预算而非仅凭 CPU 核数设置 max_worker_processes。保护延迟敏感 OLTP 不受报表与维护突发影响，并检查实际 Workers Planned 与 Workers Launched。
OLAP 分析负载可使用更大的 max_worker_processes，但要把每节点内存与 I/O 乘以并发语句数；应在真实 worker 竞争下测吞吐，而不是只测一条孤立查询。
小规格 小主机上应保守设置 max_worker_processes。更多潜在 worker 可能因上下文切换与内存压力降低总吞吐，即使一条查询变快。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 24 不同于 boot 值 {{ pg_max_worker_processes + 8 }}
OLAP 28 不同于 boot 值 {{ pg_max_worker_processes + 8 }}
CRIT 24 不同于 boot 值 {{ pg_max_worker_processes + 8 }}
TINY 20 不同于 boot 值 {{ pg_max_worker_processes + 8 }}
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 = 24 (dcs)；OLAP: PG9.4–19 Beta 3 = 28 (dcs)；CRIT: PG9.4–19 Beta 3 = 24 (dcs)；TINY: PG9.4–19 Beta 3 = 20 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：模板表达式在配置变量之上增加 worker 余量，可能用于扩展、复制与并行工作；精确容量模型需维护者确认。

常见坑

  • 把 max_worker_processes 当作已预留容量，而不是与其他工作共享的上限。
  • 忽略并行计划会放大 CPU、I/O 与受 work_mem 限制的节点。
  • 只测一条查询，没有模拟并发 worker 竞争。
  • 认为规划的 worker 数在执行时总能全部启动。

关联参数

max_parallel_workers · max_parallel_workers_per_gather · max_parallel_maintenance_workers · max_logical_replication_workers · max_wal_senders

参考资料

12.35 - min_dynamic_shared_memory

min_dynamic_shared_memory：设置启动时为并行查询预留的动态共享内存。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 B，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置启动时为并行查询预留的动态共享内存。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值MB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值0
0 B

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 84b1c63ad418 — Preallocate some DSM space at startup.
提交日期 2020-07-31
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 0 MB 0 B

机制详解

min_dynamic_shared_memory 在服务器启动时为并行查询动态共享内存实际预分配空间。它是预留池，不是上限，也不是缓存规模估计。

预留池不足时，并行查询仍可通过 dynamic_shared_memory_type 临时分配动态共享内存，但会增加操作系统分配开销。

启动时预分配会进入主共享内存区域，在支持平台上可受益于大页。预留过多会在没有并行工作时也占用内存。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非反复并行查询启动显示动态共享内存分配开销可测，否则保持 0。任何非零值都是启动时真实常驻内存，即使没有并行查询也必须计入集群预算。
OLAP 频繁并发并行查询时，预分配可减少临时 DSM 建立开销。应测 DSM 分配延迟与池使用，只预留有依据的下限；池耗尽后仍会回退动态分配。
小规格 保持 0 或很小的实测预留。不能把推测中的未来并行需求变成受限主机上的永久内存分配。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 min_dynamic_shared_memory 当成上限，而不是实际预分配下限。
  • 误以为预留池耗尽后并行查询会失败；PostgreSQL 仍可分配额外动态段。
  • 预留在没有并行工作时仍持续占用的内存。
  • 忽略 dynamic_shared_memory_type、大页行为与必需的重启。

关联参数

dynamic_shared_memory_type · huge_pages · max_parallel_workers · max_parallel_workers_per_gather · shared_buffers

参考资料

12.36 - multixact_member_buffers

multixact_member_buffers：设置 MultiXact member 缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 256 KiB (32 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 MultiXact member 缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值16 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值32
256 KiB (32 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 32 8kB 256 KiB (32 × 8kB)

机制详解

multixact_member_buffers 为 pg_multixact/members 分配专用共享缓冲池，用于缓存MultiXact member 条目。这是启动时真实共享内存，不是规划器估算。

配置的块数会在服务器启动时实际分配。单位是 BLCKSZ 块，通常为 8kB。

更大缓存可在底层功能负载异常高时减少 SLRU 读写抖动，但会永久消耗共享内存，也不会提高该功能的逻辑容量。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 multixact_member_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 multixact_member_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 multixact_member_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 multixact_member_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

multixact_offset_buffers · shared_buffers · max_locks_per_transaction

参考资料

12.37 - multixact_offset_buffers

multixact_offset_buffers：设置 MultiXact offset 缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 128 KiB (16 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 MultiXact offset 缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值16 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值16
128 KiB (16 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

机制详解

multixact_offset_buffers 为 pg_multixact/offsets 分配专用共享缓冲池，用于缓存MultiXact offset。这是启动时真实共享内存，不是规划器估算。

配置的块数会在服务器启动时实际分配。单位是 BLCKSZ 块，通常为 8kB。

更大缓存可在底层功能负载异常高时减少 SLRU 读写抖动，但会永久消耗共享内存，也不会提高该功能的逻辑容量。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 multixact_offset_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 multixact_offset_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 multixact_offset_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 multixact_offset_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

multixact_member_buffers · shared_buffers · max_locks_per_transaction

参考资料

12.38 - notify_buffers

notify_buffers：设置 LISTEN/NOTIFY 消息缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 128 KiB (16 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 LISTEN/NOTIFY 消息缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值16 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值16
128 KiB (16 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 16 8kB 128 KiB (16 × 8kB)

机制详解

notify_buffers 为 pg_notify 分配专用共享缓冲池，用于缓存LISTEN/NOTIFY 队列页面。这是启动时真实共享内存，不是规划器估算。

配置的块数会在服务器启动时实际分配。单位是 BLCKSZ 块，通常为 8kB。

更大缓存可在底层功能负载异常高时减少 SLRU 读写抖动，但会永久消耗共享内存，也不会提高该功能的逻辑容量。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 notify_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 notify_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 notify_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 notify_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

max_notify_queue_pages · shared_buffers · track_activities

参考资料

12.39 - old_snapshot_threshold

old_snapshot_threshold：设置快照因过旧而不能读取后来被修改页面的时间阈值。实测在档范围为 PG9.6–16；最后在档的 PG16 启动默认值为 -1 min，context 为 postmaster。它在 PG17 被移除。
说明

Fact — 官方简述译文：设置快照因过旧而不能读取后来被修改页面的时间阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值min
原始单位
范围 值-1 – 86400
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Asynchronous Behavior
上游分类
最后 boot 值 值-1
-1 min

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–16
移除版本 PG17
引入提交 848ef42bb8c7 — Add the “snapshot too old” feature
提交日期 2016-04-08
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–16 -1 min -1 min

机制详解

old_snapshot_threshold 在 PG16 及以前可用、PG17 移除；它在配置时间后把快照标为过旧，让页面清理更积极，后续读取可能报 snapshot-too-old，而不是取得历史页面版本。

它不是事务超时：事务可继续运行，直到访问旧版本已被清除的数据。即使尚未出现错误，该功能也需要在启动时启用跟踪开销。

它不能替代正确 vacuum，也不能避免所有膨胀。由于功能已移除，迁移到 PG17+ 时不能携带该参数，应用也不能依赖其报错语义。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前 PostgreSQL 不应调优 old_snapshot_threshold：升级目标中应删除它，并采用上文所述当前替代行为；只有复现历史版本时才保留。
OLAP 不要把 old_snapshot_threshold 带入现代分析集群，应测试受支持的当前机制，而不是模拟已移除实现细节。
小规格 版本迁移时删除 old_snapshot_threshold；它更可能造成未知参数启动失败，而不是带来收益。历史测试实例应保留旧版本上游默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG16 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–16 未修改；OLAP: PG9.6–16 未修改；CRIT: PG9.6–16 未修改；TINY: PG9.6–16 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 old_snapshot_threshold 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

vacuum_defer_cleanup_age · autovacuum · hot_standby_feedback · idle_in_transaction_session_timeout

参考资料

12.40 - parallel_leader_participation

parallel_leader_participation：控制 Gather 或 Gather Merge 的 leader 是否也执行子计划。实测在档范围为 PG11–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：控制 Gather 或 Gather Merge 的 leader 是否也执行子计划。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Worker Processes
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 e5253fdc4f5f — Add parallel_leader_participation GUC.
提交日期 2017-11-15
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 on — on

机制详解

parallel_leader_participation 控制 Gather 或 Gather Merge 上方的进程在协调 worker 时是否也执行并行子计划；关闭时 leader 更专注于读取 worker 输出。

当结果生成昂贵时，leader 参与可增加有效 CPU；但 leader 忙于执行子计划时，可能更慢地消费大量 worker 结果流。

它是符合条件并行计划的规划/执行策略，不是额外 worker 名额。效果取决于元组量、Gather 类型、worker 可用性与瓶颈位置。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非代表性 Gather 计划表明 leader 忙于执行子计划，无法及时消费 worker 元组，否则保留默认 on。只在会话范围测试 off，并比较首行延迟、总延迟与 worker 阻塞。
OLAP 对 CPU 密集子计划，leader 参与通常能增加有效执行能力；对超大结果流，关闭后可让 leader 更早专注于排空 worker。应在相同计划与并发度下比较两个布尔状态。
小规格 该布尔值不会增加或减少 worker 名额。除非实测存在结果消费瓶颈，否则保持 on；worker 数应由 max_parallel_workers_per_gather 与共享池另行规划。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把该布尔值误当成并行度或 worker 数量设置。
  • 使用“更大取值”描述只有 on/off 两种状态的参数。
  • 关闭参与却没有测量等待 worker 产出首批元组所增加的时间。
  • 开启参与却没有检查 leader 是否因此过慢地消费大型 worker 结果流。

关联参数

max_parallel_workers_per_gather · max_parallel_workers · enable_gathermerge · parallel_tuple_cost · parallel_setup_cost

参考资料

12.41 - replacement_sort_tuples

replacement_sort_tuples：设置使用替换选择排序的最大元组数。实测在档范围为 PG9.6–10；最后在档的 PG10 启动默认值为 150000，context 为 user。它在 PG11 被移除。
说明

Fact — 官方简述译文：设置使用替换选择排序的最大元组数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值150000
150000

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–10
移除版本 PG11
引入提交 0711803775a3 — Use quicksort, not replacement selection, for external sorting.
提交日期 2016-04-08
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–10 150000 — 150000

机制详解

在 PG10 中，replacement_sort_tuples 决定内存排序何时使用替换选择，为外部归并排序生成更长的首个 run；PG11 随旧替换选择路径一并移除。

数值按元组计数而非字节，因此内存影响取决于行宽与 work_mem。它是算法阈值，不是通用排序内存上限。

现代 PostgreSQL 不再识别该参数。升级时应删除它，改用 work_mem、计划形态与实测临时文件用量调优当前排序行为。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前 PostgreSQL 不应调优 replacement_sort_tuples：升级目标中应删除它，并采用上文所述当前替代行为；只有复现历史版本时才保留。
OLAP 不要把 replacement_sort_tuples 带入现代分析集群，应测试受支持的当前机制，而不是模拟已移除实现细节。
小规格 版本迁移时删除 replacement_sort_tuples；它更可能造成未知参数启动失败，而不是带来收益。历史测试实例应保留旧版本上游默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG10 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–10 未修改；OLAP: PG9.6–10 未修改；CRIT: PG9.6–10 未修改；TINY: PG9.6–10 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 replacement_sort_tuples 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

work_mem · temp_file_limit · enable_sort · trace_sort · log_temp_files

参考资料

12.42 - serializable_buffers

serializable_buffers：设置可串行化事务缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 256 KiB (32 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置可串行化事务缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值16 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值32
256 KiB (32 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 32 8kB 256 KiB (32 × 8kB)

机制详解

serializable_buffers 为 pg_serial 分配专用共享缓冲池，用于缓存可串行化事务状态。这是启动时真实共享内存，不是规划器估算。

配置的块数会在服务器启动时实际分配。单位是 BLCKSZ 块，通常为 8kB。

更大缓存可在底层功能负载异常高时减少 SLRU 读写抖动，但会永久消耗共享内存，也不会提高该功能的逻辑容量。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 serializable_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 serializable_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 serializable_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 serializable_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

shared_buffers · max_connections · max_pred_locks_per_transaction

参考资料

12.43 - shared_buffers

shared_buffers：设置服务器使用的共享缓冲区数量。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 128 MiB (16384 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器使用的共享缓冲区数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值16 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值16384
128 MiB (16384 × 8kB)

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–14 1024 8kB 8 MiB (1024 × 8kB)
PG15–19 Beta 3 16384 8kB 128 MiB (16384 × 8kB)

机制详解

shared_buffers 在服务器启动时实际分配 PostgreSQL 共享缓冲缓存。这里的页面由 PostgreSQL 管理，并与操作系统页缓存共存；它不是规划器估算值。

本目录中 PG10–14 Docker 启动值为 8MB，PG15–18 为 128MB，反映历史 initdb/容器默认而不是通用硬件建议。官方把专用服务器 RAM 的约 25% 视为起点，并指出超过 40% 通常很少更好。

更大的缓存会改变 checkpoint 与 WAL 压力，往往需要更大的 max_wal_size，同时减少后端、work_mem、维护、扩展与 OS 可用内存。分配单位是 BLCKSZ，通常为 8kB。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在并发下定位到对应资源瓶颈后才修改 shared_buffers。应预算总内存、I/O、磁盘或内核容量，而不是孤立优化一个进程。
OLAP 使用代表性的批处理与扫描阶段测试 shared_buffers，同时观察持续吞吐、落盘/回写及对其他会话的干扰，不能只看单次操作耗时。
小规格 小主机上应保守设置 shared_buffers；证据不足时优先上游默认。照搬大服务器取值可能占用不成比例的资源。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 8192MB 不同于 boot 值 {{ pg_shared_buffers }}MB
OLAP 8192MB 不同于 boot 值 {{ pg_shared_buffers }}MB
CRIT 8192MB 不同于 boot 值 {{ pg_shared_buffers }}MB
TINY 8192MB 不同于 boot 值 {{ pg_shared_buffers }}MB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 8192MB (dcs)；OLAP: PG9.0–19 Beta 3 = 8192MB (dcs)；CRIT: PG9.0–19 Beta 3 = 8192MB (dcs)；TINY: PG9.0–19 Beta 3 = 8192MB (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：Pigsty 有意用变量计算真实共享缓冲区分配，而不是固定为夹具的 8192MB；发布理由必须引用主机内存计算公式，不能把 8192MB 写成通用默认。

常见坑

  • 修改 shared_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

effective_cache_size · work_mem · max_wal_size · huge_pages · checkpoint_completion_target · wal_buffers

参考资料

12.44 - shared_memory_type

shared_memory_type：选择主共享内存区域的实现。实测在档范围为 PG12–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 mmap，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：选择主共享内存区域的实现。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值sysv, mmap
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值mmap
mmap

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 f1bebef60ec8 — Add shared_memory_type GUC.
提交日期 2019-02-03
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 mmap — mmap

机制详解

shared_memory_type 选择 PostgreSQL 主共享内存区域使用的操作系统机制，其中包含 shared_buffers 与其他固定共享状态；它不设置区域大小。

可用枚举值与第一个受支持的启动默认值依平台而定。Docker/Linux 目录实测为 mmap；Windows 有自己的实现，sysv 在大分配时可能需要非默认内核限制。

Linux 上显式 huge_pages 需要 mmap。该参数不同于 dynamic_shared_memory_type，后者管理并行查询与扩展使用的临时动态段。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保留平台第一个受支持默认实现；Linux 通常是 mmap，且 PostgreSQL 显式大页要求它。只有明确兼容需求才用 sysv，并在重启前配置好内核限制。
OLAP shared_buffers 很大时，可靠分配主共享区域更重要，但负载标签不决定 API。应在目标操作系统验证启动、大页、故障转移与服务限制，而不是基准存储吞吐。
小规格 保留平台默认。更换实现不会减小已配置共享内存大小，反而可能增加内核限制或可移植性故障。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 Linux-Docker 的 mmap boot 值当成所有操作系统的可移植默认。
  • 没有提高主区域所需 System V 共享内存内核限制就选择 sysv。
  • 忘记 Linux 上显式大页要求 shared_memory_type=mmap。
  • 期待该参数改变 shared_buffers 或其他共享分配的大小。

关联参数

dynamic_shared_memory_type · shared_buffers · huge_pages · huge_page_size · min_dynamic_shared_memory

参考资料

12.45 - subtransaction_buffers

subtransaction_buffers：设置子事务状态缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 B (0 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置子事务状态缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值0 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值0
0 B (0 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 0 8kB 0 B (0 × 8kB)

机制详解

subtransaction_buffers 为 pg_subtrans 分配专用共享缓冲池，用于缓存子事务父级映射。这是启动时真实共享内存，不是规划器估算。

零表示自动计算：PostgreSQL 按 shared_buffers/512 推导，并限制在 16 到 1024 个块之间。单位是 BLCKSZ 块，通常为 8kB。

更大缓存可在底层功能负载异常高时减少 SLRU 读写抖动，但会永久消耗共享内存，也不会提高该功能的逻辑容量。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 subtransaction_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 subtransaction_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 subtransaction_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 subtransaction_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

transaction_buffers · shared_buffers · max_locks_per_transaction

参考资料

12.46 - temp_buffers

每会话、按需分配且仅用于访问临时表的缓冲区上限。
说明

Fact — 官方简述译文：设置每个会话使用的最大临时缓冲区内存。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值8kB
原始单位
范围 值100 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值1024
8 MiB (1024 × 8kB)

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 1024 8kB 8 MiB (1024 × 8kB)

机制详解

temp_buffers 控制访问临时表时使用的会话本地缓冲区，不控制普通查询执行中排序或哈希产生的临时文件。

会话只能在首次使用临时表之前修改该值；首次访问之后再执行 SET 对该会话无效。缓冲区会按需增长，直到达到上限。

即使未真正使用，提高上限仍会产生缓冲描述符开销；每个实际使用的缓冲会消耗一个数据库块，通常为 8kB。因此总用量取决于同时活跃使用临时表的会话数。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非应用明确大量使用临时表，否则保留默认值。优先只在创建临时表的会话中调整，并确保在首次访问前设置。
OLAP 仅在确实使用 PostgreSQL 临时表的流程中调高；排序和哈希的主要控制项是 work_mem，而不是 temp_buffers。预算中必须计入会话并发。
小规格 保留默认值，避免全局提高每会话上限。临时表密集任务应隔离运行或局部调整。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把临时表缓冲与排序、哈希产生的临时文件混淆。
  • 会话已经访问临时表之后才执行 SET。
  • 忽略大量会话同时使用临时表时的乘数效应。
  • 认为大值会立即全部分配；实际数据页按需增长，但描述符仍有开销。

关联参数

work_mem · temp_file_limit · temp_tablespaces · max_connections · log_temp_files

参考资料

12.47 - temp_file_limit

限制单个进程在同一时刻由执行器临时文件占用磁盘空间的安全阀。
说明

Fact — 官方简述译文：限制每个 PostgreSQL 进程使用的全部临时文件总大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值kB
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Disk
上游分类
最后 boot 值 值-1
-1 kB

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 23e5b16c71f2 — Add temp_file_limit GUC parameter to constrain temporary file space usage.
提交日期 2011-07-17
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 -1 kB -1 kB

机制详解

temp_file_limit 限制单个 PostgreSQL 进程在同一时刻拥有的临时文件总大小，包括排序与哈希落盘文件以及保持游标的存储；超过上限会取消事务。

它是每进程而非全局限制，因此并发后端与并行工作进程的合计占用可以达到该值的许多倍。默认值 -1 表示无限制。

显式临时表占用不计入此限制。log_temp_files 与 pg_stat_database.temp_bytes 可以观察相关临时文件活动，但不会改变限制边界。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按文件系统余量与最坏并发落盘数设置有限安全阀，并监控 temp_bytes 与 log_temp_files，使上限拦截异常查询而不是正常峰值。
OLAP 为已知的大型连接和排序提供更大但仍有限的预算，并与查询并发和并行度联动；依赖该限制前先测试取消行为。
小规格 选择数据文件系统的较小比例并保留应急空间。较低 temp_file_limit 应与保守 work_mem 和查询超时配套。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
OLAP 20GB 不同于 boot 值 {{ ([pg_size_twentieth * 4, 2000])|min }}GB
CRIT 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
TINY 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = 5GB (dcs)；OLAP: PG9.2–19 Beta 3 = 20GB (dcs)；CRIT: PG9.2–19 Beta 3 = 5GB (dcs)；TINY: PG9.2–19 Beta 3 = 5GB (dcs)。 建议（待人工复核）——编辑推断：这些值充当每进程熔断线，同时为分析落盘提供更大空间；多进程合计风险仍需容量复核。

常见坑

  • 把每进程限制当作整个集群的磁盘上限。
  • 期待它约束显式临时表，而这部分并不计入。
  • 在共享文件系统上保留 -1，让单条失控查询可能耗尽空间。
  • 把上限设得低于正常落盘规模，最终通过事务取消才发现。

关联参数

work_mem · hash_mem_multiplier · log_temp_files · temp_tablespaces · max_parallel_workers_per_gather

参考资料

12.48 - timing_clock_source

timing_clock_source：控制收集计时测量时使用的时钟来源。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 auto，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：控制收集计时测量时使用的时钟来源。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值auto, system, tsc
非枚举类型记为 —
分类 值Resource Usage / Time
上游分类
最后 boot 值 值auto
auto

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 294520c44487 — instrumentation: Use Time-Stamp Counter on x86-64 to lower overhead
提交日期 2026-04-07
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 auto — auto

机制详解

timing_clock_source：控制收集计时测量时使用的时钟来源。运行时只有超级用户或获得相应 SET 授权的角色可以修改。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

auto 会在合适的 x86-64 CPU 上选择时间戳计数器，否则使用操作系统单调时钟；system 强制系统时钟，tsc 请求 RDTSC/RDTSCP 等 CPU 指令。快速时钟可降低 EXPLAIN ANALYZE 的测量开销，但模拟或不稳定的 TSC 可能更慢甚至产生无效结果。

应与 track_io_timing、track_wal_io_timing、log_executor_stats、compute_query_id 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 必须在生产存储栈与真实并发下测试，优化尾延迟和队列深度，而不只看平均吞吐，并为 WAL、检查点与前台读取保留容量。
OLAP 使用有代表性的扫描、预取与落盘阶段；只有吞吐继续提升且 CPU、内存与存储没有不可接受的饱和时，才增加并发或 worker 容量。
小规格 优先采用 auto 或上游 worker 上限，并按场景使用 pg_test_timing 或 I/O 统计验证；小节点上的大进程池可能只增加上下文切换。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 timing_clock_source 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 superuser context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

track_io_timing · track_wal_io_timing · log_executor_stats · compute_query_id

参考资料

12.49 - transaction_buffers

transaction_buffers：设置事务状态缓存专用缓冲池的大小。实测在档范围为 PG17–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 B (0 × 8kB)，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置事务状态缓存专用缓冲池的大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值0 – 131072
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值0
0 B (0 × 8kB)

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 53c2a97a9266 — Improve performance of subsystems on top of SLRU
提交日期 2024-02-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 0 8kB 0 B (0 × 8kB)

机制详解

transaction_buffers 为 pg_xact 分配专用共享缓冲池，用于缓存事务提交状态页面。这是启动时真实共享内存，不是规划器估算。

零表示自动计算：PostgreSQL 按 shared_buffers/512 推导，并限制在 16 到 1024 个块之间。单位是 BLCKSZ 块，通常为 8kB。

更大缓存可在底层功能负载异常高时减少 SLRU 读写抖动，但会永久消耗共享内存，也不会提高该功能的逻辑容量。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非特定 SLRU I/O 与竞争证明缓存不足，否则让 transaction_buffers 保持自动或上游大小；提高后会在整个服务器生命周期占用共享内存。
OLAP 仅凭“分析负载”标签不能调整 transaction_buffers；只有底层事务状态设施而非表扫描成为实测瓶颈时才考虑。
小规格 小主机上保留 transaction_buffers 默认值。没有直接证据就把稀缺共享内存移入内部缓存，会挤压更有价值的缓存与进程空间。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 transaction_buffers 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

subtransaction_buffers · shared_buffers · commit_timestamp_buffers

参考资料

12.50 - vacuum_buffer_usage_limit

vacuum_buffer_usage_limit：设置 VACUUM、ANALYZE 与 autovacuum 的缓冲区访问环大小。实测在档范围为 PG16–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2 MiB，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM、ANALYZE 与 autovacuum 的缓冲区访问环大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值0 – 16777216
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值2048
2 MiB

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 1cbbee033857 — Add VACUUM/ANALYZE BUFFER_USAGE_LIMIT option
提交日期 2023-04-07
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16 256 kB 256 KiB
PG17–19 Beta 3 2048 kB 2 MiB

机制详解

vacuum_buffer_usage_limit 设置 VACUUM、ANALYZE 与 autovacuum 使用的共享缓冲区访问策略环大小。它不是私有内存分配，也不限制这些操作一共能触碰多少缓冲区。

非零值会被静默限制为 shared_buffers 的八分之一；零允许不受环限制地使用共享缓冲区。该环在扫描期间反复复用，同时减少驱逐无关热点页面。

较大环可能提高维护吞吐，也会挤掉更多有用缓存。VACUUM 与 ANALYZE 可用 BUFFER_USAGE_LIMIT 按命令覆盖；启动默认从 PG16 的 256kB 提高到 PG17 的 2MB。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在并发下定位到对应资源瓶颈后才修改 vacuum_buffer_usage_limit。应预算总内存、I/O、磁盘或内核容量，而不是孤立优化一个进程。
OLAP 使用代表性的批处理与扫描阶段测试 vacuum_buffer_usage_limit，同时观察持续吞吐、落盘/回写及对其他会话的干扰，不能只看单次操作耗时。
小规格 小主机上应保守设置 vacuum_buffer_usage_limit；证据不足时优先上游默认。照搬大服务器取值可能占用不成比例的资源。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 vacuum_buffer_usage_limit 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

shared_buffers · maintenance_work_mem · autovacuum_work_mem · maintenance_io_concurrency · track_io_timing

参考资料

12.51 - work_mem

控制排序及其他查询工作区何时开始落盘到临时文件的单个执行操作内存预算。
说明

Fact — 官方简述译文：设置查询工作区可使用的最大内存。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Resource Usage / Memory
上游分类
最后 boot 值 值4096
4 MiB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.3 1024 kB 1 MiB
PG9.4–19 Beta 3 4096 kB 4 MiB

机制详解

work_mem 是每个执行操作的基础上限，不是整条查询或整个会话的内存预留。一份复杂计划可以同时执行多个排序或哈希操作，多个会话也可并发执行，因此总内存可能是配置值的许多倍。

ORDER BY、DISTINCT 与归并连接使用的排序通常先消耗 work_mem，超过后才落盘。哈希连接、哈希聚合、Memoize 节点以及 IN 子查询的哈希处理，则以 work_mem 乘以 hash_mem_multiplier 计算内存上限。

并行查询还会放大风险，因为 work_mem 这类资源限制分别应用到各个工作进程。评估它时必须同时考虑执行计划形态、并行度与活跃查询并发数。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 集群全局值应偏保守，并按峰值活跃后端而非单看连接上限估算。对已知报表任务，在确认实际落盘行为后使用事务、角色或数据库级覆盖。
OLAP 较大取值可以减少昂贵的排序与哈希落盘，但必须同时给出并发预算。每次调整前后都应比较 EXPLAIN (ANALYZE, BUFFERS) 与临时文件统计。
小规格 优先保留默认值或较低的几十 MiB，并为 shared buffers、autovacuum、操作系统与其他进程留出余量；小机器不适合全局设置一个宽松的大值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 64MB 不同于 boot 值 {{ pg_workmem }}MB
OLAP 64MB 不同于 boot 值 {{ pg_workmem }}MB
CRIT 64MB 不同于 boot 值 {{ pg_workmem }}MB
TINY 32MB 不同于 boot 值 {{ pg_workmem }}MB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 64MB (dcs)；OLAP: PG9.0–19 Beta 3 = 64MB (dcs)；CRIT: PG9.0–19 Beta 3 = 64MB (dcs)；TINY: PG9.0–19 Beta 3 = 32MB (dcs)。 建议（待人工复核）——编辑推断：该公式意在减少落盘与控制并发最坏内存之间折中。

常见坑

  • 把 work_mem 当作每连接或每查询总上限；它通常可供每个符合条件的计划操作分别使用。
  • 忽略并行工作进程也会分别获得 work_mem 预算。
  • 为解决哈希落盘而提高 work_mem，却没有计入 hash_mem_multiplier。
  • 误以为它控制临时表缓冲；临时表使用的是 temp_buffers。

关联参数

hash_mem_multiplier · temp_file_limit · log_temp_files · max_connections · max_parallel_workers_per_gather

参考资料

13 - 统计信息

Statistics 分类下的 14 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

13.1 - compute_query_id

compute_query_id：启用 PostgreSQL 内核计算查询标识符。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 auto，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：启用 PostgreSQL 内核计算查询标识符。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值auto, regress, on, off
非枚举类型记为 —
分类 值Statistics / Monitoring
上游分类
最后 boot 值 值auto
auto

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 5fd9dfa5f50e — Move pg_stat_statements query jumbling to core.
提交日期 2021-04-07
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 auto — auto

机制详解

compute_query_id 控制 PostgreSQL 内核生成的规范化查询标识符。该标识可出现在 pg_stat_activity、EXPLAIN 与日志中；除非其他模块负责计算，pg_stat_statements 也需要它。

auto 允许模块请求内核计算，on 始终计算，off 禁止计算，regress 与 auto 相同但为稳定回归输出而不在 EXPLAIN 显示 ID。

只能有一个 provider 计算标识。采用其他算法的扩展必须关闭内核实现并检测冲突，不能静默发布两个不兼容 ID。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP pg_stat_statements 等模块应按需请求内核 ID 时使用 auto；没有此类模块但日志、EXPLAIN 或监控仍需要 ID 时才用 on。应在峰值解析/规划速率下测查询规范化开销。
OLAP auto 或 on 可把长分析语句在 pg_stat_activity、EXPLAIN 与日志间关联。主要成本是查询树规范化与哈希，不是时钟读取；超大语句负载应比较规划 CPU。
小规格 除非外部 query-ID provider 要求 off，否则保留 auto。regress 用于稳定回归输出，不是更小的生产取值；off 会移除 pg_stat_statements 等工具需要的 ID。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 内核 provider 与扩展同时尝试计算不同查询标识。
  • 设置 off 后静默丢失 pg_stat_statements、日志或关联工具需要的 ID。
  • 把 regress 当作生产优化，而不是测试输出模式。
  • 把 query ID 当成跨大版本稳定或具备密码学性质的标识。

关联参数

track_activities · shared_preload_libraries · log_line_prefix · track_activity_query_size

参考资料

13.2 - log_executor_stats

log_executor_stats：把执行器性能统计写入服务器日志。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：把执行器性能统计写入服务器日志。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Monitoring
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_executor_stats 使用类似 getrusage 的粗粒度分析器，为每条查询输出执行阶段资源使用，结果进入服务器日志，适合短时间诊断。

log_statement_stats 报告整条语句，parser、planner 与 executor 开关分别报告各阶段；总开关不能与任何分阶段开关同时启用。

这是同步诊断日志，不是累计统计系统；其数量与格式都不适合作为常规生产遥测。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把 log_executor_stats 当作常规 OLTP 调优。只在隔离复现或受控会话中短暂启用，取得所需日志后立即关闭。
OLAP 对特定分析语句，EXPLAIN (ANALYZE, BUFFERS) 与累计视图通常比全局 log_executor_stats 更可操作；若使用必须限定范围并预算日志量。
小规格 保持 log_executor_stats=off。小主机尤其容易受到诊断日志 I/O 与磁盘写满影响。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 启用或扩大 log_executor_stats 前没有测量收集与观察开销。
  • 把统计收集语义误认为性能控制或 I/O 控制。
  • 认为长事务内看到的所有统计都会立即更新。
  • 收集敏感查询文本或标识，却没有匹配的访问与保留策略。

关联参数

log_statement_stats · log_parser_stats · log_planner_stats · log_min_duration_statement · track_io_timing

参考资料

13.3 - log_parser_stats

log_parser_stats：把解析器性能统计写入服务器日志。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：把解析器性能统计写入服务器日志。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Monitoring
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_parser_stats 使用类似 getrusage 的粗粒度分析器，为每条查询输出解析阶段资源使用，结果进入服务器日志，适合短时间诊断。

log_statement_stats 报告整条语句，parser、planner 与 executor 开关分别报告各阶段；总开关不能与任何分阶段开关同时启用。

这是同步诊断日志，不是累计统计系统；其数量与格式都不适合作为常规生产遥测。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把 log_parser_stats 当作常规 OLTP 调优。只在隔离复现或受控会话中短暂启用，取得所需日志后立即关闭。
OLAP 对特定分析语句，EXPLAIN (ANALYZE, BUFFERS) 与累计视图通常比全局 log_parser_stats 更可操作；若使用必须限定范围并预算日志量。
小规格 保持 log_parser_stats=off。小主机尤其容易受到诊断日志 I/O 与磁盘写满影响。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 启用或扩大 log_parser_stats 前没有测量收集与观察开销。
  • 把统计收集语义误认为性能控制或 I/O 控制。
  • 认为长事务内看到的所有统计都会立即更新。
  • 收集敏感查询文本或标识，却没有匹配的访问与保留策略。

关联参数

log_statement_stats · log_planner_stats · log_executor_stats · log_min_duration_statement

参考资料

13.4 - log_planner_stats

log_planner_stats：把规划器性能统计写入服务器日志。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：把规划器性能统计写入服务器日志。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Monitoring
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_planner_stats 使用类似 getrusage 的粗粒度分析器，为每条查询输出规划阶段资源使用，结果进入服务器日志，适合短时间诊断。

log_statement_stats 报告整条语句，parser、planner 与 executor 开关分别报告各阶段；总开关不能与任何分阶段开关同时启用。

这是同步诊断日志，不是累计统计系统；其数量与格式都不适合作为常规生产遥测。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把 log_planner_stats 当作常规 OLTP 调优。只在隔离复现或受控会话中短暂启用，取得所需日志后立即关闭。
OLAP 对特定分析语句，EXPLAIN (ANALYZE, BUFFERS) 与累计视图通常比全局 log_planner_stats 更可操作；若使用必须限定范围并预算日志量。
小规格 保持 log_planner_stats=off。小主机尤其容易受到诊断日志 I/O 与磁盘写满影响。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 启用或扩大 log_planner_stats 前没有测量收集与观察开销。
  • 把统计收集语义误认为性能控制或 I/O 控制。
  • 认为长事务内看到的所有统计都会立即更新。
  • 收集敏感查询文本或标识，却没有匹配的访问与保留策略。

关联参数

log_statement_stats · log_parser_stats · log_executor_stats · log_min_duration_statement · join_collapse_limit

参考资料

13.5 - log_statement_stats

log_statement_stats：把语句累计性能统计写入服务器日志。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：把语句累计性能统计写入服务器日志。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Monitoring
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

log_statement_stats 使用类似 getrusage 的粗粒度分析器，为每条查询输出整条语句的资源使用，结果进入服务器日志，适合短时间诊断。

log_statement_stats 报告整条语句，parser、planner 与 executor 开关分别报告各阶段；总开关不能与任何分阶段开关同时启用。

这是同步诊断日志，不是累计统计系统；其数量与格式都不适合作为常规生产遥测。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把 log_statement_stats 当作常规 OLTP 调优。只在隔离复现或受控会话中短暂启用，取得所需日志后立即关闭。
OLAP 对特定分析语句，EXPLAIN (ANALYZE, BUFFERS) 与累计视图通常比全局 log_statement_stats 更可操作；若使用必须限定范围并预算日志量。
小规格 保持 log_statement_stats=off。小主机尤其容易受到诊断日志 I/O 与磁盘写满影响。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 启用或扩大 log_statement_stats 前没有测量收集与观察开销。
  • 把统计收集语义误认为性能控制或 I/O 控制。
  • 认为长事务内看到的所有统计都会立即更新。
  • 收集敏感查询文本或标识，却没有匹配的访问与保留策略。

关联参数

log_parser_stats · log_planner_stats · log_executor_stats · log_min_duration_statement · track_functions

参考资料

13.6 - stats_fetch_consistency

stats_fetch_consistency：设置读取累计统计信息时的一致性方式。实测在档范围为 PG15–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 cache，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置读取累计统计信息时的一致性方式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值none, cache, snapshot
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值cache
cache

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 5891c7a8ed8f — pgstat: store statistics in shared memory.
提交日期 2022-04-06
Discussion 讨论 1 · 讨论 2 · 讨论 3

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 cache — cache

机制详解

stats_fetch_consistency 定义同一事务内重复读取累计统计的行为。none 每次重新取对象，cache 首次读取后缓存该对象，snapshot 首次访问时物化当前数据库全部可见统计。

缓存或快照持续到事务结束或调用 pg_stat_clear_snapshot()；事务内修改该参数会丢弃当前统计快照。

none 适合每个计数只读一次的监控查询；cache 保证同一对象重复读取稳定；snapshot 提供一致的交互视图，但对象很多时开销更高。其 user 上下文允许按会话或事务局部修改，之后执行或重新规划的工作会读取新值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 普通 SQL 使用 cache；每项只读一次的抓取查询使用 none；只有明确需要一致观察时才用 snapshot，且不要让监控事务无限保持。
OLAP 对象很多时 snapshot 代价较高；应按监控查询访问模式选择 stats_fetch_consistency，不能只看负载标签。
小规格 保留 cache，除非简单单遍采集器能从 none 获益。该参数改变读取语义，不改变收集准确性，也不会减少底层计数开销。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 启用或扩大 stats_fetch_consistency 前没有测量收集与观察开销。
  • 把统计收集语义误认为性能控制或 I/O 控制。
  • 认为长事务内看到的所有统计都会立即更新。
  • 收集敏感查询文本或标识，却没有匹配的访问与保留策略。

关联参数

track_counts · track_activities · track_io_timing · track_functions

参考资料

13.7 - stats_temp_directory

stats_temp_directory：设置旧统计收集器写临时统计文件的目录。实测在档范围为 PG9.0–14；最后在档的 PG14 启动默认值为 pg_stat_tmp，context 为 sighup。它在 PG15 被移除。
说明

Fact — 官方简述译文：设置旧统计收集器写临时统计文件的目录。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Query and Index Statistics Collector
上游分类
最后 boot 值 值pg_stat_tmp
pg_stat_tmp

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–14
移除版本 PG15
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–14 pg_stat_tmp — pg_stat_tmp

机制详解

PG14 及以前，stats_temp_directory 选择旧统计收集器写临时统计文件的目录；它不保存 ANALYZE 生成的持久列统计。

快速的本地内存目录可减少收集器文件 I/O，且临时内容丢失是可接受的，但权限与目录可用性仍必须让服务器正常工作。

PostgreSQL 15 用共享内存累计统计替换基于文件的收集器架构，并移除该 GUC。迁移到 PG15+ 时应删除配置，而不是映射到另一个目录。其 SIGHUP 上下文允许通过重载配置生效，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前 PostgreSQL 不应调优 stats_temp_directory：升级目标中应删除它，并采用上文所述当前替代行为；只有复现历史版本时才保留。
OLAP 不要把 stats_temp_directory 带入现代分析集群，应测试受支持的当前机制，而不是模拟已移除实现细节。
小规格 版本迁移时删除 stats_temp_directory；它更可能造成未知参数启动失败，而不是带来收益。历史测试实例应保留旧版本上游默认。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG14 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–14 未修改；OLAP: PG9.0–14 未修改；CRIT: PG9.0–14 未修改；TINY: PG9.0–14 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 修改 stats_temp_directory 时忽略文档单位与配置生效上下文。
  • 只优化孤立基准，却忽略并发后的资源总量。
  • 认为配置值能够保证操作系统或存储层实际行为。
  • 修改后没有重新验证启动、故障转移与负载延迟。

关联参数

stats_fetch_consistency · track_counts · track_activities · data_directory

参考资料

13.8 - track_activities

track_activities：收集会话当前执行命令的信息。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：收集会话当前执行命令的信息。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

track_activities 为 pg_stat_activity 记录每个会话的当前命令、查询标识与时间元数据；即使启用收集，访问仍受权限过滤。

关闭会失去关键实时可观测性，但不会终止命令，也不会直接让命令更快。每会话保存的文本受 track_activity_query_size 限制。

获授权用户可以修改该开关，因此监控应识别主动禁用活动报告的会话。它与 track_counts 控制的累计计数相互独立。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 生产环境保持 on，让 pg_stat_activity 提供事故响应所需的当前命令、query ID 与时间信息。应限制视图权限，并单独设置 track_activity_query_size，而不是通过关闭活动收集隐藏文本。
OLAP 长分析会话保持 on；资源竞争时实时阶段与等待上下文尤其重要。若怀疑开销，应先明确测量，再决定是否接受 off 带来的可观测性损失。
小规格 保持 on。它是布尔收集开关，不是缓冲区大小；若要减少查询文本内存，应单独调整 track_activity_query_size，并保留足够诊断文本。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 关闭后丢失诊断阻塞或失控会话所需的当前命令证据。
  • 把实时活动收集与 track_counts 控制的累计计数混为一谈。
  • 认为 on 会让每个角色看到所有会话查询文本；可见性仍受权限过滤。
  • 忽略获授权会话可在允许的上下文中关闭自身活动报告。

关联参数

track_activity_query_size · track_counts · compute_query_id · log_line_prefix · log_min_duration_statement

参考资料

13.9 - track_activity_query_size

track_activity_query_size：设置 pg_stat_activity.query 预留的字节数。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 KiB，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 pg_stat_activity.query 预留的字节数。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值B
原始单位
范围 值100 – 1048576
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值1024
1 KiB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–10 1024 — 1024
PG11–19 Beta 3 1024 B 1 KiB

机制详解

track_activity_query_size 为每个活动会话在 pg_stat_activity.query 中保存的当前查询文本实际预留共享内存，单位为字节，并在服务器启动时固定。

长语句会按该存储大小截断；提高它能改善故障上下文，但内存会乘以后端名额数，包括已配置连接容量。

它不改变日志语句长度、pg_stat_statements 查询文本存储或应用 payload 限制。compute_query_id 可用时，查询标识能把截断文本与其他遥测关联。其 postmaster 上下文在服务器启动时固定取值，修改后必须重启。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 选择足以保留诊断价值 SQL 的字节数，再按全部后端名额而不是仅活动查询预算近似存储。提高它属于启动共享内存决策，修改后必须重启。
OLAP 很长的生成 SQL 往往需要超过 1kB 才能保持可识别。应把截断频率与事故需求同“取值乘以 MaxBackends”比较；该参数消耗内存，不产生反复读取时钟的开销。
小规格 使用仍能保留有效语句身份的最小值。不能未经乘以小主机连接与 worker 名额，就照搬 crit 模板的 32kB。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 8192 不同于 boot 值 8192
OLAP 8192 不同于 boot 值 8192
CRIT 32768 不同于 boot 值 32768
TINY 8192 不同于 boot 值 8192
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 8192 (dcs)；OLAP: PG9.0–19 Beta 3 = 8192 (dcs)；CRIT: PG9.0–19 Beta 3 = 32768 (dcs)；TINY: PG9.0–19 Beta 3 = 8192 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：模板比上游保留更多查询文本，crit 的更大值意在保存更完整的诊断上下文。

常见坑

  • 把它当成只为当前活动查询使用的内存，而不是跨后端名额预留的存储。
  • 忘记单位是字节；多字节查询文本可容纳的字符数会少于字节数直觉。
  • 期待它改变日志语句长度或 pg_stat_statements 查询文本存储。
  • 修改后没有执行必需的服务器重启。

关联参数

track_activities · max_connections · compute_query_id · log_line_prefix · shared_buffers

参考资料

13.10 - track_cost_delay_timing

track_cost_delay_timing：收集基于成本的 vacuum 延迟计时。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：收集基于成本的 vacuum 延迟计时。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 bb8dff9995f2 — Add cost-based vacuum delay time to progress views.
提交日期 2025-02-11
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 off — off

机制详解

track_cost_delay_timing 测量 VACUUM 与 ANALYZE 因成本限速实际休眠的时间，并出现在进度视图、详细命令输出与符合条件的 autovacuum 日志中。

收集会反复读取操作系统时钟，开销依平台而异。它不会启用 vacuum delay，也不会改变 vacuum_cost_* 策略。

该指标用于区分实际工作与有意节流。广泛启用前可用 pg_test_timing 测量读取时钟的开销。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 需要区分 VACUUM/ANALYZE 实际工作与有意 cost-delay 休眠时启用。用 pg_test_timing 和 autovacuum 负载测时钟读取开销；它是布尔值，不设置大小，也不会自行启用成本延迟。
OLAP 长维护与分析工作重叠、需要量化节流时间时有用。应把报告的延迟时间与维护总时长、前台延迟一起比较，并且只有运维真正使用该证据时才长期开启。
小规格 除非需要 vacuum-delay 诊断且平台时钟读取足够便宜，否则保持 off。启用本身不改变维护节流策略；vacuum_cost_* 参数仍然独立。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 = on (dcs)；CRIT: PG18–19 Beta 3 = on (dcs)；TINY: PG18–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：仅 OLAP/crit 启用意在长维护或关键可观测场景暴露 vacuum/analyze 成本延迟时间，并接受读取时钟的开销。

常见坑

  • 误以为该开关会启用成本型 vacuum delay，而不是只计时已有延迟。
  • 不使用 pg_test_timing 测量，就忽略平台相关的时钟读取开销。
  • 没有启用相关进度、verbose 或 autovacuum 日志输出，却寻找该指标。
  • 把布尔值当成时长或缓冲区尺寸参数。

关联参数

vacuum_cost_delay · autovacuum_vacuum_cost_delay · log_autovacuum_min_duration · track_io_timing · vacuum_buffer_usage_limit

参考资料

13.11 - track_counts

track_counts：收集数据库活动累计统计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：收集数据库活动累计统计。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

track_counts 为 PostgreSQL 的数据库、表与索引累计活动计数提供数据；autovacuum 依赖这些计数决定何时 vacuum 与 analyze。

关闭会移除规划与维护遥测，并可能阻止正常 autovacuum 触发；它本身不会重置已经保存的计数。

统计通过 pg_stat 视图暴露，并遵守 stats_fetch_consistency 的快照规则。收集是服务器级的，但可见性仍受权限控制。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 track_counts=on；正常 autovacuum 与容量监控依赖它。只有不代表生产配置的受控实验才可关闭。
OLAP 即使以批查询为主，也应保持 track_counts=on 以支持维护决策；失去 autovacuum 输入换来的微小节省不值得。
小规格 保持 track_counts=on；小系统同样需要 autovacuum 与表活动可见性，关闭后节省的少量开销通常不值得。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 启用或扩大 track_counts 前没有测量收集与观察开销。
  • 把统计收集语义误认为性能控制或 I/O 控制。
  • 认为长事务内看到的所有统计都会立即更新。
  • 收集敏感查询文本或标识，却没有匹配的访问与保留策略。

关联参数

autovacuum · stats_fetch_consistency · track_activities · default_statistics_target · log_autovacuum_min_duration

参考资料

13.12 - track_functions

track_functions：收集函数调用次数与耗时统计。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 none，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：收集函数调用次数与耗时统计。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值none, pl, all
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值none
none

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 none — none

机制详解

track_functions 在 pl 模式统计过程语言函数调用与耗时，在 all 模式还包括 SQL/C 函数；none 关闭函数级累计统计。

被规划器内联的简单 SQL 函数会并入调用者，无论本值如何都不会单独统计。嵌套函数时间按统计系统的 total/self 规则报告。

all 扩大插桩范围，在函数密集负载上可能增加开销；计数为累计值，通过 pg_stat_user_functions 等视图观察。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非函数级调用次数与耗时能回答明确生产问题，否则保持 none。用 pl 把插桩限制到过程语言；只有在函数密集流量上测过开销后才用 all。
OLAP 需要把函数内部时间与调用者时间分开时，可在限时分析中启用 pl 或 all。简单 SQL 函数可能被内联而不可见，因此视图中没有记录不能证明未执行。
小规格 优先 none 或短时局部诊断。该枚举控制插桩范围，不是数值采样率；CPU 受限主机上 all 的开销可能占比很高。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP all 不同于 boot 值 all
OLAP all 不同于 boot 值 all
CRIT all 不同于 boot 值 all
TINY all 不同于 boot 值 all
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = all (dcs)；OLAP: PG9.0–19 Beta 3 = all (dcs)；CRIT: PG9.0–19 Beta 3 = all (dcs)；TINY: PG9.0–19 Beta 3 = all (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：显式 all 在所有模板最大化函数级可观测性，同时接受插桩开销与 SQL 内联盲区。

常见坑

  • 期待被内联的 SQL 语言函数出现在函数统计中。
  • 没有测量函数密集负载的插桩开销就全局启用 all。
  • 读取累计 total/self 时间时忽略嵌套调用与统计快照行为。
  • 把 none、pl、all 当作采样等级，而不是不同插桩范围。

关联参数

track_counts · stats_fetch_consistency · compute_query_id · jit_expressions · log_statement_stats

参考资料

13.13 - track_io_timing

track_io_timing：收集数据库 I/O 等待计时。实测在档范围为 PG9.2–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：收集数据库 I/O 等待计时。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.2
在档版本 PG9.2–19 Beta 3
移除版本 否
引入提交 309c64745ea1 — Rename track_iotiming GUC to track_io_timing.
提交日期 2012-04-29
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.2–19 Beta 3 off — off

机制详解

track_io_timing 测量 WAL 对象以外的数据库 I/O 等待时间，并填充 pg_stat_database、pg_stat_io、pg_stat_get_backend_io()、带 BUFFERS 的 EXPLAIN、维护输出与相关扩展。

该设置会反复读取操作系统时钟，开销依平台而异，可用 pg_test_timing 测量；记录的是等待经过时间，不是纯设备服务时间。

WAL I/O 由 track_wal_io_timing 单独控制。启用计时只增加可观测性，不会让 I/O 异步化，也不会改变规划成本。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP pg_stat_io、带 BUFFERS 的 EXPLAIN 或事故分析需要数据库 I/O 等待时间时启用。用 pg_test_timing 与峰值语句速率测时钟开销；Pigsty 的 on 是可观测性选择，不是吞吐调优数值。
OLAP 长扫描与落盘会让关系和临时文件计时很有价值。只有这些计数真正用于诊断时才长期开启，并比较执行开销，区分经过等待与纯设备服务时间。
小规格 只有平台时钟读取成本可接受且指标有人使用时才用 on。该布尔值没有“保守数值大小”；off 只移除计时，不会移除 I/O。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.2–19 Beta 3 = on (dcs)；OLAP: PG9.2–19 Beta 3 = on (dcs)；CRIT: PG9.2–19 Beta 3 = on (dcs)；TINY: PG9.2–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：显式 on 与源码注释“收集 I/O 统计”的目标一致，并接受依平台而异的时钟开销。

常见坑

  • 把等待经过时间当成不含排队和调度影响的纯设备服务时间。
  • 期待该开关让 I/O 异步化或改变规划器成本估计。
  • 误以为它包含 WAL 计时；WAL 由 track_wal_io_timing 控制。
  • 没有在实际平台测量时钟读取开销就启用。

关联参数

track_wal_io_timing · track_counts · stats_fetch_consistency · effective_io_concurrency · compute_query_id

参考资料

13.14 - track_wal_io_timing

track_wal_io_timing：收集 WAL I/O 等待计时。实测在档范围为 PG14–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：收集 WAL I/O 等待计时。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Statistics / Cumulative Query and Index Statistics
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 ff99918c625a — Track total amounts of times spent writing and syncing WAL data to disk.
提交日期 2021-03-09
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 off — off

机制详解

track_wal_io_timing 测量 WAL I/O 等待，并在 pg_stat_io 与 pg_stat_get_backend_io() 的 wal 对象下暴露；它与普通数据库 I/O 计时相互独立。

收集会反复读取操作系统时钟，可能产生依平台而异的开销。pg_test_timing 可测时钟读取成本，负载测试则反映总影响。

它不会改变 wal_sync_method、持久性或 WAL 吞吐。与 track_io_timing 配合可把 WAL 等待与关系/临时文件 I/O 分开。其 superuser 上下文允许获授权会话修改，无需重启服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 分析提交延迟、需要把 WAL write/sync 等待与关系 I/O 分开时启用。测量平台时钟开销，并把计数与 synchronous_commit、wal_sync_method 和存储行为关联。
OLAP 读密集分析可能很少受益，而批量导入与刷新任务的写阶段可能很有价值。应按真正使用证据的写阶段启用，而不是仅因负载标签是 OLAP。
小规格 除非正在诊断 WAL 延迟且时钟读取便宜，否则保持 off。只有需要同时区分 WAL 与非 WAL 等待时，才与 track_io_timing 配合。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待 WAL 计时包含 track_io_timing 测量的关系与临时文件 I/O。
  • 把 WAL 等待经过时间当成纯设备服务时间。
  • 认为该开关会改变持久性、wal_sync_method 或 WAL 吞吐。
  • 没有在生产平台测量时钟读取开销就启用。

关联参数

track_io_timing · wal_sync_method · synchronous_commit · track_counts · stats_fetch_consistency

参考资料

14 - 清理与冻结

Vacuuming 分类下的 34 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

14.1 - autovacuum

Autovacuum 通过后台调度 VACUUM 与 ANALYZE 维持 MVCC 表的可用状态。它既是性能机制，也是防止事务号回卷的安全网，并非可有可无的清洁任务。
说明

Fact — 官方简述译文：控制 PostgreSQL 是否运行自动清理启动器。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

启用后，一个 launcher 在各数据库之间协调多个 worker。Worker 依据累计的表变更统计判断是否执行 VACUUM 或 ANALYZE，因此普通自动清理还依赖 track_counts 开启。

常规触发条件响应插入、更新与删除产生的变更。除此之外，即使关闭本参数，PostgreSQL 仍会在必要时启动防回卷 autovacuum，因为旧事务号或 multixact 回卷会威胁数据正确性。

多数触发阈值与成本参数可通过表级 storage parameter 覆盖。临时表无法由 autovacuum 访问；分区会被正常处理，但分区父表仍可能需要手工 ANALYZE。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持开启。优先按热点表单独调优，并结合死元组、autovacuum 时长、worker 被取消情况和 XID 年龄判断是否需要全局加速。
OLAP 为安全起见保持开启，但应与批量装载窗口协调；大批导入后主动 ANALYZE，需要父表统计时对分区父表单独执行 ANALYZE。
小规格 保持默认开启。若资源紧张，优先减少 worker 或降低特定表的积极程度，不要仅为节省少量后台活动而关闭 launcher。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 关闭它并不会关闭紧急的防回卷 autovacuum。
  • 普通 autovacuum 决策依赖 track_counts。
  • 长事务和陈旧复制槽可能让 worker 即使成功运行也无法回收旧版本。
  • 仅有分区发生变化时，autovacuum 不会自动分析分区父表。
  • 临时表必须由持有它的会话自行维护。

关联参数

autovacuum_max_workers · autovacuum_naptime · autovacuum_vacuum_scale_factor · autovacuum_analyze_scale_factor · autovacuum_freeze_max_age · track_counts

参考资料

14.2 - autovacuum_analyze_scale_factor

autovacuum_analyze_scale_factor：以 reltuples 的比例设置触发 ANALYZE 前的元组插入、更新或删除数量。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：以 reltuples 的比例设置触发 ANALYZE 前的元组插入、更新或删除数量。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 100
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值0.1
0.1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0.1 — 0.1

机制详解

以 reltuples 的比例设置触发 ANALYZE 前的元组插入、更新或删除数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

自动 ANALYZE 的触发量由固定项 autovacuum_analyze_threshold 加上 autovacuum_analyze_scale_factor × pg_class.reltuples 组成；插入、更新与删除都计入累计统计。表级 storage parameter 可覆盖全局值，统计是最终一致的估计。

应把 autovacuum_analyze_scale_factor 与 autovacuum_analyze_threshold、default_statistics_target、track_counts 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_analyze_scale_factor，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0.04 不同于 boot 值 0.04
OLAP 0.04 不同于 boot 值 0.04
CRIT 0.04 不同于 boot 值 0.04
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 0.04 (dcs)；OLAP: PG9.0–19 Beta 3 = 0.04 (dcs)；CRIT: PG9.0–19 Beta 3 = 0.04 (dcs)；TINY: PG9.0–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让持续增长的生产表更早刷新优化器统计；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum_analyze_threshold · default_statistics_target · track_counts · autovacuum · autovacuum_freeze_max_age · autovacuum_max_workers

参考资料

14.3 - autovacuum_analyze_score_weight

autovacuum_analyze_score_weight：设置 autovacuum 优先级中 ANALYZE 得分的缩放系数。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 优先级中 ANALYZE 得分的缩放系数。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
提交日期 2026-03-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 1 — 1

机制详解

autovacuum_analyze_score_weight：设置 autovacuum 优先级中 ANALYZE 得分的缩放系数。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PostgreSQL 19 会为每个候选表计算得分，并按加权分量的最大值安排工作。该参数乘在ANALYZE 变更压力分量上：大于 1 会提高其调度影响，0 到 1 会降低影响；把全部得分权重设为 0 可恢复 PG19 之前按目录顺序处理的策略。可通过 pg_stat_autovacuum_scores 检查各分量。

应与 autovacuum_freeze_score_weight、autovacuum_multixact_freeze_score_weight、autovacuum_vacuum_score_weight、autovacuum_vacuum_insert_score_weight 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先使用上游默认值，再依据 pg_stat_autovacuum_scores、表变更量、冻结年龄、排队与前台延迟决定是否修改。必须保护防回卷任务，避免偏爱忙表而饿死低流量表。
OLAP 批处理环境可能受益于优先处理最大维护债务或并行清理索引，但必须衡量整个维护窗口的 I/O 饱和、维护内存、worker 竞争与完成时间。
小规格 权重和并行度应保守；一个额外 worker 就可能占据很大比例的 CPU、内存与存储队列。先修正阈值，并确保 autovacuum 有足够时间完成。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 autovacuum_analyze_score_weight 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

autovacuum_freeze_score_weight · autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_max_workers · autovacuum_naptime

参考资料

14.4 - autovacuum_analyze_threshold

autovacuum_analyze_threshold：设置触发 ANALYZE 前元组插入、更新或删除数量的最低阈值。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 50，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置触发 ANALYZE 前元组插入、更新或删除数量的最低阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值50
50

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 50 — 50

机制详解

设置触发 ANALYZE 前元组插入、更新或删除数量的最低阈值。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

自动 ANALYZE 的触发量由固定项 autovacuum_analyze_threshold 加上 autovacuum_analyze_scale_factor × pg_class.reltuples 组成；插入、更新与删除都计入累计统计。表级 storage parameter 可覆盖全局值，统计是最终一致的估计。

应把 autovacuum_analyze_threshold 与 autovacuum_analyze_scale_factor、default_statistics_target、track_counts 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_analyze_threshold，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 250 不同于 boot 值 250
OLAP 500 不同于 boot 值 500
CRIT 250 不同于 boot 值 250
TINY 250 不同于 boot 值 250
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 250 (dcs)；OLAP: PG9.0–19 Beta 3 = 500 (dcs)；CRIT: PG9.0–19 Beta 3 = 250 (dcs)；TINY: PG9.0–19 Beta 3 = 250 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在避免极小变更就分析，同时给 OLAP 更大的固定门槛；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum_analyze_scale_factor · default_statistics_target · track_counts · autovacuum · autovacuum_freeze_max_age · autovacuum_max_workers

参考资料

14.5 - autovacuum_freeze_max_age

autovacuum_freeze_max_age：设置为防止事务 ID 回卷而强制自动清理表的年龄。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 200000000，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置为防止事务 ID 回卷而强制自动清理表的年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值100000 – 2000000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值200000000
200000000

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 200000000 — 200000000

机制详解

设置为防止事务 ID 回卷而强制自动清理表的年龄。该值在服务器启动时固定，修改后必须重启。

当表的 relfrozenxid 年龄越过该上限时，即使普通 autovacuum 已关闭，也会安排不可轻易取消的防回卷清理。提高上限会扩大维护窗口和旧 XID 元数据占用，并缩短从发现积压到回卷保护线之间的余量。

应把 autovacuum_freeze_max_age 与 vacuum_freeze_min_age、vacuum_freeze_table_age、vacuum_failsafe_age 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 以全库最大 XID/MXID 年龄、最旧表和清理完成速率校准 autovacuum_freeze_max_age；优先消除长事务、失效槽和被阻塞 worker，绝不能靠提高年龄掩盖积压。
OLAP 在批量窗口主动 VACUUM (FREEZE) 新装载/静态分区，并给全表扫描留 I/O 时间；年龄预算按峰值事务速率而不是墙钟经验换算。
小规格 保持上游默认通常最安全。容量较小不等于可关闭防回卷维护；监控所有数据库，而不只是当前业务库。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1000000000 不同于 boot 值 1000000000
OLAP 1000000000 不同于 boot 值 1000000000
CRIT 1000000000 不同于 boot 值 1000000000
TINY 1000000000 不同于 boot 值 1000000000
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 1000000000 (dcs)；OLAP: PG9.0–19 Beta 3 = 1000000000 (dcs)；CRIT: PG9.0–19 Beta 3 = 1000000000 (dcs)；TINY: PG9.0–19 Beta 3 = 1000000000 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在以更大的 XID 年龄运行窗口换取更少的强制防回卷清理；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 不按实际事务速率就把事务年龄换算成天数。
  • 用提高上限掩盖被阻塞或资源不足的 VACUUM。
  • 只监控当前数据库而漏掉其他数据库与表。
  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。

关联参数

vacuum_freeze_min_age · vacuum_freeze_table_age · vacuum_failsafe_age · autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age · vacuum_multixact_freeze_table_age

参考资料

14.6 - autovacuum_freeze_score_weight

autovacuum_freeze_score_weight：设置 autovacuum 优先级中事务 ID 冻结得分的缩放系数。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 优先级中事务 ID 冻结得分的缩放系数。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
提交日期 2026-03-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 1 — 1

机制详解

autovacuum_freeze_score_weight：设置 autovacuum 优先级中事务 ID 冻结得分的缩放系数。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PostgreSQL 19 会为每个候选表计算得分，并按加权分量的最大值安排工作。该参数乘在事务 ID 冻结年龄分量上：大于 1 会提高其调度影响，0 到 1 会降低影响；把全部得分权重设为 0 可恢复 PG19 之前按目录顺序处理的策略。可通过 pg_stat_autovacuum_scores 检查各分量。

应与 autovacuum_multixact_freeze_score_weight、autovacuum_vacuum_score_weight、autovacuum_vacuum_insert_score_weight、autovacuum_analyze_score_weight 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先使用上游默认值，再依据 pg_stat_autovacuum_scores、表变更量、冻结年龄、排队与前台延迟决定是否修改。必须保护防回卷任务，避免偏爱忙表而饿死低流量表。
OLAP 批处理环境可能受益于优先处理最大维护债务或并行清理索引，但必须衡量整个维护窗口的 I/O 饱和、维护内存、worker 竞争与完成时间。
小规格 权重和并行度应保守；一个额外 worker 就可能占据很大比例的 CPU、内存与存储队列。先修正阈值，并确保 autovacuum 有足够时间完成。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 autovacuum_freeze_score_weight 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

参考资料

14.7 - autovacuum_max_parallel_workers

autovacuum_max_parallel_workers：设置单个 autovacuum worker 可使用的最大并行 worker 数。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置单个 autovacuum worker 可使用的最大并行 worker 数。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 1024
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 1ff3180ca016 — Allow autovacuum to use parallel vacuum workers.
提交日期 2026-04-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 0 — 0

机制详解

autovacuum_max_parallel_workers：设置单个 autovacuum worker 可使用的最大并行 worker 数。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这个上限按单个 autovacuum worker 计算，只作用于索引清理与索引 cleanup 阶段。0 会禁用并行 autovacuum；实际数量还受 max_parallel_workers 限制，同时每个参与进程都会消耗 CPU 与维护内存。

应与 autovacuum_max_workers、autovacuum_worker_slots、max_parallel_workers、maintenance_work_mem 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先使用上游默认值，再依据 pg_stat_autovacuum_scores、表变更量、冻结年龄、排队与前台延迟决定是否修改。必须保护防回卷任务，避免偏爱忙表而饿死低流量表。
OLAP 批处理环境可能受益于优先处理最大维护债务或并行清理索引，但必须衡量整个维护窗口的 I/O 饱和、维护内存、worker 竞争与完成时间。
小规格 权重和并行度应保守；一个额外 worker 就可能占据很大比例的 CPU、内存与存储队列。先修正阈值，并确保 autovacuum 有足够时间完成。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 autovacuum_max_parallel_workers 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

autovacuum_max_workers · autovacuum_worker_slots · max_parallel_workers · maintenance_work_mem · autovacuum_work_mem

参考资料

14.8 - autovacuum_max_workers

设置集群内可同时运行的 autovacuum worker 上限，不包含 launcher。增加 worker 能提高调度容量，但也会提高并发维护的资源需求。
说明

Fact — 官方简述译文：限制可同时运行的 autovacuum worker 进程数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值1 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值3
3

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 3 — 3

机制详解

Launcher 在各数据库间启动 worker，直到达到该上限。每个 worker 同时处理一张表，多个 worker 可以位于同一数据库；这些进程不占用 max_connections 名额。

在 PostgreSQL 18 中，autovacuum worker 来自 autovacuum_worker_slots 预留池，因此本值高于 slot 数量也不会生效。本地事实矩阵还显示：PG10-17 需要重启，PG18 改为可重新加载。

多个 worker 活跃时，autovacuum 成本额度通常会在它们之间平衡。因此只提高 worker 数主要改善并发和排队，不一定成倍提高允许的总维护 I/O 速率。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在待处理表排队过久且存储仍有余量时才逐步增加，并同时观察 worker 饱和度、清理时长、I/O 延迟与 autovacuum_worker_slots。
OLAP 大表可能长期占据 worker，适量增加可减少跨库积压；同时应复核维护窗口和成本限流参数。
小规格 两到三个通常是合理起点。受限主机优先减少并发 worker，不要关闭 autovacuum。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 3 等于 boot 值 3
OLAP 3 等于 boot 值 3
CRIT 3 等于 boot 值 3
TINY 2 不同于 boot 值 2
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 3 (dcs)；OLAP: PG9.0–19 Beta 3 = 3 (dcs)；CRIT: PG9.0–19 Beta 3 = 3 (dcs)；TINY: PG9.0–19 Beta 3 = 2 (dcs)。 建议（待人工复核）——编辑推断（待维护者复核）：TINY 通过减少维护并发来控制 CPU 与 I/O 争用，其余模板保留保守的上游并发度。

常见坑

  • PG18 中高于 autovacuum_worker_slots 的部分不会生效。
  • 更多 worker 可能在缩短积压的同时放大 I/O 延迟。
  • 只提高 worker 数不一定提高成本限流下的总清理吞吐。
  • 少数大表可能占满全部 worker，拖延其他数据库。
  • PG10-17 修改后需重启；PG18 可重新加载。

关联参数

autovacuum · autovacuum_worker_slots · autovacuum_naptime · autovacuum_vacuum_cost_limit · autovacuum_vacuum_cost_delay · max_worker_processes

参考资料

14.9 - autovacuum_multixact_freeze_max_age

autovacuum_multixact_freeze_max_age：设置为防止 MultiXact 回卷而强制自动清理表的 MultiXact 年龄。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 400000000，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置为防止 MultiXact 回卷而强制自动清理表的 MultiXact 年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值10000 – 2000000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值400000000
400000000

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 fb47de2be6e4 — Separate multixact freezing parameters from xid’s
提交日期 2014-02-13
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 400000000 — 400000000

机制详解

设置为防止 MultiXact 回卷而强制自动清理表的 MultiXact 年龄。该值在服务器启动时固定，修改后必须重启。

当 relminmxid 的年龄越过该上限时会强制进行防 MultiXact 回卷清理，即便普通 autovacuum 被关闭。成员存储压力还可能让扫描更早发生，不能只看一个配置数值判断安全。

应把 autovacuum_multixact_freeze_max_age 与 autovacuum_freeze_max_age、vacuum_freeze_min_age、vacuum_freeze_table_age 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 以全库最大 XID/MXID 年龄、最旧表和清理完成速率校准 autovacuum_multixact_freeze_max_age；优先消除长事务、失效槽和被阻塞 worker，绝不能靠提高年龄掩盖积压。
OLAP 在批量窗口主动 VACUUM (FREEZE) 新装载/静态分区，并给全表扫描留 I/O 时间；年龄预算按峰值事务速率而不是墙钟经验换算。
小规格 保持上游默认通常最安全。容量较小不等于可关闭防回卷维护；监控所有数据库，而不只是当前业务库。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 忽略 MultiXact member 空间压力会提前触发维护。
  • 误以为 XID 年龄监控也覆盖 MXID。
  • 长期行锁持续生成旧 MultiXact 时仍提高上限。
  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。

关联参数

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_freeze_table_age · vacuum_failsafe_age · vacuum_multixact_freeze_min_age · vacuum_multixact_freeze_table_age

参考资料

14.10 - autovacuum_multixact_freeze_score_weight

autovacuum_multixact_freeze_score_weight：设置 autovacuum 优先级中 MultiXact 冻结得分的缩放系数。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 优先级中 MultiXact 冻结得分的缩放系数。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
提交日期 2026-03-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 1 — 1

机制详解

autovacuum_multixact_freeze_score_weight：设置 autovacuum 优先级中 MultiXact 冻结得分的缩放系数。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PostgreSQL 19 会为每个候选表计算得分，并按加权分量的最大值安排工作。该参数乘在MultiXact 冻结年龄分量上：大于 1 会提高其调度影响，0 到 1 会降低影响；把全部得分权重设为 0 可恢复 PG19 之前按目录顺序处理的策略。可通过 pg_stat_autovacuum_scores 检查各分量。

应与 autovacuum_freeze_score_weight、autovacuum_vacuum_score_weight、autovacuum_vacuum_insert_score_weight、autovacuum_analyze_score_weight 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先使用上游默认值，再依据 pg_stat_autovacuum_scores、表变更量、冻结年龄、排队与前台延迟决定是否修改。必须保护防回卷任务，避免偏爱忙表而饿死低流量表。
OLAP 批处理环境可能受益于优先处理最大维护债务或并行清理索引，但必须衡量整个维护窗口的 I/O 饱和、维护内存、worker 竞争与完成时间。
小规格 权重和并行度应保守；一个额外 worker 就可能占据很大比例的 CPU、内存与存储队列。先修正阈值，并确保 autovacuum 有足够时间完成。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 autovacuum_multixact_freeze_score_weight 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

autovacuum_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

参考资料

14.11 - autovacuum_naptime

autovacuum_naptime：设置两轮 autovacuum 扫描之间的休眠时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 min，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置两轮 autovacuum 扫描之间的休眠时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值1 – 2147483
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值60
1 min

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 60 s 1 min

机制详解

设置两轮 autovacuum 扫描之间的休眠时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

Launcher 尝试在每个数据库每隔该时长启动一次 worker；若有 N 个数据库，启动尝试通常按约 naptime/N 分散。它不是每张表的固定轮询周期，worker 槽位和长任务会进一步影响实际延迟。

应把 autovacuum_naptime 与 autovacuum、autovacuum_max_workers、autovacuum_worker_slots 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_naptime，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1min 等于 boot 值 1min
OLAP 1min 等于 boot 值 1min
CRIT 1min 等于 boot 值 1min
TINY 1min 等于 boot 值 1min
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 1min (dcs)；OLAP: PG9.0–19 Beta 3 = 1min (dcs)；CRIT: PG9.0–19 Beta 3 = 1min (dcs)；TINY: PG9.0–19 Beta 3 = 1min (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在显式保留 PostgreSQL 每分钟的数据库调度节奏；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum · autovacuum_max_workers · autovacuum_worker_slots · autovacuum_work_mem · track_counts · autovacuum_analyze_scale_factor

参考资料

14.12 - autovacuum_vacuum_cost_delay

autovacuum_vacuum_cost_delay：设置 autovacuum 的清理成本延迟（毫秒）。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2 ms，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 的清理成本延迟（毫秒）。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值-1 – 100
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值2
2 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–11 20 ms 20 ms
PG12–19 Beta 3 2 ms 2 ms

机制详解

设置 autovacuum 的清理成本延迟（毫秒）。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

这些值控制 autovacuum worker 的成本节流；-1 表示分别继承 vacuum_cost_delay 或 vacuum_cost_limit。多个 worker 活跃时，autovacuum 成本额度会在 worker 间平衡，因此单 worker 观察值不能直接乘以并发数。

应把 autovacuum_vacuum_cost_delay 与 vacuum_cost_delay、vacuum_cost_limit、vacuum_cost_page_hit 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 autovacuum_vacuum_cost_delay；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP -1 不同于 boot 值 -1
OLAP -1 不同于 boot 值 -1
CRIT -1 不同于 boot 值 -1
TINY -1 不同于 boot 值 -1
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = -1 (dcs)；OLAP: PG9.0–19 Beta 3 = -1 (dcs)；CRIT: PG9.0–19 Beta 3 = -1 (dcs)；TINY: PG9.0–19 Beta 3 = -1 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在用 -1 让 autovacuum 延迟继承普通 vacuum 成本设置；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_limit

参考资料

14.13 - autovacuum_vacuum_cost_limit

autovacuum_vacuum_cost_limit：设置 autovacuum 休眠前可用的清理成本额度。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 -1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 休眠前可用的清理成本额度。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值-1 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值-1
-1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 -1 — -1

机制详解

设置 autovacuum 休眠前可用的清理成本额度。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

这些值控制 autovacuum worker 的成本节流；-1 表示分别继承 vacuum_cost_delay 或 vacuum_cost_limit。多个 worker 活跃时，autovacuum 成本额度会在 worker 间平衡，因此单 worker 观察值不能直接乘以并发数。

应把 autovacuum_vacuum_cost_limit 与 vacuum_cost_delay、vacuum_cost_limit、vacuum_cost_page_hit 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 autovacuum_vacuum_cost_limit；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP -1 等于 boot 值 -1
OLAP -1 等于 boot 值 -1
CRIT -1 等于 boot 值 -1
TINY -1 等于 boot 值 -1
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = -1 (dcs)；OLAP: PG9.0–19 Beta 3 = -1 (dcs)；CRIT: PG9.0–19 Beta 3 = -1 (dcs)；TINY: PG9.0–19 Beta 3 = -1 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在用 -1 让 autovacuum 成本额度继承 vacuum_cost_limit；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay

参考资料

14.14 - autovacuum_vacuum_insert_scale_factor

autovacuum_vacuum_insert_scale_factor：以 reltuples 的比例设置触发 VACUUM 前的插入元组数量。它是 PG13–18 的 sighup 参数；最新实测启动默认值为 0.2。
说明

Fact — 官方简述译文：以 reltuples 的比例设置触发 VACUUM 前的插入元组数量。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 100
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值0.2
0.2

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 b07642dbcd8d — Trigger autovacuum based on number of INSERTs
提交日期 2020-03-28
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 0.2 — 0.2

机制详解

以 reltuples 的比例设置触发 VACUUM 前的插入元组数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

仅插入表的触发量由 insert threshold + insert scale factor × reltuples × 未 all-frozen 比例计算。该清理主要推进 visibility map 与冻结，即使没有死元组也能减少未来 aggressive VACUUM 工作。

应把 autovacuum_vacuum_insert_scale_factor 与 autovacuum_vacuum_threshold、autovacuum_vacuum_scale_factor、autovacuum_vacuum_max_threshold 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_vacuum_insert_scale_factor，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum_vacuum_threshold · autovacuum_vacuum_scale_factor · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_threshold · autovacuum · autovacuum_analyze_scale_factor

参考资料

14.15 - autovacuum_vacuum_insert_score_weight

autovacuum_vacuum_insert_score_weight：设置 autovacuum 优先级中仅插入清理得分的缩放系数。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 优先级中仅插入清理得分的缩放系数。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
提交日期 2026-03-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 1 — 1

机制详解

autovacuum_vacuum_insert_score_weight：设置 autovacuum 优先级中仅插入清理得分的缩放系数。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PostgreSQL 19 会为每个候选表计算得分，并按加权分量的最大值安排工作。该参数乘在插入驱动的清理压力分量上：大于 1 会提高其调度影响，0 到 1 会降低影响；把全部得分权重设为 0 可恢复 PG19 之前按目录顺序处理的策略。可通过 pg_stat_autovacuum_scores 检查各分量。

应与 autovacuum_freeze_score_weight、autovacuum_multixact_freeze_score_weight、autovacuum_vacuum_score_weight、autovacuum_analyze_score_weight 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先使用上游默认值，再依据 pg_stat_autovacuum_scores、表变更量、冻结年龄、排队与前台延迟决定是否修改。必须保护防回卷任务，避免偏爱忙表而饿死低流量表。
OLAP 批处理环境可能受益于优先处理最大维护债务或并行清理索引，但必须衡量整个维护窗口的 I/O 饱和、维护内存、worker 竞争与完成时间。
小规格 权重和并行度应保守；一个额外 worker 就可能占据很大比例的 CPU、内存与存储队列。先修正阈值，并确保 autovacuum 有足够时间完成。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 autovacuum_vacuum_insert_score_weight 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

autovacuum_freeze_score_weight · autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

参考资料

14.16 - autovacuum_vacuum_insert_threshold

autovacuum_vacuum_insert_threshold：设置触发 VACUUM 前插入元组数量的最低阈值。它是 PG13–18 的 sighup 参数；最新实测启动默认值为 1000。
说明

Fact — 官方简述译文：设置触发 VACUUM 前插入元组数量的最低阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值1000
1000

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 b07642dbcd8d — Trigger autovacuum based on number of INSERTs
提交日期 2020-03-28
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 1000 — 1000

机制详解

设置触发 VACUUM 前插入元组数量的最低阈值。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

仅插入表的触发量由 insert threshold + insert scale factor × reltuples × 未 all-frozen 比例计算。该清理主要推进 visibility map 与冻结，即使没有死元组也能减少未来 aggressive VACUUM 工作。

应把 autovacuum_vacuum_insert_threshold 与 autovacuum_vacuum_threshold、autovacuum_vacuum_scale_factor、autovacuum_vacuum_max_threshold 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_vacuum_insert_threshold，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum_vacuum_threshold · autovacuum_vacuum_scale_factor · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum · autovacuum_analyze_scale_factor

参考资料

14.17 - autovacuum_vacuum_max_threshold

autovacuum_vacuum_max_threshold：设置触发 VACUUM 前更新或删除元组数量的最高阈值。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 100000000，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置触发 VACUUM 前更新或删除元组数量的最高阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值-1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值100000000
100000000

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 306dc520b9df — Introduce autovacuum_vacuum_max_threshold.
提交日期 2025-02-05
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 100000000 — 100000000

机制详解

设置触发 VACUUM 前更新或删除元组数量的最高阈值。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

普通自动清理阈值为固定项加 scale factor × reltuples；PG18 起再由 autovacuum_vacuum_max_threshold 给出上界。它针对更新/删除产生的死元组，表级 storage parameter 可覆盖各项；防回卷清理另有独立强制条件。

应把 autovacuum_vacuum_max_threshold 与 autovacuum_vacuum_threshold、autovacuum_vacuum_scale_factor、autovacuum_vacuum_insert_threshold 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_vacuum_max_threshold，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum_vacuum_threshold · autovacuum_vacuum_scale_factor · autovacuum_vacuum_insert_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum · autovacuum_analyze_scale_factor

参考资料

14.18 - autovacuum_vacuum_scale_factor

控制普通 autovacuum VACUUM 触发条件中与表大小成比例的部分。数值越低，大表在更小比例的行变成旧版本后就会进入清理候选。
说明

Fact — 官方简述译文：把表大小的一定比例加入触发 VACUUM 的元组变更阈值。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 100
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值0.2
0.2

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0.2 — 0.2

机制详解

核心触发值为基础阈值加上本参数乘以 pg_class.reltuples；后者是近似行数。PostgreSQL 18 还会用 autovacuum_vacuum_max_threshold 对结果封顶。

该触发器统计 UPDATE 或 DELETE 产生的旧元组；仅插入负载有独立的 insert threshold 与 scale factor。防回卷清理由事务年龄规则控制，不依赖本参数。

表级 autovacuum_vacuum_scale_factor storage parameter 会覆盖全局值。当不同表的大小和更新率差异很大时，表级设置通常更合适。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 对大型高更新表使用更低的表级值，避免死元组形成巨大的绝对积压；应依据实际变更量与清理时长验证，而不是只看百分比。
OLAP 追加与批处理负载应让阈值配合装载周期及显式 VACUUM/ANALYZE；过低的全局值可能在批处理期间触发不必要维护。
小规格 真正的小表通常可使用上游默认值。优先逐表处理例外；过低的集群级值可能导致频繁而细碎的 vacuum。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0.08 不同于 boot 值 0.08
OLAP 0.08 不同于 boot 值 0.08
CRIT 0.08 不同于 boot 值 0.08
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 0.08 (dcs)；OLAP: PG9.0–19 Beta 3 = 0.08 (dcs)；CRIT: PG9.0–19 Beta 3 = 0.08 (dcs)；TINY: PG9.0–19 Beta 3 未修改。 建议（待人工复核）——编辑推断（待维护者复核）：较大规格模板通过更早清理限制大表的绝对死元组积压，而 TINY 避免在受限资源上增加清理频率。

常见坑

  • 看似很小的比例在大表上仍可能代表数百万死元组。
  • 全局降低可能让大量表持续产生 I/O 压力。
  • 它不控制仅插入触发的 vacuum，也不控制防回卷 vacuum。
  • reltuples 是估算值，触发点不是精确的死元组比例。
  • 表级 storage parameter 可能让该表忽略全局值。

关联参数

autovacuum_vacuum_threshold · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum_analyze_scale_factor · autovacuum_naptime · autovacuum_freeze_max_age

参考资料

14.19 - autovacuum_vacuum_score_weight

autovacuum_vacuum_score_weight：设置 autovacuum 优先级中普通 VACUUM 得分的缩放系数。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 autovacuum 优先级中普通 VACUUM 得分的缩放系数。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 d7965d65fc5b — Add rudimentary table prioritization to autovacuum.
提交日期 2026-03-27
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG19 Beta 3 1 — 1

机制详解

autovacuum_vacuum_score_weight：设置 autovacuum 优先级中普通 VACUUM 得分的缩放系数。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

PostgreSQL 19 会为每个候选表计算得分，并按加权分量的最大值安排工作。该参数乘在更新或删除元组带来的清理压力分量上：大于 1 会提高其调度影响，0 到 1 会降低影响；把全部得分权重设为 0 可恢复 PG19 之前按目录顺序处理的策略。可通过 pg_stat_autovacuum_scores 检查各分量。

应与 autovacuum_freeze_score_weight、autovacuum_multixact_freeze_score_weight、autovacuum_vacuum_insert_score_weight、autovacuum_analyze_score_weight 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先使用上游默认值，再依据 pg_stat_autovacuum_scores、表变更量、冻结年龄、排队与前台延迟决定是否修改。必须保护防回卷任务，避免偏爱忙表而饿死低流量表。
OLAP 批处理环境可能受益于优先处理最大维护债务或并行清理索引，但必须衡量整个维护窗口的 I/O 饱和、维护内存、worker 竞争与完成时间。
小规格 权重和并行度应保守；一个额外 worker 就可能占据很大比例的 CPU、内存与存储队列。先修正阈值，并确保 autovacuum 有足够时间完成。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG19 Beta 3 未修改；OLAP: PG19 Beta 3 未修改；CRIT: PG19 Beta 3 未修改；TINY: PG19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 autovacuum_vacuum_score_weight 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

autovacuum_freeze_score_weight · autovacuum_multixact_freeze_score_weight · autovacuum_vacuum_insert_score_weight · autovacuum_analyze_score_weight · autovacuum_max_workers · autovacuum_naptime

参考资料

14.20 - autovacuum_vacuum_threshold

autovacuum_vacuum_threshold：设置触发 VACUUM 前更新或删除元组数量的最低阈值。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 50，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置触发 VACUUM 前更新或删除元组数量的最低阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值50
50

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 50 — 50

机制详解

设置触发 VACUUM 前更新或删除元组数量的最低阈值。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

普通自动清理阈值为固定项加 scale factor × reltuples；PG18 起再由 autovacuum_vacuum_max_threshold 给出上界。它针对更新/删除产生的死元组，表级 storage parameter 可覆盖各项；防回卷清理另有独立强制条件。

应把 autovacuum_vacuum_threshold 与 autovacuum_vacuum_scale_factor、autovacuum_vacuum_max_threshold、autovacuum_vacuum_insert_threshold 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_vacuum_threshold，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 500 不同于 boot 值 500
OLAP 1000 不同于 boot 值 1000
CRIT 500 不同于 boot 值 500
TINY 500 不同于 boot 值 500
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 500 (dcs)；OLAP: PG9.0–19 Beta 3 = 1000 (dcs)；CRIT: PG9.0–19 Beta 3 = 500 (dcs)；TINY: PG9.0–19 Beta 3 = 500 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在提高固定触发项，避免小表只产生少量死元组就清理；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum_vacuum_scale_factor · autovacuum_vacuum_max_threshold · autovacuum_vacuum_insert_threshold · autovacuum_vacuum_insert_scale_factor · autovacuum · autovacuum_analyze_scale_factor

参考资料

14.21 - autovacuum_worker_slots

autovacuum_worker_slots：设置为 autovacuum worker 分配的后端槽位数量。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 16，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置为 autovacuum worker 分配的后端槽位数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值1 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Automatic Vacuuming
上游分类
最后 boot 值 值16
16

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 c758119e5bfb — Allow changing autovacuum_max_workers without restarting.
提交日期 2025-01-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 16 — 16

机制详解

设置为 autovacuum worker 分配的后端槽位数量。该值在服务器启动时固定，修改后必须重启。

PG18 把可注册的 autovacuum worker 后端槽数量与实际并发上限 autovacuum_max_workers 分离。槽位在启动时分配，使 reload 后可以在既有槽预算内改变 worker 并发。

应把 autovacuum_worker_slots 与 autovacuum、autovacuum_naptime、autovacuum_max_workers 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 autovacuum_worker_slots，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

autovacuum · autovacuum_naptime · autovacuum_max_workers · autovacuum_work_mem · track_counts · autovacuum_analyze_scale_factor

参考资料

14.22 - vacuum_cost_delay

vacuum_cost_delay：设置清理成本延迟（毫秒）。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 ms，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置清理成本延迟（毫秒）。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 100
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Cost-Based Vacuum Delay
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 ms 0 ms

机制详解

设置清理成本延迟（毫秒）。它可在会话级修改，因此不同会话可能采用不同的行为。

VACUUM 按页命中、未命中和弄脏操作累加虚拟成本；余额达到 vacuum_cost_limit 后按 vacuum_cost_delay 休眠并重置。该模型是粗粒度 I/O 节流，不是精确带宽上限；防回卷 failsafe 会绕过节流。

应把 vacuum_cost_delay 与 vacuum_cost_limit、vacuum_cost_page_hit、vacuum_cost_page_miss 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 vacuum_cost_delay；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 20ms 不同于 boot 值 20ms
OLAP 10ms 不同于 boot 值 10ms
CRIT 20ms 不同于 boot 值 20ms
TINY 20ms 不同于 boot 值 20ms
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 20ms (dcs)；OLAP: PG9.0–19 Beta 3 = 10ms (dcs)；CRIT: PG9.0–19 Beta 3 = 20ms (dcs)；TINY: PG9.0–19 Beta 3 = 20ms (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在节流手工 VACUUM 及继承它的 autovacuum I/O，并让高吞吐 OLAP 使用更短延迟；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

参考资料

14.23 - vacuum_cost_limit

vacuum_cost_limit：设置清理进程休眠前可用的成本额度。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 200，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置清理进程休眠前可用的成本额度。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值1 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Cost-Based Vacuum Delay
上游分类
最后 boot 值 值200
200

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 200 — 200

机制详解

设置清理进程休眠前可用的成本额度。它可在会话级修改，因此不同会话可能采用不同的行为。

VACUUM 按页命中、未命中和弄脏操作累加虚拟成本；余额达到 vacuum_cost_limit 后按 vacuum_cost_delay 休眠并重置。该模型是粗粒度 I/O 节流，不是精确带宽上限；防回卷 failsafe 会绕过节流。

应把 vacuum_cost_limit 与 vacuum_cost_delay、vacuum_cost_page_hit、vacuum_cost_page_miss 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 vacuum_cost_limit；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 2000 不同于 boot 值 2000
OLAP 10000 不同于 boot 值 10000
CRIT 2000 不同于 boot 值 2000
TINY 2000 不同于 boot 值 2000
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 2000 (dcs)；OLAP: PG9.0–19 Beta 3 = 10000 (dcs)；CRIT: PG9.0–19 Beta 3 = 2000 (dcs)；TINY: PG9.0–19 Beta 3 = 2000 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在配合延迟提供更大的工作额度，尤其提高 OLAP 维护吞吐；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_delay · vacuum_cost_page_hit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

参考资料

14.24 - vacuum_cost_page_dirty

vacuum_cost_page_dirty：设置 VACUUM 弄脏一个页面的成本。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 20，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 弄脏一个页面的成本。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Cost-Based Vacuum Delay
上游分类
最后 boot 值 值20
20

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 20 — 20

机制详解

设置 VACUUM 弄脏一个页面的成本。它可在会话级修改，因此不同会话可能采用不同的行为。

VACUUM 按页命中、未命中和弄脏操作累加虚拟成本；余额达到 vacuum_cost_limit 后按 vacuum_cost_delay 休眠并重置。该模型是粗粒度 I/O 节流，不是精确带宽上限；防回卷 failsafe 会绕过节流。

应把 vacuum_cost_page_dirty 与 vacuum_cost_delay、vacuum_cost_limit、vacuum_cost_page_hit 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 vacuum_cost_page_dirty；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_miss · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

参考资料

14.25 - vacuum_cost_page_hit

vacuum_cost_page_hit：设置 VACUUM 访问缓冲区缓存命中页面的成本。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 访问缓冲区缓存命中页面的成本。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Cost-Based Vacuum Delay
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 1 — 1

机制详解

设置 VACUUM 访问缓冲区缓存命中页面的成本。它可在会话级修改，因此不同会话可能采用不同的行为。

VACUUM 按页命中、未命中和弄脏操作累加虚拟成本；余额达到 vacuum_cost_limit 后按 vacuum_cost_delay 休眠并重置。该模型是粗粒度 I/O 节流，不是精确带宽上限；防回卷 failsafe 会绕过节流。

应把 vacuum_cost_page_hit 与 vacuum_cost_delay、vacuum_cost_limit、vacuum_cost_page_miss 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 vacuum_cost_page_hit；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_miss · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

参考资料

14.26 - vacuum_cost_page_miss

vacuum_cost_page_miss：设置 VACUUM 访问缓冲区缓存未命中页面的成本。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 2，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 访问缓冲区缓存未命中页面的成本。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Cost-Based Vacuum Delay
上游分类
最后 boot 值 值2
2

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–13 10 — 10
PG14–19 Beta 3 2 — 2

机制详解

设置 VACUUM 访问缓冲区缓存未命中页面的成本。它可在会话级修改，因此不同会话可能采用不同的行为。

VACUUM 按页命中、未命中和弄脏操作累加虚拟成本；余额达到 vacuum_cost_limit 后按 vacuum_cost_delay 休眠并重置。该模型是粗粒度 I/O 节流，不是精确带宽上限；防回卷 failsafe 会绕过节流。

应把 vacuum_cost_page_miss 与 vacuum_cost_delay、vacuum_cost_limit、vacuum_cost_page_hit 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用 autovacuum 时长、死元组增长和前台 I/O 延迟共同调 vacuum_cost_page_miss；优先表级覆盖热点表，避免全局节流让清理永远追不上。
OLAP 在装载后维护窗口可提高成本额度或缩短延迟，但要验证扫描吞吐不会挤占查询/导入；failsafe 触发说明常态策略已失效。
小规格 保持温和默认；若磁盘很慢，降低并发或给单表覆盖通常比无限增大 delay 更可控。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。
  • 不看长事务、复制槽和 worker 饱和就责怪阈值。
  • 用降低维护频率换取短期平静，最终进入防回卷 failsafe。

关联参数

vacuum_cost_delay · vacuum_cost_limit · vacuum_cost_page_hit · vacuum_cost_page_dirty · autovacuum_vacuum_cost_delay · autovacuum_vacuum_cost_limit

参考资料

14.27 - vacuum_failsafe_age

vacuum_failsafe_age：设置 VACUUM 为避免事务 ID 回卷停机而进入保护模式的年龄。它是 PG14–18 的 user 参数；最新实测启动默认值为 1600000000。
说明

Fact — 官方简述译文：设置 VACUUM 为避免事务 ID 回卷停机而进入保护模式的年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2100000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值1600000000
1600000000

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 1e55e7d1755c — Add wraparound failsafe to VACUUM.
提交日期 2021-04-07
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 1600000000 — 1600000000

机制详解

设置 VACUUM 为避免事务 ID 回卷停机而进入保护模式的年龄。它可在会话级修改，因此不同会话可能采用不同的行为。

年龄达到 failsafe 后，正在运行的 VACUUM 优先尽快推进冻结边界，会停止成本延迟并跳过部分非必要工作（包括索引清理与表尾截断）。这是避免回卷停机的最后保护，不是日常性能模式。

应把 vacuum_failsafe_age 与 autovacuum_freeze_max_age、vacuum_freeze_min_age、vacuum_freeze_table_age 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 以全库最大 XID/MXID 年龄、最旧表和清理完成速率校准 vacuum_failsafe_age；优先消除长事务、失效槽和被阻塞 worker，绝不能靠提高年龄掩盖积压。
OLAP 在批量窗口主动 VACUUM (FREEZE) 新装载/静态分区，并给全表扫描留 I/O 时间；年龄预算按峰值事务速率而不是墙钟经验换算。
小规格 保持上游默认通常最安全。容量较小不等于可关闭防回卷维护；监控所有数据库，而不只是当前业务库。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 failsafe 当作常态高吞吐 VACUUM 模式。
  • 紧急结束后忽略被跳过的索引清理。
  • 提高年龄以压制维护失败的证据。
  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。

关联参数

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_freeze_table_age · autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age · vacuum_multixact_freeze_table_age

参考资料

14.28 - vacuum_freeze_min_age

vacuum_freeze_min_age：设置 VACUUM 冻结表行所需的最小年龄。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 50000000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 冻结表行所需的最小年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1000000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值50000000
50000000

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 50000000 — 50000000

机制详解

设置 VACUUM 冻结元组 xmin 时采用的最小 XID 年龄。它是 user context，手工 VACUUM 可在会话中覆盖。

VACUUM 根据该年龄计算 XID 冻结截止点。较小值更早冻结 XID，可能在即将更新的行上重复工作；较大值推迟工作。有效值最高为 autovacuum_freeze_max_age 的一半。

监控各表 age(relfrozenxid) 与所有数据库的 age(datfrozenxid)。应与 vacuum_freeze_table_age、autovacuum_freeze_max_age、vacuum_failsafe_age 联合解释；MXID 由独立的 vacuum_multixact_freeze_min_age 控制。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在 autovacuum_freeze_max_age 之前保留足够余量，使日常 VACUUM 能推进 relfrozenxid。依据 XID 峰值消耗与实测清理完成时间调优，不按日历天数猜测。
OLAP 对以追加为主或静态分区，可在计划 VACUUM 中降低该值以更早冻结 XID、减少后续 aggressive 工作；需验证额外 WAL 与扫描成本。
小规格 没有 XID 年龄证据就保持上游默认。小数据库同样共享集群事务计数器，仍需监控每个数据库。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把该截止点描述成 MXID 控制；MultiXact 使用 vacuum_multixact_freeze_min_age。
  • 不按实测事务速率就把 XID 年龄换算成时间。
  • 把数值提高到日常 VACUUM 在防回卷工作前失去有效余量。
  • 忽略表级 autovacuum_freeze_min_age 覆盖。

关联参数

autovacuum_freeze_max_age · vacuum_freeze_table_age · vacuum_failsafe_age · vacuum_multixact_freeze_min_age · autovacuum · log_autovacuum_min_duration

参考资料

14.29 - vacuum_freeze_table_age

vacuum_freeze_table_age：设置 VACUUM 为冻结元组而扫描整张表的年龄。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 150000000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 为冻结元组而扫描整张表的年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2000000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值150000000
150000000

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 150000000 — 150000000

机制详解

设置 VACUUM 为推进表 relfrozenxid 而切换到 aggressive 扫描的 XID 年龄。它是 user context。

XID aggressive 扫描会访问所有尚未 all-frozen 的页面并冻结合格 XID。PostgreSQL 将有效值限制为 autovacuum_freeze_max_age 的 95%，为强制防回卷 autovacuum 前的手工维护留出空间。

监控 age(relfrozenxid) 与 age(datfrozenxid)，而不是 relminmxid。MXID 驱动的 aggressive 扫描由独立的 vacuum_multixact_freeze_table_age 控制。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 设置日常维护能够在 autovacuum_freeze_max_age 前触发并完成的 XID aggressive 阈值；在最大关系上验证全表扫描时间。
OLAP 在有 I/O 余量时为静态或新装载分区安排 aggressive XID 冻结；降低阈值可把工作分散到多个维护窗口。
小规格 保持默认并监控每个数据库最旧的 relfrozenxid。设为零会让每次 VACUUM 都采用 aggressive 行为，通常不适合作为全局值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 监控 relminmxid，而不是 XID 边界 relfrozenxid。
  • 设置高于 autovacuum_freeze_max_age 95% 的值，并误以为 PostgreSQL 会原样采用。
  • 在大型频繁修改表上过度频繁地强制 aggressive 扫描。
  • 只等待强制防回卷 autovacuum，而不测量日常全表扫描完成时间。

关联参数

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_failsafe_age · vacuum_multixact_freeze_table_age · autovacuum · log_autovacuum_min_duration

参考资料

14.30 - vacuum_max_eager_freeze_failure_rate

vacuum_max_eager_freeze_failure_rate：设置 VACUUM 在关闭积极冻结扫描前，允许扫描但未能冻结的页面比例。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.03，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 在关闭积极冻结扫描前，允许扫描但未能冻结的页面比例。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值0.03
0.03

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 052026c9b903 — Eagerly scan all-visible pages to amortize aggressive vacuum
提交日期 2025-02-11
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 0.03 — 0.03

机制详解

设置 VACUUM 在关闭积极冻结扫描前，允许扫描但未能冻结的页面比例。它可在会话级修改，因此不同会话可能采用不同的行为。

PG18 的普通 VACUUM 可积极扫描 all-visible 但尚未 all-frozen 的页；若扫描却不能冻结的失败比例过高，就停止这类额外扫描。提高该值可能提前冻结更多页、减轻未来 aggressive VACUUM，也会增加当次扫描 I/O。

应把 vacuum_max_eager_freeze_failure_rate 与 vacuum_truncate、vacuum_freeze_table_age、autovacuum_freeze_max_age 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 以全库最大 XID/MXID 年龄、最旧表和清理完成速率校准 vacuum_max_eager_freeze_failure_rate；优先消除长事务、失效槽和被阻塞 worker，绝不能靠提高年龄掩盖积压。
OLAP 在批量窗口主动 VACUUM (FREEZE) 新装载/静态分区，并给全表扫描留 I/O 时间；年龄预算按峰值事务速率而不是墙钟经验换算。
小规格 保持上游默认通常最安全。容量较小不等于可关闭防回卷维护；监控所有数据库，而不只是当前业务库。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把数值当作百分比整数，而不是 0 到 1 的比例。
  • 提高数值、增加 all-visible 页面扫描，却未测量额外 I/O 与 WAL。
  • 误以为积极冻结可以消除周期性 aggressive VACUUM。
  • 忽略表级 storage parameter 覆盖。
  • 只看扫描页数，不看实际冻结页数与未来 aggressive 扫描工作。

关联参数

vacuum_truncate · vacuum_freeze_table_age · autovacuum_freeze_max_age · maintenance_work_mem · vacuum_failsafe_age · vacuum_freeze_min_age

参考资料

14.31 - vacuum_multixact_failsafe_age

vacuum_multixact_failsafe_age：设置 VACUUM 为避免 MultiXact 回卷停机而进入保护模式的年龄。它是 PG14–18 的 user 参数；最新实测启动默认值为 1600000000。
说明

Fact — 官方简述译文：设置 VACUUM 为避免 MultiXact 回卷停机而进入保护模式的年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2100000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值1600000000
1600000000

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 1e55e7d1755c — Add wraparound failsafe to VACUUM.
提交日期 2021-04-07
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 1600000000 — 1600000000

机制详解

设置 VACUUM 为避免 MultiXact 回卷停机而进入保护模式的年龄。它可在会话级修改，因此不同会话可能采用不同的行为。

年龄达到 failsafe 后，正在运行的 VACUUM 优先尽快推进冻结边界，会停止成本延迟并跳过部分非必要工作（包括索引清理与表尾截断）。这是避免回卷停机的最后保护，不是日常性能模式。

应把 vacuum_multixact_failsafe_age 与 autovacuum_freeze_max_age、vacuum_freeze_min_age、vacuum_freeze_table_age 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 以全库最大 XID/MXID 年龄、最旧表和清理完成速率校准 vacuum_multixact_failsafe_age；优先消除长事务、失效槽和被阻塞 worker，绝不能靠提高年龄掩盖积压。
OLAP 在批量窗口主动 VACUUM (FREEZE) 新装载/静态分区，并给全表扫描留 I/O 时间；年龄预算按峰值事务速率而不是墙钟经验换算。
小规格 保持上游默认通常最安全。容量较小不等于可关闭防回卷维护；监控所有数据库，而不只是当前业务库。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 failsafe 当作常态而非紧急状态。
  • 只监控 XID，漏掉 MXID 耗尽。
  • 忽略 failsafe 后的索引清理债务。
  • 只改全局值，忽略表级 storage parameter 覆盖。
  • 把 reltuples 与累计变更统计当作精确实时计数。

关联参数

autovacuum_freeze_max_age · vacuum_freeze_min_age · vacuum_freeze_table_age · vacuum_failsafe_age · autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age

参考资料

14.32 - vacuum_multixact_freeze_min_age

vacuum_multixact_freeze_min_age：设置 VACUUM 冻结表行中 MultiXactId 所需的最小年龄。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 5000000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 冻结表行中 MultiXactId 所需的最小年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1000000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值5000000
5000000

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 fb47de2be6e4 — Separate multixact freezing parameters from xid’s
提交日期 2014-02-13
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 5000000 — 5000000

机制详解

设置 VACUUM 替换元组 xmax 中旧 MultiXact ID 时采用的最小 MXID 年龄。它是 user context，并与 XID 截止点相互独立。

较小值使 VACUUM 更早处理 MXID，较大值推迟该工作。PostgreSQL 仍可能主动移除 MultiXact；有效截止点最高为 autovacuum_multixact_freeze_max_age 的一半。

监控 mxid_age(relminmxid)、mxid_age(datminmxid) 与 pg_multixact member 空间。应与 vacuum_multixact_freeze_table_age、autovacuum_multixact_freeze_max_age、vacuum_multixact_failsafe_age 联合解释。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 依据行锁与多事务负载产生的 MXID 消耗调优。与 autovacuum_multixact_freeze_max_age 保持充足距离，并同时监控 member 空间与年龄。
OLAP 单纯批量读取通常不需要修改，但并发行锁装载可能快速消耗 MXID；应在真实负载中测量 mxid_age 与 pg_multixact 增长。
小规格 没有 MXID 证据就保持默认。事务量低并不代表大量共享行锁的工作负载安全。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把该截止点描述成 XID 控制，或只监控 relfrozenxid。
  • 忽略 pg_multixact member 空间压力；它可能在配置年龄前就强制 aggressive 工作。
  • 长期共享行锁持续产生旧 MXID 时仍提高该值。
  • 计算上限时误用 autovacuum_freeze_max_age，而不是 MultiXact 专用上限。

关联参数

autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_table_age · vacuum_multixact_failsafe_age · vacuum_freeze_min_age · autovacuum · log_autovacuum_min_duration

参考资料

14.33 - vacuum_multixact_freeze_table_age

vacuum_multixact_freeze_table_age：设置 VACUUM 为冻结 MultiXact 而扫描整张表的年龄。实测在档范围为 PG9.3–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 150000000，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 VACUUM 为冻结 MultiXact 而扫描整张表的年龄。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2000000000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Freezing
上游分类
最后 boot 值 值150000000
150000000

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 fb47de2be6e4 — Separate multixact freezing parameters from xid’s
提交日期 2014-02-13
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 150000000 — 150000000

机制详解

设置 VACUUM 为推进表 relminmxid 而切换到 aggressive 扫描的 MultiXact 年龄。它是 user context。

MXID aggressive 扫描会访问所有尚未 all-frozen 的页面并处理合格 MultiXact。PostgreSQL 将有效值限制为 autovacuum_multixact_freeze_max_age 的 95%。

监控 mxid_age(relminmxid)、mxid_age(datminmxid) 与 pg_multixact 空间。XID 边界 relfrozenxid 则由 vacuum_freeze_table_age 控制。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 选择在 autovacuum_multixact_freeze_max_age 前留出足够时间完成 aggressive 扫描的 MXID 阈值；重点测量大量共享行锁的负载。
OLAP 纯只读分析通常很少消耗 MXID，但并发装载可能不同；应依据实测 mxid_age 与 member 空间增长安排扫描，不要照搬 XID 设置。
小规格 保持默认并监控 relminmxid/datminmxid。小数据库也可能因行锁模式快速消耗 MXID。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 监控 relfrozenxid，而不是 MultiXact 边界 relminmxid。
  • 计算 95% 上限时使用 autovacuum_freeze_max_age，而不是 autovacuum_multixact_freeze_max_age。
  • 把 XID 年龄策略照搬到消耗速率完全不同的 MXID 负载。
  • 年龄看似宽裕时忽略 pg_multixact member 空间压力。

关联参数

autovacuum_multixact_freeze_max_age · vacuum_multixact_freeze_min_age · vacuum_multixact_failsafe_age · vacuum_freeze_table_age · autovacuum · log_autovacuum_min_duration

参考资料

14.34 - vacuum_truncate

vacuum_truncate：允许 VACUUM 截断表尾的空页面。实测在档范围为 PG18–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许 VACUUM 截断表尾的空页面。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Vacuuming / Default Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 0164a0f9ee12 — Add vacuum_truncate configuration parameter.
提交日期 2025-03-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 on — on

机制详解

允许 VACUUM 截断表尾的空页面。它可在会话级修改，因此不同会话可能采用不同的行为。

它参与 VACUUM 的触发、节流或冻结决策；多数行为可被表级 storage parameter 覆盖。应结合 pg_stat_*、pg_class 年龄与真实维护日志判断，而不是只看全局值。

应把 vacuum_truncate 与 vacuum_max_eager_freeze_failure_rate、vacuum_freeze_table_age、autovacuum_freeze_max_age 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据表大小、变更速率与维护 SLA 调 vacuum_truncate，大表优先使用表级阈值；观察触发间隔、死元组和 ANALYZE/VACUUM 时长。
OLAP 批量装载后主动 ANALYZE/VACUUM，不要只等待比例阈值；对 append-only 分区单独规划冻结与 visibility map 推进。
小规格 先保持默认或 Pigsty 矩阵值；小表固定阈值比比例项更重要，修改后确认 worker 数量和 I/O 仍有余量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为截断能删除关系中间的空页；只有连续空表尾可以移除。
  • 忽略 ACCESS EXCLUSIVE 锁尝试及其在繁忙表上的阻塞延迟。
  • 关闭截断后仍期待操作系统文件大小自动缩小。
  • 忘记表级 vacuum_truncate storage parameter 可覆盖会话/全局值。
  • 依赖 failsafe 期间截断空间；为尽快完成，VACUUM 可能跳过它。

关联参数

vacuum_max_eager_freeze_failure_rate · vacuum_freeze_table_age · autovacuum_freeze_max_age · maintenance_work_mem · autovacuum · autovacuum_analyze_scale_factor

参考资料

15 - 版本与平台兼容

Version and Platform Compatibility 分类下的 12 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

15.1 - allow_alter_system

allow_alter_system：允许执行 ALTER SYSTEM 命令。它是 PG17–18 的 sighup 参数；最新实测启动默认值为 on。
说明

Fact — 官方简述译文：允许执行 ALTER SYSTEM 命令。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Other Platforms and Clients
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 d3ae2a24f265 — Add allow_alter_system GUC.
提交日期 2024-03-29
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 on — on

机制详解

允许执行 ALTER SYSTEM 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

关闭后，PostgreSQL 会在 ALTER SYSTEM 改写 postgresql.auto.conf 前拒绝该命令。它既不会删除 auto.conf 现有条目，也无法阻止操作系统管理员改文件，因此这是 SQL 管理边界而不是文件系统安全边界。

应把 allow_alter_system 与 config_file、data_directory、hba_file 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 由配置管理器拥有 postgresql.conf/auto.conf 的托管环境可关闭它，减少 SQL 管理面；同时审计现有 auto.conf，并限制文件与超级用户权限。
OLAP 策略与 OLTP 相同。若批处理平台依赖 ALTER SYSTEM，先迁移到声明式配置接口，避免任务在 reload 后悄然失败。
小规格 单管理员实例可保持默认，但不要把 ALTER SYSTEM 当作变更审计系统；保留配置版本、回滚与重启/reload 记录。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

config_file · data_directory · hba_file · ident_file · external_pid_file · transform_null_equals

参考资料

15.2 - array_nulls

array_nulls：允许在数组输入中使用 NULL 元素。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许在数组输入中使用 NULL 元素。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

允许在数组输入中使用 NULL 元素。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 array_nulls 与 backslash_quote、escape_string_warning、standard_conforming_strings 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 array_nulls 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

backslash_quote · escape_string_warning · standard_conforming_strings · transform_null_equals · quote_all_identifiers · default_with_oids

参考资料

15.3 - backslash_quote

backslash_quote：设置字符串字面量中是否允许使用反斜杠转义的单引号（'）。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 safe_encoding，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置字符串字面量中是否允许使用反斜杠转义的单引号（'）。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值safe_encoding, on, off
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值safe_encoding
safe_encoding

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 safe_encoding — safe_encoding

机制详解

设置字符串字面量中是否允许使用反斜杠转义的单引号（'）。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 backslash_quote 与 array_nulls、escape_string_warning、standard_conforming_strings 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 backslash_quote 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

array_nulls · escape_string_warning · standard_conforming_strings · transform_null_equals · quote_all_identifiers · default_with_oids

参考资料

15.4 - default_with_oids

default_with_oids：默认创建带 OID 的新表。实测在档范围为 PG9.0–11；最后在档的 PG11 启动默认值为 off，context 为 user。它在 PG12 被移除。
说明

Fact — 官方简述译文：默认创建带 OID 的新表。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–11
移除版本 PG12
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–11 off — off

机制详解

默认创建带 OID 的新表。该参数在 PG11 仍存在，并从 PG12 起不再被识别。PostgreSQL 12 移除了用户表 OID；应改用 identity 列、序列或其他显式主键。

该参数存在时，会改变未显式写 WITH/WITHOUT OIDS 的 CREATE TABLE。表 OID 既不是稳定业务键，也不保证全局唯一；PostgreSQL 12 随用户表 OID 一并移除该功能。

升级前应联合检查 lo_compat_privileges、operator_precedence_warning、synchronize_seqscans，从配置、ALTER SYSTEM、角色/数据库设置和自动化模板中删除旧名，并先验证替代机制再启动 PG12+。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要在 PG12+ 调优或继续下发 default_with_oids。PostgreSQL 12 移除了用户表 OID；应改用 identity 列、序列或其他显式主键。升级前扫描所有配置层并做业务回归。
OLAP 迁移方案与 OLTP 相同；另外在长批处理、备库或大对象/扩展工作流中验证新机制，不要假定删除旧开关会保留旧行为。
小规格 直接删除旧配置并采用受支持替代项；若没有真实兼容需求，不要用脚本伪造旧行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG11 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–11 未修改；OLAP: PG9.0–11 未修改；CRIT: PG9.0–11 未修改；TINY: PG9.0–11 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在 PG12+ 配置中继续下发未知参数 default_with_oids。
  • 只删除参数名，却未迁移依赖它的应用行为。
  • 把历史默认值当作新版本替代机制的默认值。
  • 遗漏 ALTER SYSTEM、角色/数据库设置或自动化模板中的旧条目。

关联参数

lo_compat_privileges · operator_precedence_warning · synchronize_seqscans · standard_conforming_strings · array_nulls · backslash_quote

参考资料

15.5 - escape_string_warning

escape_string_warning：当普通字符串字面量含反斜杠转义时发出警告。实测在档范围为 PG9.0–18；最后在档的 PG18 启动默认值为 on，context 为 user。它在 PG19 Beta 3 被移除。
说明

Fact — 官方简述译文：当普通字符串字面量含反斜杠转义时发出警告。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–18
移除版本 PG19 Beta 3
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–18 on — on

机制详解

当普通字符串字面量含反斜杠转义时发出警告。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 escape_string_warning 与 array_nulls、backslash_quote、standard_conforming_strings 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 escape_string_warning 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG18 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–18 未修改；OLAP: PG9.0–18 未修改；CRIT: PG9.0–18 未修改；TINY: PG9.0–18 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

array_nulls · backslash_quote · standard_conforming_strings · transform_null_equals · quote_all_identifiers · default_with_oids

参考资料

15.6 - lo_compat_privileges

lo_compat_privileges：启用大对象权限检查的向后兼容模式。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：启用大对象权限检查的向后兼容模式。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

启用大对象权限检查的向后兼容模式。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 lo_compat_privileges 与 default_with_oids、operator_precedence_warning、synchronize_seqscans 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 lo_compat_privileges 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

default_with_oids · operator_precedence_warning · synchronize_seqscans · standard_conforming_strings · array_nulls · backslash_quote

参考资料

15.7 - operator_precedence_warning

operator_precedence_warning：对自 PostgreSQL 9.4 起含义发生变化的表达式发出警告。实测在档范围为 PG9.5–13；最后在档的 PG13 启动默认值为 off，context 为 user。它在 PG14 被移除。
说明

Fact — 官方简述译文：对自 PostgreSQL 9.4 起含义发生变化的表达式发出警告。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–13
移除版本 PG14
引入提交 c6b3c939b7e0 — Make operator precedence follow the SQL standard more closely.
提交日期 2015-03-11
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–13 off — off

机制详解

对自 PostgreSQL 9.4 起含义发生变化的表达式发出警告。该参数在 PG13 仍存在，并从 PG14 起不再被识别。PostgreSQL 14 移除了这一迁移警告；应给有歧义的表达式显式加括号，并在目标版本上测试。

它曾为 PostgreSQL 9.5 改变结合规则的表达式发出迁移警告，并不会恢复旧优先级。参数移除后，可靠方案是显式括号与回归测试。

升级前应联合检查 default_with_oids、lo_compat_privileges、synchronize_seqscans，从配置、ALTER SYSTEM、角色/数据库设置和自动化模板中删除旧名，并先验证替代机制再启动 PG14+。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要在 PG14+ 调优或继续下发 operator_precedence_warning。PostgreSQL 14 移除了这一迁移警告；应给有歧义的表达式显式加括号，并在目标版本上测试。升级前扫描所有配置层并做业务回归。
OLAP 迁移方案与 OLTP 相同；另外在长批处理、备库或大对象/扩展工作流中验证新机制，不要假定删除旧开关会保留旧行为。
小规格 直接删除旧配置并采用受支持替代项；若没有真实兼容需求，不要用脚本伪造旧行为。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG13 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–13 未修改；OLAP: PG9.5–13 未修改；CRIT: PG9.5–13 未修改；TINY: PG9.5–13 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在 PG14+ 配置中继续下发未知参数 operator_precedence_warning。
  • 只删除参数名，却未迁移依赖它的应用行为。
  • 把历史默认值当作新版本替代机制的默认值。
  • 遗漏 ALTER SYSTEM、角色/数据库设置或自动化模板中的旧条目。

关联参数

default_with_oids · lo_compat_privileges · synchronize_seqscans · standard_conforming_strings · array_nulls · backslash_quote

参考资料

15.8 - quote_all_identifiers

quote_all_identifiers：生成 SQL 片段时引用所有标识符。实测在档范围为 PG9.1–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：生成 SQL 片段时引用所有标识符。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 ce68df468a41 — Add options to force quoting of all identifiers.
提交日期 2010-07-22
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

生成 SQL 片段时引用所有标识符。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 quote_all_identifiers 与 array_nulls、backslash_quote、escape_string_warning 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 quote_all_identifiers 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

array_nulls · backslash_quote · escape_string_warning · standard_conforming_strings · transform_null_equals · default_with_oids

参考资料

15.9 - sql_inheritance

sql_inheritance：让多种 SQL 命令默认包含继承子表。实测在档范围为 PG9.0–9.6；最后在档的 PG9.6 启动默认值为 on，context 为 user。它在 PG10 被移除。
说明

Fact — 官方简述译文：让多种 SQL 命令默认包含继承子表。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.6
移除版本 PG10
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 on — on

机制详解

sql_inheritance：让多种 SQL 命令默认包含继承子表。它可以按会话修改，便于在不影响全部负载的前提下比较计划或行为。 本站在 PG9.0–9.6 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

启用时，多种命令会默认作用于继承后代，除非显式写 ONLY。PG10 移除了该兼容开关：现代 SQL 用 ONLY 排除后代，而声明式分区裁剪与 constraint_exclusion 决定实际扫描哪些子关系。

应与 constraint_exclusion、enable_partition_pruning、search_path、default_table_access_method 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.6 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.6 未修改；OLAP: PG9.0–9.6 未修改；CRIT: PG9.0–9.6 未修改；TINY: PG9.0–9.6 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 sql_inheritance 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 user context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

constraint_exclusion · enable_partition_pruning · search_path · default_table_access_method

参考资料

15.10 - standard_conforming_strings

standard_conforming_strings：使普通单引号字符串中的反斜杠按字面处理。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：使普通单引号字符串中的反斜杠按字面处理。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 off — off
PG9.1–19 Beta 3 on — on

机制详解

使普通单引号字符串中的反斜杠按字面处理。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 standard_conforming_strings 与 array_nulls、backslash_quote、escape_string_warning 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 standard_conforming_strings 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

array_nulls · backslash_quote · escape_string_warning · transform_null_equals · quote_all_identifiers · default_with_oids

参考资料

15.11 - synchronize_seqscans

synchronize_seqscans：启用同步顺序扫描。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：启用同步顺序扫描。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Previous PostgreSQL Versions
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

启用同步顺序扫描。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 synchronize_seqscans 与 default_with_oids、lo_compat_privileges、operator_precedence_warning 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 通常保持开启，让并发大表扫描共享缓存足迹；需要确定行序时必须写 ORDER BY，不能靠关闭该参数。
OLAP 分析负载最可能受益于 synchronized scans。只在可重复基准显示共享扫描位置损害局部性时做会话级试验。
小规格 保持默认；数据完全驻留缓存或几乎没有并发扫描时，它通常既无需调也不会成为瓶颈。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

default_with_oids · lo_compat_privileges · operator_precedence_warning · standard_conforming_strings · array_nulls · backslash_quote

参考资料

15.12 - transform_null_equals

transform_null_equals：将 expr = NULL 视为 expr IS NULL。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：将 expr = NULL 视为 expr IS NULL。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Version and Platform Compatibility / Other Platforms and Clients
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

将 expr = NULL 视为 expr IS NULL。它可在会话级修改，因此不同会话可能采用不同的行为。

该兼容开关改变旧客户端或旧 SQL 的解析/输出行为，而不是执行计划的常规性能旋钮。长期方案应修复客户端与 SQL，并在升级测试中移除兼容依赖。

应把 transform_null_equals 与 array_nulls、backslash_quote、escape_string_warning 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持现代默认并修复依赖 transform_null_equals 的旧客户端/SQL；先在会话级做迁移测试，不要把兼容开关永久设为集群全局策略。
OLAP 重点回归 ETL、生成 SQL 与旧驱动，因为它们常隐藏解析/引用假设；性能差异通常不是调该开关的理由。
小规格 没有遗留需求就保持默认。若临时启用，记录责任人、受影响连接与移除日期。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把兼容开关当作永久方案而不修复客户端。
  • 只在一个会话测试，却全局部署到所有应用。
  • 混淆解析兼容性与数据或安全兼容性。
  • 升级后忘记清理已经不需要的覆盖。

关联参数

array_nulls · backslash_quote · escape_string_warning · standard_conforming_strings · quote_all_identifiers · allow_alter_system

参考资料

16 - 预写日志

Write-Ahead Log 分类下的 41 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

16.1 - archive_cleanup_command

archive_cleanup_command：设置每次重启点执行的 shell 命令。它是 PG12–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置每次重启点执行的 shell 命令。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Archive Recovery
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置每次重启点执行的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

归档恢复的每个 restartpoint 都会执行该命令，并把 %r 展开为保持恢复可重新启动所需的最早 WAL 文件。通常使用 pg_archivecleanup；若多个备库共享归档，贸然删除可能让其他消费者断链。

应把 archive_cleanup_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 archive_cleanup_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
OLAP 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
小规格 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 对其他备库或恢复任务共享的归档执行破坏性清理。
  • 把 %r 误读为最后重放文件；它表示保持恢复可重新启动所需的最早文件。
  • restartpoint 重复或归档文件已不存在时，命令不具备幂等性。
  • 误以为 reload 会立即执行命令；它只在恢复 restartpoint 运行。
  • shell 引用或异常归档路径使清理越过预期归档目录。

关联参数

archive_mode · archive_command · archive_library · archive_timeout · restore_command · recovery_end_command

参考资料

16.2 - archive_command

archive_command：设置归档 WAL 文件时调用的 shell 命令。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 empty string，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置归档 WAL 文件时调用的 shell 命令。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Archiving
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

设置归档 WAL 文件时调用的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

归档进程把 %p 展开为源路径、%f 展开为 WAL 文件名，并把退出码 0 当作持久成功；非零会重试。虚假成功会允许 PostgreSQL 回收唯一的本地副本，悄然破坏归档链。

应把 archive_command 与 archive_mode、archive_library、archive_timeout 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 archive_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
OLAP 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
小规格 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP pgbackrest --stanza=fixture archive-push %p 不同于 boot 值 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
OLAP pgbackrest --stanza=fixture archive-push %p 不同于 boot 值 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
CRIT pgbackrest --stanza=fixture archive-push %p 不同于 boot 值 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
TINY pgbackrest --stanza=fixture archive-push %p 不同于 boot 值 'pgbackrest --stanza={{ pg_cluster }} archive-push %p'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)；OLAP: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)；CRIT: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)；TINY: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在把归档绑定到 Pigsty 用于 PITR 的 pgBackRest stanza；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 归档副本尚未持久化或校验就返回成功。
  • shell 命令没有安全引用 %p/%f。
  • 反复失败写满 pg_wal 并使服务器停摆。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

archive_mode · archive_library · archive_timeout · archive_cleanup_command · restore_command · recovery_end_command

参考资料

16.3 - archive_library

archive_library：设置归档 WAL 文件时调用的库。它是 PG15–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置归档 WAL 文件时调用的库。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Archiving
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 5ef1eefd76f4 — Allow archiving via loadable modules.
提交日期 2022-02-03
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 "" — empty string

机制详解

设置归档 WAL 文件时调用的库。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

非空值通过 _PG_archive_module_init 回调选择归档模块，取代 shell 命令。archive_command 与 archive_library 是二选一实现；二者可重载，但 archive_mode 必须已经启用。

应把 archive_library 与 archive_mode、archive_command、archive_timeout 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 archive_library 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
OLAP 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
小规格 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 同时配置库，却期待 archive_command 在库失败时自动兜底。
  • 把不可信归档代码加载到服务器进程内。
  • 把模块返回成功误当成归档一定可恢复。
  • reload 到新模块后未验证积压处理、失败报告和回滚。
  • 模块反复失败却没有归档延迟告警，最终让保留 WAL 填满 pg_wal。

关联参数

archive_mode · archive_command · archive_timeout · archive_cleanup_command · restore_command · recovery_end_command

参考资料

16.4 - archive_mode

archive_mode：允许使用 archive_command 归档 WAL 文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：允许使用 archive_command 归档 WAL 文件。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值always, on, off
非枚举类型记为 —
分类 值Write-Ahead Log / Archiving
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

启用后，PostgreSQL 会运行 WAL 归档进程，并在段文件可被回收之前将每个已完成段交给 archive_command，或在支持版本中交给 archive_library。模式与命令或库相互独立，因此归档逻辑可以重载而无需退出归档模式。

在普通主库运行期间，on 与 always 没有区别。在恢复或备库模式下，on 不归档收到的 WAL，而 always 还会归档从归档恢复或通过流复制收到的段。

打开该模式并不能证明归档健康或可恢复。命令失败会让 WAL 在 pg_wal 中积累；错误地返回成功会造成不可恢复的 WAL 链。时间点恢复还需要合适的基础备份和经过验证的恢复流程。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只为明确的 PITR 或日志传送需求启用，并使用可靠、幂等的归档实现。监控 pg_stat_archiver 失败、最新归档时间和 pg_wal 增长；恢复演练比命令返回成功更有说服力。
OLAP 按批量导入的 WAL 峰值规划归档带宽和目标容量。归档跟不上时，应节流或错峰批任务，而不是放任 pg_wal 写满。
小规格 只有理解保留策略和恢复步骤时才使用 pgBackRest 等托管工具。对于可随时重建的数据库，应保持关闭，而不是配置一个占位归档命令。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 启用 archive_mode 却使用空命令或失败命令，最终写满 pg_wal。
  • 使用 /bin/true 一类虚假成功命令，破坏可恢复的 WAL 链。
  • 误以为 archive_mode 可重载；修改它需要重启服务器。
  • 把 WAL 归档当作基础备份和恢复演练的替代品。
  • always 模式写共享归档时没有处理重复文件和并发竞态。

关联参数

archive_command · archive_library · archive_timeout · wal_level · restore_command · max_wal_size

参考资料

16.5 - archive_timeout

archive_timeout：设置强制切换到下一个 WAL 文件前的最长等待时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置强制切换到下一个 WAL 文件前的最长等待时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值0 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Archiving
上游分类
最后 boot 值 值0
0 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 s 0 s

机制详解

设置强制切换到下一个 WAL 文件前的最长等待时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

在间隔内没有自然换段时，PostgreSQL 强制切换 WAL 段以便归档当前部分。它不会让 WAL 更早持久化；过小会产生大量未写满但仍占完整段空间的归档文件。

应把 archive_timeout 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 archive_timeout 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
OLAP 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
小规格 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 300 不同于 boot 值 300
OLAP 300 不同于 boot 值 300
CRIT 300 不同于 boot 值 300
TINY 300 不同于 boot 值 300
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 300 (dcs)；OLAP: PG9.0–19 Beta 3 = 300 (dcs)；CRIT: PG9.0–19 Beta 3 = 300 (dcs)；TINY: PG9.0–19 Beta 3 = 300 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在限制低流量主库最新 WAL 尚未进入归档的最长时间；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把它误当成提交持久化超时。
  • 间隔过小，制造大量几乎为空却占完整段空间的归档文件。
  • 误以为强制换段能解决归档进程缓慢或失败。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

archive_mode · archive_command · archive_library · archive_cleanup_command · restore_command · recovery_end_command

参考资料

16.6 - checkpoint_completion_target

checkpoint_completion_target：设置在检查点间隔中用于刷新脏缓冲区的目标时间比例。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0.9，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置在检查点间隔中用于刷新脏缓冲区的目标时间比例。

身份

类型 值real
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值0 – 1
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值0.9
0.9

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–13 0.5 — 0.5
PG14–19 Beta 3 0.9 — 0.9

机制详解

PostgreSQL 会节流检查点写入，使其预计在可用间隔的这一比例处完成。可用间隔可能在下一次定时检查点结束，也可能因 WAL 容量更早触发，因此它是节奏目标，不是固定时长。

较大比例通常能把检查点 I/O 更均匀地摊开。较小比例会更快完成写入，形成更高的阶段性 I/O，随后出现空档；官方文档因此不建议降低该值。

过于接近 1 会给最终同步和其他检查点工作留下很少余量。PG14 将历史默认值从 0.5 改为 0.9，因此跨大版本比较配置时必须考虑这一变化。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 从对应版本的 0.9 默认值开始，只在延迟与 pg_stat_checkpointer 证据支持时调整。0.95 可能进一步平滑写入，但要验证检查点能稳定赶在下一触发条件之前完成。
OLAP 突发批处理往往由 WAL 容量提前触发检查点，因此通常先调大 max_wal_size。目标值应足够高以平滑 I/O，又不能让最终同步工作集中在末尾。
小规格 除非测量显示明确收益，否则使用 0.9。小型或慢速存储在目标值余量不足时，尤其容易受到检查点末尾同步尖峰影响。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 0.95 不同于 boot 值 0.95
OLAP 0.95 不同于 boot 值 0.95
CRIT 0.95 不同于 boot 值 0.95
TINY 0.95 不同于 boot 值 0.95
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 0.95 (dcs)；OLAP: PG9.0–19 Beta 3 = 0.95 (dcs)；CRIT: PG9.0–19 Beta 3 = 0.95 (dcs)；TINY: PG9.0–19 Beta 3 = 0.95 (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 把该值误解成秒数而不是比例。
  • 认为调低会减少总 I/O，实际只是把写入集中起来。
  • 设为 1.0，未给检查点收尾工作保留余量。
  • 忽略 max_wal_size 导致的提前检查点。
  • 跨版本比较时漏掉 PG14 的默认值变化。

关联参数

checkpoint_timeout · max_wal_size · checkpoint_flush_after · checkpoint_warning · shared_buffers

参考资料

16.7 - checkpoint_flush_after

checkpoint_flush_after：设置检查点每写入多少页后刷出先前写入的数据。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 256 KiB (32 × 8kB)，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置检查点每写入多少页后刷出先前写入的数据。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值8kB
原始单位
范围 值0 – 256
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值32
256 KiB (32 × 8kB)

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes.
提交日期 2016-02-19
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 32 8kB 256 KiB (32 × 8kB)

机制详解

设置检查点每写入多少页后刷出先前写入的数据。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 checkpoint_flush_after 与 checkpoint_warning、checkpoint_timeout、checkpoint_completion_target 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 checkpoint_flush_after；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 未修改；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 未修改；TINY: PG9.6–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把原始值当作字节；未带单位的值按数据库块计量。
  • 设置过小，增加 writeback 调用与 I/O 碎片。
  • 设置过大，失去检查点最终同步前平滑写回的作用。
  • 把 writeback 提示误当持久化保证；真正的持久性仍由 fsync 与 wal_sync_method 决定。
  • 未测量检查点延迟与脏页行为就跨操作系统或文件系统照搬数值。

关联参数

checkpoint_warning · checkpoint_timeout · checkpoint_completion_target · max_wal_size · min_wal_size · archive_cleanup_command

参考资料

16.8 - checkpoint_segments

checkpoint_segments：设置两次自动 WAL 检查点之间允许的最大日志段距离。实测在档范围为 PG9.0–9.4；最后在档的 PG9.4 启动默认值为 3，context 为 sighup。它在 PG9.5 被移除。
说明

Fact — 官方简述译文：设置两次自动 WAL 检查点之间允许的最大日志段距离。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值""
原始单位
范围 值1 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值3
3

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–9.4
移除版本 PG9.5
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.4 3 — 3

机制详解

checkpoint_segments：设置两次自动 WAL 检查点之间允许的最大日志段距离。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG9.0–9.4 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

这是 PostgreSQL 9.5 之前的检查点容量控制：累计 WAL 接近指定段数时请求自动检查点。PG9.5 以 max_wal_size 取代它；新参数使用软性的字节容量预算，并与 checkpoint_timeout、checkpoint_completion_target 协同，而不是直接暴露 WAL 段数。

应与 max_wal_size、checkpoint_timeout、checkpoint_completion_target、wal_segment_size 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。
OLAP 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。
小规格 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.4 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.4 未修改；OLAP: PG9.0–9.4 未修改；CRIT: PG9.0–9.4 未修改；TINY: PG9.0–9.4 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 checkpoint_segments 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。

关联参数

max_wal_size · checkpoint_timeout · checkpoint_completion_target · wal_segment_size · min_wal_size

参考资料

16.9 - checkpoint_timeout

checkpoint_timeout：设置两次自动 WAL 检查点之间的最长时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 5 min，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置两次自动 WAL 检查点之间的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值30 – 86400
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值300
5 min

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 300 s 5 min

机制详解

达到 checkpoint_timeout 后系统会考虑执行自动检查点，但 max_wal_size 可以更早触发。如果上次检查点后没有写入 WAL，PostgreSQL 可以跳过这次定时检查点，因此它是最长调度间隔，而不是固定周期工作的承诺。

较长间隔通常会减少检查点次数和全页写放大，但崩溃恢复时可能需要重放更多 WAL。较短间隔能收紧重放区间，却会增加脏页写回以及每次检查点后的全页镜像。

主库检查点记录也限制备库可执行重启点的位置。不要用本参数定义 WAL 归档的 RPO；低 WAL 负载下强制切换段应使用 archive_timeout。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 与 max_wal_size 联合调优，并通过 checkpoint_completion_target 平摊检查点 I/O。只有在量化恢复要求、请求型与定时型检查点比例、写延迟和 WAL 量之后才延长间隔。
OLAP 批处理期间通常是 max_wal_size 先触发。如果容量型检查点占主导，应先增加 WAL 空间，同时保留能满足重启与恢复目标的超时值。
小规格 在恢复时间重要且存储有限的环境里，上游 5 分钟是合理起点。延长间隔必须有明确的磁盘余量和经过测试的崩溃恢复预算。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 15min 不同于 boot 值 15min
OLAP 15min 不同于 boot 值 15min
CRIT 15min 不同于 boot 值 15min
TINY 15min 不同于 boot 值 15min
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 15min (dcs)；OLAP: PG9.0–19 Beta 3 = 15min (dcs)；CRIT: PG9.0–19 Beta 3 = 15min (dcs)；TINY: PG9.0–19 Beta 3 = 15min (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 认为空闲系统也必然严格按该间隔执行检查点。
  • 忘记 max_wal_size 可能更早触发检查点。
  • 用 checkpoint_timeout 代替 archive_timeout 限制归档延迟。
  • 增大后没有计入更长的崩溃恢复重放区间。
  • 设置过小导致全页写和检查点 I/O 占主导。

关联参数

max_wal_size · checkpoint_completion_target · checkpoint_warning · archive_timeout · full_page_writes · checkpoint_flush_after

参考资料

16.10 - checkpoint_warning

checkpoint_warning：设置 WAL 容量触发的检查点过于频繁时发出警告的时间阈值。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 30 s，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 WAL 容量触发的检查点过于频繁时发出警告的时间阈值。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值s
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值30
30 s

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 30 s 30 s

机制详解

设置 WAL 容量触发的检查点过于频繁时发出警告的时间阈值。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

该参数只在 WAL 容量触发的检查点间隔短于阈值时写日志，并不会推迟检查点。频繁告警通常意味着 max_wal_size 相对 WAL 生成速率过小。

应把 checkpoint_warning 与 checkpoint_flush_after、checkpoint_timeout、checkpoint_completion_target 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 checkpoint_warning；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把告警阈值误当成会推迟或节流检查点的控制项。
  • 设为零，掩盖 WAL 容量触发检查点过于频繁的证据。
  • 只提高阈值，而不调查 WAL 速率、max_wal_size 与 requested checkpoint 频率。
  • 把 checkpoint_warning 设得高于 checkpoint_timeout，却期待时间触发检查点产生该告警。

关联参数

checkpoint_flush_after · checkpoint_timeout · checkpoint_completion_target · max_wal_size · min_wal_size · archive_cleanup_command

参考资料

16.11 - commit_delay

commit_delay：设置事务提交与将 WAL 刷入磁盘之间的延迟（微秒）。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 0，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置事务提交与将 WAL 刷入磁盘之间的延迟（微秒）。

身份

类型 值integer
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值0 – 100000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

设置事务提交与将 WAL 刷入磁盘之间的延迟（微秒）。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

后端准备刷提交 WAL 时可等待这些微秒，让并发提交共用一次持久化刷写；只有至少存在 commit_siblings 个其他活动事务时才考虑等待。这是在单次提交延迟与 group commit 效率之间取舍。

应把 commit_delay 与 commit_siblings、synchronous_commit、wal_writer_delay 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只在高并发、WALSync 明显且 p95/p99 提交延迟可接受时基准测试 commit_delay；同时成对调整 commit_delay 与 commit_siblings，并保留关闭基线。
OLAP 批量事务通常应通过合理批次大小减少提交频率；不要用 group-commit 延迟弥补每行提交的 ETL 设计。
小规格 并发不足时几乎没有收益，保持 commit_delay=0 最简单；微秒级设置也要从端到端延迟测量证明。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 20 不同于 boot 值 20
OLAP 20 不同于 boot 值 20
CRIT 20 不同于 boot 值 20
TINY 20 不同于 boot 值 20
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 20 (dcs)；OLAP: PG9.0–19 Beta 3 = 20 (dcs)；CRIT: PG9.0–19 Beta 3 = 20 (dcs)；TINY: PG9.0–19 Beta 3 = 20 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在并发提交负载下促成极短的 group commit 批处理；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 设置了延迟，但真实并发从未达到 commit_siblings 门槛。
  • 把数值误读成毫秒；该参数单位是微秒。
  • 平均 group commit 吞吐提高，却违反 p95/p99 提交延迟目标。
  • 在提交路径无需刷 WAL 时仍期待该延迟生效。
  • 没有与 commit_siblings、WALSync 等待一起测量就修改 commit_delay。

关联参数

commit_siblings · synchronous_commit · wal_writer_delay · wal_sync_method · fsync · full_page_writes

参考资料

16.12 - commit_siblings

commit_siblings：设置启用 commit_delay 前所需的并发活动事务最低数量。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 5，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置启用 commit_delay 前所需的并发活动事务最低数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值5
5

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 5 — 5

机制详解

设置启用 commit_delay 前所需的并发活动事务最低数量。它可在会话级修改，因此不同会话可能采用不同的行为。

这是 commit_delay 的并发门槛，在需要提交刷写时按其他活动事务计数，而不是已经排队的 commit 数量。commit_delay 为零时它没有实际作用。

应把 commit_siblings 与 commit_delay、synchronous_commit、wal_writer_delay 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只在高并发、WALSync 明显且 p95/p99 提交延迟可接受时基准测试 commit_siblings；同时成对调整 commit_delay 与 commit_siblings，并保留关闭基线。
OLAP 批量事务通常应通过合理批次大小减少提交频率；不要用 group-commit 延迟弥补每行提交的 ETL 设计。
小规格 并发不足时几乎没有收益，保持 commit_delay=0 最简单；微秒级设置也要从端到端延迟测量证明。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 10 不同于 boot 值 10
OLAP 10 不同于 boot 值 10
CRIT 10 不同于 boot 值 10
TINY 10 不同于 boot 值 10
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 10 (dcs)；OLAP: PG9.0–19 Beta 3 = 10 (dcs)；CRIT: PG9.0–19 Beta 3 = 10 (dcs)；TINY: PG9.0–19 Beta 3 = 10 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在只在事务并发已经较高时才应用 commit_delay；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • commit_delay 为零时仍调该参数；此时门槛没有作用。
  • 把它当作已等待 commit 的数量，而不是其他活动事务数量。
  • 门槛过低，在普通中等并发下也增加提交延迟。
  • 把会话级试验直接全局发布，却没有比较提交延迟与 WALSync 行为。

关联参数

commit_delay · synchronous_commit · wal_writer_delay · wal_sync_method · fsync · full_page_writes

参考资料

16.13 - fsync

fsync：强制将更新同步到磁盘。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：强制将更新同步到磁盘。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

强制将更新同步到磁盘。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

开启时，PostgreSQL 发出持久化屏障，保证 WAL 与数据写入顺序能承受操作系统或掉电故障。关闭可能改善写入跑分，但崩溃后会留下 crash recovery 无法修复的损坏；重新开启也不能追溯同步此前的不安全写入。

应把 fsync 与 data_sync_retry、restart_after_crash、recovery_init_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 持久生产数据保持 fsync=on。性能问题应从存储延迟、检查点、WAL 压缩和批处理着手，不要用关闭崩溃安全换吞吐。
OLAP 批量装载同样需要可恢复性；用 UNLOGGED/临时数据结构或可重建 staging 明确缩小耐久范围，而不是全局关闭保护。
小规格 持久小实例也保持开启。只有数据可随时重建且与生产明确隔离的临时集群，才可在书面接受风险后例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在持久数据上关闭，并误以为 UPS 或 RAID cache 单独就足够。
  • 重新开启后误以为此前不安全写入已自动持久化。
  • 只测试干净关机，不测试掉电恢复。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

data_sync_retry · restart_after_crash · recovery_init_sync_method · full_page_writes · wal_sync_method · synchronous_commit

参考资料

16.14 - full_page_writes

full_page_writes：检查点后页面首次修改时将完整页面写入 WAL。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：检查点后页面首次修改时将完整页面写入 WAL。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

检查点后页面首次修改时将完整页面写入 WAL。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

每次检查点后，数据页第一次修改会把完整页映像写入 WAL，避免撕裂页恢复时拼接新旧扇区。额外 WAL 集中在检查点后并受 wal_compression 影响；除非存储栈提供等价的原子页保证，否则不应关闭。

应把 full_page_writes 与 data_sync_retry、restart_after_crash、recovery_init_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 持久生产数据保持 full_page_writes=on。性能问题应从存储延迟、检查点、WAL 压缩和批处理着手，不要用关闭崩溃安全换吞吐。
OLAP 批量装载同样需要可恢复性；用 UNLOGGED/临时数据结构或可重建 staging 明确缩小耐久范围，而不是全局关闭保护。
小规格 持久小实例也保持开启。只有数据可随时重建且与生产明确隔离的临时集群，才可在书面接受风险后例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 没有端到端原子页写保证就关闭该参数。
  • 把它增加的 WAL 量误解成每次修改都会记录整页。
  • 忽略检查点之后全页镜像集中出现的 WAL 突发。
  • 误以为 reload 后会追溯保护在 full_page_writes=off 期间已经生成的 WAL。
  • 关闭参数做基准，却没有端到端崩溃、恢复与 torn-page 测试。

关联参数

data_sync_retry · restart_after_crash · recovery_init_sync_method · fsync · wal_sync_method · synchronous_commit

参考资料

16.15 - max_wal_size

max_wal_size：设置触发自动检查点的 WAL 大小。实测在档范围为 PG9.5–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 GiB，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置触发自动检查点的 WAL 大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值MB
原始单位
范围 值2 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值1024
1 GiB

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 88e982302684 — Replace checkpoint_segments with min_wal_size and max_wal_size.
提交日期 2015-02-23
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–9.6 64 16MB 1 GiB (64 × 16MB)
PG10–19 Beta 3 1024 MB 1 GiB

机制详解

检查点进程会在 checkpoint_timeout 到期或 WAL 即将超过 max_wal_size 时启动自动检查点，二者谁先发生就由谁触发。检查点越频繁，脏页被写回得越频繁，并且每次检查点之后产生的全页镜像也会更多。

max_wal_size 不是磁盘配额。高写入负载、恢复过程、归档变慢或失败、wal_keep_size 保留文件，以及复制槽仍需要旧 WAL 时，实际 pg_wal 都可能超过该值。

增大它通常能减少请求型检查点和检查点写入抖动，但会扩大崩溃后需要重放的 WAL 区间，也要求更多 pg_wal 余量。min_wal_size 只控制 WAL 文件回收的下限，并不会把 max_wal_size 变成硬上限。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 根据实测峰值 WAL 产生速率和可接受的检查点频率定值。持续观察 pg_stat_checkpointer、checkpoint_warning、写延迟、归档延迟与剩余空间；只有请求型检查点长期占主导时才有依据上调。
OLAP 批量导入和大型维护任务会突发产生 WAL，较大值可减少检查点风暴。必须同时确认 pg_wal 容量、归档吞吐以及更长的崩溃恢复窗口都可接受。
小规格 小磁盘应使用保守且有明确上限的值。复制槽保留量和归档积压要另算，并预留应急空间，不要把卷的大部分空间都分配给名义上的检查点阈值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 20GB 不同于 boot 值 {{ ([pg_size_twentieth * 4, 2000])|min }}GB
OLAP 20GB 不同于 boot 值 {{ ([pg_size_twentieth * 4, 2000])|min }}GB
CRIT 20GB 不同于 boot 值 {{ ([pg_size_twentieth * 4, 2000])|min }}GB
TINY 20GB 不同于 boot 值 {{ ([pg_size_twentieth * 4, 2000])|min }}GB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 = 20GB (dcs)；OLAP: PG9.5–19 Beta 3 = 20GB (dcs)；CRIT: PG9.5–19 Beta 3 = 20GB (dcs)；TINY: PG9.5–19 Beta 3 = 20GB (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。

常见坑

  • 误以为 max_wal_size 是 pg_wal 的硬上限。
  • 通过增大该值掩盖归档失败或废弃复制槽。
  • 下调前没有评估全页镜像量和检查点延迟。
  • 忽略无单位数字按 MB 解释。
  • 脱离 checkpoint_timeout 与 checkpoint_completion_target 单独调参。

关联参数

min_wal_size · checkpoint_timeout · checkpoint_completion_target · checkpoint_warning · wal_keep_size · max_slot_wal_keep_size

参考资料

16.16 - min_wal_size

min_wal_size：设置 WAL 可收缩到的最小规模。实测在档范围为 PG9.5–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 80 MiB，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 WAL 可收缩到的最小规模。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值MB
原始单位
范围 值2 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Checkpoints
上游分类
最后 boot 值 值80
80 MiB

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 88e982302684 — Replace checkpoint_segments with min_wal_size and max_wal_size.
提交日期 2015-02-23
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–9.6 5 16MB 80 MiB (5 × 16MB)
PG10–19 Beta 3 80 MB 80 MiB

机制详解

设置 WAL 可收缩到的最小规模。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

低于该下限时，检查点会保留旧 WAL 段供复用而不是删除。它是保留/回收空间的下限，不是上限；归档失败、复制槽、wal_keep_size 与 max_wal_size 都可能让 pg_wal 远大于它。

应把 min_wal_size 与 max_wal_size、wal_keep_size、wal_segment_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按检查点之间的常态 WAL 生成量与文件创建成本设置回收池下限；它应明显低于可用 pg_wal 空间，并与 max_wal_size 一起测量。
OLAP 大批装载可受益于更大的预留回收池，但应依据可重复批次峰值，而不是照搬任意 GB 数；归档与复制槽空间另算。
小规格 先核对 Pigsty 的 5GB 矩阵值是否适合实际磁盘；对小盘这不是免费的默认值，调低时要接受更多段创建/删除抖动。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
OLAP 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
CRIT 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
TINY 5GB 不同于 boot 值 {{ ([pg_size_twentieth, 200])|min }}GB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 = 5GB (dcs)；OLAP: PG9.5–19 Beta 3 = 5GB (dcs)；CRIT: PG9.5–19 Beta 3 = 5GB (dcs)；TINY: PG9.5–19 Beta 3 = 5GB (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在保留足以吸收常规突发、避免文件抖动的可复用 WAL 池；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把它理解成 pg_wal 上限。
  • 不考虑 wal_segment_size 取整和突发速率。
  • 忽略归档/复制槽保留可同时越过 min_wal_size 与 max_wal_size。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

max_wal_size · wal_keep_size · wal_segment_size · checkpoint_timeout · checkpoint_completion_target · checkpoint_flush_after

参考资料

16.17 - recovery_end_command

recovery_end_command：设置恢复结束时执行一次的 shell 命令。它是 PG12–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置恢复结束时执行一次的 shell 命令。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Archive Recovery
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置恢复结束时执行一次的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 recovery_end_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 recovery_end_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
OLAP 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
小规格 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 shell 命令当作事务性的提升钩子，并误以为失败会回滚恢复。
  • 误读 %r，删除其他恢复消费者仍需要的 WAL。
  • 没有考虑提升或恢复重试，就执行非幂等的外部副作用。
  • 误以为 reload 会执行命令；它只在归档恢复结束时运行一次。
  • 在 postgres 服务账号执行的命令中嵌入凭据或不安全的 shell 展开。

关联参数

archive_mode · archive_command · archive_library · archive_timeout · archive_cleanup_command · restore_command

参考资料

16.18 - recovery_prefetch

recovery_prefetch：在恢复期间预取 WAL 引用的数据块。它是 PG15–18 的 sighup 参数；最新实测启动默认值为 try。
说明

Fact — 官方简述译文：在恢复期间预取 WAL 引用的数据块。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值off, on, try
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery
上游分类
最后 boot 值 值try
try

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 1d257577e08d — Optionally prefetch referenced data in recovery.
提交日期 2021-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 try — try

机制详解

在恢复期间预取 WAL 引用的数据块。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 recovery_prefetch 与 wal_decode_buffer_size、maintenance_io_concurrency、effective_io_concurrency 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在与生产相同的存储上用恢复/备库追赶基准调 recovery_prefetch，同时观察 replay I/O wait、缓存命中与 maintenance_io_concurrency；没有测量收益就保留默认。
OLAP 大型数据集且随机读取较慢时可能收益更大，但过度预取会挤占查询 I/O 与缓存；在故障恢复与读备库两种场景分别测试。
小规格 默认通常足够。内存与 I/O 队列有限时，不要为扩大超前窗口占用资源，除非恢复时间目标有明确缺口。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为 try 在操作系统不支持所需 read-ahead advice 时也一定启用预取。
  • 扩大超前读取，却不考虑 wal_decode_buffer_size 与 maintenance_io_concurrency。
  • 让恢复预取与 hot standby 查询争夺缓存和 I/O 队列深度。
  • 只测试顺序恢复场景，而该场景的块预取收益可能很小。

关联参数

wal_decode_buffer_size · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command

参考资料

16.19 - recovery_target

recovery_target：设为 immediate，使恢复在首次达到一致状态时结束。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设为 immediate，使恢复在首次达到一致状态时结束。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设为 immediate，使恢复在首次达到一致状态时结束。该值在服务器启动时固定，修改后必须重启。

唯一允许的值是 immediate，使目标恢复停在首个一致点，通常即在线基础备份结束位置。它与 LSN、名称、时间和 XID 目标选择器互斥。

recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 immediate 与 LSN、名称、时间或 XID 选择器同时设置。
  • 把在线备份后的首个一致点误当成业务所需恢复点。
  • 在普通备库配置中残留 immediate，意外结束恢复。
  • 未创建 recovery.signal 就期待该目标控制崩溃恢复。
  • 所需 WAL 链未达到一致点却误判恢复成功。

关联参数

recovery_target_time · recovery_target_xid · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action

参考资料

16.20 - recovery_target_action

recovery_target_action：设置到达恢复目标后执行的动作。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 pause。
说明

Fact — 官方简述译文：设置到达恢复目标后执行的动作。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值pause, promote, shutdown
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值pause
pause

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 pause — pause

机制详解

选择 PostgreSQL 到达已配置恢复目标后的动作。恢复启动时读取该值。

pause 暂停恢复供检查，promote 结束恢复并进入正常服务，shutdown 在目标处停止服务器；使用 pause 查询检查需要启用 hot_standby。

没有停止目标时该设置无效。使用 shutdown 时 recovery.signal 不会删除，配置不变的再次启动会到达目标后再次停机；验证后必须有意清理或修改恢复配置。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_action，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 未配置停止目标却期待动作生效。
  • hot_standby 关闭时使用 pause，却期待用查询检查数据库。
  • 尚未验证恢复状态就使用 promote。
  • 使用 shutdown 后保留 recovery.signal 与相同目标直接重启。
  • 把 shutdown 当作永久删除目标后的 WAL；下次启动仍会从最后检查点重放到目标。

关联参数

recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_inclusive · recovery_target_timeline · hot_standby

参考资料

16.21 - recovery_target_inclusive

recovery_target_inclusive：设置是否包含恢复目标所对应的事务。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 on。
说明

Fact — 官方简述译文：设置是否包含恢复目标所对应的事务。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 on — on

机制详解

选择精确恢复边界的哪一侧被保留。它是 postmaster 参数，在目标恢复启动时读取。

on 在目标之后停止并包含目标 LSN、提交时间或 XID；off 在目标之前停止并排除它。该设置只适用于 recovery_target_lsn、recovery_target_time 与 recovery_target_xid。

它对 immediate 或命名还原点目标无效。应依据已识别的 WAL/业务证据选择边界，并验证恢复后的行与事务，而不只查看显示的时间戳或 LSN。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_inclusive，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待它影响 immediate 或命名还原点目标。
  • 未识别准确边界事务或 WAL 记录就选择 on/off。
  • 误以为相同时间戳对应唯一确定的提交边界。
  • 只验证报告的重放位置，而不验证恢复后的应用数据。
  • 把该值留在复用恢复模板中，却未记录预期边界侧。

关联参数

recovery_target_lsn · recovery_target_time · recovery_target_xid · recovery_target_action · recovery_target_timeline · restore_command

参考资料

16.22 - recovery_target_lsn

recovery_target_lsn：设置恢复所推进到的 WAL LSN。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置恢复所推进到的 WAL LSN。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置恢复所推进到的 WAL LSN。该值在服务器启动时固定，修改后必须重启。

恢复推进到一个 pg_lsn 位置，并由 recovery_target_inclusive 选择边界哪一侧。该 LSN 必须位于所选恢复时间线上，且基础备份之后的 WAL 链能够到达。

recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_lsn，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 使用另一集群的 LSN，或使用不源自基础备份的时间线 LSN。
  • 同时设置另一个恢复目标选择器。
  • 未识别必须包含的 WAL 记录就选择 inclusive。
  • 请求超过归档/流式 WAL 可用范围的 LSN，形成不可达目标。
  • 把 LSN 当普通十进制数比较，而不是 pg_lsn 值。

关联参数

recovery_target · recovery_target_time · recovery_target_xid · recovery_target_name · recovery_target_inclusive · recovery_target_action

参考资料

16.23 - recovery_target_name

recovery_target_name：设置恢复所推进到的命名还原点。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置恢复所推进到的命名还原点。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置恢复所推进到的命名还原点。该值在服务器启动时固定，修改后必须重启。

恢复停在此前由 pg_create_restore_point() 写入的命名还原点。只有所选时间线的 WAL 中确实存在对应记录，名称才有意义。

recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_name，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 指定的还原点 WAL 记录不在所选时间线中。
  • 误以为 recovery_target_inclusive 会改变命名还原点边界。
  • 同时设置另一个恢复目标选择器。
  • 拼错区分大小写的还原点名称，使目标不可达。
  • 只记录业务标签，却未记录集群、时间线与基础备份关系。

关联参数

recovery_target · recovery_target_time · recovery_target_xid · recovery_target_lsn · recovery_target_inclusive · recovery_target_action

参考资料

16.24 - recovery_target_time

recovery_target_time：设置恢复所推进到的时间戳。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置恢复所推进到的时间戳。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置恢复所推进到的时间戳。该值在服务器启动时固定，修改后必须重启。

恢复用事务提交记录与该时间戳比较；数值 UTC 偏移或完整时区名可避免缩写歧义。recovery_target_inclusive 决定是否重放恰好位于边界的提交。

recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_time，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 使用有歧义的时区缩写，而不是数值偏移或完整时区名。
  • 误以为一个墙钟时间戳能唯一标识业务事务。
  • 同时设置另一个恢复目标选择器。
  • 未识别准确边界提交就选择 inclusive on/off。
  • 请求的时间不在可达 WAL 范围内或位于错误时间线。

关联参数

recovery_target · recovery_target_xid · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action

参考资料

16.25 - recovery_target_timeline

recovery_target_timeline：指定要恢复到的时间线。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 latest。
说明

Fact — 官方简述译文：指定要恢复到的时间线。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值latest
latest

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 latest — latest

机制详解

指定恢复要沿用的时间线历史。它是 postmaster 参数，只在本次恢复启动时读取。

latest 跟随归档中最新时间线，current 留在基础备份当时的时间线；显式十进制或带 0x 前缀的十六进制 ID 选择特定分支。时间线既可单独选择，也可与更早的停止目标组合。

所选时间线必须源自该基础备份，并且对应 history/WAL 文件可用。该参数只选择分支，不会自行选择事务边界或提升服务器。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_timeline，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 需要沿旧分支重新恢复时仍使用 latest。
  • 所需 WAL 只在后代时间线时仍使用 current。
  • 选择不源自基础备份的时间线。
  • 未保留时间线 history 文件与对应 WAL。
  • 把时间线选择误当成停止目标或提升命令。

关联参数

recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_action · restore_command · primary_conninfo

参考资料

16.26 - recovery_target_xid

recovery_target_xid：设置恢复所推进到的事务 ID。它是 PG12–18 的 postmaster 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置恢复所推进到的事务 ID。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery Target
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置恢复所推进到的事务 ID。该值在服务器启动时固定，修改后必须重启。

目标是指定事务 ID 的提交记录，而不是所有事务的简单数值顺序：XID 在事务开始时分配，提交顺序可能不同。recovery_target_inclusive 决定是否包含目标事务。

recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_xid，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。
OLAP 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。
小规格 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为 XID 数值顺序等于提交顺序；XID 在事务开始时分配。
  • 使用来自另一集群或无关时间线的 XID。
  • 同时设置另一个恢复目标选择器。
  • 未决定是否需要目标事务本身就选择 inclusive。
  • 把 XID 当作跨回卷与跨集群全局唯一的业务标识。

关联参数

recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action

参考资料

16.27 - restore_command

restore_command：设置取回归档 WAL 文件时调用的 shell 命令。它是 PG12–18 的 sighup 参数；最新实测启动默认值为 empty。
说明

Fact — 官方简述译文：设置取回归档 WAL 文件时调用的 shell 命令。

身份

类型 值string
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Archive Recovery
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf
提交日期 2018-11-25
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

设置取回归档 WAL 文件时调用的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

归档恢复时 PostgreSQL 把 %f 展开为请求文件、%p 展开为目标路径。成功必须表示准确文件已可靠复制；正常的未找到应返回非零，以便继续尝试流复制或 pg_wal，同时 shell 引用必须安全。

应把 restore_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 restore_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
OLAP 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
小规格 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 缺失或错误 WAL 文件也返回零。
  • 没有安全引用 %f 与 %p。
  • 归档可能返回另一时间线或集群的同名段。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

archive_mode · archive_command · archive_library · archive_timeout · archive_cleanup_command · recovery_end_command

参考资料

16.28 - summarize_wal

summarize_wal：启动 WAL summarizer 进程以支持增量备份。它是 PG17–18 的 sighup 参数；最新实测启动默认值为 off。
说明

Fact — 官方简述译文：启动 WAL summarizer 进程以支持增量备份。

身份

类型 值bool
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Summarization
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 174c480508ac — Add a new WAL summarizer process.
提交日期 2023-12-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 off — off

机制详解

启动 WAL summarizer 进程以支持增量备份。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

WAL summarizer 记录各 WAL 范围修改过的块，让 pg_basebackup 能构造增量备份。它可在主库或备库运行，但无法汇总以 wal_level=minimal 生成的 WAL。

应把 summarize_wal 与 wal_summary_keep_time、wal_level、archive_mode 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有采用 PostgreSQL 增量备份时才启用/调整 summarize_wal；监控 summarizer 进度，并让摘要覆盖任何相邻基础/增量备份之间的完整 WAL 范围。
OLAP 批量写入会增加摘要工作；把备份间隔、WAL 峰值和备份窗口一起做容量测试，摘要缺口会使增量备份失败。
小规格 不做增量备份就保持 summarize_wal 关闭；若启用，保留期要由实际备份链决定，并给摘要目录设置容量告警。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在 wal_level=minimal 下启用，却期待生成可用摘要。
  • 把 WAL 摘要本身当作 WAL 归档或备份。
  • 关闭 summarizer 后仍期待 wal_summary_keep_time 继续清理。
  • 未检查 summarizer 进度与摘要覆盖范围就执行增量备份。

关联参数

wal_summary_keep_time · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command

参考资料

16.29 - synchronous_commit

synchronous_commit：设置当前事务提交时使用的同步级别。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 on，context 为 user。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置当前事务提交时使用的同步级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值local, remote_write, remote_apply, on, off
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

除 off 外的所有模式都会等待本地 WAL 刷入持久存储。off 可以在本地持久化之前返回成功；崩溃可能丢失最近已确认的事务，但恢复后的数据库仍保持事务一致性，不会产生 fsync = off 那类结构损坏风险。

当 synchronous_standby_names 选定同步备库时，remote_write 等待备库接收并写入操作系统，on 等待备库持久化刷新，remote_apply 还要等待重放并对查询可见；local 只等待本地持久化。如果没有选中同步备库，这些远程模式不会增加远程保证。

事务采用提交开始时生效的值。应用可以对单个事务使用 SET LOCAL，使关键事务和可重建事务在同一服务器上采用不同持久性策略。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 全局默认保持 on。仅对明确可重建的事务使用 off；只有提交后必须立即在同步备库读到结果时才使用 remote_apply，并把网络往返和备库健康纳入延迟预算。
OLAP 可重复执行的批量导入可在事务内使用 off，前提是能够接受最后一小段未刷盘数据丢失并可重跑。目录变更、交接标记和对外宣布完成的记录仍应同步提交。
小规格 保持 on。小型系统通常得不到足以抵消语义风险的全局降级收益，应只优化个别非关键任务。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 把 synchronous_commit = off 与 fsync = off 混为一谈；前者风险是近期数据丢失，不是结构损坏。
  • 没有选定同步备库时仍期待 remote_write、on 或 remote_apply 提供远程等待。
  • 使用 remote_write 却假设备库能抵御操作系统崩溃。
  • 同步备库不可用时没有 HA 处置方案，导致提交无限等待。
  • 连接池中使用会话级 SET 而未使用 SET LOCAL 或重置纪律，造成设置泄漏。

关联参数

synchronous_standby_names · fsync · wal_writer_delay · wal_sync_method · commit_delay · wal_level

参考资料

16.30 - wal_buffers

wal_buffers：设置共享内存中用于 WAL 的磁盘页缓冲区数量。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 -1 8kB，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置共享内存中用于 WAL 的磁盘页缓冲区数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值8kB
原始单位
范围 值-1 – 262143
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值-1
-1 8kB

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 8 8kB 64 KiB (8 × 8kB)
PG9.1–19 Beta 3 -1 8kB -1 8kB

机制详解

设置共享内存中用于 WAL 的磁盘页缓冲区数量。该值在服务器启动时固定，修改后必须重启。

自动值 -1 选择约 shared_buffers 的 1/32，并受最低值与一个 WAL 段上限约束。缓冲区吸收写出前的 WAL；过小会在突发中增加 WALWrite 压力，过大则占启动共享内存且不能替代持久化刷写。

应把 wal_buffers 与 fsync、full_page_writes、wal_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_buffers；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 16MB 不同于 boot 值 16MB
OLAP 16MB 不同于 boot 值 16MB
CRIT 16MB 不同于 boot 值 16MB
TINY 16MB 不同于 boot 值 16MB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 16MB (dcs)；OLAP: PG9.0–19 Beta 3 = 16MB (dcs)；CRIT: PG9.0–19 Beta 3 = 16MB (dcs)；TINY: PG9.0–19 Beta 3 = 16MB (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在显式使用通常为一个 WAL 段的上限来吸收突发；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把 -1 读成负分配，而不是自动尺寸。
  • 忘记自动值依据 shared_buffers 计算，并以一个 WAL 段为上限。
  • 把未带单位的正值读成字节，而不是 WAL 块；过小正值会提升到最低值。
  • 没有 WALInsert/WALWrite 压力证据就手工分配很大缓冲。
  • 误以为更多 WAL buffer 能替代持久刷盘或改善受存储限制的 WALSync。

关联参数

fsync · full_page_writes · wal_sync_method · synchronous_commit · wal_writer_delay · wal_writer_flush_after

参考资料

16.31 - wal_compression

wal_compression：使用指定方法压缩写入 WAL 的整页映像。实测在档范围为 PG9.5–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 superuser。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：使用指定方法压缩写入 WAL 的整页映像。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值pglz, lz4, zstd, on, off
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 57aa5b2bb11a — Add GUC to enable compression of full page images stored in WAL.
提交日期 2015-03-11
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 off — off

机制详解

使用指定方法压缩写入 WAL 的整页映像。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

压缩对象是 full_page_writes、备份或 hint logging 产生的整页映像，而非每条 WAL 记录。pglz 内置，lz4/zstd 取决于构建；它用主库压缩和备库解压 CPU 换取更小 WAL。

应把 wal_compression 与 full_page_writes、wal_log_hints、wal_level 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_compression；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP lz4 不同于 boot 值 lz4
OLAP lz4 不同于 boot 值 lz4
CRIT lz4 不同于 boot 值 lz4
TINY lz4 不同于 boot 值 lz4
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)；OLAP: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)；CRIT: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)；TINY: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在支持枚举压缩方法的版本上用 LZ4 降低整页映像 WAL 量；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 误以为压缩作用于每条 WAL，而不是整页映像。
  • 服务器构建未提供相应方法时选择 lz4 或 zstd。
  • 忽略主库压缩 CPU 与恢复重放解压 CPU。
  • 修改特权会话值后，误以为其他会话或新连接会自动继承。
  • 未控制检查点频率与 full_page_writes 活动就比较 WAL 字节量。

关联参数

full_page_writes · wal_log_hints · wal_level · wal_buffers · commit_delay · commit_siblings

参考资料

16.32 - wal_decode_buffer_size

wal_decode_buffer_size：设置恢复期间超前读取 WAL 的缓冲区大小。它是 PG15–18 的 postmaster 参数；最新实测启动默认值为 512 KiB。
说明

Fact — 官方简述译文：设置恢复期间超前读取 WAL 的缓冲区大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值B
原始单位
范围 值65536 – 1073741823
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Recovery
上游分类
最后 boot 值 值524288
512 KiB

生命周期

Fact 值
首次观测 PG15
在档版本 PG15–19 Beta 3
移除版本 否
引入提交 1d257577e08d — Optionally prefetch referenced data in recovery.
提交日期 2021-04-08
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG15–19 Beta 3 524288 B 512 KiB

机制详解

设置恢复期间超前读取 WAL 的缓冲区大小。该值在服务器启动时固定，修改后必须重启。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_decode_buffer_size 与 recovery_prefetch、maintenance_io_concurrency、effective_io_concurrency 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 在与生产相同的存储上用恢复/备库追赶基准调 wal_decode_buffer_size，同时观察 replay I/O wait、缓存命中与 maintenance_io_concurrency；没有测量收益就保留默认。
OLAP 大型数据集且随机读取较慢时可能收益更大，但过度预取会挤占查询 I/O 与缓存；在故障恢复与读备库两种场景分别测试。
小规格 默认通常足够。内存与 I/O 队列有限时，不要为扩大超前窗口占用资源，除非恢复时间目标有明确缺口。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。
  • 忽略检查点、复制槽或归档失败造成的联动。
  • 在需要 restart 的参数上只 reload 就认为已生效。

关联参数

recovery_prefetch · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command

参考资料

16.33 - wal_init_zero

wal_init_zero：新 WAL 文件首次使用前先写零。它是 PG12–18 的 superuser 参数；最新实测启动默认值为 on。
说明

Fact — 官方简述译文：新 WAL 文件首次使用前先写零。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 475861b2615d — Add wal_recycle and wal_init_zero GUCs.
提交日期 2019-04-02
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 on — on

机制详解

新 WAL 文件首次使用前先写零。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_init_zero 与 wal_recycle、wal_segment_size、min_wal_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_init_zero；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在传统文件系统上关闭写零，把空间分配停顿推到 WAL 峰值创建阶段。
  • 在写时复制存储上保留写零，却未测量分配与碎片成本。
  • 看到稀疏文件就误以为 PostgreSQL 改变了 wal_segment_size。
  • 修改会话值后，期待已经创建的 WAL 段被重写。

关联参数

wal_recycle · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings

参考资料

16.34 - wal_level

wal_level：设置写入 WAL 的信息级别。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 replica，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置写入 WAL 的信息级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值minimal, replica, logical
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值replica
replica

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.6 minimal — minimal
PG10–19 Beta 3 replica — replica

机制详解

设置写入 WAL 的信息级别。该值在服务器启动时固定，修改后必须重启。

minimal 只记录崩溃恢复所需信息，不能支持要求 replica 信息的归档/流复制；replica 支持物理复制与归档恢复；logical 再增加逻辑解码信息。修改必须重启，并可能改变 WAL 量。

应把 wal_level 与 wal_compression、full_page_writes、wal_log_hints 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_level；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP logical 不同于 boot 值 logical
OLAP logical 不同于 boot 值 logical
CRIT logical 不同于 boot 值 logical
TINY logical 不同于 boot 值 logical
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = logical (dcs)；OLAP: PG9.0–19 Beta 3 = logical (dcs)；CRIT: PG9.0–19 Beta 3 = logical (dcs)；TINY: PG9.0–19 Beta 3 = logical (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让所有 Pigsty profile 默认具备逻辑解码能力；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 选择 minimal 却仍期待归档、流复制或逻辑解码。
  • 提高级别却不预算额外 WAL 与重启。
  • 槽/订阅仍依赖高级别时就降低。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

wal_compression · full_page_writes · wal_log_hints · wal_buffers · max_wal_senders · max_replication_slots

参考资料

16.35 - wal_log_hints

wal_log_hints：页面在检查点后首次发生非关键修改时也将完整页面写入 WAL。实测在档范围为 PG9.4–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 off，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：页面在检查点后首次发生非关键修改时也将完整页面写入 WAL。

身份

类型 值bool
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 961bf59fb7a7 — Rename wal_log_hintbits to wal_log_hints, per discussion on pgsql-hackers.
提交日期 2013-12-21
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 off — off

机制详解

页面在检查点后首次发生非关键修改时也将完整页面写入 WAL。该值在服务器启动时固定，修改后必须重启。

未启用数据校验和时，它让检查点后第一次 hint bit 修改也记录整页 WAL，为 pg_rewind 提供所需块变化安全性。启用校验和后等价日志本就发生，因此该开关不再增加效果。

应把 wal_log_hints 与 wal_compression、full_page_writes、wal_level 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_log_hints；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP on 不同于 boot 值 'on'
OLAP on 不同于 boot 值 'on'
CRIT on 不同于 boot 值 'on'
TINY on 不同于 boot 值 'on'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 = on (dcs)；OLAP: PG9.4–19 Beta 3 = on (dcs)；CRIT: PG9.4–19 Beta 3 = on (dcs)；TINY: PG9.4–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在即使未由数据校验和强制记录 hint bit WAL，也保持 pg_rewind 可用；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。
  • 忽略检查点、复制槽或归档失败造成的联动。
  • 在需要 restart 的参数上只 reload 就认为已生效。

关联参数

wal_compression · full_page_writes · wal_level · wal_buffers · max_wal_senders · max_replication_slots

参考资料

16.36 - wal_recycle

wal_recycle：通过重命名复用 WAL 文件。它是 PG12–18 的 superuser 参数；最新实测启动默认值为 on。
说明

Fact — 官方简述译文：通过重命名复用 WAL 文件。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 475861b2615d — Add wal_recycle and wal_init_zero GUCs.
提交日期 2019-04-02
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 on — on

机制详解

通过重命名复用 WAL 文件。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_recycle 与 wal_init_zero、wal_segment_size、min_wal_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_recycle；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 误以为在写时复制存储上，重命名复用一定比新分配更快。
  • 关闭复用前没有测量 WAL 突发期间的段创建延迟。
  • 期待会话修改改变已经复用或删除的文件。
  • 把文件复用策略误当成 WAL 保留上限。

关联参数

wal_init_zero · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings

参考资料

16.37 - wal_skip_threshold

wal_skip_threshold：设置用 fsync 新文件代替写 WAL 的最小文件规模。它是 PG13–18 的 user 参数；最新实测启动默认值为 2 MiB。
说明

Fact — 官方简述译文：设置用 fsync 新文件代替写 WAL 的最小文件规模。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值2048
2 MiB

生命周期

Fact 值
首次观测 PG13
在档版本 PG13–19 Beta 3
移除版本 否
引入提交 cb2fd7eac285 — Skip WAL for new relfilenodes, under wal_level=minimal.
提交日期 2020-03-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG13–19 Beta 3 2048 kB 2 MiB

机制详解

设置用 fsync 新文件代替写 WAL 的最小文件规模。它可在会话级修改，因此不同会话可能采用不同的行为。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_skip_threshold 与 commit_delay、commit_siblings、fsync 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_skip_threshold；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 在 wal_level=replica 或 logical 下调优；此时该参数没有作用。
  • 把它应用到普通行修改，而它只涉及新建或重写的关系文件。
  • 把未带单位的值读成字节，而不是 kB。
  • 未基于真实存储与并发提交影响测试，就在 fsync 与写 WAL 之间作选择。

关联参数

commit_delay · commit_siblings · fsync · full_page_writes · synchronous_commit · wal_buffers

参考资料

16.38 - wal_summary_keep_time

wal_summary_keep_time：设置 WAL 摘要文件的保留时间。它是 PG17–18 的 sighup 参数；最新实测启动默认值为 10 d。
说明

Fact — 官方简述译文：设置 WAL 摘要文件的保留时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值min
原始单位
范围 值0 – 35791394
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Summarization
上游分类
最后 boot 值 值14400
10 d

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 174c480508ac — Add a new WAL summarizer process.
提交日期 2023-12-20
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 14400 min 10 d

机制详解

设置 WAL 摘要文件的保留时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

summarizer 按文件时间戳删除超过该年龄的摘要。保留期必须长于一次增量备份与其依赖的先前备份之间的最长间隔；零表示无限保留，summarize_wal 关闭时也不会清理。

应把 wal_summary_keep_time 与 summarize_wal、wal_level、archive_mode 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有采用 PostgreSQL 增量备份时才启用/调整 wal_summary_keep_time；监控 summarizer 进度，并让摘要覆盖任何相邻基础/增量备份之间的完整 WAL 范围。
OLAP 批量写入会增加摘要工作；把备份间隔、WAL 峰值和备份窗口一起做容量测试，摘要缺口会使增量备份失败。
小规格 不做增量备份就保持 summarize_wal 关闭；若启用，保留期要由实际备份链决定，并给摘要目录设置容量告警。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 删除连接前后两次增量备份仍需要的摘要。
  • 设为零却不监控无界增长。
  • 关闭 summarize_wal 后仍期待保留清理继续。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

关联参数

summarize_wal · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command

参考资料

16.39 - wal_sync_method

wal_sync_method：选择将 WAL 更新强制写入磁盘的方法。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 fdatasync，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：选择将 WAL 更新强制写入磁盘的方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值fsync, fdatasync, open_sync, open_datasync
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值fdatasync
fdatasync

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 fdatasync — fdatasync

机制详解

选择将 WAL 更新强制写入磁盘的方法。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_sync_method 与 fsync、full_page_writes、synchronous_commit 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_sync_method；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 选择操作系统或文件系统不支持的同步方法。
  • 在与生产不同的内核、挂载参数或存储缓存上做基准。
  • 混淆写吞吐与持久同步延迟。
  • 修改方法却不做崩溃或掉电耐久性测试。
  • 误以为数据文件上最快的方法也一定最适合 WAL。

关联参数

fsync · full_page_writes · synchronous_commit · wal_buffers · wal_writer_delay · commit_delay

参考资料

16.40 - wal_writer_delay

wal_writer_delay：设置 WAL writer 两次刷写之间的时间。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 200 ms，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置 WAL writer 两次刷写之间的时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值ms
原始单位
范围 值1 – 10000
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值200
200 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 200 ms 200 ms

机制详解

设置 WAL writer 两次刷写之间的时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_writer_delay 与 fsync、full_page_writes、wal_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_writer_delay；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 20ms 不同于 boot 值 20ms
OLAP 20ms 不同于 boot 值 20ms
CRIT 10ms 不同于 boot 值 10ms
TINY 20ms 不同于 boot 值 20ms
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 20ms (dcs)；OLAP: PG9.0–19 Beta 3 = 20ms (dcs)；CRIT: PG9.0–19 Beta 3 = 10ms (dcs)；TINY: PG9.0–19 Beta 3 = 20ms (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让 WAL 更频繁地由后台移出前台后端，CRIT 采用更短节奏；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把间隔当成严格的提交刷盘期限；writer 可提前唤醒，前台提交也可独立刷盘。
  • 设置过低，产生过多唤醒与小写入开销。
  • 设置过高，把更多 WAL 写入推回前台后端。
  • 解释写出与持久刷盘时机时忽略 wal_writer_flush_after。
  • 使用异步提交却没有为可能的数据丢失窗口做预算。

关联参数

fsync · full_page_writes · wal_sync_method · synchronous_commit · wal_buffers · commit_delay

参考资料

16.41 - wal_writer_flush_after

wal_writer_flush_after：设置触发 WAL writer 刷盘的写出 WAL 数量。实测在档范围为 PG9.6–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 1 MiB (128 × 8kB)，context 为 sighup。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置触发 WAL writer 刷盘的写出 WAL 数量。

身份

类型 值integer
上游 pg_settings 类型
Context 值sighup
配置 reload 后生效
单位 值8kB
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Write-Ahead Log / Settings
上游分类
最后 boot 值 值128
1 MiB (128 × 8kB)

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 7975c5e0a992 — Allow the WAL writer to flush WAL at a reduced rate.
提交日期 2016-02-15
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 128 8kB 1 MiB (128 × 8kB)

机制详解

设置触发 WAL writer 刷盘的写出 WAL 数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。

应把 wal_writer_flush_after 与 wal_buffers、wal_writer_delay、wal_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_writer_flush_after；每次改动都做崩溃/恢复与归档监控验证。
OLAP 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。
小规格 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 1MB 等于 boot 值 1MB
OLAP 1MB 等于 boot 值 1MB
CRIT 0 不同于 boot 值 0
TINY 1MB 等于 boot 值 1MB
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 1MB (dcs)；OLAP: PG9.6–19 Beta 3 = 1MB (dcs)；CRIT: PG9.6–19 Beta 3 = 0 (dcs)；TINY: PG9.6–19 Beta 3 = 1MB (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让 WAL writer 按 1 MiB 批量刷盘，而 CRIT 要求立即刷盘；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。

常见坑

  • 把未带单位的值读成字节，而不是 WAL 块。
  • 忘记零表示 WAL writer 立即请求刷盘。
  • 选择大批量，却不考虑异步提交的数据丢失暴露与脏 WAL。
  • 把该参数当作同步提交刷盘的替代品。
  • 不结合 wal_writer_delay 与存储刷盘延迟就调优。

关联参数

wal_buffers · wal_writer_delay · wal_sync_method · synchronous_commit · commit_delay · commit_siblings

参考资料