这是本节的多页打印视图。 .
预写日志
- 1: archive_cleanup_command
- 2: archive_command
- 3: archive_library
- 4: archive_mode
- 5: archive_timeout
- 6: checkpoint_completion_target
- 7: checkpoint_flush_after
- 8: checkpoint_segments
- 9: checkpoint_timeout
- 10: checkpoint_warning
- 11: commit_delay
- 12: commit_siblings
- 13: fsync
- 14: full_page_writes
- 15: max_wal_size
- 16: min_wal_size
- 17: recovery_end_command
- 18: recovery_prefetch
- 19: recovery_target
- 20: recovery_target_action
- 21: recovery_target_inclusive
- 22: recovery_target_lsn
- 23: recovery_target_name
- 24: recovery_target_time
- 25: recovery_target_timeline
- 26: recovery_target_xid
- 27: restore_command
- 28: summarize_wal
- 29: synchronous_commit
- 30: wal_buffers
- 31: wal_compression
- 32: wal_decode_buffer_size
- 33: wal_init_zero
- 34: wal_level
- 35: wal_log_hints
- 36: wal_recycle
- 37: wal_skip_threshold
- 38: wal_summary_keep_time
- 39: wal_sync_method
- 40: wal_writer_delay
- 41: wal_writer_flush_after
条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。
1 - archive_cleanup_command
Fact — 官方简述译文：设置每次重启点执行的 shell 命令。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置每次重启点执行的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
归档恢复的每个 restartpoint 都会执行该命令，并把 %r 展开为保持恢复可重新启动所需的最早 WAL 文件。通常使用 pg_archivecleanup；若多个备库共享归档，贸然删除可能让其他消费者断链。
应把 archive_cleanup_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 把 archive_cleanup_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。 |
| OLAP | 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。 |
| 小规格 | 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 对其他备库或恢复任务共享的归档执行破坏性清理。
- 把 %r 误读为最后重放文件；它表示保持恢复可重新启动所需的最早文件。
- restartpoint 重复或归档文件已不存在时，命令不具备幂等性。
- 误以为 reload 会立即执行命令；它只在恢复 restartpoint 运行。
- shell 引用或异常归档路径使清理越过预期归档目录。
关联参数
archive_mode · archive_command · archive_library · archive_timeout · restore_command · recovery_end_command
参考资料
2 - archive_command
Fact — 官方简述译文：设置归档 WAL 文件时调用的 shell 命令。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | "" |
— | empty string |
机制详解
设置归档 WAL 文件时调用的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
归档进程把 %p 展开为源路径、%f 展开为 WAL 文件名，并把退出码 0 当作持久成功；非零会重试。虚假成功会允许 PostgreSQL 回收唯一的本地副本，悄然破坏归档链。
应把 archive_command 与 archive_mode、archive_library、archive_timeout 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 把 archive_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。 |
| OLAP | 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。 |
| 小规格 | 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | pgbackrest --stanza=fixture archive-push %p |
不同于 boot 值 | 'pgbackrest --stanza={{ pg_cluster }} archive-push %p' |
| OLAP | pgbackrest --stanza=fixture archive-push %p |
不同于 boot 值 | 'pgbackrest --stanza={{ pg_cluster }} archive-push %p' |
| CRIT | pgbackrest --stanza=fixture archive-push %p |
不同于 boot 值 | 'pgbackrest --stanza={{ pg_cluster }} archive-push %p' |
| TINY | pgbackrest --stanza=fixture archive-push %p |
不同于 boot 值 | 'pgbackrest --stanza={{ pg_cluster }} archive-push %p' |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)；OLAP: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)；CRIT: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)；TINY: PG9.0–19 Beta 3 = pgbackrest –stanza=fixture archive-push %p (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在把归档绑定到 Pigsty 用于 PITR 的 pgBackRest stanza；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 归档副本尚未持久化或校验就返回成功。
- shell 命令没有安全引用 %p/%f。
- 反复失败写满 pg_wal 并使服务器停摆。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
archive_mode · archive_library · archive_timeout · archive_cleanup_command · restore_command · recovery_end_command
参考资料
3 - archive_library
Fact — 官方简述译文：设置归档 WAL 文件时调用的库。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG15 |
| 在档版本 | PG15–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 5ef1eefd76f4 — Allow archiving via loadable modules. |
| 提交日期 | 2022-02-03 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG15–19 Beta 3 | "" |
— | empty string |
机制详解
设置归档 WAL 文件时调用的库。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
非空值通过 _PG_archive_module_init 回调选择归档模块，取代 shell 命令。archive_command 与 archive_library 是二选一实现；二者可重载，但 archive_mode 必须已经启用。
应把 archive_library 与 archive_mode、archive_command、archive_timeout 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 把 archive_library 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。 |
| OLAP | 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。 |
| 小规格 | 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 同时配置库，却期待 archive_command 在库失败时自动兜底。
- 把不可信归档代码加载到服务器进程内。
- 把模块返回成功误当成归档一定可恢复。
- reload 到新模块后未验证积压处理、失败报告和回滚。
- 模块反复失败却没有归档延迟告警，最终让保留 WAL 填满 pg_wal。
关联参数
archive_mode · archive_command · archive_timeout · archive_cleanup_command · restore_command · recovery_end_command
参考资料
4 - archive_mode
Fact — 官方简述译文：允许使用 archive_command 归档 WAL 文件。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- off
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | off |
— | off |
机制详解
启用后，PostgreSQL 会运行 WAL 归档进程，并在段文件可被回收之前将每个已完成段交给 archive_command，或在支持版本中交给 archive_library。模式与命令或库相互独立，因此归档逻辑可以重载而无需退出归档模式。
在普通主库运行期间，on 与 always 没有区别。在恢复或备库模式下，on 不归档收到的 WAL，而 always 还会归档从归档恢复或通过流复制收到的段。
打开该模式并不能证明归档健康或可恢复。命令失败会让 WAL 在 pg_wal 中积累；错误地返回成功会造成不可恢复的 WAL 链。时间点恢复还需要合适的基础备份和经过验证的恢复流程。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 只为明确的 PITR 或日志传送需求启用，并使用可靠、幂等的归档实现。监控 pg_stat_archiver 失败、最新归档时间和 pg_wal 增长；恢复演练比命令返回成功更有说服力。 |
| OLAP | 按批量导入的 WAL 峰值规划归档带宽和目标容量。归档跟不上时，应节流或错峰批任务，而不是放任 pg_wal 写满。 |
| 小规格 | 只有理解保留策略和恢复步骤时才使用 pgBackRest 等托管工具。对于可随时重建的数据库，应保持关闭，而不是配置一个占位归档命令。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | on |
不同于 boot 值 | 'on' |
| OLAP | on |
不同于 boot 值 | 'on' |
| CRIT | on |
不同于 boot 值 | 'on' |
| TINY | on |
不同于 boot 值 | 'on' |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = on (dcs)；OLAP: PG9.0–19 Beta 3 = on (dcs)；CRIT: PG9.0–19 Beta 3 = on (dcs)；TINY: PG9.0–19 Beta 3 = on (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。
常见坑
- 启用 archive_mode 却使用空命令或失败命令，最终写满 pg_wal。
- 使用 /bin/true 一类虚假成功命令，破坏可恢复的 WAL 链。
- 误以为 archive_mode 可重载；修改它需要重启服务器。
- 把 WAL 归档当作基础备份和恢复演练的替代品。
- always 模式写共享归档时没有处理重复文件和并发竞态。
关联参数
archive_command · archive_library · archive_timeout · wal_level · restore_command · max_wal_size
参考资料
5 - archive_timeout
Fact — 官方简述译文：设置强制切换到下一个 WAL 文件前的最长等待时间。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 0 s
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | 0 |
s |
0 s |
机制详解
设置强制切换到下一个 WAL 文件前的最长等待时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
在间隔内没有自然换段时，PostgreSQL 强制切换 WAL 段以便归档当前部分。它不会让 WAL 更早持久化；过小会产生大量未写满但仍占完整段空间的归档文件。
应把 archive_timeout 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 把 archive_timeout 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。 |
| OLAP | 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。 |
| 小规格 | 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 300 |
不同于 boot 值 | 300 |
| OLAP | 300 |
不同于 boot 值 | 300 |
| CRIT | 300 |
不同于 boot 值 | 300 |
| TINY | 300 |
不同于 boot 值 | 300 |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 300 (dcs)；OLAP: PG9.0–19 Beta 3 = 300 (dcs)；CRIT: PG9.0–19 Beta 3 = 300 (dcs)；TINY: PG9.0–19 Beta 3 = 300 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在限制低流量主库最新 WAL 尚未进入归档的最长时间；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 把它误当成提交持久化超时。
- 间隔过小，制造大量几乎为空却占完整段空间的归档文件。
- 误以为强制换段能解决归档进程缓慢或失败。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
archive_mode · archive_command · archive_library · archive_cleanup_command · restore_command · recovery_end_command
参考资料
6 - checkpoint_completion_target
Fact — 官方简述译文：设置在检查点间隔中用于刷新脏缓冲区的目标时间比例。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 0.9
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–13 | 0.5 |
— | 0.5 |
| PG14–19 Beta 3 | 0.9 |
— | 0.9 |
机制详解
PostgreSQL 会节流检查点写入，使其预计在可用间隔的这一比例处完成。可用间隔可能在下一次定时检查点结束，也可能因 WAL 容量更早触发，因此它是节奏目标，不是固定时长。
较大比例通常能把检查点 I/O 更均匀地摊开。较小比例会更快完成写入，形成更高的阶段性 I/O，随后出现空档；官方文档因此不建议降低该值。
过于接近 1 会给最终同步和其他检查点工作留下很少余量。PG14 将历史默认值从 0.5 改为 0.9，因此跨大版本比较配置时必须考虑这一变化。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 从对应版本的 0.9 默认值开始，只在延迟与 pg_stat_checkpointer 证据支持时调整。0.95 可能进一步平滑写入，但要验证检查点能稳定赶在下一触发条件之前完成。 |
| OLAP | 突发批处理往往由 WAL 容量提前触发检查点，因此通常先调大 max_wal_size。目标值应足够高以平滑 I/O，又不能让最终同步工作集中在末尾。 |
| 小规格 | 除非测量显示明确收益，否则使用 0.9。小型或慢速存储在目标值余量不足时，尤其容易受到检查点末尾同步尖峰影响。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 0.95 |
不同于 boot 值 | 0.95 |
| OLAP | 0.95 |
不同于 boot 值 | 0.95 |
| CRIT | 0.95 |
不同于 boot 值 | 0.95 |
| TINY | 0.95 |
不同于 boot 值 | 0.95 |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 0.95 (dcs)；OLAP: PG9.0–19 Beta 3 = 0.95 (dcs)；CRIT: PG9.0–19 Beta 3 = 0.95 (dcs)；TINY: PG9.0–19 Beta 3 = 0.95 (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。
常见坑
- 把该值误解成秒数而不是比例。
- 认为调低会减少总 I/O，实际只是把写入集中起来。
- 设为 1.0，未给检查点收尾工作保留余量。
- 忽略 max_wal_size 导致的提前检查点。
- 跨版本比较时漏掉 PG14 的默认值变化。
关联参数
checkpoint_timeout · max_wal_size · checkpoint_flush_after · checkpoint_warning · shared_buffers
参考资料
7 - checkpoint_flush_after
Fact — 官方简述译文：设置检查点每写入多少页后刷出先前写入的数据。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 256 KiB (32 × 8kB)
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.6 |
| 在档版本 | PG9.6–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 428b1d6b29ca — Allow to trigger kernel writeback after a configurable number of writes. |
| 提交日期 | 2016-02-19 |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.6–19 Beta 3 | 32 |
8kB |
256 KiB (32 × 8kB) |
机制详解
设置检查点每写入多少页后刷出先前写入的数据。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 checkpoint_flush_after 与 checkpoint_warning、checkpoint_timeout、checkpoint_completion_target 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 checkpoint_flush_after；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 未修改；OLAP: PG9.6–19 Beta 3 未修改；CRIT: PG9.6–19 Beta 3 未修改；TINY: PG9.6–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把原始值当作字节；未带单位的值按数据库块计量。
- 设置过小，增加 writeback 调用与 I/O 碎片。
- 设置过大，失去检查点最终同步前平滑写回的作用。
- 把 writeback 提示误当持久化保证；真正的持久性仍由 fsync 与 wal_sync_method 决定。
- 未测量检查点延迟与脏页行为就跨操作系统或文件系统照搬数值。
关联参数
checkpoint_warning · checkpoint_timeout · checkpoint_completion_target · max_wal_size · min_wal_size · archive_cleanup_command
参考资料
8 - checkpoint_segments
Fact — 官方简述译文：设置两次自动 WAL 检查点之间允许的最大日志段距离。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 3
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–9.4 |
| 移除版本 | PG9.5 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–9.4 | 3 |
— | 3 |
机制详解
checkpoint_segments：设置两次自动 WAL 检查点之间允许的最大日志段距离。重新加载配置即可让服务器采用新值，无需完整重启。 本站在 PG9.0–9.4 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。
这是 PostgreSQL 9.5 之前的检查点容量控制：累计 WAL 接近指定段数时请求自动检查点。PG9.5 以 max_wal_size 取代它；新参数使用软性的字节容量预算，并与 checkpoint_timeout、checkpoint_completion_target 协同，而不是直接暴露 WAL 段数。
应与 max_wal_size、checkpoint_timeout、checkpoint_completion_target、wal_segment_size 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 不要把这个已退出的名称加入现代 OLTP 配置。应把原意迁移到文档给出的后继参数，在连接与写并发下验证，并清理仍会输出旧名称的自动化。 |
| OLAP | 升级分析型环境前应盘点所有生成配置，把旧控制映射到后继项，并比较执行计划、吞吐、WAL 或日志行为；不能假设旧数值可直接搬用。 |
| 小规格 | 记录旧覆盖存在的原因后将其删除。小节点应先采用后继参数默认值，实测后再调整；未知的启动参数可能直接阻止服务器启动。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG9.4 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–9.4 未修改；OLAP: PG9.0–9.4 未修改；CRIT: PG9.0–9.4 未修改；TINY: PG9.0–9.4 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把 checkpoint_segments 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
- 忽略 pg_settings 报告的 sighup context，误以为修改会立即生效。
- 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
- 把已移除名称复制到现代 postgresql.conf，而没有迁移到文档给出的后继参数。
关联参数
max_wal_size · checkpoint_timeout · checkpoint_completion_target · wal_segment_size · min_wal_size
参考资料
9 - checkpoint_timeout
Fact — 官方简述译文：设置两次自动 WAL 检查点之间的最长时间。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 5 min
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | 300 |
s |
5 min |
机制详解
达到 checkpoint_timeout 后系统会考虑执行自动检查点，但 max_wal_size 可以更早触发。如果上次检查点后没有写入 WAL，PostgreSQL 可以跳过这次定时检查点，因此它是最长调度间隔，而不是固定周期工作的承诺。
较长间隔通常会减少检查点次数和全页写放大，但崩溃恢复时可能需要重放更多 WAL。较短间隔能收紧重放区间，却会增加脏页写回以及每次检查点后的全页镜像。
主库检查点记录也限制备库可执行重启点的位置。不要用本参数定义 WAL 归档的 RPO；低 WAL 负载下强制切换段应使用 archive_timeout。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 与 max_wal_size 联合调优，并通过 checkpoint_completion_target 平摊检查点 I/O。只有在量化恢复要求、请求型与定时型检查点比例、写延迟和 WAL 量之后才延长间隔。 |
| OLAP | 批处理期间通常是 max_wal_size 先触发。如果容量型检查点占主导，应先增加 WAL 空间，同时保留能满足重启与恢复目标的超时值。 |
| 小规格 | 在恢复时间重要且存储有限的环境里，上游 5 分钟是合理起点。延长间隔必须有明确的磁盘余量和经过测试的崩溃恢复预算。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 15min |
不同于 boot 值 | 15min |
| OLAP | 15min |
不同于 boot 值 | 15min |
| CRIT | 15min |
不同于 boot 值 | 15min |
| TINY | 15min |
不同于 boot 值 | 15min |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 15min (dcs)；OLAP: PG9.0–19 Beta 3 = 15min (dcs)；CRIT: PG9.0–19 Beta 3 = 15min (dcs)；TINY: PG9.0–19 Beta 3 = 15min (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。
常见坑
- 认为空闲系统也必然严格按该间隔执行检查点。
- 忘记 max_wal_size 可能更早触发检查点。
- 用 checkpoint_timeout 代替 archive_timeout 限制归档延迟。
- 增大后没有计入更长的崩溃恢复重放区间。
- 设置过小导致全页写和检查点 I/O 占主导。
关联参数
max_wal_size · checkpoint_completion_target · checkpoint_warning · archive_timeout · full_page_writes · checkpoint_flush_after
参考资料
10 - checkpoint_warning
Fact — 官方简述译文：设置 WAL 容量触发的检查点过于频繁时发出警告的时间阈值。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 30 s
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | 30 |
s |
30 s |
机制详解
设置 WAL 容量触发的检查点过于频繁时发出警告的时间阈值。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
该参数只在 WAL 容量触发的检查点间隔短于阈值时写日志，并不会推迟检查点。频繁告警通常意味着 max_wal_size 相对 WAL 生成速率过小。
应把 checkpoint_warning 与 checkpoint_flush_after、checkpoint_timeout、checkpoint_completion_target 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 checkpoint_warning；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把告警阈值误当成会推迟或节流检查点的控制项。
- 设为零，掩盖 WAL 容量触发检查点过于频繁的证据。
- 只提高阈值，而不调查 WAL 速率、max_wal_size 与 requested checkpoint 频率。
- 把 checkpoint_warning 设得高于 checkpoint_timeout，却期待时间触发检查点产生该告警。
关联参数
checkpoint_flush_after · checkpoint_timeout · checkpoint_completion_target · max_wal_size · min_wal_size · archive_cleanup_command
参考资料
11 - commit_delay
Fact — 官方简述译文：设置事务提交与将 WAL 刷入磁盘之间的延迟（微秒）。
身份
类型,- 上游 pg_settings 类型
Context,- 超级用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 0
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | 0 |
— | 0 |
机制详解
设置事务提交与将 WAL 刷入磁盘之间的延迟（微秒）。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。
后端准备刷提交 WAL 时可等待这些微秒，让并发提交共用一次持久化刷写；只有至少存在 commit_siblings 个其他活动事务时才考虑等待。这是在单次提交延迟与 group commit 效率之间取舍。
应把 commit_delay 与 commit_siblings、synchronous_commit、wal_writer_delay 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 只在高并发、WALSync 明显且 p95/p99 提交延迟可接受时基准测试 commit_delay；同时成对调整 commit_delay 与 commit_siblings，并保留关闭基线。 |
| OLAP | 批量事务通常应通过合理批次大小减少提交频率；不要用 group-commit 延迟弥补每行提交的 ETL 设计。 |
| 小规格 | 并发不足时几乎没有收益，保持 commit_delay=0 最简单；微秒级设置也要从端到端延迟测量证明。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 20 |
不同于 boot 值 | 20 |
| OLAP | 20 |
不同于 boot 值 | 20 |
| CRIT | 20 |
不同于 boot 值 | 20 |
| TINY | 20 |
不同于 boot 值 | 20 |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 20 (dcs)；OLAP: PG9.0–19 Beta 3 = 20 (dcs)；CRIT: PG9.0–19 Beta 3 = 20 (dcs)；TINY: PG9.0–19 Beta 3 = 20 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在并发提交负载下促成极短的 group commit 批处理；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 设置了延迟，但真实并发从未达到 commit_siblings 门槛。
- 把数值误读成毫秒；该参数单位是微秒。
- 平均 group commit 吞吐提高，却违反 p95/p99 提交延迟目标。
- 在提交路径无需刷 WAL 时仍期待该延迟生效。
- 没有与 commit_siblings、WALSync 等待一起测量就修改 commit_delay。
关联参数
commit_siblings · synchronous_commit · wal_writer_delay · wal_sync_method · fsync · full_page_writes
参考资料
12 - commit_siblings
Fact — 官方简述译文：设置启用 commit_delay 前所需的并发活动事务最低数量。
身份
类型,- 上游 pg_settings 类型
Context,- 普通用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 5
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | 5 |
— | 5 |
机制详解
设置启用 commit_delay 前所需的并发活动事务最低数量。它可在会话级修改，因此不同会话可能采用不同的行为。
这是 commit_delay 的并发门槛，在需要提交刷写时按其他活动事务计数，而不是已经排队的 commit 数量。commit_delay 为零时它没有实际作用。
应把 commit_siblings 与 commit_delay、synchronous_commit、wal_writer_delay 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 只在高并发、WALSync 明显且 p95/p99 提交延迟可接受时基准测试 commit_siblings；同时成对调整 commit_delay 与 commit_siblings，并保留关闭基线。 |
| OLAP | 批量事务通常应通过合理批次大小减少提交频率；不要用 group-commit 延迟弥补每行提交的 ETL 设计。 |
| 小规格 | 并发不足时几乎没有收益，保持 commit_delay=0 最简单；微秒级设置也要从端到端延迟测量证明。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 10 |
不同于 boot 值 | 10 |
| OLAP | 10 |
不同于 boot 值 | 10 |
| CRIT | 10 |
不同于 boot 值 | 10 |
| TINY | 10 |
不同于 boot 值 | 10 |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 10 (dcs)；OLAP: PG9.0–19 Beta 3 = 10 (dcs)；CRIT: PG9.0–19 Beta 3 = 10 (dcs)；TINY: PG9.0–19 Beta 3 = 10 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在只在事务并发已经较高时才应用 commit_delay；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- commit_delay 为零时仍调该参数；此时门槛没有作用。
- 把它当作已等待 commit 的数量，而不是其他活动事务数量。
- 门槛过低，在普通中等并发下也增加提交延迟。
- 把会话级试验直接全局发布，却没有比较提交延迟与 WALSync 行为。
关联参数
commit_delay · synchronous_commit · wal_writer_delay · wal_sync_method · fsync · full_page_writes
参考资料
13 - fsync
Fact — 官方简述译文：强制将更新同步到磁盘。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- on
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | on |
— | on |
机制详解
强制将更新同步到磁盘。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
开启时，PostgreSQL 发出持久化屏障，保证 WAL 与数据写入顺序能承受操作系统或掉电故障。关闭可能改善写入跑分，但崩溃后会留下 crash recovery 无法修复的损坏；重新开启也不能追溯同步此前的不安全写入。
应把 fsync 与 data_sync_retry、restart_after_crash、recovery_init_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 持久生产数据保持 fsync=on。性能问题应从存储延迟、检查点、WAL 压缩和批处理着手，不要用关闭崩溃安全换吞吐。 |
| OLAP | 批量装载同样需要可恢复性；用 UNLOGGED/临时数据结构或可重建 staging 明确缩小耐久范围，而不是全局关闭保护。 |
| 小规格 | 持久小实例也保持开启。只有数据可随时重建且与生产明确隔离的临时集群，才可在书面接受风险后例外。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 在持久数据上关闭，并误以为 UPS 或 RAID cache 单独就足够。
- 重新开启后误以为此前不安全写入已自动持久化。
- 只测试干净关机，不测试掉电恢复。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
data_sync_retry · restart_after_crash · recovery_init_sync_method · full_page_writes · wal_sync_method · synchronous_commit
参考资料
14 - full_page_writes
Fact — 官方简述译文：检查点后页面首次修改时将完整页面写入 WAL。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- on
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | on |
— | on |
机制详解
检查点后页面首次修改时将完整页面写入 WAL。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
每次检查点后，数据页第一次修改会把完整页映像写入 WAL，避免撕裂页恢复时拼接新旧扇区。额外 WAL 集中在检查点后并受 wal_compression 影响；除非存储栈提供等价的原子页保证，否则不应关闭。
应把 full_page_writes 与 data_sync_retry、restart_after_crash、recovery_init_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 持久生产数据保持 full_page_writes=on。性能问题应从存储延迟、检查点、WAL 压缩和批处理着手，不要用关闭崩溃安全换吞吐。 |
| OLAP | 批量装载同样需要可恢复性；用 UNLOGGED/临时数据结构或可重建 staging 明确缩小耐久范围，而不是全局关闭保护。 |
| 小规格 | 持久小实例也保持开启。只有数据可随时重建且与生产明确隔离的临时集群，才可在书面接受风险后例外。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 没有端到端原子页写保证就关闭该参数。
- 把它增加的 WAL 量误解成每次修改都会记录整页。
- 忽略检查点之后全页镜像集中出现的 WAL 突发。
- 误以为 reload 后会追溯保护在 full_page_writes=off 期间已经生成的 WAL。
- 关闭参数做基准，却没有端到端崩溃、恢复与 torn-page 测试。
关联参数
data_sync_retry · restart_after_crash · recovery_init_sync_method · fsync · wal_sync_method · synchronous_commit
参考资料
15 - max_wal_size
Fact — 官方简述译文：设置触发自动检查点的 WAL 大小。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 1 GiB
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.5 |
| 在档版本 | PG9.5–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 88e982302684 — Replace checkpoint_segments with min_wal_size and max_wal_size. |
| 提交日期 | 2015-02-23 |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.5–9.6 | 64 |
16MB |
1 GiB (64 × 16MB) |
| PG10–19 Beta 3 | 1024 |
MB |
1 GiB |
机制详解
检查点进程会在 checkpoint_timeout 到期或 WAL 即将超过 max_wal_size 时启动自动检查点，二者谁先发生就由谁触发。检查点越频繁，脏页被写回得越频繁，并且每次检查点之后产生的全页镜像也会更多。
max_wal_size 不是磁盘配额。高写入负载、恢复过程、归档变慢或失败、wal_keep_size 保留文件，以及复制槽仍需要旧 WAL 时，实际 pg_wal 都可能超过该值。
增大它通常能减少请求型检查点和检查点写入抖动，但会扩大崩溃后需要重放的 WAL 区间，也要求更多 pg_wal 余量。min_wal_size 只控制 WAL 文件回收的下限，并不会把 max_wal_size 变成硬上限。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 根据实测峰值 WAL 产生速率和可接受的检查点频率定值。持续观察 pg_stat_checkpointer、checkpoint_warning、写延迟、归档延迟与剩余空间；只有请求型检查点长期占主导时才有依据上调。 |
| OLAP | 批量导入和大型维护任务会突发产生 WAL，较大值可减少检查点风暴。必须同时确认 pg_wal 容量、归档吞吐以及更长的崩溃恢复窗口都可接受。 |
| 小规格 | 小磁盘应使用保守且有明确上限的值。复制槽保留量和归档积压要另算，并预留应急空间，不要把卷的大部分空间都分配给名义上的检查点阈值。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 20GB |
不同于 boot 值 | {{ ([pg_size_twentieth * 4, 2000])|min }}GB |
| OLAP | 20GB |
不同于 boot 值 | {{ ([pg_size_twentieth * 4, 2000])|min }}GB |
| CRIT | 20GB |
不同于 boot 值 | {{ ([pg_size_twentieth * 4, 2000])|min }}GB |
| TINY | 20GB |
不同于 boot 值 | {{ ([pg_size_twentieth * 4, 2000])|min }}GB |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 = 20GB (dcs)；OLAP: PG9.5–19 Beta 3 = 20GB (dcs)；CRIT: PG9.5–19 Beta 3 = 20GB (dcs)；TINY: PG9.5–19 Beta 3 = 20GB (dcs)。 建议（待人工复核）——发布前应结合当前 Pigsty 模板及其实际支持的 PostgreSQL 版本确认运维意图。
常见坑
- 误以为 max_wal_size 是 pg_wal 的硬上限。
- 通过增大该值掩盖归档失败或废弃复制槽。
- 下调前没有评估全页镜像量和检查点延迟。
- 忽略无单位数字按 MB 解释。
- 脱离 checkpoint_timeout 与 checkpoint_completion_target 单独调参。
关联参数
min_wal_size · checkpoint_timeout · checkpoint_completion_target · checkpoint_warning · wal_keep_size · max_slot_wal_keep_size
参考资料
16 - min_wal_size
Fact — 官方简述译文：设置 WAL 可收缩到的最小规模。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 80 MiB
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.5 |
| 在档版本 | PG9.5–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 88e982302684 — Replace checkpoint_segments with min_wal_size and max_wal_size. |
| 提交日期 | 2015-02-23 |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.5–9.6 | 5 |
16MB |
80 MiB (5 × 16MB) |
| PG10–19 Beta 3 | 80 |
MB |
80 MiB |
机制详解
设置 WAL 可收缩到的最小规模。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
低于该下限时，检查点会保留旧 WAL 段供复用而不是删除。它是保留/回收空间的下限，不是上限；归档失败、复制槽、wal_keep_size 与 max_wal_size 都可能让 pg_wal 远大于它。
应把 min_wal_size 与 max_wal_size、wal_keep_size、wal_segment_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 按检查点之间的常态 WAL 生成量与文件创建成本设置回收池下限；它应明显低于可用 pg_wal 空间，并与 max_wal_size 一起测量。 |
| OLAP | 大批装载可受益于更大的预留回收池，但应依据可重复批次峰值，而不是照搬任意 GB 数；归档与复制槽空间另算。 |
| 小规格 | 先核对 Pigsty 的 5GB 矩阵值是否适合实际磁盘；对小盘这不是免费的默认值，调低时要接受更多段创建/删除抖动。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 5GB |
不同于 boot 值 | {{ ([pg_size_twentieth, 200])|min }}GB |
| OLAP | 5GB |
不同于 boot 值 | {{ ([pg_size_twentieth, 200])|min }}GB |
| CRIT | 5GB |
不同于 boot 值 | {{ ([pg_size_twentieth, 200])|min }}GB |
| TINY | 5GB |
不同于 boot 值 | {{ ([pg_size_twentieth, 200])|min }}GB |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 = 5GB (dcs)；OLAP: PG9.5–19 Beta 3 = 5GB (dcs)；CRIT: PG9.5–19 Beta 3 = 5GB (dcs)；TINY: PG9.5–19 Beta 3 = 5GB (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在保留足以吸收常规突发、避免文件抖动的可复用 WAL 池；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 把它理解成 pg_wal 上限。
- 不考虑 wal_segment_size 取整和突发速率。
- 忽略归档/复制槽保留可同时越过 min_wal_size 与 max_wal_size。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
max_wal_size · wal_keep_size · wal_segment_size · checkpoint_timeout · checkpoint_completion_target · checkpoint_flush_after
参考资料
17 - recovery_end_command
Fact — 官方简述译文：设置恢复结束时执行一次的 shell 命令。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置恢复结束时执行一次的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 recovery_end_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 把 recovery_end_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。 |
| OLAP | 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。 |
| 小规格 | 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把 shell 命令当作事务性的提升钩子，并误以为失败会回滚恢复。
- 误读 %r，删除其他恢复消费者仍需要的 WAL。
- 没有考虑提升或恢复重试，就执行非幂等的外部副作用。
- 误以为 reload 会执行命令；它只在归档恢复结束时运行一次。
- 在 postgres 服务账号执行的命令中嵌入凭据或不安全的 shell 展开。
关联参数
archive_mode · archive_command · archive_library · archive_timeout · archive_cleanup_command · restore_command
参考资料
18 - recovery_prefetch
Fact — 官方简述译文：在恢复期间预取 WAL 引用的数据块。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- try
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG15 |
| 在档版本 | PG15–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 1d257577e08d — Optionally prefetch referenced data in recovery. |
| 提交日期 | 2021-04-08 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG15–19 Beta 3 | try |
— | try |
机制详解
在恢复期间预取 WAL 引用的数据块。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 recovery_prefetch 与 wal_decode_buffer_size、maintenance_io_concurrency、effective_io_concurrency 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 在与生产相同的存储上用恢复/备库追赶基准调 recovery_prefetch，同时观察 replay I/O wait、缓存命中与 maintenance_io_concurrency；没有测量收益就保留默认。 |
| OLAP | 大型数据集且随机读取较慢时可能收益更大，但过度预取会挤占查询 I/O 与缓存；在故障恢复与读备库两种场景分别测试。 |
| 小规格 | 默认通常足够。内存与 I/O 队列有限时，不要为扩大超前窗口占用资源，除非恢复时间目标有明确缺口。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 误以为 try 在操作系统不支持所需 read-ahead advice 时也一定启用预取。
- 扩大超前读取，却不考虑 wal_decode_buffer_size 与 maintenance_io_concurrency。
- 让恢复预取与 hot standby 查询争夺缓存和 I/O 队列深度。
- 只测试顺序恢复场景，而该场景的块预取收益可能很小。
关联参数
wal_decode_buffer_size · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command
参考资料
19 - recovery_target
Fact — 官方简述译文：设为 immediate，使恢复在首次达到一致状态时结束。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设为 immediate，使恢复在首次达到一致状态时结束。该值在服务器启动时固定，修改后必须重启。
唯一允许的值是 immediate，使目标恢复停在首个一致点，通常即在线基础备份结束位置。它与 LSN、名称、时间和 XID 目标选择器互斥。
recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把 immediate 与 LSN、名称、时间或 XID 选择器同时设置。
- 把在线备份后的首个一致点误当成业务所需恢复点。
- 在普通备库配置中残留 immediate，意外结束恢复。
- 未创建 recovery.signal 就期待该目标控制崩溃恢复。
- 所需 WAL 链未达到一致点却误判恢复成功。
关联参数
recovery_target_time · recovery_target_xid · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action
参考资料
20 - recovery_target_action
Fact — 官方简述译文：设置到达恢复目标后执行的动作。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- pause
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | pause |
— | pause |
机制详解
选择 PostgreSQL 到达已配置恢复目标后的动作。恢复启动时读取该值。
pause 暂停恢复供检查，promote 结束恢复并进入正常服务，shutdown 在目标处停止服务器；使用 pause 查询检查需要启用 hot_standby。
没有停止目标时该设置无效。使用 shutdown 时 recovery.signal 不会删除，配置不变的再次启动会到达目标后再次停机；验证后必须有意清理或修改恢复配置。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_action，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 未配置停止目标却期待动作生效。
- hot_standby 关闭时使用 pause，却期待用查询检查数据库。
- 尚未验证恢复状态就使用 promote。
- 使用 shutdown 后保留 recovery.signal 与相同目标直接重启。
- 把 shutdown 当作永久删除目标后的 WAL；下次启动仍会从最后检查点重放到目标。
关联参数
recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_inclusive · recovery_target_timeline · hot_standby
参考资料
21 - recovery_target_inclusive
Fact — 官方简述译文：设置是否包含恢复目标所对应的事务。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- on
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | on |
— | on |
机制详解
选择精确恢复边界的哪一侧被保留。它是 postmaster 参数，在目标恢复启动时读取。
on 在目标之后停止并包含目标 LSN、提交时间或 XID；off 在目标之前停止并排除它。该设置只适用于 recovery_target_lsn、recovery_target_time 与 recovery_target_xid。
它对 immediate 或命名还原点目标无效。应依据已识别的 WAL/业务证据选择边界，并验证恢复后的行与事务，而不只查看显示的时间戳或 LSN。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_inclusive，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 期待它影响 immediate 或命名还原点目标。
- 未识别准确边界事务或 WAL 记录就选择 on/off。
- 误以为相同时间戳对应唯一确定的提交边界。
- 只验证报告的重放位置，而不验证恢复后的应用数据。
- 把该值留在复用恢复模板中，却未记录预期边界侧。
关联参数
recovery_target_lsn · recovery_target_time · recovery_target_xid · recovery_target_action · recovery_target_timeline · restore_command
参考资料
22 - recovery_target_lsn
Fact — 官方简述译文：设置恢复所推进到的 WAL LSN。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置恢复所推进到的 WAL LSN。该值在服务器启动时固定，修改后必须重启。
恢复推进到一个 pg_lsn 位置，并由 recovery_target_inclusive 选择边界哪一侧。该 LSN 必须位于所选恢复时间线上，且基础备份之后的 WAL 链能够到达。
recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_lsn，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 使用另一集群的 LSN，或使用不源自基础备份的时间线 LSN。
- 同时设置另一个恢复目标选择器。
- 未识别必须包含的 WAL 记录就选择 inclusive。
- 请求超过归档/流式 WAL 可用范围的 LSN，形成不可达目标。
- 把 LSN 当普通十进制数比较，而不是 pg_lsn 值。
关联参数
recovery_target · recovery_target_time · recovery_target_xid · recovery_target_name · recovery_target_inclusive · recovery_target_action
参考资料
23 - recovery_target_name
Fact — 官方简述译文：设置恢复所推进到的命名还原点。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置恢复所推进到的命名还原点。该值在服务器启动时固定，修改后必须重启。
恢复停在此前由 pg_create_restore_point() 写入的命名还原点。只有所选时间线的 WAL 中确实存在对应记录，名称才有意义。
recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_name，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 指定的还原点 WAL 记录不在所选时间线中。
- 误以为 recovery_target_inclusive 会改变命名还原点边界。
- 同时设置另一个恢复目标选择器。
- 拼错区分大小写的还原点名称，使目标不可达。
- 只记录业务标签，却未记录集群、时间线与基础备份关系。
关联参数
recovery_target · recovery_target_time · recovery_target_xid · recovery_target_lsn · recovery_target_inclusive · recovery_target_action
参考资料
24 - recovery_target_time
Fact — 官方简述译文：设置恢复所推进到的时间戳。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置恢复所推进到的时间戳。该值在服务器启动时固定，修改后必须重启。
恢复用事务提交记录与该时间戳比较；数值 UTC 偏移或完整时区名可避免缩写歧义。recovery_target_inclusive 决定是否重放恰好位于边界的提交。
recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_time，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 使用有歧义的时区缩写，而不是数值偏移或完整时区名。
- 误以为一个墙钟时间戳能唯一标识业务事务。
- 同时设置另一个恢复目标选择器。
- 未识别准确边界提交就选择 inclusive on/off。
- 请求的时间不在可达 WAL 范围内或位于错误时间线。
关联参数
recovery_target · recovery_target_xid · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action
参考资料
25 - recovery_target_timeline
Fact — 官方简述译文：指定要恢复到的时间线。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- latest
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | latest |
— | latest |
机制详解
指定恢复要沿用的时间线历史。它是 postmaster 参数，只在本次恢复启动时读取。
latest 跟随归档中最新时间线，current 留在基础备份当时的时间线；显式十进制或带 0x 前缀的十六进制 ID 选择特定分支。时间线既可单独选择，也可与更早的停止目标组合。
所选时间线必须源自该基础备份，并且对应 history/WAL 文件可用。该参数只选择分支，不会自行选择事务边界或提升服务器。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_timeline，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 需要沿旧分支重新恢复时仍使用 latest。
- 所需 WAL 只在后代时间线时仍使用 current。
- 选择不源自基础备份的时间线。
- 未保留时间线 history 文件与对应 WAL。
- 把时间线选择误当成停止目标或提升命令。
关联参数
recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_action · restore_command · primary_conninfo
参考资料
26 - recovery_target_xid
Fact — 官方简述译文：设置恢复所推进到的事务 ID。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置恢复所推进到的事务 ID。该值在服务器启动时固定，修改后必须重启。
目标是指定事务 ID 的提交记录，而不是所有事务的简单数值顺序：XID 在事务开始时分配，提交顺序可能不同。recovery_target_inclusive 决定是否包含目标事务。
recovery_target、recovery_target_lsn、recovery_target_name、recovery_target_time 与 recovery_target_xid 最多只能设置一个；timeline、inclusive 与 action 是修饰项。必须从同一基础备份沿完整 WAL 链演练，目标不可达会使目标恢复失败。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 这不是常态性能参数。只在隔离的恢复实例中设置 recovery_target_xid，先记录目标证据、基础备份、时间线和预期边界，再演练并由第二人复核。 |
| OLAP | 大型恢复应先估算 WAL 重放时间与检查窗口；目标命中后用只读校验确认事实，不能用大查询拖住或污染恢复决策。 |
| 小规格 | 优先用备份工具生成受控恢复配置；不要在日常主库/备库模板中永久保留目标参数，恢复后清理 signal 文件与目标设置。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 误以为 XID 数值顺序等于提交顺序；XID 在事务开始时分配。
- 使用来自另一集群或无关时间线的 XID。
- 同时设置另一个恢复目标选择器。
- 未决定是否需要目标事务本身就选择 inclusive。
- 把 XID 当作跨回卷与跨集群全局唯一的业务标识。
关联参数
recovery_target · recovery_target_time · recovery_target_lsn · recovery_target_name · recovery_target_inclusive · recovery_target_action
参考资料
27 - restore_command
Fact — 官方简述译文：设置取回归档 WAL 文件时调用的 shell 命令。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- empty string
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 2dedf4d9a899 — Integrate recovery.conf into postgresql.conf |
| 提交日期 | 2018-11-25 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | "" |
— | empty string |
机制详解
设置取回归档 WAL 文件时调用的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
归档恢复时 PostgreSQL 把 %f 展开为请求文件、%p 展开为目标路径。成功必须表示准确文件已可靠复制；正常的未找到应返回非零，以便继续尝试流复制或 pg_wal，同时 shell 引用必须安全。
应把 restore_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 把 restore_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。 |
| OLAP | 按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。 |
| 小规格 | 有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 缺失或错误 WAL 文件也返回零。
- 没有安全引用 %f 与 %p。
- 归档可能返回另一时间线或集群的同名段。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
archive_mode · archive_command · archive_library · archive_timeout · archive_cleanup_command · recovery_end_command
参考资料
28 - summarize_wal
Fact — 官方简述译文：启动 WAL summarizer 进程以支持增量备份。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- off
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG17 |
| 在档版本 | PG17–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 174c480508ac — Add a new WAL summarizer process. |
| 提交日期 | 2023-12-20 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG17–19 Beta 3 | off |
— | off |
机制详解
启动 WAL summarizer 进程以支持增量备份。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
WAL summarizer 记录各 WAL 范围修改过的块，让 pg_basebackup 能构造增量备份。它可在主库或备库运行，但无法汇总以 wal_level=minimal 生成的 WAL。
应把 summarize_wal 与 wal_summary_keep_time、wal_level、archive_mode 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 只有采用 PostgreSQL 增量备份时才启用/调整 summarize_wal；监控 summarizer 进度，并让摘要覆盖任何相邻基础/增量备份之间的完整 WAL 范围。 |
| OLAP | 批量写入会增加摘要工作；把备份间隔、WAL 峰值和备份窗口一起做容量测试，摘要缺口会使增量备份失败。 |
| 小规格 | 不做增量备份就保持 summarize_wal 关闭；若启用，保留期要由实际备份链决定，并给摘要目录设置容量告警。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 在 wal_level=minimal 下启用，却期待生成可用摘要。
- 把 WAL 摘要本身当作 WAL 归档或备份。
- 关闭 summarizer 后仍期待 wal_summary_keep_time 继续清理。
- 未检查 summarizer 进度与摘要覆盖范围就执行增量备份。
关联参数
wal_summary_keep_time · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command
参考资料
29 - synchronous_commit
Fact — 官方简述译文：设置当前事务提交时使用的同步级别。
身份
类型,- 上游 pg_settings 类型
Context,- 普通用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- on
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | on |
— | on |
机制详解
除 off 外的所有模式都会等待本地 WAL 刷入持久存储。off 可以在本地持久化之前返回成功；崩溃可能丢失最近已确认的事务，但恢复后的数据库仍保持事务一致性，不会产生 fsync = off 那类结构损坏风险。
当 synchronous_standby_names 选定同步备库时，remote_write 等待备库接收并写入操作系统，on 等待备库持久化刷新，remote_apply 还要等待重放并对查询可见；local 只等待本地持久化。如果没有选中同步备库，这些远程模式不会增加远程保证。
事务采用提交开始时生效的值。应用可以对单个事务使用 SET LOCAL，使关键事务和可重建事务在同一服务器上采用不同持久性策略。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 全局默认保持 on。仅对明确可重建的事务使用 off；只有提交后必须立即在同步备库读到结果时才使用 remote_apply，并把网络往返和备库健康纳入延迟预算。 |
| OLAP | 可重复执行的批量导入可在事务内使用 off，前提是能够接受最后一小段未刷盘数据丢失并可重跑。目录变更、交接标记和对外宣布完成的记录仍应同步提交。 |
| 小规格 | 保持 on。小型系统通常得不到足以抵消语义风险的全局降级收益，应只优化个别非关键任务。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把 synchronous_commit = off 与 fsync = off 混为一谈；前者风险是近期数据丢失，不是结构损坏。
- 没有选定同步备库时仍期待 remote_write、on 或 remote_apply 提供远程等待。
- 使用 remote_write 却假设备库能抵御操作系统崩溃。
- 同步备库不可用时没有 HA 处置方案，导致提交无限等待。
- 连接池中使用会话级 SET 而未使用 SET LOCAL 或重置纪律，造成设置泄漏。
关联参数
synchronous_standby_names · fsync · wal_writer_delay · wal_sync_method · commit_delay · wal_level
参考资料
30 - wal_buffers
Fact — 官方简述译文：设置共享内存中用于 WAL 的磁盘页缓冲区数量。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- -1 8kB
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0 | 8 |
8kB |
64 KiB (8 × 8kB) |
| PG9.1–19 Beta 3 | -1 |
8kB |
-1 8kB |
机制详解
设置共享内存中用于 WAL 的磁盘页缓冲区数量。该值在服务器启动时固定，修改后必须重启。
自动值 -1 选择约 shared_buffers 的 1/32，并受最低值与一个 WAL 段上限约束。缓冲区吸收写出前的 WAL；过小会在突发中增加 WALWrite 压力，过大则占启动共享内存且不能替代持久化刷写。
应把 wal_buffers 与 fsync、full_page_writes、wal_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_buffers；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 16MB |
不同于 boot 值 | 16MB |
| OLAP | 16MB |
不同于 boot 值 | 16MB |
| CRIT | 16MB |
不同于 boot 值 | 16MB |
| TINY | 16MB |
不同于 boot 值 | 16MB |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 16MB (dcs)；OLAP: PG9.0–19 Beta 3 = 16MB (dcs)；CRIT: PG9.0–19 Beta 3 = 16MB (dcs)；TINY: PG9.0–19 Beta 3 = 16MB (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在显式使用通常为一个 WAL 段的上限来吸收突发；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 把 -1 读成负分配，而不是自动尺寸。
- 忘记自动值依据 shared_buffers 计算，并以一个 WAL 段为上限。
- 把未带单位的正值读成字节，而不是 WAL 块；过小正值会提升到最低值。
- 没有 WALInsert/WALWrite 压力证据就手工分配很大缓冲。
- 误以为更多 WAL buffer 能替代持久刷盘或改善受存储限制的 WALSync。
关联参数
fsync · full_page_writes · wal_sync_method · synchronous_commit · wal_writer_delay · wal_writer_flush_after
参考资料
31 - wal_compression
Fact — 官方简述译文：使用指定方法压缩写入 WAL 的整页映像。
身份
类型,- 上游 pg_settings 类型
Context,- 超级用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- off
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.5 |
| 在档版本 | PG9.5–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 57aa5b2bb11a — Add GUC to enable compression of full page images stored in WAL. |
| 提交日期 | 2015-03-11 |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.5–19 Beta 3 | off |
— | off |
机制详解
使用指定方法压缩写入 WAL 的整页映像。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。
压缩对象是 full_page_writes、备份或 hint logging 产生的整页映像，而非每条 WAL 记录。pglz 内置，lz4/zstd 取决于构建；它用主库压缩和备库解压 CPU 换取更小 WAL。
应把 wal_compression 与 full_page_writes、wal_log_hints、wal_level 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_compression；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | lz4 |
不同于 boot 值 | lz4 |
| OLAP | lz4 |
不同于 boot 值 | lz4 |
| CRIT | lz4 |
不同于 boot 值 | lz4 |
| TINY | lz4 |
不同于 boot 值 | lz4 |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)；OLAP: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)；CRIT: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)；TINY: PG9.5–14 未修改, PG15–19 Beta 3 = lz4 (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在在支持枚举压缩方法的版本上用 LZ4 降低整页映像 WAL 量；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 误以为压缩作用于每条 WAL，而不是整页映像。
- 服务器构建未提供相应方法时选择 lz4 或 zstd。
- 忽略主库压缩 CPU 与恢复重放解压 CPU。
- 修改特权会话值后，误以为其他会话或新连接会自动继承。
- 未控制检查点频率与 full_page_writes 活动就比较 WAL 字节量。
关联参数
full_page_writes · wal_log_hints · wal_level · wal_buffers · commit_delay · commit_siblings
参考资料
32 - wal_decode_buffer_size
Fact — 官方简述译文：设置恢复期间超前读取 WAL 的缓冲区大小。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 512 KiB
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG15 |
| 在档版本 | PG15–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 1d257577e08d — Optionally prefetch referenced data in recovery. |
| 提交日期 | 2021-04-08 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG15–19 Beta 3 | 524288 |
B |
512 KiB |
机制详解
设置恢复期间超前读取 WAL 的缓冲区大小。该值在服务器启动时固定，修改后必须重启。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_decode_buffer_size 与 recovery_prefetch、maintenance_io_concurrency、effective_io_concurrency 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 在与生产相同的存储上用恢复/备库追赶基准调 wal_decode_buffer_size，同时观察 replay I/O wait、缓存命中与 maintenance_io_concurrency；没有测量收益就保留默认。 |
| OLAP | 大型数据集且随机读取较慢时可能收益更大，但过度预取会挤占查询 I/O 与缓存；在故障恢复与读备库两种场景分别测试。 |
| 小规格 | 默认通常足够。内存与 I/O 队列有限时，不要为扩大超前窗口占用资源，除非恢复时间目标有明确缺口。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG15–19 Beta 3 未修改；OLAP: PG15–19 Beta 3 未修改；CRIT: PG15–19 Beta 3 未修改；TINY: PG15–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
- 忽略检查点、复制槽或归档失败造成的联动。
- 在需要 restart 的参数上只 reload 就认为已生效。
关联参数
recovery_prefetch · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command
参考资料
33 - wal_init_zero
Fact — 官方简述译文：新 WAL 文件首次使用前先写零。
身份
类型,- 上游 pg_settings 类型
Context,- 超级用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- on
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 475861b2615d — Add wal_recycle and wal_init_zero GUCs. |
| 提交日期 | 2019-04-02 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | on |
— | on |
机制详解
新 WAL 文件首次使用前先写零。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_init_zero 与 wal_recycle、wal_segment_size、min_wal_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_init_zero；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 在传统文件系统上关闭写零，把空间分配停顿推到 WAL 峰值创建阶段。
- 在写时复制存储上保留写零，却未测量分配与碎片成本。
- 看到稀疏文件就误以为 PostgreSQL 改变了 wal_segment_size。
- 修改会话值后，期待已经创建的 WAL 段被重写。
关联参数
wal_recycle · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings
参考资料
34 - wal_level
Fact — 官方简述译文：设置写入 WAL 的信息级别。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- replica
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–9.6 | minimal |
— | minimal |
| PG10–19 Beta 3 | replica |
— | replica |
机制详解
设置写入 WAL 的信息级别。该值在服务器启动时固定，修改后必须重启。
minimal 只记录崩溃恢复所需信息，不能支持要求 replica 信息的归档/流复制；replica 支持物理复制与归档恢复；logical 再增加逻辑解码信息。修改必须重启，并可能改变 WAL 量。
应把 wal_level 与 wal_compression、full_page_writes、wal_log_hints 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_level；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | logical |
不同于 boot 值 | logical |
| OLAP | logical |
不同于 boot 值 | logical |
| CRIT | logical |
不同于 boot 值 | logical |
| TINY | logical |
不同于 boot 值 | logical |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = logical (dcs)；OLAP: PG9.0–19 Beta 3 = logical (dcs)；CRIT: PG9.0–19 Beta 3 = logical (dcs)；TINY: PG9.0–19 Beta 3 = logical (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让所有 Pigsty profile 默认具备逻辑解码能力；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 选择 minimal 却仍期待归档、流复制或逻辑解码。
- 提高级别却不预算额外 WAL 与重启。
- 槽/订阅仍依赖高级别时就降低。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
wal_compression · full_page_writes · wal_log_hints · wal_buffers · max_wal_senders · max_replication_slots
参考资料
35 - wal_log_hints
Fact — 官方简述译文：页面在检查点后首次发生非关键修改时也将完整页面写入 WAL。
身份
类型,- 上游 pg_settings 类型
Context,- 修改后需要重启数据库
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- off
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.4 |
| 在档版本 | PG9.4–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 961bf59fb7a7 — Rename wal_log_hintbits to wal_log_hints, per discussion on pgsql-hackers. |
| 提交日期 | 2013-12-21 |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.4–19 Beta 3 | off |
— | off |
机制详解
页面在检查点后首次发生非关键修改时也将完整页面写入 WAL。该值在服务器启动时固定，修改后必须重启。
未启用数据校验和时，它让检查点后第一次 hint bit 修改也记录整页 WAL，为 pg_rewind 提供所需块变化安全性。启用校验和后等价日志本就发生，因此该开关不再增加效果。
应把 wal_log_hints 与 wal_compression、full_page_writes、wal_level 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_log_hints；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | on |
不同于 boot 值 | 'on' |
| OLAP | on |
不同于 boot 值 | 'on' |
| CRIT | on |
不同于 boot 值 | 'on' |
| TINY | on |
不同于 boot 值 | 'on' |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 = on (dcs)；OLAP: PG9.4–19 Beta 3 = on (dcs)；CRIT: PG9.4–19 Beta 3 = on (dcs)；TINY: PG9.4–19 Beta 3 = on (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在即使未由数据校验和强制记录 hint bit WAL，也保持 pg_rewind 可用；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
- 忽略检查点、复制槽或归档失败造成的联动。
- 在需要 restart 的参数上只 reload 就认为已生效。
关联参数
wal_compression · full_page_writes · wal_level · wal_buffers · max_wal_senders · max_replication_slots
参考资料
36 - wal_recycle
Fact — 官方简述译文：通过重命名复用 WAL 文件。
身份
类型,- 上游 pg_settings 类型
Context,- 超级用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- on
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG12 |
| 在档版本 | PG12–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 475861b2615d — Add wal_recycle and wal_init_zero GUCs. |
| 提交日期 | 2019-04-02 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG12–19 Beta 3 | on |
— | on |
机制详解
通过重命名复用 WAL 文件。超级用户或获授 SET 权限的角色可在相应的会话或配置作用域中修改它。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_recycle 与 wal_init_zero、wal_segment_size、min_wal_size 一起监控和变更。先在对应角色与真实负载上验证，再按其 superuser context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_recycle；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 误以为在写时复制存储上，重命名复用一定比新分配更快。
- 关闭复用前没有测量 WAL 突发期间的段创建延迟。
- 期待会话修改改变已经复用或删除的文件。
- 把文件复用策略误当成 WAL 保留上限。
关联参数
wal_init_zero · wal_segment_size · min_wal_size · max_wal_size · commit_delay · commit_siblings
参考资料
37 - wal_skip_threshold
Fact — 官方简述译文：设置用 fsync 新文件代替写 WAL 的最小文件规模。
身份
类型,- 上游 pg_settings 类型
Context,- 普通用户可在运行时修改
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 2 MiB
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG13 |
| 在档版本 | PG13–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | cb2fd7eac285 — Skip WAL for new relfilenodes, under wal_level=minimal. |
| 提交日期 | 2020-03-21 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG13–19 Beta 3 | 2048 |
kB |
2 MiB |
机制详解
设置用 fsync 新文件代替写 WAL 的最小文件规模。它可在会话级修改，因此不同会话可能采用不同的行为。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_skip_threshold 与 commit_delay、commit_siblings、fsync 一起监控和变更。先在对应角色与真实负载上验证，再按其 user context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_skip_threshold；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 在 wal_level=replica 或 logical 下调优；此时该参数没有作用。
- 把它应用到普通行修改，而它只涉及新建或重写的关系文件。
- 把未带单位的值读成字节，而不是 kB。
- 未基于真实存储与并发提交影响测试，就在 fsync 与写 WAL 之间作选择。
关联参数
commit_delay · commit_siblings · fsync · full_page_writes · synchronous_commit · wal_buffers
参考资料
38 - wal_summary_keep_time
Fact — 官方简述译文：设置 WAL 摘要文件的保留时间。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 10 d
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG17 |
| 在档版本 | PG17–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 174c480508ac — Add a new WAL summarizer process. |
| 提交日期 | 2023-12-20 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG17–19 Beta 3 | 14400 |
min |
10 d |
机制详解
设置 WAL 摘要文件的保留时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
summarizer 按文件时间戳删除超过该年龄的摘要。保留期必须长于一次增量备份与其依赖的先前备份之间的最长间隔；零表示无限保留，summarize_wal 关闭时也不会清理。
应把 wal_summary_keep_time 与 summarize_wal、wal_level、archive_mode 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 只有采用 PostgreSQL 增量备份时才启用/调整 wal_summary_keep_time；监控 summarizer 进度，并让摘要覆盖任何相邻基础/增量备份之间的完整 WAL 范围。 |
| OLAP | 批量写入会增加摘要工作；把备份间隔、WAL 峰值和备份窗口一起做容量测试，摘要缺口会使增量备份失败。 |
| 小规格 | 不做增量备份就保持 summarize_wal 关闭；若启用，保留期要由实际备份链决定，并给摘要目录设置容量告警。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 删除连接前后两次增量备份仍需要的摘要。
- 设为零却不监控无界增长。
- 关闭 summarize_wal 后仍期待保留清理继续。
- 混淆 pg_settings 的原始单位与配置文件可读单位。
- 只做吞吐基准，不做崩溃恢复与归档还原。
关联参数
summarize_wal · wal_level · archive_mode · max_wal_size · archive_cleanup_command · archive_command
参考资料
39 - wal_sync_method
Fact — 官方简述译文：选择将 WAL 更新强制写入磁盘的方法。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- fdatasync
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | fdatasync |
— | fdatasync |
机制详解
选择将 WAL 更新强制写入磁盘的方法。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_sync_method 与 fsync、full_page_writes、synchronous_commit 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_sync_method；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 选择操作系统或文件系统不支持的同步方法。
- 在与生产不同的内核、挂载参数或存储缓存上做基准。
- 混淆写吞吐与持久同步延迟。
- 修改方法却不做崩溃或掉电耐久性测试。
- 误以为数据文件上最快的方法也一定最适合 WAL。
关联参数
fsync · full_page_writes · synchronous_commit · wal_buffers · wal_writer_delay · commit_delay
参考资料
40 - wal_writer_delay
Fact — 官方简述译文：设置 WAL writer 两次刷写之间的时间。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 200 ms
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.0（研究下界） |
| 在档版本 | PG9.0–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 不作断言：早于 PG9.0 研究边界 |
| 提交日期 | — |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.0–19 Beta 3 | 200 |
ms |
200 ms |
机制详解
设置 WAL writer 两次刷写之间的时间。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_writer_delay 与 fsync、full_page_writes、wal_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_writer_delay；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 20ms |
不同于 boot 值 | 20ms |
| OLAP | 20ms |
不同于 boot 值 | 20ms |
| CRIT | 10ms |
不同于 boot 值 | 10ms |
| TINY | 20ms |
不同于 boot 值 | 20ms |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = 20ms (dcs)；OLAP: PG9.0–19 Beta 3 = 20ms (dcs)；CRIT: PG9.0–19 Beta 3 = 10ms (dcs)；TINY: PG9.0–19 Beta 3 = 20ms (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让 WAL 更频繁地由后台移出前台后端，CRIT 采用更短节奏；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 把间隔当成严格的提交刷盘期限；writer 可提前唤醒，前台提交也可独立刷盘。
- 设置过低，产生过多唤醒与小写入开销。
- 设置过高，把更多 WAL 写入推回前台后端。
- 解释写出与持久刷盘时机时忽略 wal_writer_flush_after。
- 使用异步提交却没有为可能的数据丢失窗口做预算。
关联参数
fsync · full_page_writes · wal_sync_method · synchronous_commit · wal_buffers · commit_delay
参考资料
41 - wal_writer_flush_after
Fact — 官方简述译文：设置触发 WAL writer 刷盘的写出 WAL 数量。
身份
类型,- 上游 pg_settings 类型
Context,- 配置 reload 后生效
单位,- 原始单位
范围,- 最后在档版本的原始上下限
枚举值,- 非枚举类型记为 —
分类,- 上游分类
最后 boot 值,- 1 MiB (128 × 8kB)
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG9.6 |
| 在档版本 | PG9.6–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | 7975c5e0a992 — Allow the WAL writer to flush WAL at a reduced rate. |
| 提交日期 | 2016-02-15 |
| Discussion | — |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG9.6–19 Beta 3 | 128 |
8kB |
1 MiB (128 × 8kB) |
机制详解
设置触发 WAL writer 刷盘的写出 WAL 数量。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
它位于 WAL 生成、写出、检查点、归档与恢复链路中；实际效果还受 wal_level、检查点节奏、持久化设置与存储语义影响。只观察单一参数不足以证明耐久性或恢复能力。
应把 wal_writer_flush_after 与 wal_buffers、wal_writer_delay、wal_sync_method 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 先保证耐久性与恢复目标，再以 WAL 生成速率、刷写延迟、检查点和 pg_wal 峰值调 wal_writer_flush_after；每次改动都做崩溃/恢复与归档监控验证。 |
| OLAP | 按批量装载峰值规划 WAL、归档带宽和恢复 I/O；需要降低峰值时应协调装载节奏与检查点，而不是牺牲恢复链。 |
| 小规格 | 从安全默认或实测 Pigsty 值开始，按有限磁盘容量设置明确告警；不要仅为节省少量 I/O 就关闭耐久性或破坏恢复链。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 1MB |
等于 boot 值 | 1MB |
| OLAP | 1MB |
等于 boot 值 | 1MB |
| CRIT | 0 |
不同于 boot 值 | 0 |
| TINY | 1MB |
等于 boot 值 | 1MB |
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 1MB (dcs)；OLAP: PG9.6–19 Beta 3 = 1MB (dcs)；CRIT: PG9.6–19 Beta 3 = 0 (dcs)；TINY: PG9.6–19 Beta 3 = 1MB (dcs)。 建议（待人工复核）——编辑推断（待维护者人工复核）：该选择看起来意在让 WAL writer 按 1 MiB 批量刷盘，而 CRIT 要求立即刷盘；发布前应结合当前 Pigsty 模板、硬件夹具和运维保证复核。
常见坑
- 把未带单位的值读成字节，而不是 WAL 块。
- 忘记零表示 WAL writer 立即请求刷盘。
- 选择大批量，却不考虑异步提交的数据丢失暴露与脏 WAL。
- 把该参数当作同步提交刷盘的替代品。
- 不结合 wal_writer_delay 与存储刷盘延迟就调优。
关联参数
wal_buffers · wal_writer_delay · wal_sync_method · synchronous_commit · commit_delay · commit_siblings