{"Entry":{"collection":"guc","key":"checkpoint_flush_after","name":"checkpoint_flush_after","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Checkpoints","category_zh":"","changed_in":["18"],"changes":[{"documentation_changed":false,"fields":{},"from":"9.5","status":"added","to":"9.6"},{"documentation_changed":true,"fields":{},"from":"11","status":"changed","to":"12"},{"documentation_changed":false,"fields":{"extra_desc":{"from":null,"to":"0 disables forced writeback."}},"from":"17","status":"changed","to":"18"}],"content_hash":"3f1795d4047e0c6bc4de3d40203f203390ed392f5975c0556577183415e475d8","context":"","default_changed_in":[],"default_history":[{"from":"9.6","to":"19","value":"256 KiB (32 × 8kB)"}],"editorial":{"advice":{"olap":"Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.","oltp":"Establish durability and recovery objectives first, then tune checkpoint_flush_after from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.","small":"Start from safe defaults and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O."},"mechanism":["Number of pages after which previously performed writes are flushed to disk. A configuration reload applies a new value; existing work already in flight is not retroactively changed.","Checkpoint writes are periodically handed to the operating system for writeback after this much data, smoothing the final sync and reducing dirty-cache bursts. Zero disables these intermediate flush requests; the best value is operating-system and storage dependent.","Monitor and change checkpoint_flush_after together with checkpoint_warning, checkpoint_timeout, checkpoint_completion_target. 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":["Treating the raw value as bytes even though an unqualified value is measured in database blocks.","Setting it too small and increasing writeback calls and I/O fragmentation.","Setting it too large and losing the intended smoothing before the checkpoint sync phase.","Confusing writeback hints with a durability guarantee; fsync and wal_sync_method still define persistence.","Copying a value across operating systems or filesystems without measuring checkpoint latency and dirty-page behavior."],"references":[{"title":"PostgreSQL 19 Beta 4: checkpoint_flush_after","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-CHECKPOINT-FLUSH-AFTER"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["checkpoint_warning","checkpoint_timeout","checkpoint_completion_target","max_wal_size","min_wal_size","archive_cleanup_command"],"summary":"checkpoint_flush_after — Number of pages after which previously performed writes are flushed to disk. Observed in PG9.6–19 Beta 4; its last measured boot default is 256 KiB (32 × 8kB) in PG19 Beta 4, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"9.6","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:30.924395+08:00","intro_commit":{"authored_at":"2016-02-19T12:13:05-08:00","discussion":[],"hash":"428b1d6b29ca599c5700d4bc4f4ce4c5880369bf","subject":"Allow to trigger kernel writeback after a configurable number of writes.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=428b1d6b29ca599c5700d4bc4f4ce4c5880369bf"},"key":"checkpoint_flush_after","last_version":"20","max_val":"","min_val":"","name":"checkpoint_flush_after","position":56,"present_in":["9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"Whenever more than this amount of data has been written while performing a checkpoint, attempt to force the OS to issue these writes to the underlying storage.","short_desc_zh":"","source_rev":"english-manuals:657696290c345108d70211dc59e0c9c591cfe93ea2e86fe19d0ce4f62d8f91d1","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"checkpoint_flush_after","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"checkpoint_flush_after","SourceRevision":"english-manuals:657696290c345108d70211dc59e0c9c591cfe93ea2e86fe19d0ce4f62d8f91d1","Facts":{"boot_val":"32","category":"Write-Ahead Log / Checkpoints","context":"sighup","description":"Whenever more than this amount of data has been written while performing a checkpoint, attempt to force the OS to issue these writes to the underlying storage. Doing so will limit the amount of dirty data in the kernel's page cache, reducing the likelihood of stalls when an fsync is issued at the end of the checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads that are bigger than shared_buffers, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. If this value is specified without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB. The valid range is between 0, which disables forced writeback, and 2MB. The default is 256kB on Linux, 0 elsewhere. (If BLCKSZ is not 8kB, the default and maximum values scale proportionally to it.) This parameter can only be set in the postgresql.conf file or on the server command line.","doc":{"anchor":"GUC-CHECKPOINT-FLUSH-AFTER","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"0 disables forced writeback.","lang":"en","max_val":"256","metadata_version":"18","min_val":"0","name":"checkpoint_flush_after","short_desc":"Number of pages after which previously performed writes are flushed to disk.","source":"pg-settings-source-snapshot","unit":"8kB","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-CHECKPOINT-FLUSH-AFTER","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"checkpoint_flush_after","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"checkpoint_flush_after","Summary":"","BodyHTML":"\u003cp\u003e当执行检查点时写入的数据量超过此数量时，就尝试强制 OS 把这些写发送到底层存储。这样做将会限制内核页面高速缓存中的脏数据数量，降低在检查点末尾发出\u003ccode\u003efsync\u003c/code\u003e或者 OS 在后台大批量写回数据时被卡住的可能性。这通常能显著降低事务延迟，但是也有一些情况（特别是负载超过\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-SHARED-BUFFERS\" rel=\"nofollow\"\u003eshared_buffers\u003c/a\u003e但小于 OS 页面高速缓存）的性能会降低。这种设置可能会在某些平台上没有效果。如果指定值时没有单位，则以块为单位，即为\u003ccode\u003eBLCKSZ\u003c/code\u003e 字节，通常为8kB。合法的范围在\u003ccode\u003e0\u003c/code\u003e（禁用强制写回）和\u003ccode\u003e2MB\u003c/code\u003e之间。Linux 上的默认值是\u003ccode\u003e256kB\u003c/code\u003e，其他平台上是\u003ccode\u003e0\u003c/code\u003e（如果\u003ccode\u003eBLCKSZ\u003c/code\u003e不是8kB，则默认值和最大值会按比例缩放到它）。这个参数只能在\u003ccode\u003epostgresql.conf\u003c/code\u003e文件中或者服务器命令行上设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"4b865c856a793d38377b751c0dcdf2c1d1712a9c0aa8b11a55e0352c9ed89e97","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e当执行检查点时写入的数据量超过此数量时，就尝试强制 OS 把这些写发送到底层存储。这样做将会限制内核页面高速缓存中的脏数据数量，降低在检查点末尾发出\u003ccode class=\"function\"\u003efsync\u003c/code\u003e或者 OS 在后台大批量写回数据时被卡住的可能性。这通常能显著降低事务延迟，但是也有一些情况（特别是负载超过\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-SHARED-BUFFERS\"\u003eshared_buffers\u003c/a\u003e但小于 OS 页面高速缓存）的性能会降低。这种设置可能会在某些平台上没有效果。如果指定值时没有单位，则以块为单位，即为\u003ccode class=\"symbol\"\u003eBLCKSZ\u003c/code\u003e 字节，通常为8kB。合法的范围在\u003ccode class=\"literal\"\u003e0\u003c/code\u003e（禁用强制写回）和\u003ccode class=\"literal\"\u003e2MB\u003c/code\u003e之间。Linux 上的默认值是\u003ccode class=\"literal\"\u003e256kB\u003c/code\u003e，其他平台上是\u003ccode class=\"literal\"\u003e0\u003c/code\u003e（如果\u003ccode class=\"symbol\"\u003eBLCKSZ\u003c/code\u003e不是8kB，则默认值和最大值会按比例缩放到它）。这个参数只能在\u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e文件中或者服务器命令行上设置。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20","9.6"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}