CONFIGURATION PARAMETER预写式日志 / 归档恢复
archive_cleanup_command
设置每次重启点执行的 shell 命令。
Sets the shell command that will be executed at every restart point.
字符串 重载生效 引入 12 现存至 20 devel 0 次默认值变更
- 类型
- 字符串string
- 上下文
- 重载生效改配置文件后重载（pg_ctl reload / SIGHUP）即可生效
- 默认值
空字符串原始值 ''- 分类
- 预写式日志 / 归档恢复
- 引入版本
- 12
- 状态
- 现存
版本轨迹
相对 PostgreSQL 17 无变化。
默认值变迁
默认值自 PostgreSQL 12 起没有变过。带单位的取值换算成了可读形式，原始的 boot_val 与单位写在悬浮提示里。
手册说明
这个可选参数指定了一个 shell 命令，它将在每一个重启点被执行。 archive_cleanup_command的目的是提供一种清除不再被备库需要的旧的已归档 WAL 文件的机制。 任何%r会被替换为包含最后一个可用重启点的文件的名称。 那是使一次恢复变成可重启的所必须被保留的最早的文件，并且因此比%r更早的所有文件可以被安全地移除。 这个信息可以被用来把归档截断为支持从当前恢复重启所需的最小值。 对于单一备库配置，pg_archivecleanup模块常常被用在archive_cleanup_command中，例如：
archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'
但是注意，如果多个备库正在从同一个归档目录中恢复，你将需要保证只有当任意服务器都不再需要 WAL 文件时才会删除它们。 archive_cleanup_command通常被用于一种温备配置（见Section 26.2）中。 要在该命令中嵌入一个真正的%字符，需要写成%%。
如果该命令返回一个非零退出状态，则将会写出一个警告日志消息。 一个例外是如果该命令被一个信号或者一个 shell 错误（例如命令未找到）终止，则会抛出一个致命错误。
这个参数只能在postgresql.conf文件中或通过服务器命令行进行设置。
机制详解
设置每次重启点执行的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。
归档恢复的每个 restartpoint 都会执行该命令，并把 %r 展开为保持恢复可重新启动所需的最早 WAL 文件。通常使用 pg_archivecleanup；若多个备库共享归档，贸然删除可能让其他消费者断链。
应把 archive_cleanup_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。
调优建议
按典型负载给出的取值思路，不是放之四海皆准的配方：实际取值要看数据量、并发度与硬件。
-
OLTP在线事务处理
把 archive_cleanup_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。
-
OLAP分析与批处理
按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。
-
小规格低配实例与开发机
有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。
常见问题
- 对其他备库或恢复任务共享的归档执行破坏性清理。
- 把 %r 误读为最后重放文件；它表示保持恢复可重新启动所需的最早文件。
- restartpoint 重复或归档文件已不存在时，命令不具备幂等性。
- 误以为 reload 会立即执行命令；它只在恢复 restartpoint 运行。
- shell 引用或异常归档路径使清理越过预期归档目录。
演化历史
相邻两个大版本之间的差异，新的在前。版本号链到该版的快照。
-
PostgreSQL 20 ← 19 沿用 19
事实沿用 19
-
PostgreSQL 12 ← 11 新增此参数
PostgreSQL 12 起可用
逐版本快照
每个收录版本里的 7 项事实，与上一个存在的版本不同的格子带底色。版本号链到该版。
参考资料
同类参数
| 参数 | 类型 | 上下文 | 默认值 | 版本变动 | 最近变更 |
|---|---|---|---|---|---|
| 归档恢复 3 | |||||
archive_cleanup_command |
字符串 | 重载生效 | 空字符串 |
— | |
| 设置每次重启点执行的 shell 命令。 | 现存 | ||||
recovery_end_command |
字符串 | 重载生效 | 空字符串 |
— | |
| 设置恢复结束时执行一次的 shell 命令。 | 现存 | ||||
restore_command |
字符串 | 重载生效 | 空字符串 |
141 次 | |
| 设置取回归档 WAL 文件时调用的 shell 命令。 | 现存 | ||||