1/*-------------------------------------------------------------------------
4 * Plan cache management.
6 * The plan cache manager has two principal responsibilities: deciding when
7 * to use a generic plan versus a custom (parameter-value-specific) plan,
8 * and tracking whether cached plans need to be invalidated because of schema
9 * changes in the objects they depend on.
11 * The logic for choosing generic or custom plans is in choose_custom_plan,
12 * which see for comments.
14 * Cache invalidation is driven off sinval events. Any CachedPlanSource
15 * that matches the event is marked invalid, as is its generic CachedPlan
16 * if it has one. When (and if) the next demand for a cached plan occurs,
17 * parse analysis and/or rewrite is repeated to build a new valid query tree,
18 * and then planning is performed as normal. We also force re-analysis and
19 * re-planning if the active search_path is different from the previous time
20 * or, if RLS is involved, if the user changes or the RLS environment changes.
22 * Note that if the sinval was a result of user DDL actions, parse analysis
23 * could throw an error, for example if a column referenced by the query is
24 * no longer present. Another possibility is for the query's output tupdesc
25 * to change (for instance "SELECT *" might expand differently than before).
26 * The creator of a cached plan can specify whether it is allowable for the
27 * query to change output tupdesc on replan --- if so, it's up to the
28 * caller to notice changes and cope with them.
30 * Currently, we track exactly the dependencies of plans on relations,
31 * user-defined functions, and domains. On relcache invalidation events or
32 * pg_proc or pg_type syscache invalidation events, we invalidate just those
33 * plans that depend on the particular object being modified. (Note: this
34 * scheme assumes that any table modification that requires replanning will
35 * generate a relcache inval event.) We also watch for inval events on
36 * certain other system catalogs, such as pg_namespace; but for them, our
37 * response is just to invalidate all plans. We expect updates on those
38 * catalogs to be infrequent enough that more-detailed tracking is not worth
41 * In addition to full-fledged query plans, we provide a facility for
42 * detecting invalidations of simple scalar expressions. This is fairly
43 * bare-bones; it's the caller's responsibility to build a new expression
44 * if the old one gets invalidated.
47 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
48 * Portions Copyright (c) 1994, Regents of the University of California
51 * src/backend/utils/cache/plancache.c
53 *-------------------------------------------------------------------------
79 * This is the head of the backend's list of "saved" CachedPlanSources (i.e.,
80 * those that are in long-lived storage and are examined for sinval events).
81 * We use a dlist instead of separate List cells so that we can guarantee
82 * to save a CachedPlanSource without error.
87 * This is the head of the backend's list of CachedExpressions.
112/* ResourceOwner callbacks to track plancache references */
117 .
name =
"plancache reference",
121 .DebugPrint = NULL
/* the default message is fine */
124/* Convenience wrappers over ResourceOwnerRemember/Forget */
141 * InitPlanCache: initialize module during InitPostgres.
143 * All we need to do is hook into inval.c's callback lists.
159 * CreateCachedPlan: initially create a plan cache entry for a raw parse tree.
161 * Creation of a cached plan is divided into two steps, CreateCachedPlan and
162 * CompleteCachedPlan. CreateCachedPlan should be called after running the
163 * query through raw_parser, but before doing parse analysis and rewrite;
164 * CompleteCachedPlan is called after that. The reason for this arrangement
165 * is that it can save one round of copying of the raw parse tree, since
166 * the parser will normally scribble on the raw parse tree. Callers would
167 * otherwise need to make an extra copy of the parse tree to ensure they
168 * still had a clean copy to present at plan cache creation time.
170 * All arguments presented to CreateCachedPlan are copied into a memory
171 * context created as a child of the call-time CurrentMemoryContext, which
172 * should be a reasonably short-lived working context that will go away in
173 * event of an error. This ensures that the cached plan data structure will
174 * likewise disappear if an error occurs before we have fully constructed it.
175 * Once constructed, the cached plan can be made longer-lived, if needed,
176 * by calling SaveCachedPlan.
178 * raw_parse_tree: output of raw_parser(), or NULL if empty query
179 * query_string: original query text
180 * commandTag: command tag for query, or UNKNOWN if empty query
184 const char *query_string,
191 Assert(query_string != NULL);
/* required as of 8.4 */
194 * Make a dedicated memory context for the CachedPlanSource and its
195 * permanent subsidiary data. It's probably not going to be large, but
196 * just in case, allow it to grow large. Initially it's a child of the
197 * caller's context (which we assume to be transient), so that it will be
198 * cleaned up on error.
205 * Create and fill the CachedPlanSource struct within the new context.
206 * Most fields are just left empty for the moment.
226 plansource->
context = source_context;
235 plansource->
gplan = NULL;
252 * CreateCachedPlanForQuery: initially create a plan cache entry for a Query.
254 * This is used in the same way as CreateCachedPlan, except that the source
255 * query has already been through parse analysis, and the plancache will never
256 * try to re-do that step.
258 * Currently this is used only for new-style SQL functions, where we have a
259 * Query from the function's prosqlbody, but no source text. The query_string
260 * is typically empty, but is required anyway.
264 const char *query_string,
270 /* Rather than duplicating CreateCachedPlan, just do this: */
280 * CreateOneShotCachedPlan: initially create a one-shot plan cache entry.
282 * This variant of CreateCachedPlan creates a plan cache entry that is meant
283 * to be used only once. No data copying occurs: all data structures remain
284 * in the caller's memory context (which typically should get cleared after
285 * completing execution). The CachedPlanSource struct itself is also created
288 * A one-shot plan cannot be saved or copied, since we make no effort to
289 * preserve the raw parse tree unmodified. There is also no support for
290 * invalidation, so plan use must be completed in the current transaction,
291 * and DDL that might invalidate the querytree_list must be avoided as well.
293 * raw_parse_tree: output of raw_parser(), or NULL if empty query
294 * query_string: original query text
295 * commandTag: command tag for query, or NULL if empty query
299 const char *query_string,
304 Assert(query_string != NULL);
/* required as of 8.4 */
307 * Create and fill the CachedPlanSource struct within the caller's memory
308 * context. Most fields are just left empty for the moment.
334 plansource->
gplan = NULL;
349 * CompleteCachedPlan: second step of creating a plan cache entry.
351 * Pass in the analyzed-and-rewritten form of the query, as well as the
352 * required subsidiary data about parameters and such. All passed values will
353 * be copied into the CachedPlanSource's memory, except as specified below.
354 * After this is called, GetCachedPlan can be called to obtain a plan, and
355 * optionally the CachedPlanSource can be saved using SaveCachedPlan.
357 * If querytree_context is not NULL, the querytree_list must be stored in that
358 * context (but the other parameters need not be). The querytree_list is not
359 * copied, rather the given context is kept as the initial query_context of
360 * the CachedPlanSource. (It should have been created as a child of the
361 * caller's working memory context, but it will now be reparented to belong
362 * to the CachedPlanSource.) The querytree_context is normally the context in
363 * which the caller did raw parsing and parse analysis. This approach saves
364 * one tree copying step compared to passing NULL, but leaves lots of extra
365 * cruft in the query_context, namely whatever extraneous stuff parse analysis
366 * created, as well as whatever went unused from the raw parse tree. Using
367 * this option is a space-for-time tradeoff that is appropriate if the
368 * CachedPlanSource is not expected to survive long.
370 * plancache.c cannot know how to copy the data referenced by parserSetupArg,
371 * and it would often be inappropriate to do so anyway. When using that
372 * option, it is caller's responsibility that the referenced data remains
373 * valid for as long as the CachedPlanSource exists.
375 * If the CachedPlanSource is a "oneshot" plan, then no querytree copying
376 * occurs at all, and querytree_context is ignored; it is caller's
377 * responsibility that the passed querytree_list is sufficiently long-lived.
379 * plansource: structure returned by CreateCachedPlan
380 * querytree_list: analyzed-and-rewritten form of query (list of Query nodes)
381 * querytree_context: memory context containing querytree_list,
382 * or NULL to copy querytree_list into a fresh context
383 * param_types: array of fixed parameter type OIDs, or NULL if none
384 * num_params: number of fixed parameters
385 * parserSetup: alternate method for handling query parameters
386 * parserSetupArg: data to pass to parserSetup
387 * cursor_options: options bitmask to pass to planner
388 * fixed_result: true to disallow future changes in query's result tupdesc
392 List *querytree_list,
397 void *parserSetupArg,
404 /* Assert caller is doing things in a sane order */
409 * If caller supplied a querytree_context, reparent it underneath the
410 * CachedPlanSource's context; otherwise, create a suitable context and
411 * copy the querytree_list into it. But no data copying should be done
412 * for one-shot plans; for those, assume the passed querytree_list is
413 * sufficiently long-lived.
419 else if (querytree_context != NULL)
426 /* Again, it's a good bet the querytree_context can be small */
440 * Use the planner machinery to extract dependencies. Data is saved
441 * in query_context. (We assume that not a lot of extra cruft is
442 * created by this call.) We can skip this for one-shot plans, and
443 * plans not needing revalidation have no such dependencies anyway.
450 /* Update RLS info as well. */
455 * Also save the current search_path in the query_context. (This
456 * should not generate much extra cruft either, since almost certainly
457 * the path is already valid.) Again, we don't really need this for
458 * one-shot plans; and we *must* skip this for transaction control
459 * commands, because this could result in catalog accesses.
465 * Save the final parameter types (or other parameter specification data)
466 * into the source_context, as well as our other parameters.
473 memcpy(plansource->
param_types, param_types, num_params *
sizeof(
Oid));
484 * Also save the result tuple descriptor. PlanCacheComputeResultDesc may
485 * leak some cruft; normally we just accept that to save a copy step, but
486 * in USE_VALGRIND mode be tidy by running it in the caller's context.
507 * SetPostRewriteHook: set a hook to modify post-rewrite query trees
509 * Some callers have a need to modify the query trees between rewriting and
510 * planning. In the initial call to CompleteCachedPlan, it's assumed such
511 * work was already done on the querytree_list. However, if we're forced
512 * to replan, it will need to be done over. The caller can set this hook
513 * to provide code to make that happen.
515 * postRewriteArg is just passed verbatim to the hook. As with parserSetupArg,
516 * it is caller's responsibility that the referenced data remains
517 * valid for as long as the CachedPlanSource exists.
522 void *postRewriteArg)
530 * SaveCachedPlan: save a cached plan permanently
532 * This function moves the cached plan underneath CacheMemoryContext (making
533 * it live for the life of the backend, unless explicitly dropped), and adds
534 * it to the list of cached plans that are checked for invalidation when an
535 * sinval event occurs.
537 * This is guaranteed not to throw error, except for the caller-error case
538 * of trying to save a one-shot plan. Callers typically depend on that
539 * since this is called just before or just after adding a pointer to the
540 * CachedPlanSource to some permanent data structure of their own. Up until
541 * this is done, a CachedPlanSource is just transient data that will go away
542 * automatically on transaction abort.
547 /* Assert caller is doing things in a sane order */
552 /* This seems worth a real test, though */
554 elog(
ERROR,
"cannot save one-shot cached plan");
557 * In typical use, this function would be called before generating any
558 * plans from the CachedPlanSource. If there is a generic plan, moving it
559 * into CacheMemoryContext would be pretty risky since it's unclear
560 * whether the caller has taken suitable care with making references
561 * long-lived. Best thing to do seems to be to discard the plan.
566 * Reparent the source memory context under CacheMemoryContext so that it
567 * will live indefinitely. The query_context follows along since it's
568 * already a child of the other one.
573 * Add the entry to the global list of cached plans.
581 * DropCachedPlan: destroy a cached plan.
583 * Actually this only destroys the CachedPlanSource: any referenced CachedPlan
584 * is released, but not destroyed until its refcount goes to zero. That
585 * handles the situation where DropCachedPlan is called while the plan is
593 /* If it's been saved, remove it from the list */
600 /* Decrement generic CachedPlan's refcount and drop if no longer needed */
603 /* Mark it no longer valid */
604 plansource->
magic = 0;
607 * Remove the CachedPlanSource and all subsidiary data (including the
608 * query_context if any). But if it's a one-shot we can't free anything.
615 * ReleaseGenericPlan: release a CachedPlanSource's generic plan, if any.
620 /* Be paranoid about the possibility that ReleaseCachedPlan fails */
621 if (plansource->
gplan)
626 plansource->
gplan = NULL;
632 * We must skip "overhead" operations that involve database access when the
633 * cached plan's subject statement is a transaction control command or one
634 * that requires a snapshot not to be set yet (such as SET or LOCK). More
635 * generally, statements that do not require parse analysis/rewrite/plan
636 * activity never need to be revalidated, so we can treat them all like that.
637 * For the convenience of postgres.c, treat empty statements that way too.
646 /* empty query never needs revalidation */
651 * Determine if creating a plan for this CachedPlanSource requires a snapshot.
652 * In fact this function matches StmtPlanRequiresRevalidation(), but we want
653 * to preserve the distinction between stmt_requires_parse_analysis() and
654 * analyze_requires_snapshot().
663 /* empty query never needs a snapshot */
668 * RevalidateCachedQuery: ensure validity of analyzed-and-rewritten query tree.
670 * What we do here is re-acquire locks and redo parse analysis if necessary.
671 * On return, the query_list is valid and we have sufficient locks to begin
674 * If any parse analysis activity is required, the caller's memory context is
675 * used for that work.
677 * The result value is the transient analyzed-and-rewritten query tree if we
678 * had to do re-analysis, and NIL otherwise. (This is returned just to save
679 * a tree copying step in a subsequent BuildCachedPlan call.)
686 List *tlist;
/* transient query-tree list */
687 List *qlist;
/* permanent query-tree list */
693 * For one-shot plans, we do not support revalidation checking; it's
694 * assumed the query is parsed, planned, and executed in one transaction,
695 * so that no lock re-acquisition is necessary. Also, if the statement
696 * type can't require revalidation, we needn't do anything (and we mustn't
697 * risk catalog accesses when handling, eg, transaction control commands).
706 * If the query is currently valid, we should have a saved search_path ---
707 * check to see if that matches the current environment. If not, we want
708 * to force replan. (We could almost ignore this consideration when
709 * working from an analyzed parse tree; but there are scenarios where
710 * planning can have search_path-dependent results, for example if it
711 * inlines an old-style SQL function.)
718 /* Invalidate the querytree and generic plan */
720 if (plansource->
gplan)
726 * If the query rewrite phase had a possible RLS dependency, we must redo
727 * it if either the role or the row_security setting has changed.
735 * If the query is currently valid, acquire locks on the referenced
736 * objects; then check again. We need to do it this way to cover the race
737 * condition that an invalidation message arrives before we get the locks.
744 * By now, if any invalidation has happened, the inval callback
745 * functions will have marked the query invalid.
749 /* Successfully revalidated and locked the query. */
753 /* Oops, the race case happened. Release useless locks. */
758 * Discard the no-longer-useful rewritten query tree. (Note: we don't
759 * want to do this any earlier, else we'd not have been able to release
760 * locks correctly in the race condition case.)
769 * Free the query_context. We don't really expect MemoryContextDelete to
770 * fail, but just in case, make sure the CachedPlanSource is left in a
771 * reasonably sane state. (The generic plan won't get unlinked yet, but
772 * that's acceptable.)
782 /* Drop the generic plan reference if any */
786 * Now re-do parse analysis and rewrite. This not incidentally acquires
787 * the locks we need to do planning safely.
792 * If a snapshot is already set (the normal case), we can just use that
793 * for parsing/planning. But if it isn't, install one. Note: no point in
794 * checking whether parse analysis requires a snapshot; utility commands
795 * don't have invalidatable plans, so we'd not get here for such a
798 snapshot_set =
false;
806 * Run parse analysis (if needed) and rule rewriting.
810 /* Source is raw parse tree */
814 * The parser tends to scribble on its input, so we must copy the raw
815 * parse tree to prevent corruption of the cache.
833 /* Source is pre-analyzed query, so we only need to rewrite */
834 Query *analyzed_tree;
836 /* The rewriter scribbles on its input, too, so copy */
838 /* Acquire locks needed before rewriting ... */
845 /* Empty query, nothing to do */
849 /* Apply post-rewrite callback if there is one */
853 /* Release snapshot if we got one */
858 * Check or update the result tupdesc.
860 * We assume the parameter types didn't change from the first time, so no
861 * need to update that.
864 if (resultDesc == NULL && plansource->
resultDesc == NULL)
866 /* OK, doesn't return tuples */
868 else if (resultDesc == NULL || plansource->
resultDesc == NULL ||
871 /* can we give a better error message? */
874 (
errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
875 errmsg(
"cached plan must not change result type")));
886 * Allocate new query_context and copy the completed querytree into it.
887 * It's transient until we complete the copying and dependency extraction.
897 * Use the planner machinery to extract dependencies. Data is saved in
898 * query_context. (We assume that not a lot of extra cruft is created by
906 /* Update RLS info as well. */
911 * Also save the current search_path in the query_context. (This should
912 * not generate much extra cruft either, since almost certainly the path
919 /* Now reparent the finished query_context and save the links */
926 * Note: we do not reset generic_cost or total_custom_cost, although we
927 * could choose to do so. If the DDL or statistics change that prompted
928 * the invalidation meant a significant change in the cost estimates, it
929 * would be better to reset those variables and start fresh; but often it
930 * doesn't, and we're better retaining our hard-won knowledge about the
936 /* Return transient copy of querytrees for possible use in planning */
941 * CheckCachedPlan: see if the CachedPlanSource's generic plan is valid.
943 * Caller must have already called RevalidateCachedQuery to verify that the
944 * querytree is up to date.
946 * On a "true" return, we have acquired the locks needed to run the plan.
947 * (We must do this for the "true" result to be race-condition-free.)
954 /* Assert that caller checked the querytree */
957 /* If there's no generic plan, just say "false" */
962 /* Generic plans are never one-shot */
966 * If plan isn't valid for current role, we can't use it.
968 if (
plan->is_valid &&
plan->dependsOnRole &&
970 plan->is_valid =
false;
973 * If it appears valid, acquire locks and recheck; this is much the same
974 * logic as in RevalidateCachedQuery, but for a plan.
979 * Plan must have positive refcount because it is referenced by
980 * plansource; so no need to fear it disappears under us here.
987 * If plan was transient, check to see if TransactionXmin has
988 * advanced, and if so invalidate it.
990 if (
plan->is_valid &&
993 plan->is_valid =
false;
996 * By now, if any invalidation has happened, the inval callback
997 * functions will have marked the plan invalid.
1001 /* Successfully revalidated and locked the query. */
1005 /* Oops, the race case happened. Release useless locks. */
1010 * Plan has been invalidated, so unlink it from the parent and release it.
1018 * BuildCachedPlan: construct a new CachedPlan from a CachedPlanSource.
1020 * qlist should be the result value from a previous RevalidateCachedQuery,
1021 * or it can be set to NIL if we need to re-copy the plansource's query_list.
1023 * To build a generic, parameter-value-independent plan, pass NULL for
1024 * boundParams. To build a custom plan, pass the actual parameter values via
1025 * boundParams. For best effect, the PARAM_FLAG_CONST flag should be set on
1026 * each parameter value; otherwise the planner will treat the value as a
1027 * hint rather than a hard constant.
1029 * Planning work is done in the caller's memory context. The finished plan
1030 * is in a child memory context, which typically should get reparented
1031 * (unless this is a one-shot plan, in which case we don't copy the plan).
1046 * Normally the querytree should be valid already, but if it's not,
1049 * NOTE: GetCachedPlan should have called RevalidateCachedQuery first, so
1050 * we ought to be holding sufficient locks to prevent any invalidation.
1051 * However, if we're building a custom plan after having built and
1052 * rejected a generic plan, it's possible to reach here with is_valid
1053 * false due to an invalidation while making the generic plan. In theory
1054 * the invalidation must be a false positive, perhaps a consequence of an
1055 * sinval reset event or the debug_discard_caches code. But for safety,
1056 * let's treat it as real and redo the RevalidateCachedQuery call.
1062 * If we don't already have a copy of the querytree list that can be
1063 * scribbled on by the planner, make one. For a one-shot plan, we assume
1064 * it's okay to scribble on the original query_list.
1075 * If a snapshot is already set (the normal case), we can just use that
1076 * for planning. But if it isn't, and we need one, install one.
1078 snapshot_set =
false;
1083 snapshot_set =
true;
1087 * Generate the plan.
1092 /* Release snapshot if we got one */
1097 * Normally we make a dedicated memory context for the CachedPlan and its
1098 * subsidiary data. (It's probably not going to be large, but just in
1099 * case, allow it to grow large. It's transient for the moment.) But for
1100 * a one-shot plan, we just leave it in the caller's memory context.
1110 * Copy plan into the new context.
1120 * Create and fill the CachedPlan struct within the new context.
1124 plan->stmt_list = plist;
1127 * CachedPlan is dependent on role either if RLS affected the rewrite
1128 * phase or if a role dependency was injected during planning. And it's
1129 * transient if any plan is marked so.
1133 is_transient =
false;
1139 continue;
/* Ignore utility statements */
1142 is_transient =
true;
1144 plan->dependsOnRole =
true;
1154 plan->context = plan_context;
1156 plan->is_saved =
false;
1157 plan->is_valid =
true;
1159 /* assign generation number to new plan */
1168 * choose_custom_plan: choose whether to use custom or generic plan
1170 * This defines the policy followed by GetCachedPlan.
1175 double avg_custom_cost;
1177 /* One-shot plans will always be considered custom */
1181 /* Otherwise, never any point in a custom plan if there's no parameters */
1182 if (boundParams == NULL)
1184 /* ... nor when planning would be a no-op */
1188 /* Let settings force the decision */
1194 /* See if caller wants to force the decision */
1200 /* Generate custom plans until we have done at least 5 (arbitrary) */
1207 * Prefer generic plan if it's less expensive than the average custom
1208 * plan. (Because we include a charge for cost of planning in the
1209 * custom-plan costs, this means the generic plan only has to be less
1210 * expensive than the execution cost plus replan cost of the custom
1213 * Note that if generic_cost is -1 (indicating we've not yet determined
1214 * the generic plan cost), we'll always prefer generic at this point.
1223 * cached_plan_cost: calculate estimated cost of a plan
1225 * If include_planner is true, also include the estimated cost of constructing
1226 * the plan. (We must factor that into the cost of using a custom plan, but
1227 * we don't count it for a generic plan.)
1235 foreach(lc,
plan->stmt_list)
1240 continue;
/* Ignore utility statements */
1244 if (include_planner)
1247 * Currently we use a very crude estimate of planning effort based
1248 * on the number of relations in the finished plan's rangetable.
1249 * Join planning effort actually scales much worse than linearly
1250 * in the number of relations --- but only until the join collapse
1251 * limits kick in. Also, while inheritance child relations surely
1252 * add to planning effort, they don't make the join situation
1253 * worse. So the actual shape of the planning cost curve versus
1254 * number of relations isn't all that obvious. It will take
1255 * considerable work to arrive at a less crude estimate, and for
1256 * now it's not clear that's worth doing.
1258 * The other big difficulty here is that we don't have any very
1259 * good model of how planning cost compares to execution costs.
1260 * The current multiplier of 1000 * cpu_operator_cost is probably
1261 * on the low side, but we'll try this for awhile before making a
1262 * more aggressive correction.
1264 * If we ever do write a more complicated estimator, it should
1265 * probably live in src/backend/optimizer/ not here.
1277 * GetCachedPlan: get a cached plan from a CachedPlanSource.
1279 * This function hides the logic that decides whether to use a generic
1280 * plan or a custom plan for the given parameters: the caller does not know
1281 * which it will get.
1283 * On return, the plan is valid and we have sufficient locks to begin
1286 * On return, the refcount of the plan has been incremented; a later
1287 * ReleaseCachedPlan() call is expected. If "owner" is not NULL then
1288 * the refcount has been reported to that ResourceOwner (note that this
1289 * is only supported for "saved" CachedPlanSources).
1291 * Note: if any replanning activity is required, the caller's memory context
1292 * is used for that work.
1303 /* Assert caller is doing things in a sane order */
1306 /* This seems worth a real test, though */
1307 if (owner && !plansource->
is_saved)
1308 elog(
ERROR,
"cannot apply ResourceOwner to non-saved cached plan");
1310 /* Make sure the querytree list is valid and we have parse-time locks */
1313 /* Decide whether to use a custom plan */
1320 /* We want a generic plan, and we already have a valid one */
1326 /* Build a new generic plan */
1328 /* Just make real sure plansource->gplan is clear */
1330 /* Link the new generic plan into the plansource */
1333 /* Immediately reparent into appropriate context */
1336 /* saved plans all live under CacheMemoryContext */
1338 plan->is_saved =
true;
1342 /* otherwise, it should be a sibling of the plansource */
1346 /* Update generic_cost whenever we make a new generic plan */
1350 * If, based on the now-known value of generic_cost, we'd not have
1351 * chosen to use a generic plan, then forget it and make a custom
1352 * plan. This is a bit of a wart but is necessary to avoid a
1353 * glitch in behavior when the custom plans are consistently big
1354 * winners; at some point we'll experiment with a generic plan and
1355 * find it's a loser, but we don't want to actually execute that
1361 * If we choose to plan again, we need to re-copy the query_list,
1362 * since the planner probably scribbled on it. We can force
1363 * BuildCachedPlan to do that by passing NIL.
1371 /* Build a custom plan */
1373 /* Accumulate total costs of custom plans */
1385 /* Flag the plan as in use by caller */
1393 * Saved plans should be under CacheMemoryContext so they will not go away
1394 * until their reference count goes to zero. In the generic-plan cases we
1395 * already took care of that, but for a custom plan, do it as soon as we
1396 * have created a reference-counted link.
1398 if (customplan && plansource->
is_saved)
1401 plan->is_saved =
true;
1404 foreach(lc,
plan->stmt_list)
1415 * ReleaseCachedPlan: release active use of a cached plan.
1417 * This decrements the reference count, and frees the plan if the count
1418 * has thereby gone to zero. If "owner" is not NULL, it is assumed that
1419 * the reference count is managed by that ResourceOwner.
1421 * Note: owner == NULL is used for releasing references that are in
1422 * persistent data structures, such as the parent CachedPlanSource or a
1423 * Portal. Transient references should be protected by a resource owner.
1436 if (
plan->refcount == 0)
1438 /* Mark it no longer valid */
1441 /* One-shot plans do not own their context, so we can't free them */
1442 if (!
plan->is_oneshot)
1448 * CachedPlanAllowsSimpleValidityCheck: can we use CachedPlanIsSimplyValid?
1450 * This function, together with CachedPlanIsSimplyValid, provides a fast path
1451 * for revalidating "simple" generic plans. The core requirement to be simple
1452 * is that the plan must not require taking any locks, which translates to
1453 * not touching any tables; this happens to match up well with an important
1454 * use-case in PL/pgSQL. This function tests whether that's true, along
1455 * with checking some other corner cases that we'd rather not bother with
1456 * handling in the fast path. (Note that it's still possible for such a plan
1457 * to be invalidated, for example due to a change in a function that was
1458 * inlined into the plan.)
1460 * If the plan is simply valid, and "owner" is not NULL, record a refcount on
1461 * the plan in that resowner before returning. It is caller's responsibility
1462 * to be sure that a refcount is held on any plan that's being actively used.
1464 * This must only be called on known-valid generic plans (eg, ones just
1465 * returned by GetCachedPlan). If it returns true, the caller may re-use
1466 * the cached plan as long as CachedPlanIsSimplyValid returns true; that
1467 * check is much cheaper than the full revalidation done by GetCachedPlan.
1468 * Nonetheless, no required checks are omitted.
1477 * Sanity-check that the caller gave us a validated generic plan. Notice
1478 * that we *don't* assert plansource->is_valid as you might expect; that's
1479 * because it's possible that that's already false when GetCachedPlan
1480 * returns, e.g. because ResetPlanCache happened partway through. We
1481 * should accept the plan as long as plan->is_valid is true, and expect to
1482 * replan after the next CachedPlanIsSimplyValid call.
1491 /* We don't support oneshot plans here. */
1497 * If the plan is dependent on RLS considerations, or it's transient,
1498 * reject. These things probably can't ever happen for table-free
1499 * queries, but for safety's sake let's check.
1503 if (
plan->dependsOnRole)
1509 * Reject if AcquirePlannerLocks would have anything to do. This is
1510 * simplistic, but there's no need to inquire any more carefully; indeed,
1511 * for current callers it shouldn't even be possible to hit any of these
1525 * Reject if AcquireExecutorLocks would have anything to do. This is
1526 * probably unnecessary given the previous check, but let's be safe.
1528 foreach(lc,
plan->stmt_list)
1537 * We have to grovel through the rtable because it's likely to contain
1538 * an RTE_RESULT relation, rather than being totally empty.
1540 foreach(lc2, plannedstmt->
rtable)
1550 * Okay, it's simple. Note that what we've primarily established here is
1551 * that no locks need be taken before checking the plan's is_valid flag.
1554 /* Bump refcount if requested. */
1566 * CachedPlanIsSimplyValid: quick check for plan still being valid
1568 * This function must not be used unless CachedPlanAllowsSimpleValidityCheck
1569 * previously said it was OK.
1571 * If the plan is valid, and "owner" is not NULL, record a refcount on
1572 * the plan in that resowner before returning. It is caller's responsibility
1573 * to be sure that a refcount is held on any plan that's being actively used.
1575 * The code here is unconditionally safe as long as the only use of this
1576 * CachedPlanSource is in connection with the particular CachedPlan pointer
1577 * that's passed in. If the plansource were being used for other purposes,
1578 * it's possible that its generic plan could be invalidated and regenerated
1579 * while the current caller wasn't looking, and then there could be a chance
1580 * collision of address between this caller's now-stale plan pointer and the
1581 * actual address of the new generic plan. For current uses, that scenario
1582 * can't happen; but with a plansource shared across multiple uses, it'd be
1583 * advisable to also save plan->generation and verify that that still matches.
1590 * Careful here: since the caller doesn't necessarily hold a refcount on
1591 * the plan to start with, it's possible that "plan" is a dangling
1592 * pointer. Don't dereference it until we've verified that it still
1593 * matches the plansource's gplan (which is either valid or NULL).
1598 * Has cache invalidation fired on this plan? We can check this right
1599 * away since there are no locks that we'd need to acquire first. Note
1600 * that here we *do* check plansource->is_valid, so as to force plan
1601 * rebuild if that's become false.
1610 /* Is the search_path still the same as when we made it? */
1615 /* It's still good. Bump refcount if requested. */
1627 * CachedPlanSetParentContext: move a CachedPlanSource to a new memory context
1629 * This can only be applied to unsaved plans; once saved, a plan always
1630 * lives underneath CacheMemoryContext.
1636 /* Assert caller is doing things in a sane order */
1640 /* These seem worth real tests, though */
1642 elog(
ERROR,
"cannot move a saved cached plan to another context");
1644 elog(
ERROR,
"cannot move a one-shot cached plan to another context");
1646 /* OK, let the caller keep the plan where he wishes */
1650 * The query_context needs no special handling, since it's a child of
1651 * plansource->context. But if there's a generic plan, it should be
1652 * maintained as a sibling of plansource->context.
1654 if (plansource->
gplan)
1662 * CopyCachedPlan: make a copy of a CachedPlanSource
1664 * This is a convenience routine that does the equivalent of
1665 * CreateCachedPlan + CompleteCachedPlan, using the data stored in the
1666 * input CachedPlanSource. The result is therefore "unsaved" (regardless
1667 * of the state of the source), and we don't copy any generic plan either.
1668 * The result will be currently valid, or not, the same as the source.
1682 * One-shot plans can't be copied, because we haven't taken care that
1683 * parsing/planning didn't scribble on the raw parse tree or querytrees.
1686 elog(
ERROR,
"cannot copy a one-shot cached plan");
1721 newsource->
context = source_context;
1737 newsource->
gplan = NULL;
1745 /* We may as well copy any acquired cost knowledge */
1757 * CachedPlanIsValid: test whether the rewritten querytree within a
1758 * CachedPlanSource is currently valid (that is, not marked as being in need
1761 * This result is only trustworthy (ie, free from race conditions) if
1762 * the caller has acquired locks on all the relations used in the plan.
1772 * CachedPlanGetTargetList: return tlist, if any, describing plan's output
1774 * The result is guaranteed up-to-date. However, it is local storage
1775 * within the cached plan, and may disappear next time the plan is updated.
1783 /* Assert caller is doing things in a sane order */
1788 * No work needed if statement doesn't return tuples (we assume this
1789 * feature cannot be changed by an invalidation)
1794 /* Make sure the querytree list is valid and we have parse-time locks */
1797 /* Get the primary statement and find out what it returns */
1804 * GetCachedExpression: construct a CachedExpression for an expression.
1806 * This performs the same transformations on the expression as
1807 * expression_planner(), ie, convert an expression as emitted by parse
1808 * analysis to be ready to pass to the executor.
1810 * The result is stashed in a private, long-lived memory context.
1811 * (Note that this might leak a good deal of memory in the caller's
1812 * context before that.) The passed-in expr tree is not modified.
1824 * Pass the expression through the planner, and collect dependencies.
1825 * Everything built here is leaked in the caller's context; that's
1826 * intentional to minimize the size of the permanent data structure.
1833 * Make a private memory context, and copy what we need into that. To
1834 * avoid leaking a long-lived context if we fail while copying data, we
1835 * initially make the context under the caller's context.
1849 cexpr->
context = cexpr_context;
1854 * Reparent the expr's memory context under CacheMemoryContext so that it
1855 * will live indefinitely.
1860 * Add the entry to the global list of cached expressions.
1868 * FreeCachedExpression
1869 * Delete a CachedExpression.
1876 /* Unlink from global list */
1878 /* Free all storage associated with CachedExpression */
1883 * QueryListGetPrimaryStmt
1884 * Get the "primary" stmt within a list, ie, the one marked canSetTag.
1886 * Returns NULL if no such stmt. If multiple queries within the list are
1887 * marked canSetTag, returns the first one. Neither of these cases should
1888 * occur in present usages of this function.
1899 if (
stmt->canSetTag)
1906 * AcquireExecutorLocks: acquire locks needed for execution of a cached plan;
1907 * or release them if acquire is false.
1914 foreach(lc1, stmt_list)
1922 * Ignore utility statements, except those (such as EXPLAIN) that
1923 * contain a parsed-but-not-planned query. Note: it's okay to use
1924 * ScanQueryForLocks, even though the query hasn't been through
1925 * rule rewriting, because rewriting doesn't change the query
1935 foreach(lc2, plannedstmt->
rtable)
1944 * Acquire the appropriate type of lock on each relation OID. Note
1945 * that we don't actually try to open the rel, and hence will not
1946 * fail if it's been dropped entirely --- we'll just transiently
1947 * acquire a non-conflicting lock.
1958 * AcquirePlannerLocks: acquire locks needed for planning of a querytree list;
1959 * or release them if acquire is false.
1961 * Note that we don't actually try to open the relations, and hence will not
1962 * fail if one has been dropped entirely --- we'll just transiently acquire
1963 * a non-conflicting lock.
1970 foreach(lc, stmt_list)
1976 /* Ignore utility statements, unless they contain a Query */
1988 * ScanQueryForLocks: recursively scan one Query for AcquirePlannerLocks.
1995 /* Shouldn't get called on utility commands */
1999 * First, process RTEs of the current query level.
2001 foreach(lc, parsetree->
rtable)
2008 /* Acquire or release the appropriate type of lock */
2016 /* If this was a view, must lock/unlock the view */
2024 /* Recurse into subquery-in-FROM */
2029 /* ignore other types of RTEs */
2034 /* Recurse into subquery-in-WITH */
2035 foreach(lc, parsetree->
cteList)
2043 * Recurse into sublink subqueries, too. But we already did the ones in
2044 * the rtable and cteList.
2046 if (parsetree->hasSubLinks)
2054 * Walker to find sublink subqueries for ScanQueryForLocks
2065 /* Do what we came for */
2067 /* Fall through to process lefthand args of SubLink */
2071 * Do NOT recurse into Query nodes, because ScanQueryForLocks already
2072 * processed subselects of subselects for us.
2078 * PlanCacheComputeResultDesc: given a list of analyzed-and-rewritten Queries,
2079 * determine the result tupledesc it will produce. Returns NULL if the
2080 * execution will not return tuples.
2082 * Note: the result is created or copied into current memory context.
2107 /* will not return tuples */
2114 * PlanCacheRelCallback
2115 * Relcache inval callback function
2117 * Invalidate all plans mentioning the given rel, or all plans mentioning
2118 * any rel at all if relid == InvalidOid.
2132 /* No work if it's already invalidated */
2136 /* Never invalidate if parse/plan would be a no-op anyway */
2141 * Check the dependency list for the rewritten querytree.
2146 /* Invalidate the querytree and generic plan */
2148 if (plansource->
gplan)
2153 * The generic plan, if any, could have more dependencies than the
2154 * querytree does, so we have to check it too.
2165 continue;
/* Ignore utility statements */
2169 /* Invalidate the generic plan only */
2171 break;
/* out of stmt_list scan */
2177 /* Likewise check cached expressions */
2185 /* No work if it's already invalidated */
2198 * PlanCacheObjectCallback
2199 * Syscache inval callback function for PROCOID and TYPEOID caches
2201 * Invalidate all plans mentioning the object with the specified hash value,
2202 * or all plans mentioning any member of this cache if hashvalue == 0.
2217 /* No work if it's already invalidated */
2221 /* Never invalidate if parse/plan would be a no-op anyway */
2226 * Check the dependency list for the rewritten querytree.
2234 if (hashvalue == 0 ||
2237 /* Invalidate the querytree and generic plan */
2239 if (plansource->
gplan)
2246 * The generic plan, if any, could have more dependencies than the
2247 * querytree does, so we have to check it too.
2257 continue;
/* Ignore utility statements */
2264 if (hashvalue == 0 ||
2267 /* Invalidate the generic plan only */
2269 break;
/* out of invalItems scan */
2273 break;
/* out of stmt_list scan */
2278 /* Likewise check cached expressions */
2287 /* No work if it's already invalidated */
2297 if (hashvalue == 0 ||
2308 * PlanCacheSysCallback
2309 * Syscache inval callback function for other caches
2311 * Just invalidate everything...
2320 * ResetPlanCache: invalidate all cached plans.
2334 /* No work if it's already invalidated */
2339 * We *must not* mark transaction control statements as invalid,
2340 * particularly not ROLLBACK, because they may need to be executed in
2341 * aborted transactions when we can't revalidate them (cf bug #5269).
2342 * In general there's no point in invalidating statements for which a
2343 * new parse analysis/rewrite/plan cycle would certainly give the same
2350 if (plansource->
gplan)
2354 /* Likewise invalidate cached expressions */
2367 * Release all CachedPlans remembered by 'owner'
2375/* ResourceOwner callbacks */
#define OidIsValid(objectId)
int errcode(int sqlerrcode)
int errmsg(const char *fmt,...)
#define ereport(elevel,...)
TupleDesc ExecCleanTypeFromTL(List *targetList)
Assert(PointerIsAligned(start, uint64))
#define dlist_foreach(iter, lhead)
static void dlist_delete(dlist_node *node)
static void dlist_push_tail(dlist_head *head, dlist_node *node)
#define DLIST_STATIC_INIT(name)
#define dlist_container(type, membername, ptr)
void CacheRegisterRelcacheCallback(RelcacheCallbackFunction func, Datum arg)
void CacheRegisterSyscacheCallback(int cacheid, SyscacheCallbackFunction func, Datum arg)
bool list_member_oid(const List *list, Oid datum)
void UnlockRelationOid(Oid relid, LOCKMODE lockmode)
void LockRelationOid(Oid relid, LOCKMODE lockmode)
char * pstrdup(const char *in)
void MemoryContextSetParent(MemoryContext context, MemoryContext new_parent)
void * palloc0(Size size)
MemoryContext CurrentMemoryContext
MemoryContext MemoryContextGetParent(MemoryContext context)
MemoryContext CacheMemoryContext
void MemoryContextDelete(MemoryContext context)
void MemoryContextSetIdentifier(MemoryContext context, const char *id)
#define AllocSetContextCreate
#define ALLOCSET_START_SMALL_SIZES
#define ALLOCSET_SMALL_SIZES
#define MemoryContextCopyAndSetIdentifier(cxt, id)
SearchPathMatcher * GetSearchPathMatcher(MemoryContext context)
bool SearchPathMatchesCurrentEnvironment(SearchPathMatcher *path)
SearchPathMatcher * CopySearchPathMatcher(SearchPathMatcher *path)
#define query_tree_walker(q, w, c, f)
#define expression_tree_walker(n, w, c)
#define QTW_IGNORE_RC_SUBQUERIES
#define IsA(nodeptr, _type_)
#define castNode(_type_, nodeptr)
static MemoryContext MemoryContextSwitchTo(MemoryContext context)
void(* ParserSetupHook)(ParseState *pstate, void *arg)
#define CURSOR_OPT_GENERIC_PLAN
#define CURSOR_OPT_CUSTOM_PLAN
bool analyze_requires_snapshot(RawStmt *parseTree)
bool query_requires_rewrite_plan(Query *query)
bool stmt_requires_parse_analysis(RawStmt *parseTree)
#define lfirst_node(type, lc)
static int list_length(const List *l)
#define linitial_node(type, l)
void CachedPlanSetParentContext(CachedPlanSource *plansource, MemoryContext newcontext)
bool CachedPlanIsValid(CachedPlanSource *plansource)
static dlist_head cached_expression_list
void DropCachedPlan(CachedPlanSource *plansource)
static bool choose_custom_plan(CachedPlanSource *plansource, ParamListInfo boundParams)
bool CachedPlanAllowsSimpleValidityCheck(CachedPlanSource *plansource, CachedPlan *plan, ResourceOwner owner)
static void ReleaseGenericPlan(CachedPlanSource *plansource)
static CachedPlan * BuildCachedPlan(CachedPlanSource *plansource, List *qlist, ParamListInfo boundParams, QueryEnvironment *queryEnv)
static bool CheckCachedPlan(CachedPlanSource *plansource)
void FreeCachedExpression(CachedExpression *cexpr)
void SaveCachedPlan(CachedPlanSource *plansource)
static bool StmtPlanRequiresRevalidation(CachedPlanSource *plansource)
void CompleteCachedPlan(CachedPlanSource *plansource, List *querytree_list, MemoryContext querytree_context, Oid *param_types, int num_params, ParserSetupHook parserSetup, void *parserSetupArg, int cursor_options, bool fixed_result)
static void ResourceOwnerRememberPlanCacheRef(ResourceOwner owner, CachedPlan *plan)
CachedPlan * GetCachedPlan(CachedPlanSource *plansource, ParamListInfo boundParams, ResourceOwner owner, QueryEnvironment *queryEnv)
CachedExpression * GetCachedExpression(Node *expr)
bool CachedPlanIsSimplyValid(CachedPlanSource *plansource, CachedPlan *plan, ResourceOwner owner)
CachedPlanSource * CreateOneShotCachedPlan(RawStmt *raw_parse_tree, const char *query_string, CommandTag commandTag)
CachedPlanSource * CreateCachedPlanForQuery(Query *analyzed_parse_tree, const char *query_string, CommandTag commandTag)
static bool ScanQueryWalker(Node *node, bool *acquire)
void SetPostRewriteHook(CachedPlanSource *plansource, PostRewriteHook postRewrite, void *postRewriteArg)
static const ResourceOwnerDesc planref_resowner_desc
static void PlanCacheSysCallback(Datum arg, int cacheid, uint32 hashvalue)
static List * RevalidateCachedQuery(CachedPlanSource *plansource, QueryEnvironment *queryEnv)
CachedPlanSource * CreateCachedPlan(RawStmt *raw_parse_tree, const char *query_string, CommandTag commandTag)
static void PlanCacheObjectCallback(Datum arg, int cacheid, uint32 hashvalue)
List * CachedPlanGetTargetList(CachedPlanSource *plansource, QueryEnvironment *queryEnv)
CachedPlanSource * CopyCachedPlan(CachedPlanSource *plansource)
void ReleaseCachedPlan(CachedPlan *plan, ResourceOwner owner)
static TupleDesc PlanCacheComputeResultDesc(List *stmt_list)
static dlist_head saved_plan_list
static void AcquirePlannerLocks(List *stmt_list, bool acquire)
static void ResourceOwnerForgetPlanCacheRef(ResourceOwner owner, CachedPlan *plan)
static double cached_plan_cost(CachedPlan *plan, bool include_planner)
static void ResOwnerReleaseCachedPlan(Datum res)
static void ScanQueryForLocks(Query *parsetree, bool acquire)
void ReleaseAllPlanCacheRefsInOwner(ResourceOwner owner)
void ResetPlanCache(void)
static void PlanCacheRelCallback(Datum arg, Oid relid)
static Query * QueryListGetPrimaryStmt(List *stmts)
static bool BuildingPlanRequiresSnapshot(CachedPlanSource *plansource)
static void AcquireExecutorLocks(List *stmt_list, bool acquire)
void(* PostRewriteHook)(List *querytree_list, void *arg)
#define CACHEDPLANSOURCE_MAGIC
@ PLAN_CACHE_MODE_FORCE_CUSTOM_PLAN
@ PLAN_CACHE_MODE_FORCE_GENERIC_PLAN
Expr * expression_planner_with_deps(Expr *expr, List **relationOids, List **invalItems)
@ PLAN_STMT_CACHE_GENERIC
List * pg_analyze_and_rewrite_withcb(RawStmt *parsetree, const char *query_string, ParserSetupHook parserSetup, void *parserSetupArg, QueryEnvironment *queryEnv)
List * pg_plan_queries(List *querytrees, const char *query_string, int cursorOptions, ParamListInfo boundParams)
List * pg_analyze_and_rewrite_fixedparams(RawStmt *parsetree, const char *query_string, const Oid *paramTypes, int numParams, QueryEnvironment *queryEnv)
List * pg_rewrite_query(Query *query)
static Datum PointerGetDatum(const void *X)
static Pointer DatumGetPointer(Datum X)
PortalStrategy ChoosePortalStrategy(List *stmts)
List * FetchStatementTargetList(Node *stmt)
void ResourceOwnerForget(ResourceOwner owner, Datum value, const ResourceOwnerDesc *kind)
void ResourceOwnerReleaseAllOfKind(ResourceOwner owner, const ResourceOwnerDesc *kind)
void ResourceOwnerRemember(ResourceOwner owner, Datum value, const ResourceOwnerDesc *kind)
void ResourceOwnerEnlarge(ResourceOwner owner)
#define RELEASE_PRIO_PLANCACHE_REFS
@ RESOURCE_RELEASE_AFTER_LOCKS
void AcquireRewriteLocks(Query *parsetree, bool forExecute, bool forUpdatePushedDown)
void extract_query_dependencies(Node *query, List **relationOids, List **invalItems, bool *hasRowSecurity)
Snapshot GetTransactionSnapshot(void)
void PushActiveSnapshot(Snapshot snapshot)
TransactionId TransactionXmin
bool ActiveSnapshotSet(void)
void PopActiveSnapshot(void)
struct CachedPlan * gplan
PostRewriteHook postRewrite
Query * analyzed_parse_tree
struct SearchPathMatcher * search_path
MemoryContext query_context
const char * query_string
ParserSetupHook parserSetup
PlannedStmtOrigin planOrigin
#define InvalidTransactionId
#define TransactionIdEquals(id1, id2)
#define TransactionIdIsValid(xid)
#define TransactionIdIsNormal(xid)
void FreeTupleDesc(TupleDesc tupdesc)
TupleDesc CreateTupleDescCopy(TupleDesc tupdesc)
bool equalRowTypes(TupleDesc tupdesc1, TupleDesc tupdesc2)
Query * UtilityContainsQuery(Node *parsetree)
TupleDesc UtilityTupleDescriptor(Node *parsetree)