PostgreSQL Checkpoint and max_wal_size Tuning
Diagnoses requested checkpoints and write bursts with version-appropriate statistics, then balances WAL capacity and checkpoint pacing.
Operational Safety & Risk Notice
This runbook contains operational intervention steps; several are write-impacting (KILL, terminate, DROP, RESIZE). Verify in a staging environment first, and apply sequentially in production with verification.
1. Symptom & Signals
- M10 zorunlu checkpoint oranı > %10; logda sık `checkpoints are occurring too frequently` uyarısı veya yazma gecikmesi sıçramaları görülür.
2. Business & Technical Impact
Checkpoint sırasında yoğun I/O diğer sorguların gecikmesini artırır. `max_wal_size` çok düşükse sık checkpoint, çok yüksekse daha uzun crash recovery ve disk rezervi ihtiyacı doğurabilir.
3. Diagnosis & Root-Cause Analysis
-- PostgreSQL 16 ve öncesi:
SELECT checkpoints_timed, checkpoints_req,
checkpoint_write_time, checkpoint_sync_time, stats_reset
FROM pg_stat_bgwriter;
-- PostgreSQL 17+ (ayrı oturumda / kendi sürümünüzde):
SELECT num_timed, num_requested, write_time, sync_time, stats_reset
FROM pg_stat_checkpointer;SELECT name, setting, unit, pending_restart
FROM pg_settings
WHERE name IN ('max_wal_size', 'min_wal_size', 'checkpoint_timeout',
'checkpoint_completion_target', 'log_checkpoints');`log_checkpoints` varsayılanı sürüme göre değişebilir; disk alanı artışını önce ölçün.
4. Remediation & Action Plan
ALTER SYSTEM SET max_wal_size = '4GB';
ALTER SYSTEM SET checkpoint_completion_target = 0.9;
SELECT pg_reload_conf();5. Verification & Health Checks
- En az bir saatlik yükte zorunlu checkpoint artış oranı düşer, yazma gecikmesi iyileşir; WAL diski güvenli boş alan korur.
- `pg_settings` ile yeni ayarların uygulandığını doğrulayın; yalnızca komutun başarılı dönmesine güvenmeyin.
6. Rollback & Contingency Plan
- Önceki değerler kaydedilmişse `ALTER SYSTEM SET max_wal_size = '<onceki_deger>';` ve `checkpoint_completion_target` için aynı yöntemle dönün, ardından `SELECT pg_reload_conf();`.
- Disk doluluğunda birikmiş WAL'ı elle silmeyin; yeniden düşük sınıra dönmek anında alan boşaltmaz.