描述

SPI_prepare 为指定命令创建并返回一个 预备语句，但不执行该命令。该预备语句之后可以使用 SPI_execute_plan 反复执行。

当同一条或相似命令需要反复执行时，通常只做一次解析分析是有利的，而重用 该命令的执行计划也可能进一步带来收益。SPI_prepare 会把命令字符串转换成一个封装了解析分析结果的预备语句。如果发现为每次 执行都生成定制计划并无益处，该预备语句还可用来缓存执行计划。

预备命令可以通过在普通命令原本应写常量的位置写入参数 （$1、$2 等）而得到泛化。这些参数 的实际值会在调用 SPI_execute_plan 时指定。这样， 预备语句就能适用于比无参形式更广泛的场景。

SPI_prepare 返回的计划只能在当前这次过程调用 中使用，因为 SPI_finish 会释放为计划分配的 内存。但可以使用函数 SPI_keepplan 或 SPI_saveplan 把预备语句保存 得更久。

参数

返回值

SPI_prepare 返回一个指向 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，分别强制使用通用计划或定制计划。

该函数只能从已连接的过程调用。

SPIPlanPtr 这个名字多少带有历史色彩，因为该数据结构已不再 必然包含执行计划。

SPIPlanPtr 在 spi.h 中被声明为指向不 透明结构体类型的指针。尝试直接访问其内容并不明智，因为这会让你的代码在 PostgreSQL 后续版本中更容易失效。