{"Entry":{"collection":"guc","key":"plan_cache_mode","name":"plan_cache_mode","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Query Tuning / Other Planner Options","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"11","status":"added","to":"12"}],"content_hash":"c22e6483be7f9adacd2912b23a837294a38ea1402c582fa5e06bb181a53958a6","context":"","default_changed_in":[],"default_history":[{"from":"12","to":"19","value":"auto"}],"editorial":{"advice":{"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."},"mechanism":["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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: plan_cache_mode","url":"https://www.postgresql.org/docs/19/runtime-config-query.html#GUC-PLAN-CACHE-MODE"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["default_statistics_target","cursor_tuple_fraction","join_collapse_limit","compute_query_id","jit_above_cost"],"summary":"plan_cache_mode — Controls the planner's selection of custom or generic plan. Observed in PG12–19 Beta 4; its last measured boot default is auto in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"12","group":"Query Tuning","group_slug":"query","imported_at":"2026-09-27T17:57:31.827663+08:00","intro_commit":{"authored_at":"2018-07-16T13:35:41+02:00","discussion":["https://www.postgresql.org/message-id/flat/CAFj8pRAGLaiEm8ur5DWEBo7qHRWTk9HxkuUAz00CZZtJj-LkCA%40mail.gmail.com"],"hash":"f7cb2842bf47715133b40e4a503f35dbe60d1b72","subject":"Add plan_cache_mode setting","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=f7cb2842bf47715133b40e4a503f35dbe60d1b72"},"key":"plan_cache_mode","last_version":"20","max_val":"","min_val":"","name":"plan_cache_mode","position":311,"present_in":["12","13","14","15","16","17","18","19","20"],"short_desc":"Prepared statements (either explicitly prepared or implicitly generated, for example by PL/pgSQL) can be executed using custom or generic plans.","short_desc_zh":"","source_rev":"english-manuals:5c9a47436024691ea89419ef32bcf9e031d3306bd954540db8766c4687148af6","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"plan_cache_mode","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"plan_cache_mode","SourceRevision":"english-manuals:5c9a47436024691ea89419ef32bcf9e031d3306bd954540db8766c4687148af6","Facts":{"boot_val":"auto","category":"Query Tuning / Other Planner Options","context":"user","description":"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.","doc":{"anchor":"GUC-PLAN-CACHE-MODE","file":"runtime-config-query.html","lang":"en","sha256":"33456ca7ef52bf28e93e34b932a411db7a1b95800179add2cf867dc6ec9144bc","slug":"18"},"documented":true,"enumvals":["auto","force_generic_plan","force_custom_plan"],"extra_desc":"Prepared statements can have custom and generic plans, and the planner will attempt to choose which is better.  This can be set to override the default behavior.","lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"plan_cache_mode","short_desc":"Controls the planner's selection of custom or generic plan.","source":"pg-settings-source-snapshot","unit":null,"vartype":"enum"},"ManualEvidence":{"doc":{"anchor":"GUC-PLAN-CACHE-MODE","file":"runtime-config-query.html","lang":"en","sha256":"33456ca7ef52bf28e93e34b932a411db7a1b95800179add2cf867dc6ec9144bc","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"plan_cache_mode","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"plan_cache_mode","Summary":"","BodyHTML":"\u003cp\u003e预备语句（无论是显式预备的，还是由 PL/pgSQL 等隐式生成的）可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成，而通用计划不依赖参数值，可以在多次执行之间复用。因此，使用通用计划能够节省规划时间，但如果理想计划高度依赖参数值，通用计划可能效率较低。系统通常会自动选择这两种计划，但可以通过\u003ccode\u003eplan_cache_mode\u003c/code\u003e覆盖这一选择。允许的值为\u003ccode\u003eauto\u003c/code\u003e（默认值）、\u003ccode\u003eforce_custom_plan\u003c/code\u003e和\u003ccode\u003eforce_generic_plan\u003c/code\u003e。系统在执行缓存计划时考虑此设置，而不是在预备计划时。更多信息见\u003ca href=\"/docs/18/sql-prepare.html\" title=\"PREPARE\" rel=\"nofollow\"\u003e\u003cspan\u003ePREPARE\u003c/span\u003e\u003c/a\u003e。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"f20edd8c234236d9d73ef0fe8bd0633aa6199a402caa6582d8c676e938fb7afe","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e预备语句（无论是显式预备的，还是由 PL/pgSQL 等隐式生成的）可以使用自定义计划或通用计划执行。自定义计划会根据每次执行的具体参数值重新生成，而通用计划不依赖参数值，可以在多次执行之间复用。因此，使用通用计划能够节省规划时间，但如果理想计划高度依赖参数值，通用计划可能效率较低。系统通常会自动选择这两种计划，但可以通过\u003ccode class=\"varname\"\u003eplan_cache_mode\u003c/code\u003e覆盖这一选择。允许的值为\u003ccode class=\"literal\"\u003eauto\u003c/code\u003e（默认值）、\u003ccode class=\"literal\"\u003eforce_custom_plan\u003c/code\u003e和\u003ccode class=\"literal\"\u003eforce_generic_plan\u003c/code\u003e。系统在执行缓存计划时考虑此设置，而不是在预备计划时。更多信息见\u003ca href=\"/docs/18/sql-prepare.html\" title=\"PREPARE\"\u003e\u003cspan class=\"refentrytitle\"\u003ePREPARE\u003c/span\u003e\u003c/a\u003e。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["12","13","14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}