WAL and checkpoint tuning

WAL-related recommendations are driven by observed WAL generation rate from performance samples, checkpoint statistics, replica lag, and replication-slot retention state.

max_wal_size

The recommendation compares observed WAL generation against checkpoint behavior and the current max_wal_size. It accounts for PostgreSQL checkpoint timing behavior and leaves headroom for bursts, but the exact sizing formula is intentionally not published.

The important distinction is whether requested checkpoints appear to be caused by application WAL pressure or by administrative/provider activity. If WAL pressure is not evident, pocketPG shows an informational insight rather than recommending a larger WAL budget.

min_wal_size

The companion min_wal_size recommendation is kept proportional to max_wal_size so PostgreSQL can recycle WAL segments efficiently during bursty workloads.

wal_buffers

wal_buffers is only nudged when real WAL pressure is visible. pocketPG does not recommend changing it just because the parameter exists. The recommendation is meant for systems that are already showing meaningful WAL write pressure or checkpoint pressure, where a small increase gives the WAL writer more burst headroom.

wal_keep_size

wal_keep_size is treated as a replica safety cushion, not a default tuning knob. pocketPG only raises it when:

• streaming replicas are present
• replica lag is visible
• and physical replication slots are not already retaining WAL for those replicas

That keeps the recommendation focused on real retention risk instead of encouraging unnecessary WAL hoarding.

max_slot_wal_keep_size

max_slot_wal_keep_size is a guardrail for slot-retained WAL. pocketPG only recommends it when replication slots exist and unlimited slot retention (-1) is risky, especially when:

• inactive slots are present, or
• slot-retained WAL is already materially large

The goal is simple: stalled or abandoned slots should not be able to grow WAL forever without a cap.

wal_compression

wal_compression is recommended when the evidence suggests WAL volume is large enough for compression to matter. The recommendation is framed as a tradeoff: lower WAL volume in exchange for additional CPU work.

Checkpoint diagnosis

The evidence panel classifies the checkpoint pattern without exposing the internal thresholds:

Pattern	Meaning
WAL pressure	Application write volume is likely forcing checkpoints sooner than desired.
Administrative/provider activity	Checkpoints are likely caused by backup, maintenance, or managed-provider housekeeping.
Mixed or inconclusive	Monitor longer before changing WAL settings.