{"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"}],"derived_content_hash":"7cc5bab85bcf60ed59144772b4da6c4ab82ebcd032c22bca235eeb51cbb4d005","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"],"repair_provenance":{"original_source_revision":"english-manuals:231ef4685c1eae0cb69c5359c3bbb5a5445d5d2e8a7b9c012afe2c635dfde229","receipt_sha256":"d3f996567ea58240b5937c61d67e8628beabc09546b3581adca55cdba52a2e92","repair":"wiki-repair-20261023"},"short_desc":"This optional parameter specifies a shell command that will be executed at every restartpoint.","short_desc_zh":"","source_rev":"wiki-repair-20261023:64d24c5b4a9448d76c152dda7da629519a2898bc7df183d1b9717180d49c1a8a","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"archive_cleanup_command","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"archive_cleanup_command","SourceRevision":"wiki-repair-20261023:64d24c5b4a9448d76c152dda7da629519a2898bc7df183d1b9717180d49c1a8a","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.","description_zh":"这个可选参数指定了一个 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 通常被用于一种温备配置（见第 26.2 节）中。要在该命令中嵌入一个真正的% 字符，需要写成%%。 如果该命令返回一个非零退出状态，则将会写出一个警告日志消息。一个例外是如果该命令被一个信号或者一个 shell 错误（例如命令未找到）终止，则会抛出一个致命错误。 这个参数只能在 postgresql.conf 文件中或通过服务器命令行进行设置。","description_zh_html":"\u003cp\u003e\n        这个可选参数指定了一个 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 class=\"xref\" href=\"/zh/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 中，例如：\n\u003c/p\u003e\u003cpre class=\"programlisting\"\u003earchive_cleanup_command = 'pg_archivecleanup /mnt/server/archivedir %r'\u003c/pre\u003e\u003cp\u003e\n        但是注意，如果多个备库正在从同一个归档目录中恢复，你将需要保证只有当所有服务器都不再需要这些 WAL 文件时才会删除它们。\u003ccode class=\"varname\"\u003earchive_cleanup_command\u003c/code\u003e 通常被用于一种温备配置（见\u003ca class=\"xref\" href=\"/zh/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。\n       \u003c/p\u003e\u003cp\u003e\n        如果该命令返回一个非零退出状态，则将会写出一个警告日志消息。一个例外是如果该命令被一个信号或者一个 shell 错误（例如命令未找到）终止，则会抛出一个致命错误。\n       \u003c/p\u003e\u003cp\u003e\n        这个参数只能在 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 文件中或通过服务器命令行进行设置。\n       \u003c/p\u003e","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","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-wal.html","sha256":"94cdacb1171b4c528492ca0aec6aafa48a2c758276225fe0dbfe5b12452d4930"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"string","zh_from":"same-version-pgdoc"},"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":"center","Version":"18","Locale":"en","Title":"archive_cleanup_command","Summary":"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.","BodyHTML":"\u003cp\u003eThis 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 = \u0026#39;pg_archivecleanup /mnt/server/archivedir %r\u0026#39; 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.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:64d24c5b4a9448d76c152dda7da629519a2898bc7df183d1b9717180d49c1a8a","ContentHash":"2ad960eef099e46208a27f5ebb8625c52e189e8287edd1d61703e58ddb464205","Payload":{"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."}},"RequestedLocale":"en","Fallback":false,"Versions":["12","13","14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}