描述

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

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

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

SPI_prepare 返回的语句只能在当前这次 C 函数调用中使用，因为 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，分别强制使用通用计划或定制计划。

尽管预备语句的主要目的在于避免重复进行解析分析和规划，但只要语句中使用的数据库对象自上次使用该预备语句以来发生了定义性（DDL）变更，PostgreSQL 就会在再次使用前强制重新分析并重新规划该语句。此外，如果 search_path 的值在两次使用之间发生变化，该语句也会基于新的 search_path 重新解析。（后一种行为是从 PostgreSQL 9.3 开始引入的。）有关预备语句行为的更多信息，请参见 PREPARE。

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

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

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