wal_keep_size
为可能落后的流复制备库额外保留旧 WAL 的可重载最小值。本目录从 PG13 起收录该参数，默认 0 MB，Pigsty 四个模板均未修改。
说明
Fact — 官方简述译文：设置为备库保留的 WAL 文件大小。
身份
生命周期
| Fact | 值 |
|---|---|
| 首次观测 | PG13 |
| 在档版本 | PG13–19 Beta 3 |
| 移除版本 | 否 |
| 引入提交 | f5dff45962ec — Rename wal_keep_segments to wal_keep_size. |
| 提交日期 | 2020-07-20 |
| Discussion | 讨论 1 |
默认值变迁
| 版本 | 原始 boot_val |
单位 | 人类可读值 |
|---|---|---|---|
| PG13–19 Beta 3 | 0 |
MB |
0 B |
机制详解
发送端会在 pg_wal 中至少保留 wal_keep_size MB 的历史 WAL，使落后备库不会因旧段过早消失而中断流复制。如果落后距离超过现有文件，流连接会终止；若归档中存在缺失段，备库仍可从归档恢复。
它是保留下限，不是精确预留量，也不是上限。检查点恢复、归档、复制槽以及近期 WAL 用量估计都可能保留更多文件。值为 0 表示不专门为备库额外保留，并不表示 pg_wal 中没有旧 WAL。
复制槽依据各消费者确认位置精确保留 WAL，通常更可靠。wal_keep_size 仍可作为无槽备库或短暂重连的简单保险，但容量应按峰值 WAL 速率乘以预期中断窗口计算。
调优建议
提示
Advice。 以下建议是工作负载起点，必须用真实测量验证。
| 场景 | 建议 |
|---|---|
| OLTP | 优先使用受监控的复制槽和经过验证的归档。确需非零下限时，按峰值 WAL 字节速率与容忍断连时间计算，再增加余量并监控复制延迟。 |
| OLAP | 短时间批量导入就可能突破静态保留量。必须跨越此类峰值的消费者应使用复制槽或归档，wal_keep_size 也应按峰值而非平均速率定值。 |
| 小规格 | 复制槽和归档恢复可靠时保持 0。否则选择不会在归档或复制槽事故叠加时耗尽磁盘的适度、有界值。 |
Pigsty 取值
以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。
| 模板 | 有效值 | 与上游 boot 比较 | 源表达式 |
|---|---|---|---|
| OLTP | 未修改 | — | — |
| OLAP | 未修改 | — | — |
| CRIT | 未修改 | — | — |
| TINY | 未修改 | — | — |
注意
Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG13–19 Beta 3 未修改；OLAP: PG13–19 Beta 3 未修改；CRIT: PG13–19 Beta 3 未修改；TINY: PG13–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。
常见坑
- 把 wal_keep_size 当作 pg_wal 使用量上限。
- 把 0 理解为“不保留 WAL”，而不是“不为备库额外保留”。
- 按平均 WAL 速率定值，在批任务峰值时失效。
- 认为备库超过保留窗口后仍保证可继续复制。
- 比较 PG12 与 PG13 时漏掉前身参数 wal_keep_segments。
关联参数
wal_keep_segments · max_replication_slots · max_slot_wal_keep_size · archive_mode · max_wal_size · primary_slot_name
参考资料
- PostgreSQL 19 Beta 3 — wal_keep_size
- PostgreSQL 18：复制槽
- PostgreSQL 18：WAL 配置
- PostgreSQL 19 发行说明
- 机器可读 GUC 全量导出