说明

SPI_prepare 创建并返回指定命令的已准备语句，但不执行该命令。稍后可以使用 SPI_execute_plan 重复执行已准备语句。

如果要重复执行相同或类似的命令，通常有利于仅执行一次解析分析，并且可能有利于重新使用该命令的执行计划。 SPI_prepare 将命令字符串转换为已准备语句，该语句封装了解析分析的结果。如果发现为每次执行生成自定义计划没有帮助，已准备语句还提供了一个用于缓存执行计划的位置。

可以通过在普通命令中常量的位置编写参数（$1、$2 等）来概括已准备命令。然后在调用 SPI_execute_plan 时指定参数的实际值。这允许已准备命令用于比没有参数时更广泛的情况。

SPI_prepare 返回的语句只能在 C 函数的当前调用中使用，因为 SPI_finish 会释放为该语句分配的内存。但可以使用函数 SPI_keepplan 或 SPI_saveplan 将该语句保存更长时间。

参数

返回值

SPI_prepare 返回指向 SPIPlan 的非空指针，SPIPlan 是表示已准备语句的不透明结构。如果出错，将返回 NULL，并将 SPI_result 设置为 SPI_execute 使用的相同错误代码之一，但如果 command 为 NULL，或者如果 nargs 小于 0，或者如果 nargs 大于 0 而 argtypes 为 NULL，则将其设置为 SPI_ERROR_ARGUMENT。

注释

如果未定义任何参数，则在首次使用 SPI_execute_plan 时将创建一个通用计划，并将其用于所有后续执行。如果存在参数，则 SPI_execute_plan 的前几次使用将生成特定于所提供参数值的自定计划。在对同一预处理语句使用足够多次后，SPI_execute_plan 将构建一个通用计划，如果该计划并不比自定计划昂贵太多，它将开始使用通用计划，而不是每次都重新计划。如果此默认行为不合适，则可以通过将 CURSOR_OPT_GENERIC_PLAN 或 CURSOR_OPT_CUSTOM_PLAN 标志传递给 SPI_prepare_cursor 来更改它，以分别强制使用通用计划或自定计划。

尽管预处理语句的主要目的是避免对语句进行重复的解析分析和计划，但 PostgreSQL 会在使用语句之前强制重新分析和重新计划语句，只要语句中使用的数据库对象自上次使用预处理语句后发生了定义 (DDL) 更改。此外，如果 search_path 的值从一次使用更改为下一次使用，则将使用新的 search_path 重新解析语句。（此后一行为 PostgreSQL 9.3 中的新行为。）有关预处理语句的行为的更多信息，请参见 PREPARE。

此函数只能从已连接的 C 函数调用。

SPIPlanPtr 在 spi.h 中被声明为指向不透明结构类型的指针。尝试直接访问其内容是不明智的，因为这会使你的代码在 PostgreSQL 的未来版本中更容易中断。

名称 SPIPlanPtr 有点历史意义，因为数据结构不再一定包含执行计划。