{"Entry":{"collection":"guc","key":"restore_command","name":"restore_command","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Archive Recovery","category_zh":"","changed_in":["13","14"],"changes":[{"documentation_changed":false,"fields":{},"from":"11","status":"added","to":"12"},{"documentation_changed":false,"fields":{"short_desc":{"from":"Sets the shell command that will retrieve an archived WAL file.","to":"Sets the shell command that will be called to retrieve an archived WAL file."}},"from":"12","status":"changed","to":"13"},{"documentation_changed":true,"fields":{"context":{"from":"postmaster","to":"sighup"}},"from":"13","status":"changed","to":"14"},{"documentation_changed":true,"fields":{},"from":"16","status":"changed","to":"17"},{"documentation_changed":true,"fields":{},"from":"18","status":"changed","to":"19"}],"content_hash":"8b65aef61832007a0f50fefe879bd0e2f242577c7bf9694e8e0854061a9a436a","context":"","default_changed_in":[],"default_history":[{"from":"12","to":"19","value":"Empty string"}],"editorial":{"advice":{"olap":"Provision archive throughput and capacity for bulk-load WAL peaks. If archiving falls behind, throttle the job and alert; never hide backlog with false success or aggressive cleanup.","oltp":"Manage restore_command as part of the backup/restore protocol: the command or module must be idempotent, fail visibly, and be verified by restoring from the real archive—not merely by exit status.","small":"Enable it only for a defined PITR requirement and use a mature backup tool. Keep rebuildable instances simple, but never install a no-op command that creates the illusion of a backup."},"mechanism":["Sets the shell command that will be called to retrieve an archived WAL file. A configuration reload applies a new value; existing work already in flight is not retroactively changed.","During archive recovery PostgreSQL expands %f to the requested file and %p to its destination. Success must mean the exact file was copied durably; a normal not-found result must be nonzero so recovery can try streaming or pg_wal, while shell quoting must resist unusual paths.","Monitor and change restore_command together with archive_mode, archive_command, archive_library. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value."],"pitfalls":["Returning zero for a missing or wrong WAL file.","Failing to quote %f and %p safely.","Using an archive that can return a segment from the wrong timeline or cluster.","Confusing pg_settings base units with human-readable configuration units.","Benchmarking throughput without a crash-recovery and archive-restore test."],"references":[{"title":"PostgreSQL 19 Beta 4: restore_command","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-RESTORE-COMMAND"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["archive_mode","archive_command","archive_library","archive_timeout","archive_cleanup_command","recovery_end_command"],"summary":"restore_command sets the shell command that will be called to retrieve an archived WAL file. It is a sighup setting present in PG12–18; the latest recorded boot default is empty."},"enumvals":[],"first_version":"12","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:31.913676+08:00","intro_commit":{"authored_at":"2018-11-25T16:31:16+01:00","discussion":["https://www.postgresql.org/message-id/flat/607741529606767@web3g.yandex.ru/"],"hash":"2dedf4d9a899b36d1a8ed29be5efbd1b31a8fe85","subject":"Integrate recovery.conf into postgresql.conf","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=2dedf4d9a899b36d1a8ed29be5efbd1b31a8fe85"},"key":"restore_command","last_version":"20","max_val":"","min_val":"","name":"restore_command","position":342,"present_in":["12","13","14","15","16","17","18","19","20"],"short_desc":"The local shell command to execute to retrieve an archived segment of the WAL file series.","short_desc_zh":"","source_rev":"english-manuals:308fd5ed85f537a917b0cdc7c60ebdd31bafc2f4a7840d15cf6cae7a8edbffaf","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"restore_command","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"restore_command","SourceRevision":"english-manuals:308fd5ed85f537a917b0cdc7c60ebdd31bafc2f4a7840d15cf6cae7a8edbffaf","Facts":{"boot_val":"","category":"Write-Ahead Log / Archive Recovery","context":"sighup","description":"The local shell command to execute to retrieve an archived segment of the WAL file series. This parameter is required for archive recovery, but optional for streaming replication. Any %f in the string is replaced by the name of the file to retrieve from the archive, and any %p is replaced by the copy destination path name on the server. (The path name is relative to the current working directory, i.e., the cluster's data directory.) Any %r is replaced by the name of the file containing the last valid restart point. That is the earliest file that must be kept to allow a restore to be restartable, so this information can be used to truncate the archive to just the minimum required to support restarting from the current restore. %r is typically only used by warm-standby configurations (see Section 26.2). Write %% to embed an actual % character. It is important for the command to return a zero exit status only if it succeeds. The command will be asked for file names that are not present in the archive; it must return nonzero when so asked. Examples: restore_command = 'cp /mnt/server/archivedir/%f \"%p\"' restore_command = 'copy \"C:\\\\server\\\\archivedir\\\\%f\" \"%p\"' # Windows An exception is that if the command was terminated by a signal (other than SIGTERM, which is used as part of a database server shutdown) or an error by the shell (such as command not found), then recovery will abort and the server will not start up. This parameter can only be set in the postgresql.conf file or on the server command line.","doc":{"anchor":"GUC-RESTORE-COMMAND","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"restore_command","short_desc":"Sets the shell command that will be called to retrieve an archived WAL file.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-RESTORE-COMMAND","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"restore_command","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"restore_command","Summary":"","BodyHTML":"\u003cp\u003e用于获取 WAL 文件系列的一个已归档段的本地 shell 命令。这个参数是归档恢复所必需的，但是对于流复制是可选的。在该字符串中的任何\u003ccode\u003e%f\u003c/code\u003e会被替换为从归档中获得的文件的名字，并且任何\u003ccode\u003e%p\u003c/code\u003e会被替换为服务器上的复制目标路径名（该路径名是相对于当前工作目录的，即集簇的数据目录）。任何\u003ccode\u003e%r\u003c/code\u003e会被包含上一个可用重启点的文件的名字所替换。在那些必须被保留用于使得一次恢复变成可重启的文件中，这个文件是其中最早的一个，因此这个信息可以被用来把归档截断为支持从当前恢复重启所需的最小值。\u003ccode\u003e%r\u003c/code\u003e通常只被温备配置（见\u003ca href=\"/docs/18/warm-standby.html\" rel=\"nofollow\"\u003e第 26.2 节\u003c/a\u003e）所使用。要嵌入一个真正的\u003ccode\u003e%\u003c/code\u003e字符，需要写成\u003ccode\u003e%%\u003c/code\u003e。\u003c/p\u003e\u003cp\u003e很重要的一点是，该命令只有在成功时才返回一个为零的退出状态。该命令\u003cspan\u003e\u003cem\u003e将\u003c/em\u003e\u003c/span\u003e会被要求获取归档中不存在的文件；遇到这种情况时，它必须返回非零。示例：\u003c/p\u003e\u003cpre\u003erestore_command = \u0026#39;cp /mnt/server/archivedir/%f \u0026#34;%p\u0026#34;\u0026#39;\nrestore_command = \u0026#39;copy \u0026#34;C:\\\\server\\\\archivedir\\\\%f\u0026#34; \u0026#34;%p\u0026#34;\u0026#39;  # Windows\n\u003c/pre\u003e\u003cp\u003e一个例外是如果该命令被一个信号（不是\u003cspan\u003eSIGTERM\u003c/span\u003e，它是数据库服务器关闭的一部分）或者一个 shell 错误（例如命令未找到）终止，则恢复将会中止并且服务器将不会启动。\u003c/p\u003e\u003cp\u003e这个参数只能在\u003ccode\u003epostgresql.conf\u003c/code\u003e文件中或通过服务器命令行进行设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"8dc04914175c8ac4b397aca828ce19c916eed8eff1c7ed645dfae48d92c1b0a6","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e用于获取 WAL 文件系列的一个已归档段的本地 shell 命令。这个参数是归档恢复所必需的，但是对于流复制是可选的。在该字符串中的任何\u003ccode class=\"literal\"\u003e%f\u003c/code\u003e会被替换为从归档中获得的文件的名字，并且任何\u003ccode class=\"literal\"\u003e%p\u003c/code\u003e会被替换为服务器上的复制目标路径名（该路径名是相对于当前工作目录的，即集簇的数据目录）。任何\u003ccode class=\"literal\"\u003e%r\u003c/code\u003e会被包含上一个可用重启点的文件的名字所替换。在那些必须被保留用于使得一次恢复变成可重启的文件中，这个文件是其中最早的一个，因此这个信息可以被用来把归档截断为支持从当前恢复重启所需的最小值。\u003ccode class=\"literal\"\u003e%r\u003c/code\u003e通常只被温备配置（见\u003ca href=\"/docs/18/warm-standby.html\" title=\"26.2. 日志传送备库\"\u003e第 26.2 节\u003c/a\u003e）所使用。要嵌入一个真正的\u003ccode class=\"literal\"\u003e%\u003c/code\u003e字符，需要写成\u003ccode class=\"literal\"\u003e%%\u003c/code\u003e。\u003c/p\u003e\u003cp\u003e很重要的一点是，该命令只有在成功时才返回一个为零的退出状态。该命令\u003cspan class=\"emphasis\"\u003e\u003cem\u003e将\u003c/em\u003e\u003c/span\u003e会被要求获取归档中不存在的文件；遇到这种情况时，它必须返回非零。示例：\u003c/p\u003e\u003cpre\u003erestore_command = 'cp /mnt/server/archivedir/%f \"%p\"'\nrestore_command = 'copy \"C:\\\\server\\\\archivedir\\\\%f\" \"%p\"'  # Windows\n\u003c/pre\u003e\u003cp\u003e一个例外是如果该命令被一个信号（不是\u003cspan class=\"systemitem\"\u003eSIGTERM\u003c/span\u003e，它是数据库服务器关闭的一部分）或者一个 shell 错误（例如命令未找到）终止，则恢复将会中止并且服务器将不会启动。\u003c/p\u003e\u003cp\u003e这个参数只能在\u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e文件中或通过服务器命令行进行设置。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["12","13","14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}