CONFIGURATION PARAMETER预写式日志 / 检查点
checkpoint_timeout
自动 WAL 检查点之间的最长时间。
Sets the maximum time between automatic WAL checkpoints.
整数 重载生效 引入 7.4（基线） 现存至 20 devel 0 次默认值变更
- 类型
- 整数integer
- 上下文
- 重载生效改配置文件后重载（pg_ctl reload / SIGHUP）即可生效
- 默认值
5 min原始值 300 s- 取值范围
30 – 86400- 分类
- 预写式日志 / 检查点
- 引入版本
- 7.4（基线）
- 状态
- 现存
版本轨迹
相对 PostgreSQL 17 无变化。
默认值变迁
已记录的默认值在 PostgreSQL 9.0–19 之间未变。带单位的取值换算成了可读形式，原始的 boot_val 与单位写在悬浮提示里。
手册说明
自动 WAL 检查点之间的最长时间。如果指定值时没有单位，则以秒为单位。合理的范围在 30 秒到 1 天之间。默认是 5 分钟（5min）。增加这个参数的值可能会增加崩溃恢复所需的时间。这个参数只能在 postgresql.conf 文件中或在服务器命令行上设置。
机制详解
达到 checkpoint_timeout 后系统会考虑执行自动检查点，但 max_wal_size 可以更早触发。如果上次检查点后没有写入 WAL，PostgreSQL 可以跳过这次定时检查点，因此它是最长调度间隔，而不是固定周期工作的承诺。
较长间隔通常会减少检查点次数和全页写放大，但崩溃恢复时可能需要重放更多 WAL。较短间隔能收紧重放区间，却会增加脏页写回以及每次检查点后的全页镜像。
主库检查点记录也限制备库可执行重启点的位置。不要用本参数定义 WAL 归档的 RPO；低 WAL 负载下强制切换段应使用 archive_timeout。
调优建议
按典型负载给出的取值思路，不是放之四海皆准的配方：实际取值要看数据量、并发度与硬件。
-
OLTP在线事务处理
与 max_wal_size 联合调优，并通过 checkpoint_completion_target 平摊检查点 I/O。只有在量化恢复要求、请求型与定时型检查点比例、写延迟和 WAL 量之后才延长间隔。
-
OLAP分析与批处理
批处理期间通常是 max_wal_size 先触发。如果容量型检查点占主导，应先增加 WAL 空间，同时保留能满足重启与恢复目标的超时值。
-
小规格低配实例与开发机
在恢复时间重要且存储有限的环境里，上游 5 分钟是合理起点。延长间隔必须有明确的磁盘余量和经过测试的崩溃恢复预算。
常见问题
- 认为空闲系统也必然严格按该间隔执行检查点。
- 忘记 max_wal_size 可能更早触发检查点。
- 用 checkpoint_timeout 代替 archive_timeout 限制归档延迟。
- 增大后没有计入更长的崩溃恢复重放区间。
- 设置过小导致全页写和检查点 I/O 占主导。
演化历史
相邻两个大版本之间的差异，新的在前。版本号链到该版的快照。
-
PostgreSQL 9.6 ← 9.5 属性变更
最大值
360086400
逐版本快照
每个收录版本里的 7 项事实，与上一个存在的版本不同的格子带底色。版本号链到该版。
| 版本 | 默认值 | 单位 | 上下文 | 类型 | 最小值 | 最大值 | 枚举值 |
|---|---|---|---|---|---|---|---|
| 7.4 | — | — | — | 整数 |
— | — | — |
| 8.0 | — | — | — | 整数 |
— | — | — |
| 8.1 | — | — | — | 整数 |
— | — | — |
| 8.2 | — | — | — | 整数 |
— | — | — |
| 8.3 | — | — | — | 整数 |
— | — | — |
| 8.4 | — | — | — | 整数 |
— | — | — |
| 9.0 | 5 min |
s |
重载生效 |
整数 |
30 |
3600 |
— |
| 9.1 | 5 min |
s |
重载生效 |
整数 |
30 |
3600 |
— |
| 9.2 | 5 min |
s |
重载生效 |
整数 |
30 |
3600 |
— |
| 9.3 | 5 min |
s |
重载生效 |
整数 |
30 |
3600 |
— |
| 9.4 | 5 min |
s |
重载生效 |
整数 |
30 |
3600 |
— |
| 9.5 | 5 min |
s |
重载生效 |
整数 |
30 |
3600 |
— |
| 9.6 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 10 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 11 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 12 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 13 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 14 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 15 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 16 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 17 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 18 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 19 | 5 min |
s |
重载生效 |
整数 |
30 |
86400 |
— |
| 20 | — | — | — | 整数 |
— | — | — |
参考资料
同类参数
| 参数 | 类型 | 上下文 | 默认值 | 版本变动 | 最近变更 |
|---|---|---|---|---|---|
| 检查点 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 文件总是被回收以便未来使用，而不是直接被删除。 | 现存 | ||||