plan_cache_mode

plan_cache_mode — Controls the planner’s selection of custom or generic plan. Observed in PG12–19 Beta 3; its last measured boot default is auto in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Controls the planner’s selection of custom or generic plan.”

Identity

Type , Valueenum: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Valueauto, force_generic_plan, force_custom_plan: — for non-enum types
Category , ValueQuery Tuning / Other Planner Options: Upstream classification
Latest boot value , Valueauto: auto

Lifecycle

Fact	Value
First observed	PG12
Present in	PG12–19 Beta 3
Removed in	No
Introduction commit	`f7cb2842bf47` — Add plan_cache_mode setting
Commit date	2018-07-16
Discussion	thread 1

Default history

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

How it works

Prepared statements can use a custom plan built with current parameter values or a generic plan independent of those values. plan_cache_mode overrides PostgreSQL’s normal cost-based choice with auto, force_custom_plan, or force_generic_plan.

The setting is checked when a cached statement is executed, not when PREPARE is issued. A custom plan pays planning cost repeatedly but can adapt to skew; a generic plan saves planning work but can be poor for parameter-sensitive predicates.

PL/pgSQL and protocol-level prepared statements are both affected. Forcing a mode is diagnostic or workload-specific policy, not a cure for bad statistics or missing indexes. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Keep plan_cache_mode at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.
OLAP	Analytical SQL can make plan_cache_mode more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.
Small nodes	On a small host, avoid increasing planning search or memory pressure through plan_cache_mode without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.

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: PG12–19 Beta 3 unmodified; OLAP: PG12–19 Beta 3 unmodified; CRIT: PG12–19 Beta 3 unmodified; TINY: PG12–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Treating plan_cache_mode as an executor resource limit rather than a planning assumption or policy.
Testing only one parameter set or one data distribution.
Expecting an already cached plan to be rewritten automatically.
Using a global override to hide stale statistics or fragile SQL structure.

default_statistics_target · cursor_tuple_fraction · join_collapse_limit · compute_query_id · jit_above_cost