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

资源使用

Resource Usage 分类下的 51 个 PostgreSQL 核心配置参数档案。

1: autovacuum_work_mem
2: backend_flush_after
3: bgwriter_delay
4: bgwriter_flush_after
5: bgwriter_lru_maxpages
6: bgwriter_lru_multiplier
7: commit_timestamp_buffers
8: dynamic_shared_memory_type
9: effective_io_concurrency
10: file_copy_method
11: file_extend_method
12: hash_mem_multiplier
13: huge_page_size
14: huge_pages
15: io_combine_limit
16: io_max_combine_limit
17: io_max_concurrency
18: io_max_workers
19: io_method
20: io_min_workers
21: io_worker_idle_timeout
22: io_worker_launch_interval
23: io_workers
24: logical_decoding_work_mem
25: maintenance_io_concurrency
26: maintenance_work_mem
27: max_files_per_process
28: max_notify_queue_pages
29: max_parallel_maintenance_workers
30: max_parallel_workers
31: max_parallel_workers_per_gather
32: max_prepared_transactions
33: max_stack_depth
34: max_worker_processes
35: min_dynamic_shared_memory
36: multixact_member_buffers
37: multixact_offset_buffers
38: notify_buffers
39: old_snapshot_threshold
40: parallel_leader_participation
41: replacement_sort_tuples
42: serializable_buffers
43: shared_buffers
44: shared_memory_type
45: subtransaction_buffers
46: temp_buffers
47: temp_file_limit
48: timing_clock_source
49: transaction_buffers
50: vacuum_buffer_usage_limit
51: work_mem

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

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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 - 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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

参考资料

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

资源使用

1 - autovacuum_work_mem

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

2 - backend_flush_after

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

3 - bgwriter_delay

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

4 - bgwriter_flush_after

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

5 - bgwriter_lru_maxpages

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

6 - bgwriter_lru_multiplier

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

7 - commit_timestamp_buffers

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数

参考资料

8 - dynamic_shared_memory_type

身份

生命周期

默认值变迁

机制详解

调优建议

Pigsty 取值

常见坑

关联参数