From 66a4714523de9c6bd677a1a12bf720d238533be2 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Fri, 9 Oct 2026 15:05:26 -0400 Subject: [PATCH v2] doc: Note that plan advice does not affect cached plans Plan advice is consulted only at plan time. When a cached plan is re-executed, no re-planning occurs, so updated advice has no effect. DISCARD PLANS can be used to discard cached plans, but only affects the sessions in which it is executed. Reported-by: Noah Misch Suggested-by: Jakub Wartak Discussion: https://postgr.es/m/20260827171830.68.noahmisch@microsoft.com Co-authored-by: Dongpo Liu Co-authored-by: Robert Haas --- doc/src/sgml/pgplanadvice.sgml | 12 ++++++++++++ doc/src/sgml/pgstashadvice.sgml | 8 ++++++++ 2 files changed, 20 insertions(+) diff --git a/doc/src/sgml/pgplanadvice.sgml b/doc/src/sgml/pgplanadvice.sgml index 4592a5ced54..a618cb4a4bb 100644 --- a/doc/src/sgml/pgplanadvice.sgml +++ b/doc/src/sgml/pgplanadvice.sgml @@ -827,6 +827,18 @@ EXPLAIN (COSTS OFF) Note that scan advice is not affected by this limitation because it does not constrain the join order. + + + Plan advice is consulted only when a query is planned. If a prepared + statement is re-executed under a different value of + pg_plan_advice.advice, or with different advice supplied + by another module such as , it can still + make use of a previously cached plan. The same thing can happen when + re-executing a statement within a PL/pgSQL + block, where plans can also be cached. Sessions that do not wish to reuse + previously-cached plans can use + DISCARD PLANS. + diff --git a/doc/src/sgml/pgstashadvice.sgml b/doc/src/sgml/pgstashadvice.sgml index 7813d63d91e..532e28c1913 100644 --- a/doc/src/sgml/pgstashadvice.sgml +++ b/doc/src/sgml/pgstashadvice.sgml @@ -65,6 +65,14 @@ pg_stash_advice will enable it automatically. + + Stashed advice is applied only when a query is planned. Adding, replacing, + or removing a stash entry, or changing + pg_stash_advice.stash_name, does not affect plans that + have already been cached. See + . + + Generally, the fact that the planner is able to change query plans as the underlying distribution of data changes is a feature, not a bug. -- 2.51.0