1/*-------------------------------------------------------------------------
4 * Support for finding the values associated with Param nodes.
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/nodes/params.h
12 *-------------------------------------------------------------------------
17/* to avoid including other headers */
26 * ParamListInfo structures are used to pass parameters into the executor
27 * for parameterized plans. We support two basic approaches to supplying
28 * parameter values, the "static" way and the "dynamic" way.
30 * In the static approach, per-parameter data is stored in an array of
31 * ParamExternData structs appended to the ParamListInfo struct.
32 * Each entry in the array defines the value to be substituted for a
33 * PARAM_EXTERN parameter. The "paramid" of a PARAM_EXTERN Param
34 * can range from 1 to numParams.
36 * Although parameter numbers are normally consecutive, we allow
37 * ptype == InvalidOid to signal an unused array entry.
39 * pflags is a flags field. Currently the only used bit is:
40 * PARAM_FLAG_CONST signals the planner that it may treat this parameter
41 * as a constant (i.e., generate a plan that works only for this value
44 * In the dynamic approach, all access to parameter values is done through
45 * hook functions found in the ParamListInfo struct. In this case,
46 * the ParamExternData array is typically unused and not allocated;
47 * but the legal range of paramid is still 1 to numParams.
49 * Although the data structure is really an array, not a list, we keep
50 * the old typedef name to avoid unnecessary code changes.
52 * There are 3 hook functions that can be associated with a ParamListInfo
55 * If paramFetch isn't null, it is called to fetch the ParamExternData
56 * for a particular param ID, rather than accessing the relevant element
57 * of the ParamExternData array. This supports the case where the array
58 * isn't there at all, as well as cases where the data in the array
59 * might be obsolete or lazily evaluated. paramFetch must return the
60 * address of a ParamExternData struct describing the specified param ID;
61 * the convention above about ptype == InvalidOid signaling an invalid
62 * param ID still applies. The returned struct can either be placed in
63 * the "workspace" supplied by the caller, or it can be in storage
64 * controlled by the paramFetch hook if that's more convenient.
65 * (In either case, the struct is not expected to be long-lived.)
66 * If "speculative" is true, the paramFetch hook should not risk errors
67 * in trying to fetch the parameter value, and should report an invalid
70 * If paramCompile isn't null, then it controls what execExpr.c compiles
71 * for PARAM_EXTERN Param nodes --- typically, this hook would emit a
72 * EEOP_PARAM_CALLBACK step. This allows unnecessary work to be
73 * optimized away in compiled expressions.
75 * If parserSetup isn't null, then it is called to re-instantiate the
76 * original parsing hooks when a query needs to be re-parsed/planned.
77 * This is especially useful if the types of parameters might change
78 * from time to time, since it can replace the need to supply a fixed
79 * list of parameter types to the parser.
81 * Notice that the paramFetch and paramCompile hooks are actually passed
82 * the ParamListInfo struct's address; they can therefore access all
83 * three of the "arg" fields, and the distinction between paramFetchArg
84 * and paramCompileArg is rather arbitrary.
87 #define PARAM_FLAG_CONST 0x0001 /* parameter is constant */
100 int paramid,
bool speculative,
105 Datum *resv,
bool *resnull);
118 int numParams;
/* nominal/maximum # of Params represented */
121 * params[] may be of length zero if paramFetch is supplied; otherwise it
122 * must be of length numParams.
131 * ParamExecData entries are used for executor internal parameters
132 * (that is, values being passed into or out of a sub-query). The
133 * paramid of a PARAM_EXEC Param is a (zero-based) index into an
134 * array of ParamExecData records, which is referenced through
135 * es_param_exec_vals or ecxt_param_exec_vals.
137 * If execPlan is not NULL, it points to a SubPlanState node that needs
138 * to be executed to produce the value. (This is done so that we can have
139 * lazy evaluation of InitPlans: they aren't executed until/unless a
140 * result value is needed.) Otherwise the value is assumed to be valid
152/* type of argument for ParamsErrorCallback */
159/* Functions found in src/backend/nodes/params.c */
#define FLEXIBLE_ARRAY_MEMBER
ParamListInfo makeParamList(int numParams)
ParamListInfo copyParamList(ParamListInfo from)
struct ParamListInfoData ParamListInfoData
void(* ParamCompileHook)(ParamListInfo params, Param *param, ExprState *state, Datum *resv, bool *resnull)
struct ParamListInfoData * ParamListInfo
struct ParamsErrorCbData ParamsErrorCbData
Size EstimateParamListSpace(ParamListInfo paramLI)
char * BuildParamLogString(ParamListInfo params, char **knownTextValues, int maxlen)
void SerializeParamList(ParamListInfo paramLI, char **start_address)
struct ParamExternData ParamExternData
ParamExternData *(* ParamFetchHook)(ParamListInfo params, int paramid, bool speculative, ParamExternData *workspace)
void(* ParserSetupHook)(ParseState *pstate, void *arg)
void ParamsErrorCallback(void *arg)
ParamListInfo RestoreParamList(char **start_address)
struct ParamExecData ParamExecData
ParamExternData params[FLEXIBLE_ARRAY_MEMBER]
ParserSetupHook parserSetup
ParamCompileHook paramCompile
ParamFetchHook paramFetch