-with-args">
+extended">
- SPI_execute_with_args
+ SPI_execute_extended
3
- SPI_execute_with_args
+ SPI_execute_extended
execute a command with out-of-line parameters
-int SPI_execute_with_args(const char *
command,
- int
nargs, Oid *
argtypes,
- Datum *
values, const char *
nulls,
- bool
read_only, long
count)
+int SPI_execute_extended(const char *
command,
+ const SPIExecuteOptions *
options)
Description
- SPI_execute_with_args executes a command that might
+ SPI_execute_extended executes a command that might
include references to externally supplied parameters. The command text
- refers to a parameter as $n, and
- the call specifies data types and values for each such symbol.
-
read_only and
count have
- the same interpretation as in SPI_execute.
+ refers to a parameter as $n,
+ and the
options->params object (if supplied)
+ provides values and type information for each such symbol.
+ Various execution options can be specified
+ in the
options struct, too.
- The main advantage of this routine compared to
- SPI_execute is that data values can be inserted
- into the command without tedious quoting/escaping, and thus with much
- less risk of SQL-injection attacks.
+ The
options->params object should normally
+ mark each parameter with the PARAM_FLAG_CONST flag,
+ since a one-shot plan is always used for the query.
- Similar results can be achieved with SPI_prepare followed by
- SPI_execute_plan; however, when using this function
- the query plan is always customized to the specific parameter values
- provided.
- For one-time query execution, this function should be preferred.
- If the same command is to be executed with many different parameters,
- either method might be faster, depending on the cost of re-planning
- versus the benefit of custom plans.
+ If
options->dest is not NULL, then result
+ tuples are passed to that object as they are generated by the executor,
+ instead of being accumulated in SPI_tuptable. Using
+ a caller-supplied DestReceiver object is particularly
+ helpful for queries that might generate many tuples, since the data can
+ be processed on-the-fly instead of being accumulated in memory.
+
const SPIExecuteOptions * options
- number of input parameters ($1, $2, etc.)
+ struct containing optional arguments
+
+
+ Callers should always zero out the entire
options+ struct, then fill whichever fields they want to set. This ensures forward
+ compatibility of code, since any fields that are added to the struct in
+ future will be defined to behave backwards-compatibly if they are zero.
+ The currently available
options fields are:
+
+
- an array of length
nargs, containing the
-
OIDs of the data types of the parameters
+ data structure containing query parameter types and values; NULL if none
- an array of length
nargs, containing the actual
- parameter values
-
+
true for read-only execution
- an array of length
nargs, describing which
- parameters are null
+ true prevents SPI from managing snapshots for
+ execution of the query; use with extreme caution
+
+
+
+
- SPI_execute_with_args assumes that no parameters
- are null. Otherwise, each entry of the
nulls- array should be ' ' if the corresponding parameter
- value is non-null, or 'n' if the corresponding parameter
- value is null. (In the latter case, the actual value in the
- corresponding
values entry doesn't matter.) Note
- that
nulls is not a text string, just an array:
- it does not need a '\0' terminator.
+ maximum number of rows to return,
+ or 0 for no limit
-
true for read-only execution+ DestReceiver object that will receive any tuples
+ emitted by the query; if NULL, result tuples are accumulated into
+ a SPI_tuptable structure, as
+ in SPI_execute
+
- maximum number of rows to return,
- or 0 for no limit
+ This field is present for consistency
+ with SPI_execute_plan_extended, but it is
+ ignored, since the plan used
+ by SPI_execute_extended is never saved.
+ When
options->dest is NULL,
SPI_processed and
SPI_tuptable are set as in
- SPI_execute if successful.
+ SPI_execute.
+ When
options->dest is not NULL,
+ SPI_processed is set to zero and
+ SPI_tuptable is set to NULL. If a tuple count
+ is required, the caller's DestReceiver object must
+ calculate it.
-receiver">
-
SPI_execute_with_receiver+args">
- SPI_execute_with_receiver
+ SPI_execute_with_args
3
- SPI_execute_with_receiver
+ SPI_execute_with_args
execute a command with out-of-line parameters
- int SPI_execute_with_receiver(const char *
command,
+int SPI_execute_with_args(const char *
command,
+ int
nargs, Oid *
argtypes,
+ Datum *
values, const char *
nulls,
+ bool
read_only, long
count)
Description
- SPI_execute_with_receiver executes a command that might
+ SPI_execute_with_args executes a command that might
include references to externally supplied parameters. The command text
- refers to a parameter as $n,
- and the
params object provides values and type
- information for each such symbol.
+ refers to a parameter as $n, and
+ the call specifies data types and values for each such symbol.
the same interpretation as in SPI_execute.
- If
dest is not NULL, then result tuples are passed
- to that object as they are generated by the executor, instead of being
- accumulated in SPI_tuptable. Using a
- caller-supplied DestReceiver object is particularly
- helpful for queries that might generate many tuples, since the data can
- be processed on-the-fly instead of being accumulated in memory.
+ The main advantage of this routine compared to
+ SPI_execute is that data values can be inserted
+ into the command without tedious quoting/escaping, and thus with much
+ less risk of SQL-injection attacks.
- The
params object should normally mark each
- parameter with the PARAM_FLAG_CONST flag, since
- a one-shot plan is always used for the query.
+ Similar results can be achieved with SPI_prepare followed by
+ SPI_execute_plan; however, when using this function
+ the query plan is always customized to the specific parameter values
+ provided.
+ For one-time query execution, this function should be preferred.
+ If the same command is to be executed with many different parameters,
+ either method might be faster, depending on the cost of re-planning
+ versus the benefit of custom plans.
- data structure containing parameter types and values; NULL if none
+ number of input parameters ($1, $2, etc.)
-
true for read-only execution+ an array of length
nargs, containing the
+
OIDs of the data types of the parameters
+
- maximum number of rows to return,
- or 0 for no limit
+ an array of length
nargs, containing the actual
+ parameter values
- DestReceiver object that will receive any tuples
- emitted by the query; if NULL, tuples are returned
- in SPI_tuptable
+ an array of length
nargs, describing which
+ parameters are null
+
+
+ SPI_execute_with_args assumes that no parameters
+ are null. Otherwise, each entry of the
nulls+ array should be ' ' if the corresponding parameter
+ value is non-null, or 'n' if the corresponding parameter
+ value is null. (In the latter case, the actual value in the
+ corresponding
values entry doesn't matter.) Note
+ that
nulls is not a text string, just an array:
+ it does not need a '\0' terminator.
+
+
+
+
+
+
+
true for read-only execution+
+
+
+
+
+ maximum number of rows to return,
+ or 0 for no limit
SPI_processed and
SPI_tuptable are set as in
- SPI_execute.
- SPI_processed is set to zero and
- SPI_tuptable is set to NULL. If a tuple count
- is required, the caller's DestReceiver object must
- calculate it.
+ SPI_execute if successful.
+ When
options->dest is NULL,
SPI_processed and
SPI_tuptable are set as in
SPI_execute_plan.
+ When
options->dest is not NULL,
SPI_processed is set to zero and
SPI_tuptable is set to NULL. If a tuple count
is required, the caller's DestReceiver object must
The passed-in parameter data will be copied into the cursor's portal, so it
can be freed while the cursor still exists.
+
+ This function is now deprecated in favor
+ of SPI_cursor_parse_open, which provides equivalent
+ functionality using a more modern API for handling query parameters.
+
--with-paramlist">
-
SPI_cursor_parse_open_with_paramlist+
- SPI_cursor_parse_open_with_paramlist
+ SPI_cursor_parse_open
3
- SPI_cursor_parse_open_with_paramlist
- set up a cursor using a query and parameters
+ SPI_cursor_parse_open
+ set up a cursor using a query string and parameters
-Portal SPI_cursor_parse_open_with_paramlist(const char *
name,
+Portal SPI_cursor_parse_open(const char *
name,
+ const SPIParseOpenOptions *
options)
Description
- SPI_cursor_parse_open_with_paramlist sets up a cursor
- (internally, a portal) that will execute the specified query. This
- function is equivalent to SPI_cursor_open_with_args
- except that any parameters referenced by the query are provided by
- a ParamListInfo object, rather than in ad-hoc arrays.
+ SPI_cursor_parse_open sets up a cursor
+ (internally, a portal) that will execute the specified query string.
+ This is comparable to SPI_prepare_cursor followed
+ by SPI_cursor_open_with_paramlist, except that
+ parameter references within the query string are handled entirely by
+ supplying a ParamListInfo object.
+
+
+ For one-time query execution, this function should be preferred
+ over SPI_prepare_cursor followed by
+ SPI_cursor_open_with_paramlist.
+ If the same command is to be executed with many different parameters,
+ either method might be faster, depending on the cost of re-planning
+ versus the benefit of custom plans.
- The
params object should normally mark each
- parameter with the PARAM_FLAG_CONST flag, since
- a one-shot plan is always used for the query.
+ The
options->params object should normally
+ mark each parameter with the PARAM_FLAG_CONST flag,
+ since a one-shot plan is always used for the query.
+
const SPIParseOpenOptions * options
- data structure containing parameter types and values; NULL if none
+ struct containing optional arguments
+
+
+ Callers should always zero out the entire
options+ struct, then fill whichever fields they want to set. This ensures forward
+ compatibility of code, since any fields that are added to the struct in
+ future will be defined to behave backwards-compatibly if they are zero.
+ The currently available
options fields are:
+
+
-
true for read-only execution+ data structure containing query parameter types and values; NULL if none
+
+
+
+
+
true for read-only execution+
+
return SPI_execute(src, false, tcount);
}
+/* Parse, plan, and execute a query string, with extensible options */
+int
+SPI_execute_extended(const char *src,
+ const SPIExecuteOptions *options)
+{
+ int res;
+ _SPI_plan plan;
+
+ if (src == NULL || options == NULL)
+ return SPI_ERROR_ARGUMENT;
+
+ res = _SPI_begin_call(true);
+ if (res < 0)
+ return res;
+
+ memset(&plan, 0, sizeof(_SPI_plan));
+ plan.magic = _SPI_PLAN_MAGIC;
+ plan.parse_mode = RAW_PARSE_DEFAULT;
+ plan.cursor_options = CURSOR_OPT_PARALLEL_OK;
+ if (options->params)
+ {
+ plan.parserSetup = options->params->parserSetup;
+ plan.parserSetupArg = options->params->parserSetupArg;
+ }
+
+ _SPI_prepare_oneshot_plan(src, &plan);
+
+ res = _SPI_execute_plan(&plan, options->params,
+ InvalidSnapshot, InvalidSnapshot,
+ options->read_only, options->no_snapshots,
+ true, options->tcount,
+ options->dest, options->owner);
+
+ _SPI_end_call(true);
+ return res;
+}
+
/* Execute a previously prepared plan */
int
SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls,
return res;
}
-/*
- * SPI_execute_with_receiver -- plan and execute a query with arguments
- *
- * This is the same as SPI_execute_with_args except that parameters are
- * supplied through a ParamListInfo, and (if dest isn't NULL) we send
- * result tuples to the caller-supplied DestReceiver rather than through
- * the usual SPI output arrangements.
- */
-int
-SPI_execute_with_receiver(const char *src,
- ParamListInfo params,
- bool read_only, long tcount,
- DestReceiver *dest)
-{
- int res;
- _SPI_plan plan;
-
- if (src == NULL || tcount < 0)
- return SPI_ERROR_ARGUMENT;
-
- res = _SPI_begin_call(true);
- if (res < 0)
- return res;
-
- memset(&plan, 0, sizeof(_SPI_plan));
- plan.magic = _SPI_PLAN_MAGIC;
- plan.parse_mode = RAW_PARSE_DEFAULT;
- plan.cursor_options = CURSOR_OPT_PARALLEL_OK;
- if (params)
- {
- plan.parserSetup = params->parserSetup;
- plan.parserSetupArg = params->parserSetupArg;
- }
-
- _SPI_prepare_oneshot_plan(src, &plan);
-
- res = _SPI_execute_plan(&plan, params,
- InvalidSnapshot, InvalidSnapshot,
- read_only, false,
- true, tcount,
- dest, NULL);
-
- _SPI_end_call(true);
- return res;
-}
-
SPIPlanPtr
SPI_prepare(const char *src, int nargs, Oid *argtypes)
{
return SPI_cursor_open_internal(name, plan, params, read_only);
}
-/*
- * SPI_cursor_parse_open_with_paramlist()
- *
- * Same as SPI_cursor_open_with_args except that parameters (if any) are passed
- * as a ParamListInfo, which supports dynamic parameter set determination
- */
+/* Parse a query and open it as a cursor */
Portal
-SPI_cursor_parse_open_with_paramlist(const char *name,
- const char *src,
- ParamListInfo params,
- bool read_only, int cursorOptions)
+SPI_cursor_parse_open(const char *name,
+ const char *src,
+ const SPIParseOpenOptions *options)
{
Portal result;
_SPI_plan plan;
- if (src == NULL)
- elog(ERROR, "SPI_cursor_parse_open_with_paramlist called with invalid arguments");
+ if (src == NULL || options == NULL)
+ elog(ERROR, "SPI_cursor_parse_open called with invalid arguments");
SPI_result = _SPI_begin_call(true);
if (SPI_result < 0)
- elog(ERROR, "SPI_cursor_parse_open_with_paramlist called while not connected");
+ elog(ERROR, "SPI_cursor_parse_open called while not connected");
memset(&plan, 0, sizeof(_SPI_plan));
plan.magic = _SPI_PLAN_MAGIC;
plan.parse_mode = RAW_PARSE_DEFAULT;
- plan.cursor_options = cursorOptions;
- if (params)
+ plan.cursor_options = options->cursorOptions;
+ if (options->params)
{
- plan.parserSetup = params->parserSetup;
- plan.parserSetupArg = params->parserSetupArg;
+ plan.parserSetup = options->params->parserSetup;
+ plan.parserSetupArg = options->params->parserSetupArg;
}
_SPI_prepare_plan(src, &plan);
/* We needn't copy the plan; SPI_cursor_open_internal will do so */
- result = SPI_cursor_open_internal(name, &plan, params, read_only);
+ result = SPI_cursor_open_internal(name, &plan,
+ options->params, options->read_only);
/* And clean up */
_SPI_end_call(true);
int cursorOptions;
} SPIPrepareOptions;
-/* Optional arguments for SPI_execute_plan_extended */
+/* Optional arguments for SPI_execute[_plan]_extended */
typedef struct SPIExecuteOptions
{
ParamListInfo params;
ResourceOwner owner;
} SPIExecuteOptions;
+/* Optional arguments for SPI_cursor_parse_open */
+typedef struct SPIParseOpenOptions
+{
+ ParamListInfo params;
+ int cursorOptions;
+ bool read_only;
+} SPIParseOpenOptions;
+
/* Plans are opaque structs for standard users of SPI */
typedef struct _SPI_plan *SPIPlanPtr;
extern int SPI_connect_ext(int options);
extern int SPI_finish(void);
extern int SPI_execute(const char *src, bool read_only, long tcount);
+extern int SPI_execute_extended(const char *src,
+ const SPIExecuteOptions *options);
extern int SPI_execute_plan(SPIPlanPtr plan, Datum *Values, const char *Nulls,
bool read_only, long tcount);
extern int SPI_execute_plan_extended(SPIPlanPtr plan,
int nargs, Oid *argtypes,
Datum *Values, const char *Nulls,
bool read_only, long tcount);
-extern int SPI_execute_with_receiver(const char *src,
- ParamListInfo params,
- bool read_only, long tcount,
- DestReceiver *dest);
extern SPIPlanPtr SPI_prepare(const char *src, int nargs, Oid *argtypes);
extern SPIPlanPtr SPI_prepare_cursor(const char *src, int nargs, Oid *argtypes,
int cursorOptions);
bool read_only, int cursorOptions);
extern Portal SPI_cursor_open_with_paramlist(const char *name, SPIPlanPtr plan,
ParamListInfo params, bool read_only);
-extern Portal SPI_cursor_parse_open_with_paramlist(const char *name,
- const char *src,
- ParamListInfo params,
- bool read_only,
- int cursorOptions);
+extern Portal SPI_cursor_parse_open(const char *name,
+ const char *src,
+ const SPIParseOpenOptions *options);
extern Portal SPI_cursor_find(const char *name);
extern void SPI_cursor_fetch(Portal portal, bool forward, long count);
extern void SPI_cursor_move(Portal portal, bool forward, long count);
Oid restype;
int32 restypmod;
char *querystr;
+ SPIExecuteOptions options;
/*
* Evaluate the string expression after the EXECUTE keyword. Its
exec_eval_cleanup(estate);
/* Execute query, passing params if necessary */
- rc = SPI_execute_with_receiver(querystr,
- exec_eval_using_params(estate,
- stmt->params),
- estate->readonly_func,
- 0,
- treceiver);
+ memset(&options, 0, sizeof(options));
+ options.params = exec_eval_using_params(estate,
+ stmt->params);
+ options.read_only = estate->readonly_func;
+ options.dest = treceiver;
+
+ rc = SPI_execute_extended(querystr, &options);
if (rc < 0)
- elog(ERROR, "SPI_execute_with_receiver failed executing query \"%s\": %s",
+ elog(ERROR, "SPI_execute_extended failed executing query \"%s\": %s",
querystr, SPI_result_code_string(rc));
}
char *querystr;
int exec_res;
ParamListInfo paramLI;
+ SPIExecuteOptions options;
MemoryContext stmt_mcontext = get_stmt_mcontext(estate);
/*
* Execute the query without preparing a saved plan.
*/
paramLI = exec_eval_using_params(estate, stmt->params);
- exec_res = SPI_execute_with_receiver(querystr, paramLI,
- estate->readonly_func, 0, NULL);
+
+ memset(&options, 0, sizeof(options));
+ options.params = paramLI;
+ options.read_only = estate->readonly_func;
+
+ exec_res = SPI_execute_extended(querystr, &options);
switch (exec_res)
{
break;
default:
- elog(ERROR, "SPI_execute_with_receiver failed executing query \"%s\": %s",
+ elog(ERROR, "SPI_execute_extended failed executing query \"%s\": %s",
querystr, SPI_result_code_string(exec_res));
break;
}
Oid restype;
int32 restypmod;
char *querystr;
+ SPIParseOpenOptions options;
MemoryContext stmt_mcontext = get_stmt_mcontext(estate);
/*
exec_eval_cleanup(estate);
/*
- * Open an implicit cursor for the query. We use
- * SPI_cursor_parse_open_with_paramlist even when there are no params,
- * because this avoids making and freeing one copy of the plan.
+ * Open an implicit cursor for the query. We use SPI_cursor_parse_open
+ * even when there are no params, because this avoids making and freeing
+ * one copy of the plan.
*/
- portal = SPI_cursor_parse_open_with_paramlist(portalname,
- querystr,
- exec_eval_using_params(estate,
- params),
- estate->readonly_func,
- cursorOptions);
+ memset(&options, 0, sizeof(options));
+ options.params = exec_eval_using_params(estate, params);
+ options.cursorOptions = cursorOptions;
+ options.read_only = estate->readonly_func;
+
+ portal = SPI_cursor_parse_open(portalname, querystr, &options);
if (portal == NULL)
elog(ERROR, "could not open implicit cursor for query \"%s\": %s",
projects / postgresql.git / commitdiff