SPI_prepare

SPI_prepare — 预处理语句，不执行

概要

SPIPlanPtr SPI_prepare(const char * command, int nargs, Oid * argtypes)

说明

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

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

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

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

参数

const char * command

命令字符串

int nargs

输入参数的数量（$1、$2 等）

Oid * argtypes

指向包含参数的数据类型的 的数组的指针

返回值

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重新解析语句。（此后一行为PostgreSQL9.3 中的新行为。）有关预处理语句的行为的更多信息，请参见PREPARE。

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

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

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