Prepared statements (either explicitly prepared or implicitly
- generated, for example in PL/pgSQL) can be executed using custom or
- generic plans. A custom plan is replanned for a new parameter value,
- a generic plan is reused for repeated executions of the prepared
- statement. The choice between them is normally made automatically.
- This setting overrides the default behavior and forces either a custom
- or a generic plan. This can be used to work around performance
- problems in specific cases. Note, however, that the plan cache
- behavior is subject to change, so this setting, like all settings that
- force the planner's hand, should be reevaluated regularly.
-
-
- The allowed values are auto,
+ 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. The default value is
- auto. The setting is applied when a cached plan is
- to be executed, not when it is prepared.
+ force_generic_plan.
+ This setting is considered when a cached plan is to be executed,
+ not when it is prepared.
+ For more information see .
Notes
- Prepared statements can use generic plans rather than re-planning with
- each set of supplied EXECUTE values. This occurs
- immediately for prepared statements with no parameters; otherwise
- it occurs only after five or more executions produce plans whose
- estimated cost average (including planning overhead) is more expensive
- than the generic plan cost estimate. Once a generic plan is chosen,
- it is used for the remaining lifetime of the prepared statement.
- Using EXECUTE values which are rare in columns with
- many duplicates can generate custom plans that are so much cheaper
- than the generic plan, even after adding planning overhead, that the
- generic plan might never be used.
+ A prepared statement can be executed with either a generic
+ plan or a custom plan. A generic
+ plan is the same across all executions, while a custom plan is generated
+ for a specific execution using the parameter values given in that call.
+ Use of a generic plan avoids planning overhead, but in some situations
+ a custom plan will be much more efficient to execute because the planner
+ can make use of knowledge of the parameter values. (Of course, if the
+ prepared statement has no parameters, then this is moot and a generic
+ plan is always used.)
- A generic plan assumes that each value supplied to
- EXECUTE is one of the column's distinct values
- and that column values are uniformly distributed. For example,
- if statistics record three distinct column values, a generic plan
- assumes a column equality comparison will match 33% of processed rows.
- Column statistics also allow generic plans to accurately compute the
- selectivity of unique columns. Comparisons on non-uniformly-distributed
- columns and specification of non-existent values affects the average
- plan cost, and hence if and when a generic plan is chosen.
+ By default (that is, when is set
+ to auto), the server will automatically choose
+ whether to use a generic or custom plan for a prepared statement that
+ has parameters. The current rule for this is that the first five
+ executions are done with custom plans and the average estimated cost of
+ those plans is calculated. Then a generic plan is created and its
+ estimated cost is compared to the average custom-plan cost. Subsequent
+ executions use the generic plan if its cost is not so much higher than
+ the average custom-plan cost as to make repeated replanning seem
+ preferable.
+
+
+ This heuristic can be overridden, forcing the server to use either
+ generic or custom plans, by setting plan_cache_mode
+ to force_generic_plan
+ or force_custom_plan respectively.
+ This setting is primarily useful if the generic plan's cost estimate
+ is badly off for some reason, allowing it to be chosen even though
+ its actual cost is much more than that of a custom plan.
To examine the query plan
PostgreSQL is using
- for a prepared statement, use , e.g.
- EXPLAIN EXECUTE.
+ for a prepared statement, use , for example
+EXPLAIN EXECUTE stmt_name(parameter_values);
+
If a generic plan is in use, it will contain parameter symbols
- $n, while a custom plan will have the
- supplied parameter values substituted into it.
- The row estimates in the generic plan reflect the selectivity
- computed for the parameters.
+ $n, while a custom plan
+ will have the supplied parameter values substituted into it.
EXECUTE usrrptplan(1, current_date);
- Note that the data type of the second parameter is not specified,
+ In this example, the data type of the second parameter is not specified,
so it is inferred from the context in which $2 is used.
projects / postgresql.git / commitdiff