plan_cache_mode

Definition PG 18 manual

Prepared statements (either explicitly prepared or implicitly generated, for example by PL/pgSQL) can be executed using custom or generic plans. Custom plans are made afresh for each execution using its specific set of parameter values, while generic plans do not rely on the parameter values and can be re-used across executions. Thus, use of a generic plan saves planning time, but if the ideal plan depends strongly on the parameter values then a generic plan may be inefficient. The choice between these options is normally made automatically, but it can be overridden with plan_cache_mode. The allowed values are auto (the default), force_custom_plan and force_generic_plan. This setting is considered when a cached plan is to be executed, not when it is prepared. For more information see PREPARE.

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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: 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.