↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 配置参数 / 预写式日志

CONFIGURATION PARAMETER预写式日志 / 归档恢复

restore_command

设置取回归档 WAL 文件时调用的 shell 命令。

Sets the shell command that will be called to retrieve an archived WAL file.

字符串 重载生效 引入 12 现存至 20 devel 0 次默认值变更

类型
字符串string
上下文
重载生效改配置文件后重载（pg_ctl reload / SIGHUP）即可生效
默认值
空字符串原始值 ''
分类
预写式日志 / 归档恢复
引入版本
12
状态
现存

PostgreSQL 18 手册 官方文档 引入提交 2dedf4d9a8

版本轨迹

相对 PostgreSQL 17 无变化。

默认值变迁

空字符串 12 – 20

已记录的默认值在 PostgreSQL 12–20 之间未变。带单位的取值换算成了可读形式，原始的 boot_val 与单位写在悬浮提示里。

手册说明

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

用于获取 WAL 文件系列的一个已归档段的本地 shell 命令。这个参数是归档恢复所必需的，但是对于流复制是可选的。在该字符串中的任何%f会被替换为从归档中获得的文件的名字，并且任何%p会被替换为服务器上的复制目标路径名（该路径名是相对于当前工作目录的，即集簇的数据目录）。任何%r会被包含上一个可用重启点的文件的名字所替换。在那些必须被保留用于使得一次恢复变成可重启的文件中，这个文件是其中最早的一个，因此这个信息可以被用来把归档截断为支持从当前恢复重启所需的最小值。%r通常只被温备配置（见第 26.2 节）所使用。要嵌入一个真正的%字符，需要写成%%。

很重要的一点是，该命令只有在成功时才返回一个为零的退出状态。该命令将会被要求获取归档中不存在的文件；遇到这种情况时，它必须返回非零。示例：

restore_command = 'cp /mnt/server/archivedir/%f "%p"'
restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows

一个例外是如果该命令被一个信号（不是SIGTERM，它是数据库服务器关闭的一部分）或者一个 shell 错误（例如命令未找到）终止，则恢复将会中止并且服务器将不会启动。

这个参数只能在postgresql.conf文件中或通过服务器命令行进行设置。

机制详解

设置取回归档 WAL 文件时调用的 shell 命令。重新加载配置即可应用新值；已经开始的工作不会被追溯改变。

归档恢复时 PostgreSQL 把 %f 展开为请求文件、%p 展开为目标路径。成功必须表示准确文件已可靠复制；正常的未找到应返回非零，以便继续尝试流复制或 pg_wal，同时 shell 引用必须安全。

应把 restore_command 与 archive_mode、archive_command、archive_library 一起监控和变更。先在对应角色与真实负载上验证，再按其 sighup context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

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

  • OLTP在线事务处理

    把 restore_command 作为备份/恢复协议的一部分管理：命令或模块必须幂等、失败可见，并通过从真实归档恢复来验证，而不是只看返回码。

  • OLAP分析与批处理

    按批量装载 WAL 峰值配置归档吞吐与容量；归档跟不上时节流任务并报警，不能用虚假成功或激进清理掩盖积压。

  • 小规格低配实例与开发机

    有明确 PITR 需求才启用并交给成熟备份工具；可重建实例保持简单，但不要留下占位命令制造“已备份”的错觉。

常见问题

  • 缺失或错误 WAL 文件也返回零。
  • 没有安全引用 %f 与 %p。
  • 归档可能返回另一时间线或集群的同名段。
  • 混淆 pg_settings 的原始单位与配置文件可读单位。
  • 只做吞吐基准，不做崩溃恢复与归档还原。

演化历史

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

  1. PostgreSQL 20 ← 19 沿用 19

    事实沿用 19

  2. PostgreSQL 14 ← 13 属性变更

    上下文 重启生效 重载生效

  3. PostgreSQL 13 ← 12 仅描述更新

    简述 Sets the shell command that will retrieve an archived WAL file. Sets the shell command that will be called to retrieve an archived WAL file.

  4. PostgreSQL 12 ← 11 新增此参数

    PostgreSQL 12 起可用

逐版本快照

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

版本 默认值单位上下文类型最小值最大值枚举值
12 空字符串 — 重启生效 字符串 — — —
13 空字符串 — 重启生效 字符串 — — —
14 空字符串 — 重载生效 字符串 — — —
15 空字符串 — 重载生效 字符串 — — —
16 空字符串 — 重载生效 字符串 — — —
17 空字符串 — 重载生效 字符串 — — —
18 空字符串 — 重载生效 字符串 — — —
19 空字符串 — 重载生效 字符串 — — —
20 沿用 空字符串 — 重载生效 字符串 — — —

参考资料

同类参数

参数 类型 上下文 默认值 版本变动 最近变更
Write-Ahead Log 预写式日志 3 个 ↗
归档恢复 3
archive_cleanup_command 字符串 重载生效 空字符串 —
设置每次重启点执行的 shell 命令。 现存
recovery_end_command 字符串 重载生效 空字符串 —
设置恢复结束时执行一次的 shell 命令。 现存
restore_command 字符串 重载生效 空字符串 141 次
设置取回归档 WAL 文件时调用的 shell 命令。 现存