Postgresql 中文操作指南
Description
SPI_prepare 创建并返回针对指定命令的准备好的语句，但不会执行该命令。随后可以使用 SPI_execute_plan 重复执行已准备好的语句。
SPI_prepare creates and returns a prepared statement for the specified command, but doesn’t execute the command. The prepared statement can later be executed repeatedly using SPI_execute_plan.
如果应重复执行相同或类似的命令，通常比较有利执行一次解析分析，并可能进一步有利于重复使用该命令的执行计划。 SPI_prepare 将命令字符串转换为包含解析分析结果的已准备好的语句。如果发现为每次执行生成自定义计划并非有所帮助，则已准备好的语句还提供了一个用于缓存执行计划的位置。
When the same or a similar command is to be executed repeatedly, it is generally advantageous to perform parse analysis only once, and might furthermore be advantageous to re-use an execution plan for the command. SPI_prepare converts a command string into a prepared statement that encapsulates the results of parse analysis. The prepared statement also provides a place for caching an execution plan if it is found that generating a custom plan for each execution is not helpful.
通过编写参数（ $1 、 $2 等）替代正常命令中的常量，可使已准备好的命令通用化。然后在调用 SPI_execute_plan 时指定参数的实际值。这允许在比没有参数时更广泛的情境中使用已准备好的命令。
A prepared command can be generalized by writing parameters ($1, $2, etc.) in place of what would be constants in a normal command. The actual values of the parameters are then specified when SPI_execute_plan is called. This allows the prepared command to be used over a wider range of situations than would be possible without parameters.
SPI_prepare 返回的语句只能用于 C 函数的当前调用，因为 SPI_finish 释放了为该语句分配的内存。但可以使用函数 SPI_keepplan 或 SPI_saveplan 保存该语句更长时间。
The statement returned by SPI_prepare can be used only in the current invocation of the C function, since SPI_finish frees memory allocated for such a statement. But the statement can be saved for longer using the functions SPI_keepplan or SPI_saveplan.
Arguments
-
const char * _command_
-
command string
-
-
int _nargs_
-
number of input parameters ($1, $2, etc.)
-
-
Oid * _argtypes_
-
pointer to an array containing the OIDs of the data types of the parameters
-
Return Value
SPI_prepare 返回指向 SPIPlan 的非空指针，它是不透明的结构，代表准备好的语句。如果出错，将会返回 NULL ， SPI_result 将设置为 SPI_execute 使用的相同错误代码之一，但 if command 为 NULL ，或 if nargs 小于 0，或 if nargs 大于 0 且 argtypes 为 NULL ，则设置为 SPI_ERROR_ARGUMENT 。
SPI_prepare returns a non-null pointer to an SPIPlan, which is an opaque struct representing a prepared statement. On error, NULL will be returned, and SPI_result will be set to one of the same error codes used by SPI_execute, except that it is set to SPI_ERROR_ARGUMENT if command is NULL, or if nargs is less than 0, or if nargs is greater than 0 and argtypes is NULL.
Notes
如果未定义任何参数，将在 SPI_execute_plan 的首次使用时创建一个泛型计划，并且也用于所有后续执行。如果有参数，则 SPI_execute_plan 的前几次使用将生成特定于所提供参数值的自定计划。在对同一个准备好的语句使用多次之后， SPI_execute_plan 将构建一个泛型计划，如果这不会比自定计划付出太多代价，它将开始使用泛型计划，而不是每次都重新规划。如果此默认行为不合适，您可以向 SPI_prepare_cursor 传递 CURSOR_OPT_GENERIC_PLAN 或 CURSOR_OPT_CUSTOM_PLAN 标志，以强制分别使用泛型计划或自定计划。
If no parameters are defined, a generic plan will be created at the first use of SPI_execute_plan, and used for all subsequent executions as well. If there are parameters, the first few uses of SPI_execute_plan will generate custom plans that are specific to the supplied parameter values. After enough uses of the same prepared statement, SPI_execute_plan will build a generic plan, and if that is not too much more expensive than the custom plans, it will start using the generic plan instead of re-planning each time. If this default behavior is unsuitable, you can alter it by passing the CURSOR_OPT_GENERIC_PLAN or CURSOR_OPT_CUSTOM_PLAN flag to SPI_prepare_cursor, to force use of generic or custom plans respectively.
尽管准备好的语句的重点是避免对语句进行重复的解析分析和计划，但每当语句中使用的数据库对象自上次使用准备好的语句后经历定义 (DDL) 更改时，PostgreSQL 都将强制重新分析和重新规划语句。此外，如果 search_path 的值在前后使用中发生变化，则语句将使用新的 search_path 重新解析。（这种后一种行为自 PostgreSQL 9.3 起是一种新的行为。）有关准备好的语句的行为的更多信息，请参见 PREPARE 。
Although the main point of a prepared statement is to avoid repeated parse analysis and planning of the statement, PostgreSQL will force re-analysis and re-planning of the statement before using it whenever database objects used in the statement have undergone definitional (DDL) changes since the previous use of the prepared statement. Also, if the value of search_path changes from one use to the next, the statement will be re-parsed using the new search_path. (This latter behavior is new as of PostgreSQL 9.3.) See PREPARE for more information about the behavior of prepared statements.
此函数只能从已连接的 C 函数调用。
This function should only be called from a connected C function.
SPIPlanPtr 被声明为 spi.h 中不透明的结构类型的指针。不建议直接尝试访问其内容，因为这样会导致您的代码很可能在 PostgreSQL 的未来修订版本中中断。
SPIPlanPtr is declared as a pointer to an opaque struct type in spi.h. It is unwise to try to access its contents directly, as that makes your code much more likely to break in future revisions of PostgreSQL.
名称 SPIPlanPtr 有些历史性，因为数据结构不再必然包含执行计划。
The name SPIPlanPtr is somewhat historical, since the data structure no longer necessarily contains an execution plan.