{"Entry":{"collection":"guc","key":"checkpoint_segments","name":"checkpoint_segments","aliases":[],"metadata":{"baseline":true,"boot_human":"3","boot_val":"3","category":"Write-Ahead Log / Checkpoints","category_zh":"","changed_in":[],"changes":[{"documentation_changed":true,"fields":{},"from":"8.1","status":"changed","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.2","status":"changed","to":"8.3"},{"documentation_changed":false,"fields":{},"from":"9.4","status":"removed","to":"9.5"}],"content_hash":"eab2a4dc489146a5ac8f14d26867ca94ca4cd944666c43749727799aebbf68fe","context":"sighup","default_changed_in":[],"default_history":[{"from":"9.0","to":"9.4","value":"3"}],"editorial":{"advice":{"olap":"For an upgrade or analytical estate, inventory every generated configuration before cutover. Map the old control to its successor and compare plans, throughput, WAL, or logging behavior rather than assuming the old numeric value is portable.","oltp":"Do not add this retired name to a current OLTP configuration. Translate its intent to the documented successor, test the migration under connection and write concurrency, and remove stale automation that still emits it.","small":"Delete the obsolete override after recording why it existed. On a small node, prefer the successor's default until measurements justify a new value; an unknown startup parameter can otherwise stop the server."},"mechanism":["PostgreSQL describes checkpoint_segments as follows: “Sets the maximum distance in log segments between automatic WAL checkpoints.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG9.0–9.4; boot_val is the compiled or initialized baseline, not proof of a running cluster's effective setting.","This was the pre-9.5 checkpoint volume control: once accumulated WAL approached the configured number of segments, PostgreSQL requested an automatic checkpoint. PostgreSQL 9.5 replaced it with max_wal_size, whose soft byte-size budget works with checkpoint_timeout and checkpoint_completion_target rather than exposing a segment count.","Read it together with max_wal_size, checkpoint_timeout, checkpoint_completion_target, wal_segment_size. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change."],"pitfalls":["Treating the measured boot_val for checkpoint_segments as proof of the effective value on an initialized or managed cluster.","Applying a change as though it were immediate while pg_settings reports sighup context.","Changing this setting in isolation without checking the linked limits, observability, and rollback path.","Copying the removed name into a modern postgresql.conf instead of migrating to its documented successor."],"references":[{"title":"PostgreSQL 9.4: checkpoint_segments","url":"https://www.postgresql.org/docs/9.4/runtime-config-wal.html#GUC-CHECKPOINT-SEGMENTS"}],"related":["max_wal_size","checkpoint_timeout","checkpoint_completion_target","wal_segment_size","min_wal_size"],"summary":"checkpoint_segments — Sets the maximum distance in log segments between automatic WAL checkpoints. Observed in PG9.0–9.4; its last measured boot default is 3 in PG9.4, with sighup context. It was removed in PG9.5."},"enumvals":[],"first_version":"7.4","group":"Write-Ahead Log","group_slug":"wal","imported_at":"2026-09-27T17:57:30.928346+08:00","intro_commit":{},"key":"checkpoint_segments","last_version":"9.4","max_val":"2147483647","min_val":"1","name":"checkpoint_segments","position":57,"present_in":["7.4","8.0","8.1","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4"],"short_desc":"Maximum number of log file segments between automatic WAL checkpoints (each segment is normally 16 megabytes).","short_desc_zh":"","source_rev":"english-manuals:0055d878121c76bd62e2a69078767304330421389122903a7166637b836427a3","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"checkpoint_segments","SourceDatabase":"center","Version":"9.4","SourceTable":"guc","SourceKey":"checkpoint_segments","SourceRevision":"english-manuals:0055d878121c76bd62e2a69078767304330421389122903a7166637b836427a3","Facts":{"boot_val":"3","category":"Write-Ahead Log / Checkpoints","context":"sighup","description":"Maximum number of log file segments between automatic WAL checkpoints (each segment is normally 16 megabytes). The default is three segments. Increasing this parameter can increase the amount of time needed for crash recovery. This parameter can only be set in the postgresql.conf file or on the server command line.","doc":{"anchor":"GUC-CHECKPOINT-SEGMENTS","file":"runtime-config-wal.html","lang":"en","sha256":"e3bef89d5cb2961390e63540de54bc1db03558bb95208b9e339d04dd79b4cdf0","slug":"9.4"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"2147483647","metadata_version":"9.4","min_val":"1","name":"checkpoint_segments","short_desc":"Sets the maximum distance in log segments between automatic WAL checkpoints.","source":"pg-settings-source-snapshot","unit":"","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-CHECKPOINT-SEGMENTS","file":"runtime-config-wal.html","lang":"en","sha256":"e3bef89d5cb2961390e63540de54bc1db03558bb95208b9e339d04dd79b4cdf0","slug":"9.4"}},"MeasuredEvidence":{"metadata_version":"9.4"}},"Text":{"Collection":"guc","Key":"checkpoint_segments","SourceDatabase":"center","Version":"9.4","Locale":"en","Title":"checkpoint_segments","Summary":"Maximum number of log file segments between automatic WAL checkpoints (each segment is normally 16 megabytes). The default is three segments. Increasing this parameter can increase the amount of time needed for crash recovery. This parameter can only be set in the postgresql.conf file or on the server command line.","BodyHTML":"\u003cp\u003eMaximum number of log file segments between automatic WAL checkpoints (each segment is normally 16 megabytes). The default is three segments. Increasing this parameter can increase the amount of time needed for crash recovery. This parameter can only be set in the postgresql.conf file or on the server command line.\u003c/p\u003e","SourceRevision":"english-manuals:0055d878121c76bd62e2a69078767304330421389122903a7166637b836427a3","ContentHash":"9b96bf1ec13ac834f97f7e9c6f4b7114449ba2594e52d3479be83b4ac6573648","Payload":{"description":"Maximum number of log file segments between automatic WAL checkpoints (each segment is normally 16 megabytes). The default is three segments. Increasing this parameter can increase the amount of time needed for crash recovery. This parameter can only be set in the postgresql.conf file or on the server command line."}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["7.4","8.0","8.1","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}