# checkpoint_completion_target

> checkpoint_completion_target — Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.9 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.
---

> [!NOTE]
> **Fact — official short description:** “Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `real` | Upstream pg_settings type |
| Context | `sighup` | Takes effect after configuration reload |
| Unit | — | Raw unit |
| Range | `0` – `1` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Write-Ahead Log / Checkpoints | Upstream classification |
| Latest boot value | `0.9` | 0.9 |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.0 (research boundary) |
| Present in | PG9.0–19 Beta 3 |
| Removed in | No |
| Introduction commit | Not asserted: predates the PG9.0 research boundary |
| Commit date | — |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.0–13 | `0.5` | — | 0.5 |
| PG14–19 Beta 3 | `0.9` | — | 0.9 |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#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.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| 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. |
| 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. |
| Small nodes | 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. |
{.full-width}

## Pigsty {#pigsty}

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

| Template | Effective value | Versus upstream boot | Source expression |
| --- | --- | --- | --- |
| OLTP | `0.95` | different | `0.95` |
| OLAP | `0.95` | different | `0.95` |
| CRIT | `0.95` | different | `0.95` |
| TINY | `0.95` | different | `0.95` |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0.95 (dcs); OLAP: PG9.0–19 Beta 3 = 0.95 (dcs); CRIT: PG9.0–19 Beta 3 = 0.95 (dcs); TINY: PG9.0–19 Beta 3 = 0.95 (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

## Common pitfalls {#common-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.

## Related parameters {#related-parameters}

[`checkpoint_timeout`](/parameters/checkpoint-timeout/) · [`max_wal_size`](/parameters/max-wal-size/) · [`checkpoint_flush_after`](/parameters/checkpoint-flush-after/) · [`checkpoint_warning`](/parameters/checkpoint-warning/) · [`shared_buffers`](/parameters/shared-buffers/)

## References {#references}

- [PostgreSQL 19 Beta 3 — checkpoint_completion_target](https://www.postgresql.org/docs/19/runtime-config-wal.html#GUC-CHECKPOINT-COMPLETION-TARGET)
- [PostgreSQL 18: WAL Configuration](https://www.postgresql.org/docs/18/wal-configuration.html)
- [PostgreSQL 18: pg_stat_checkpointer](https://www.postgresql.org/docs/18/monitoring-stats.html#MONITORING-PG-STAT-CHECKPOINTER-VIEW)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)