{"Entry":{"collection":"guc","key":"checkpoint_completion_target","name":"checkpoint_completion_target","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Write-Ahead Log / Checkpoints","category_zh":"","changed_in":["14"],"changes":[{"documentation_changed":false,"fields":{},"from":"8.2","status":"added","to":"8.3"},{"documentation_changed":true,"fields":{},"from":"8.4","status":"changed","to":"9.0"},{"documentation_changed":true,"fields":{"boot_val":{"from":"0.5","to":"0.9"}},"from":"13","status":"changed","to":"14"}],"content_hash":"2e697732dd10bac7cb58c5df7734c9d486162c549aecf4b9901be7ca8552dfc4","context":"","default_changed_in":["14"],"default_history":[{"from":"9.0","to":"13","value":"0.5"},{"from":"14","to":"19","value":"0.9"}],"editorial":{"advice":{"olap":"For bursty bulk workloads, raising max_wal_size is often the first lever because a volume-triggered checkpoint shortens the pacing window. Keep this target high enough to smooth I/O but not so high that final sync work bunches at the end.","oltp":"Start with the version default of 0.9 and optimize only with latency and pg_stat_checkpointer evidence. A value of 0.95 can smooth writes further, but verify that checkpoints consistently finish before the next trigger.","small":"Use 0.9 unless measurements show a clear benefit. Small or slow storage is especially vulnerable to an end-of-checkpoint sync spike when the target leaves insufficient margin."},"mechanism":["PostgreSQL throttles checkpoint writes so that they are expected to finish after this fraction of the available interval. The available interval ends at the next timed checkpoint or sooner if WAL volume forces a checkpoint, so this is a pacing target rather than a fixed duration.","A larger fraction generally smooths checkpoint I/O over more time. A smaller fraction finishes writes faster, producing a higher I/O rate followed by an idle gap; the official documentation discourages reducing it for that reason.","Values too close to 1 leave little room for final synchronization and other checkpoint work. PostgreSQL's historical default change from 0.5 to 0.9 is material when comparing otherwise identical configurations across major versions."],"pitfalls":["Interpreting the value as seconds rather than a fraction.","Assuming a lower value reduces total I/O instead of concentrating it.","Setting 1.0 and leaving no margin for checkpoint completion overhead.","Ignoring early volume-triggered checkpoints from max_wal_size.","Overlooking the default change at PostgreSQL 14."],"references":[{"title":"PostgreSQL 19 Beta 4: checkpoint_completion_target","url":"https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-CHECKPOINT-COMPLETION-TARGET"},{"title":"PostgreSQL 18: WAL Configuration","url":"https://www.postgresql.org/docs/18/wal-configuration.html"},{"title":"PostgreSQL 18: pg_stat_checkpointer","url":"https://www.postgresql.org/docs/18/monitoring-stats.html#MONITORING-PG-STAT-CHECKPOINTER-VIEW"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["checkpoint_timeout","max_wal_size","checkpoint_flush_after","checkpoint_warning","shared_buffers"],"summary":"checkpoint_completion_target — Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval. Observed in PG9.0–19 Beta 4; its last measured boot default is 0.9 in PG19 Beta 4, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"8.3","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:30.919597+08:00","intro_commit":{},"key":"checkpoint_completion_target","last_version":"20","max_val":"","min_val":"","name":"checkpoint_completion_target","position":55,"present_in":["8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"Specifies the target of checkpoint completion, as a fraction of total time between checkpoints.","short_desc_zh":"","source_rev":"english-manuals:49ee5e40941f3ad32ba44407279e2f792fce3529bed2d7ab62da0f2f2e815544","unit":"","vartype":"real"}},"Definition":{"Collection":"guc","Key":"checkpoint_completion_target","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"checkpoint_completion_target","SourceRevision":"english-manuals:49ee5e40941f3ad32ba44407279e2f792fce3529bed2d7ab62da0f2f2e815544","Facts":{"boot_val":"0.9","category":"Write-Ahead Log / Checkpoints","context":"sighup","description":"Specifies the target of checkpoint completion, as a fraction of total time between checkpoints. The default is 0.9, which spreads the checkpoint across almost all of the available interval, providing fairly consistent I/O load while also leaving some time for checkpoint completion overhead. Reducing this parameter is not recommended because it causes the checkpoint to complete faster. This results in a higher rate of I/O during the checkpoint followed by a period of less I/O between the checkpoint completion and the next scheduled checkpoint. This parameter can only be set in the postgresql.conf file or on the server command line.","doc":{"anchor":"GUC-CHECKPOINT-COMPLETION-TARGET","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"1","metadata_version":"18","min_val":"0","name":"checkpoint_completion_target","short_desc":"Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval.","source":"pg-settings-source-snapshot","unit":null,"vartype":"real"},"ManualEvidence":{"doc":{"anchor":"GUC-CHECKPOINT-COMPLETION-TARGET","file":"runtime-config-wal.html","lang":"en","sha256":"d2646404a06e8f7ac655204b4f28c049ae8f3fd4f2272db080fcefa2c4af0763","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"checkpoint_completion_target","SourceDatabase":"center","Version":"18","Locale":"en","Title":"checkpoint_completion_target","Summary":"Specifies the target of checkpoint completion, as a fraction of total time between checkpoints. The default is 0.9, which spreads the checkpoint across almost all of the available interval, providing fairly consistent I/O load while also leaving some time for checkpoint completion overhead. Reducing this parameter is not recommended because it causes the checkpoint to complete faster. This results in a higher rate of I/O during the checkpoint followed by a period of less I/O between the checkpoint completion and the next scheduled checkpoint. This parameter can only be set in the postgresql.conf file or on the server command line.","BodyHTML":"\u003cp\u003eSpecifies the target of checkpoint completion, as a fraction of total time between checkpoints. The default is 0.9, which spreads the checkpoint across almost all of the available interval, providing fairly consistent I/O load while also leaving some time for checkpoint completion overhead. Reducing this parameter is not recommended because it causes the checkpoint to complete faster. This results in a higher rate of I/O during the checkpoint followed by a period of less I/O between the checkpoint completion and the next scheduled checkpoint. This parameter can only be set in the postgresql.conf file or on the server command line.\u003c/p\u003e","SourceRevision":"english-manuals:49ee5e40941f3ad32ba44407279e2f792fce3529bed2d7ab62da0f2f2e815544","ContentHash":"79194f68a59bb8746d9316099cb67190cfef754fd5138ac802711c5fb8a252bc","Payload":{"description":"Specifies the target of checkpoint completion, as a fraction of total time between checkpoints. The default is 0.9, which spreads the checkpoint across almost all of the available interval, providing fairly consistent I/O load while also leaving some time for checkpoint completion overhead. Reducing this parameter is not recommended because it causes the checkpoint to complete faster. This results in a higher rate of I/O during the checkpoint followed by a period of less I/O between the checkpoint completion and the next scheduled checkpoint. This parameter can only be set in the postgresql.conf file or on the server command line."}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["10","11","12","13","14","15","16","17","18","19","20","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}