{"Entry":{"collection":"guc","key":"archive_cleanup_command","name":"archive_cleanup_command","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Archive Recovery","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"11","status":"added","to":"12"},{"documentation_changed":true,"fields":{},"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":"5946dfc5dbd6a00460153dcdc873443747f4fbd38ff6aab95418e8bb11b1185f","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 archive_cleanup_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 executed at every restart point. A configuration reload applies a new value; existing work already in flight is not retroactively changed.","At every restartpoint during archive recovery, PostgreSQL expands %r to the oldest WAL file still needed for a restartable recovery and runs this command. pg_archivecleanup is the usual implementation, but deleting from an archive shared by several standbys can strand another consumer.","Monitor and change archive_cleanup_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":["Running destructive cleanup against an archive shared by other standbys or restore jobs.","Misreading %r as the last replayed file; it is the earliest file needed to keep recovery restartable.","Using a command that is not idempotent when a restartpoint repeats or an archive file is already absent.","Assuming a reload executes the command immediately; it runs at recovery restartpoints.","Letting shell quoting or an unexpected archive path turn cleanup into deletion outside the intended archive."],"references":[{"title":"PostgreSQL 19 Beta 4: archive_cleanup_command","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-ARCHIVE-CLEANUP-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","restore_command","recovery_end_command"],"summary":"archive_cleanup_command sets the shell command that will be executed at every restart point. 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:30.747539+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":"archive_cleanup_command","last_version":"20","max_val":"","min_val":"","name":"archive_cleanup_command","position":8,"present_in":["12","13","14","15","16","17","18","19","20"],"short_desc":"This optional parameter specifies a shell command that will be executed at every restartpoint.","short_desc_zh":"","source_rev":"english-manuals:231ef4685c1eae0cb69c5359c3bbb5a5445d5d2e8a7b9c012afe2c635dfde229","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"archive_cleanup_command","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"archive_cleanup_command","SourceRevision":"english-manuals:231ef4685c1eae0cb69c5359c3bbb5a5445d5d2e8a7b9c012afe2c635dfde229","Facts":{"boot_val":"","category":"Write-Ahead Log / Archive Recovery","context":"sighup","description":"This optional parameter specifies a shell command that will be executed at every restartpoint. The purpose of archive_cleanup_command is to provide a mechanism for cleaning up old archived WAL files that are no longer needed by the standby server. 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, and so all files earlier than %r may be safely removed. This information can be used to truncate the archive to just the minimum required to support restart from the current restore. The pg_archivecleanup module is often used in archive_cleanup_command for single-standby configurations, for example: archive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r' Note however that if multiple standby servers are restoring from the same archive directory, you will need to ensure that you do not delete WAL files until they are no longer needed by any of the servers. archive_cleanup_command would typically be used in a warm-standby configuration (see Section 26.2). Write %% to embed an actual % character in the command. If the command returns a nonzero exit status then a warning log message will be written. An exception is that if the command was terminated by a signal or an error by the shell (such as command not found), a fatal error will be raised. This parameter can only be set in the postgresql.conf file or on the server command line.","doc":{"anchor":"GUC-ARCHIVE-CLEANUP-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":"archive_cleanup_command","short_desc":"Sets the shell command that will be executed at every restart point.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-ARCHIVE-CLEANUP-COMMAND","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"archive_cleanup_command","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"archive_cleanup_command","Summary":"","BodyHTML":"\u003cp\u003e这个可选参数指定了一个 shell 命令，它将在每一个重启点被执行。\u003ccode\u003earchive_cleanup_command\u003c/code\u003e的目的是提供一种清除不再被备库需要的旧的已归档 WAL 文件的机制。任何\u003ccode\u003e%r\u003c/code\u003e会被替换为包含最后一个可用重启点的文件的名称。这是为使恢复可重新启动而必须\u003cspan\u003e\u003cem\u003e保留\u003c/em\u003e\u003c/span\u003e的最早文件，并且因此比\u003ccode\u003e%r\u003c/code\u003e更早的所有文件可以被安全地移除。这个信息可以被用来把归档截断为支持从当前恢复重启所需的最小值。对于单一备库配置，\u003ca href=\"/docs/18/pgarchivecleanup.html\" title=\"pg_archivecleanup\" rel=\"nofollow\"\u003e\u003cspan\u003e\u003cspan\u003epg_archivecleanup\u003c/span\u003e\u003c/span\u003e\u003c/a\u003e模块常常被用在\u003ccode\u003earchive_cleanup_command\u003c/code\u003e中，例如：\u003c/p\u003e\u003cpre\u003earchive_cleanup_command = \u0026#39;pg_archivecleanup /mnt/server/archivedir %r\u0026#39;\n\u003c/pre\u003e\u003cp\u003e但是注意，如果多个备库正在从同一个归档目录中恢复，你将需要保证只有当所有服务器都不再需要这些 WAL 文件时才会删除它们。\u003ccode\u003earchive_cleanup_command\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如果该命令返回一个非零退出状态，则将会写出一个警告日志消息。一个例外是如果该命令被一个信号或者一个 shell 错误（例如命令未找到）终止，则会抛出一个致命错误。\u003c/p\u003e\u003cp\u003e这个参数只能在\u003ccode\u003epostgresql.conf\u003c/code\u003e文件中或通过服务器命令行进行设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"e3d234e2e90189af0023a0f21b2fcec775762b8f32294e67b25ed7d2f71986e4","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e这个可选参数指定了一个 shell 命令，它将在每一个重启点被执行。\u003ccode class=\"varname\"\u003earchive_cleanup_command\u003c/code\u003e的目的是提供一种清除不再被备库需要的旧的已归档 WAL 文件的机制。任何\u003ccode class=\"literal\"\u003e%r\u003c/code\u003e会被替换为包含最后一个可用重启点的文件的名称。这是为使恢复可重新启动而必须\u003cspan class=\"emphasis\"\u003e\u003cem\u003e保留\u003c/em\u003e\u003c/span\u003e的最早文件，并且因此比\u003ccode class=\"literal\"\u003e%r\u003c/code\u003e更早的所有文件可以被安全地移除。这个信息可以被用来把归档截断为支持从当前恢复重启所需的最小值。对于单一备库配置，\u003ca href=\"/docs/18/pgarchivecleanup.html\" title=\"pg_archivecleanup\"\u003e\u003cspan class=\"refentrytitle\"\u003e\u003cspan class=\"application\"\u003epg_archivecleanup\u003c/span\u003e\u003c/span\u003e\u003c/a\u003e模块常常被用在\u003ccode class=\"varname\"\u003earchive_cleanup_command\u003c/code\u003e中，例如：\u003c/p\u003e\u003cpre\u003earchive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'\n\u003c/pre\u003e\u003cp\u003e但是注意，如果多个备库正在从同一个归档目录中恢复，你将需要保证只有当所有服务器都不再需要这些 WAL 文件时才会删除它们。\u003ccode class=\"varname\"\u003earchive_cleanup_command\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如果该命令返回一个非零退出状态，则将会写出一个警告日志消息。一个例外是如果该命令被一个信号或者一个 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}