recovery_prefetch

recovery_prefetch prefetches referenced blocks during recovery. It is a sighup setting present in PG15–18; the latest recorded boot default is try.

Note

Fact — official short description: “Prefetch referenced blocks during recovery.”

Identity

Type , Valueenum: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Valueoff, on, try: — for non-enum types
Category , ValueWrite-Ahead Log / Recovery: Upstream classification
Latest boot value , Valuetry: try

Lifecycle

Fact	Value
First observed	PG15
Present in	PG15–19 Beta 3
Removed in	No
Introduction commit	`1d257577e08d` — Optionally prefetch referenced data in recovery.
Commit date	2021-04-08
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG15–19 Beta 3	`try`	—	try

How it works

Prefetch referenced blocks during recovery. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

During recovery, PostgreSQL can issue read-ahead advice for blocks identified by WAL before replay needs them. try enables it only when the operating system supports the required advice; wal_decode_buffer_size and maintenance_io_concurrency bound how far and how much it can prefetch.

Monitor and change recovery_prefetch together with wal_decode_buffer_size, maintenance_io_concurrency, effective_io_concurrency. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
OLTP	Tune recovery_prefetch with recovery/standby catch-up benchmarks on production-like storage while observing replay I/O wait, cache behavior, and maintenance_io_concurrency. Keep the default without measured benefit.
OLAP	Large data with slow random reads may benefit more, but excess prefetch competes with query I/O and cache. Test crash recovery and a query-serving standby separately.
Small nodes	The default is usually sufficient. Do not spend scarce memory or I/O queue depth on a larger look-ahead window unless a recovery-time objective is demonstrably missed.

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	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG15–19 Beta 3 unmodified; OLAP: PG15–19 Beta 3 unmodified; CRIT: PG15–19 Beta 3 unmodified; TINY: PG15–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Assuming try always enables prefetch even when the operating system lacks the required read-ahead advice.
Increasing look-ahead without considering wal_decode_buffer_size and maintenance_io_concurrency.
Letting recovery prefetch compete with queries on a hot standby for cache and I/O queue depth.
Benchmarking sequential recovery only, where block prefetch may provide little benefit.

wal_decode_buffer_size · maintenance_io_concurrency · effective_io_concurrency · shared_buffers · archive_cleanup_command · archive_command