Postgresql 中文操作指南

SPI_prepare — 准备一条语句，但尚未执行

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 使用的相同错误代码之一，但 if command 为 NULL ，或 if nargs 小于 0，或 if nargs 大于 0 且 argtypes 为 NULL ，则设置为 SPI_ERROR_ARGUMENT 。

如果未定义任何参数，将在 SPI_execute_plan 的首次使用时创建一个泛型计划，并且也用于所有后续执行。如果有参数，则 SPI_execute_plan 的前几次使用将生成特定于所提供参数值的自定计划。在对同一个准备好的语句使用多次之后， SPI_execute_plan 将构建一个泛型计划，如果这不会比自定计划付出太多代价，它将开始使用泛型计划，而不是每次都重新规划。如果此默认行为不合适，您可以向 SPI_prepare_cursor 传递 CURSOR_OPT_GENERIC_PLAN 或 CURSOR_OPT_CUSTOM_PLAN 标志，以强制分别使用泛型计划或自定计划。

尽管准备好的语句的重点是避免对语句进行重复的解析分析和计划，但每当语句中使用的数据库对象自上次使用准备好的语句后经历定义 (DDL) 更改时，PostgreSQL 都将强制重新分析和重新规划语句。此外，如果 search_path 的值在前后使用中发生变化，则语句将使用新的 search_path 重新解析。（这种后一种行为自 PostgreSQL 9.3 起是一种新的行为。）有关准备好的语句的行为的更多信息，请参见 PREPARE 。

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

SPIPlanPtr 被声明为 spi.h 中不透明的结构类型的指针。不建议直接尝试访问其内容，因为这样会导致您的代码很可能在 PostgreSQL 的未来修订版本中中断。

名称 SPIPlanPtr 有些历史性，因为数据结构不再必然包含执行计划。