章 44. 服务器编程接口

目录
44.1. 接口函数
SPI_connect -- 把一个过程与 SPI 管理器连接起来
SPI_finish -- 把一个过程与 SPI 管理器断开
SPI_push --  对 SPI 堆栈进行压栈操作以允许递归的 SPI 使用
SPI_pop -- 弹出 SPI 堆栈以从递归的 SPI 使用中返回
SPI_execute -- 执行一条命令
SPI_exec -- 执行一个读/写命令
SPI_execute_with_args -- 执行一个带有外联参数的命令
SPI_prepare -- 准备一个规划但不立即执行它
SPI_prepare_cursor -- 准备一个语句但不立即执行它
SPI_prepare_params -- 准备一个语句但不立即执行它
SPI_getargcount -- 返回一个SPI_prepare 准备的已准备好语句需要的参数个数
SPI_getargtypeid -- 返回SPI_prepare 准备的已准备好语句的参数的数据类型OID
SPI_is_cursor_plan -- 如果一个SPI_prepare准备的语句可以和 SPI_cursor_open一起使用,则返回true
SPI_execute_plan -- 执行一个SPI_prepare准备的语句
SPI_execute_plan_with_paramlist -- 执行一个SPI_prepare准备的已准备好的语句
SPI_execp -- 以读/写模式执行一个准备的查询规划
SPI_cursor_open -- 用SPI_prepare创建的语句设置一个游标
SPI_cursor_open_with_args -- 使用查询和参数设置一个游标
SPI_cursor_open_with_paramlist -- 使用参数设置一个游标
SPI_cursor_find -- 用名字寻找并执行一个现存的游标
SPI_cursor_fetch -- 从一个游标里抓取一些行
SPI_cursor_move -- 移动一个游标
SPI_scroll_cursor_fetch -- 从一个游标中抓取一些行
SPI_scroll_cursor_move -- 移动一个游标
SPI_cursor_close -- 关闭一个游标
SPI_keepplan -- 保存一个预备语句
SPI_saveplan -- 保存一个预备语句
44.2. 接口支持函数
SPI_fname -- 从指定的字段编号判断字段名字
SPI_fnumber -- 判断声明字段名的字段编号
SPI_getvalue -- 返回声明字段的字符串值
SPI_getbinval -- 返回声明字段的二进制值
SPI_gettype -- 返回声明字段的数据类型名
SPI_gettypeid -- 返回声明字段的数据类型OID
SPI_getrelname -- 返回声明关系的名字
SPI_getnspname -- 返回声明关系的名字空间
44.3. 内存管理
SPI_palloc -- 在上层执行器环境里分配内存
SPI_repalloc -- 在上层执行器环境里重新分配内存
SPI_pfree -- 在上层执行器环境里释放内存
SPI_copytuple -- 在上层执行者环境里制作一个行的拷贝
SPI_returntuple -- 准备把一个行当作 Datum 返回
SPI_modifytuple -- 通过替换一个给出行的选定的字段创建一行
SPI_freetuple -- 释放在上层执行者环境里分配的一行
SPI_freetuptable -- 释放一个由SPI_execute或者类似的函数创建的行集
SPI_freeplan --  释放一个前面保存的预备语句
44.4. 数据改变的可视性
44.5. 例子

服务器编程接口(SPI) 给在用户定义的C函数里面运行SQL 查询的能力。SQL是一套接口函数,用于简化对分析器、 规划器和执行器的访问。SQL还进行一些内存管理的工作。

注意: 过程语言的存在也提供了其它的一些在过程里执行 SQL 命令的方法。 这些语言中的大部分本身就是基于 SPI 的, 因此这份文档可能会对那些语言的用户同样有帮助。

为了避免混淆,将使用术语"函数"(function)来代表 SPI接口函数,用"过程"(procedure) 代表用户用SPI定义的 C 函数。

注意,如果一条通过 SPI 调用的命令失败,那么控制不会返回到你的过程中。 取而代之的是,你的过程执行所在的事务或者子事务全部回滚。 这一点看起来可能很奇怪,因为大多数 SPI 函数的文档里都有错误返回习惯。 不过,那些习惯只适用于在 SPI 函数自己内部检测到的错误。 可以通过在你自己的可能失败的 SPI 调用周围建立一个子事务的方法来在错误之后恢复控制。 目前还没有写这方面的文档,因为所需要的机制仍然在变化。

如果执行成功了,SPI函数返回一个非负结果 (或者通过返回一个整数值或放在全局变量SPI_result里, 像下面描述的那样)。出错时,返回一个负数或NULL结果。

使用 SPI 的源代码文件必须包含头文件executor/spi.h