CONFIGURATION PARAMETER预写式日志 / 检查点

max_wal_size

在自动检查点期间允许 WAL 增长的最大大小。

Sets the WAL size that triggers a checkpoint.

整数重载生效引入 9.5 现存至 20 devel 1 次默认值变更

类型: 整数integer
上下文: 重载生效改配置文件后重载（pg_ctl reload / SIGHUP）即可生效
默认值: 1 GiB原始值 1024 MB
取值范围: 2 – 2147483647
分类: 预写式日志 / 检查点
引入版本: 9.5
状态: 现存

PostgreSQL 18.7 手册官方文档引入提交 88e9823026

版本轨迹

相对 PostgreSQL 17 无变化。

默认值变迁

1 GiB (64 × 16MB) 9.5 – 9.6 1 GiB 10 – 19

默认值一共换过 2 档，每段的宽度按它覆盖的大版本数伸展，深色的一段是当前查看的 PostgreSQL 18.7。带单位的取值换算成了可读形式，原始的 boot_val 与单位写在悬浮提示里。

手册说明

PostgreSQL 18.7 手册 · 19.5 预写式日志本站手册官方原文

在自动检查点期间允许 WAL 增长的最大大小。这是一个软限制；在特殊情况下，如重负载、失败的 archive_command 或 archive_library，或高 wal_keep_size 设置下，WAL 大小可能会超过 max_wal_size。如果未指定单位，则将其视为兆字节。默认值为 1 GB。增加此参数可能会增加崩溃恢复所需的时间。此参数只能在 postgresql.conf 文件或服务器命令行中设置。

机制详解

检查点进程会在 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 变成硬上限。

调优建议

按典型负载给出的取值思路，不是放之四海皆准的配方：实际取值要看数据量、并发度与硬件。

OLTP在线事务处理

根据实测峰值 WAL 产生速率和可接受的检查点频率定值。持续观察 pg_stat_checkpointer、checkpoint_warning、写延迟、归档延迟与剩余空间；只有请求型检查点长期占主导时才有依据上调。
OLAP分析与批处理

批量导入和大型维护任务会突发产生 WAL，较大值可减少检查点风暴。必须同时确认 pg_wal 容量、归档吞吐以及更长的崩溃恢复窗口都可接受。
小规格低配实例与开发机

小磁盘应使用保守且有明确上限的值。复制槽保留量和归档积压要另算，并预留应急空间，不要把卷的大部分空间都分配给名义上的检查点阈值。

常见问题

误以为 max_wal_size 是 pg_wal 的硬上限。
通过增大该值掩盖归档失败或废弃复制槽。
下调前没有评估全页镜像量和检查点延迟。
忽略无单位数字按 MB 解释。
脱离 checkpoint_timeout 与 checkpoint_completion_target 单独调参。

演化历史

相邻两个大版本之间的差异，新的在前。版本号链到该版的快照。

PostgreSQL 10 ← 9.6 默认值变更

默认值 1 GiB (64 × 16MB) 1 GiB 单位 16MB MB
PostgreSQL 9.5 ← 9.4 新增此参数

PostgreSQL 9.5 起可用

逐版本快照

每个收录版本里的 7 项事实，与上一个存在的版本不同的格子带底色。版本号链到该版。

版本	默认值	单位	上下文	类型	最小值	最大值	枚举值
9.5	`1 GiB (64 × 16MB)`	`16MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
9.6	`1 GiB (64 × 16MB)`	`16MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
10	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
11	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
12	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
13	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
14	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
15	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
16	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
17	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
18	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
19	`1 GiB`	`MB`	`重载生效`	`整数`	`2`	`2147483647`	`—`
20	—	—	—	`整数`	—	—	—

参考资料

同类参数

参数	类型	上下文	默认值	最近变更
Write-Ahead Log 预写式日志 7 个 ↗
检查点 7
`checkpoint_completion_target`	浮点	重载生效	`0.9`	141 次
指定检查点完成所用时间的目标值，以检查点之间总时间的比例表示。				现存
`checkpoint_flush_after`	整数	重载生效	`256 KiB (32 × 8kB)`	—
当执行检查点时写入的数据量超过此数量时，就尝试强制 OS 把这些写发送到底层存储。				现存
`checkpoint_segments`	整数	重载生效	`3`	—
自动 WAL 检查点之间日志文件段的最大数量（每个段通常为 16 兆字节）。				于 9.5 移除
`checkpoint_timeout`	整数	重载生效	`5 min`	9.61 次
自动 WAL 检查点之间的最长时间。				现存
`checkpoint_warning`	整数	重载生效	`30 s`	—
如果由于填充 WAL 段文件导致的检查点之间的间隔低于这个参数表示的时间量，那么就向服务器日志写一个消息（它建议增加 max_wal_size 的值）。				现存
`max_wal_size`	整数	重载生效	`1 GiB`	101 次
在自动检查点期间允许 WAL 增长的最大大小。				现存
`min_wal_size`	整数	重载生效	`80 MiB`	101 次
只要 WAL 磁盘用量保持在这个设置之下，在检查点时旧的 WAL 文件总是被回收以便未来使用，而不是直接被删除。				现存

快速链接