From 54ccf3feb7fe6be2ecf0fa293a2da02bfb29c9dc Mon Sep 17 00:00:00 2001 From: 0xPoe Date: Sun, 4 Oct 2026 14:09:20 +0200 Subject: [PATCH v1] doc: Note that plan advice does not affect cached plans Plan advice is consulted only at plan time. A change to pg_plan_advice.advice or to an advice stash therefore has no effect on a plan that is already cached, such as the generic plan of a prepared statement. Document this, because it has caused confusion. Reported-by: Noah Misch Suggested-by: Jakub Wartak Discussion: https://postgr.es/m/20260827171830.68.noahmisch@microsoft.com --- 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..05669a76c7e 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. A change to + pg_plan_advice.advice, or to the advice supplied by + another module such as , therefore does not + affect a plan that has already been cached, such as the generic plan of a + prepared statement. The new advice is used the next time the statement is + planned. In the current session, this can be forced with + DISCARD PLANS. + Plans cached by other sessions are re-planned only when something else + invalidates them; see . + diff --git a/doc/src/sgml/pgstashadvice.sgml b/doc/src/sgml/pgstashadvice.sgml index 7813d63d91e..544e8046dcf 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, including those cached by other sessions. See + for details. + + 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.54.0 (Apple Git-157)