{"Entry":{"collection":"guc","key":"max_slot_wal_keep_size","name":"max_slot_wal_keep_size","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Replication / Sending Servers","category_zh":"","changed_in":["18"],"changes":[{"documentation_changed":false,"fields":{},"from":"12","status":"added","to":"13"},{"documentation_changed":false,"fields":{"extra_desc":{"from":"Replication slots will be marked as failed, and segments released for deletion or recycling, if this much space is occupied by WAL on disk.","to":"Replication slots will be marked as failed, and segments released for deletion or recycling, if this much space is occupied by WAL on disk. -1 means no maximum."}},"from":"17","status":"changed","to":"18"}],"content_hash":"915077bae376dcfa8d96da649dda942eab402f02b4aef9e6b86b8b57e2bb53a2","context":"","default_changed_in":[],"default_history":[{"from":"13","to":"19","value":"-1 MB"}],"editorial":{"advice":{"olap":"Allow for expected bulk-WAL bursts, but do not make the cap effectively unlimited. Schedule consumers and batch jobs together, verify archive availability, and pause or repair a lagging consumer before it consumes the disk budget.","oltp":"Set a finite limit within the pg_wal emergency budget and derive it from peak WAL generation times the maximum supported repair window. Alert while safe_wal_size is still positive, and document the resynchronization path for every consumer.","small":"Use a stricter finite cap and a short repair objective. On a small volume, preserving the primary is usually more important than keeping a stale replica or CDC slot resumable forever."},"mechanism":["At checkpoint time PostgreSQL compares a slot's restart_lsn with the current WAL position. With the default -1 there is no parameter-imposed maximum; a stalled consumer can therefore retain enough WAL to fill pg_wal.","With a finite limit, required segments can be released when a slot falls too far behind. The slot can move through unreserved to lost status, and its consumer may need a new base backup or logical resynchronization. The cap protects server storage by sacrificing the guarantee that an indefinitely lagging slot remains usable.","Enforcement is checkpoint-based, so it is neither instantaneous nor an exact byte ceiling. pg_replication_slots exposes restart_lsn, wal_status, invalidation_reason, and safe_wal_size; these are the operational signals needed before the slot reaches the limit."],"pitfalls":["Leaving -1 and assuming a stalled slot cannot fill the disk.","Treating the finite value as an instantaneous hard ceiling despite checkpoint-based enforcement.","Setting it too low and invalidating a healthy consumer during a planned bulk load.","Assuming a consumer can always resume after its required WAL has been removed.","Confusing this per-slot retention cap with the wal_keep_size retention floor."],"references":[{"title":"PostgreSQL 19 Beta 4: max_slot_wal_keep_size","url":"https://www.postgresql.org/docs/19/runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE"},{"title":"PostgreSQL 18: Replication Slots","url":"https://www.postgresql.org/docs/18/warm-standby.html#STREAMING-REPLICATION-SLOTS"},{"title":"PostgreSQL 18: pg_replication_slots","url":"https://www.postgresql.org/docs/18/view-pg-replication-slots.html"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["max_replication_slots","wal_keep_size","max_wal_size","idle_replication_slot_timeout","checkpoint_timeout","archive_mode"],"summary":"A reloadable checkpoint-time limit on how much WAL replication slots may retain."},"enumvals":[],"first_version":"13","group":"Replication","group_slug":"replication","imported_at":"2026-09-27T17:57:31.739619+08:00","intro_commit":{"authored_at":"2020-04-07T18:35:00-04:00","discussion":["https://postgr.es/m/20170228.122736.123383594.horiguchi.kyotaro@lab.ntt.co.jp"],"hash":"c6550776394e25c1620bc8258427c8f1d448080d","subject":"Allow users to limit storage reserved by replication slots","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=c6550776394e25c1620bc8258427c8f1d448080d"},"key":"max_slot_wal_keep_size","last_version":"20","max_val":"","min_val":"","name":"max_slot_wal_keep_size","position":283,"present_in":["13","14","15","16","17","18","19","20"],"short_desc":"Specify the maximum size of WAL files that replication slots are allowed to retain in the pg_wal directory at checkpoint time.","short_desc_zh":"","source_rev":"english-manuals:794ce79275b20862eb6fa6f0b27ace2dda59d3e96e964fa66fc6f7636b0a01f7","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"max_slot_wal_keep_size","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"max_slot_wal_keep_size","SourceRevision":"english-manuals:794ce79275b20862eb6fa6f0b27ace2dda59d3e96e964fa66fc6f7636b0a01f7","Facts":{"boot_val":"-1","category":"Replication / Sending Servers","context":"sighup","description":"Specify the maximum size of WAL files that replication slots are allowed to retain in the pg_wal directory at checkpoint time. If max_slot_wal_keep_size is -1 (the default), replication slots may retain an unlimited amount of WAL files. Otherwise, if restart_lsn of a replication slot falls behind the current LSN by more than the given size, the standby using the slot may no longer be able to continue replication due to removal of required WAL files. You can see the WAL availability of replication slots in pg_replication_slots. If this value is specified without units, it is taken as megabytes. This parameter can only be set in the postgresql.conf file or on the server command line.","doc":{"anchor":"GUC-MAX-SLOT-WAL-KEEP-SIZE","file":"runtime-config-replication.html","lang":"en","sha256":"c78480a202f8579e2655e080060afe4859c9eb26a16318fb9099dabb178fb32d","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"Replication slots will be marked as failed, and segments released for deletion or recycling, if this much space is occupied by WAL on disk. -1 means no maximum.","lang":"en","max_val":"2147483647","metadata_version":"18","min_val":"-1","name":"max_slot_wal_keep_size","short_desc":"Sets the maximum WAL size that can be reserved by replication slots.","source":"pg-settings-source-snapshot","unit":"MB","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-MAX-SLOT-WAL-KEEP-SIZE","file":"runtime-config-replication.html","lang":"en","sha256":"c78480a202f8579e2655e080060afe4859c9eb26a16318fb9099dabb178fb32d","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"max_slot_wal_keep_size","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"max_slot_wal_keep_size","Summary":"","BodyHTML":"\u003cp\u003e指定检查点时\u003ca href=\"/docs/18/warm-standby.html#STREAMING-REPLICATION-SLOTS\" rel=\"nofollow\"\u003e复制槽\u003c/a\u003e允许在 \u003ccode\u003epg_wal\u003c/code\u003e 目录中保留的 WAL 文件最大总量。如果 \u003ccode\u003emax_slot_wal_keep_size\u003c/code\u003e 为 -1（默认值），复制槽可以保留无限量的 WAL 文件。否则，如果复制槽的 restart_lsn 落后当前 LSN 超过给定大小，使用该槽的备库可能会因为所需 WAL 文件被移除而无法继续复制。可以在 \u003ca href=\"/docs/18/view-pg-replication-slots.html\" rel=\"nofollow\"\u003epg_replication_slots\u003c/a\u003e 中查看复制槽的 WAL 可用情况。如果指定值时没有单位，则按兆字节计算。此参数只能在 \u003ccode\u003epostgresql.conf\u003c/code\u003e 文件中或服务器命令行上设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"a4b4cdd4460c1cb20ec918ceead8140922f09dc9b8b1ef02e35018aa5ca235d8","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e指定检查点时\u003ca href=\"/docs/18/warm-standby.html#STREAMING-REPLICATION-SLOTS\" title=\"26.2.6. 复制槽\"\u003e复制槽\u003c/a\u003e允许在 \u003ccode class=\"filename\"\u003epg_wal\u003c/code\u003e 目录中保留的 WAL 文件最大总量。如果 \u003ccode class=\"varname\"\u003emax_slot_wal_keep_size\u003c/code\u003e 为 -1（默认值），复制槽可以保留无限量的 WAL 文件。否则，如果复制槽的 restart_lsn 落后当前 LSN 超过给定大小，使用该槽的备库可能会因为所需 WAL 文件被移除而无法继续复制。可以在 \u003ca href=\"/docs/18/view-pg-replication-slots.html\" title=\"53.20. pg_replication_slots\"\u003epg_replication_slots\u003c/a\u003e 中查看复制槽的 WAL 可用情况。如果指定值时没有单位，则按兆字节计算。此参数只能在 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 文件中或服务器命令行上设置。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["13","14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}