SPI_prepare

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

Synopsis

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

Description

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

当相同或相似的命令要重复执行时，通常只执行一次分析分析通常是有利的，此外，对于命令重复使用执行计划也可能是有利的。 SPI_prepare将命令字符串转换为准备好的语句，该语句封装了解析分析的结果。如果发现为每个执行生成自定义计划无济于事，则 prepared 语句还提供了一个缓存执行计划的地方。

可以通过编写参数($1，$2等)代替常规命令中的常量来概括准备好的命令。然后在调用SPI_execute_plan时指定参数的实际值。与没有参数的情况相比，这可以使准备好的命令在更广泛的情况下使用。

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

Arguments

• const char * command

  • command string

• int nargs

  • Importing 参数的数量($1，$2等)

• Oid * argtypes

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

Return Value

SPI_prepare返回指向SPIPlan的非空指针，该指针是代表准备好的语句的不透明结构。发生错误时，将返回NULL，并将SPI_result设置为SPI_execute使用的相同错误代码之一，但如果* command 为NULL或 nargs 小于 0 或 nargs 大于 0 且 argtypes *为NULL。

Notes

如果未定义任何参数，则将在首次使用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。

此函数只能从连接的过程中调用。

SPIPlanPtr在spi.h中被声明为指向不透明结构类型的指针。尝试直接访问其内容是不明智的，因为这会使您的代码更有可能在 PostgreSQL 的 Future 版本中被破坏。

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