章 45. 服务器编程接口
- 目录
- 45.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 -- 保存一个预备语句
- 45.2. 接口支持函数
-
- SPI_fname -- 为指定的列号确定列名
- SPI_fnumber -- 为一个指定的列名确定列号
- SPI_getvalue -- 返回指定列的字符串值
- SPI_getbinval -- 返回指定列的二进制值
- SPI_gettype -- 返回指定列的数据类型名称
- SPI_gettypeid -- 返回指定列的数据类型的OID
- SPI_getrelname -- 返回指定关系的名称
- SPI_getnspname -- 返回指定关系的名字空间
- 45.3. 内存管理
-
- SPI_palloc -- 在上层执行器上下文中分配内存
- SPI_repalloc -- 在上层执行器上下文中重分配内存
- SPI_pfree -- 在上层执行器上下文中释放内存
- SPI_copytuple -- 在上层执行器上下文中创建一行的拷贝
- SPI_returntuple -- 准备把一个元组返回为一个 Datum
- SPI_modifytuple -- 通过替换一个给定行的选定域来创建一行
- SPI_freetuple -- 释放一个在上层执行器上下文中分配的行
- SPI_freetuptable -- 释放一个由
SPI_execute
或者类似函数创建的行集合 - SPI_freeplan -- 释放一个之前保存的预备语句
- 45.4. 数据改变的可见性
- 45.5. 例子
服务器编程接口(SPI)给予用户定义C函数编写者在其函数内运行SQL命令的能力。SPI是一组接口函数,它们可以简化对解析器、规划器和执行器的访问。SPI也做一些内存管理。
注意: 可用的过程语言提供了多种方法从过程中执行 SQL 命令。大部分这些设施都是基于 SPI 的,因此这个文档也对那些语言的用户有用。
为了避免误解,我们在谈及SPI接口函数时使用术语"函数",而谈及使用SPI的用户定义的 C 函数时使用术语"过程"。
注意如果一个通过 SPI 调用的命令失败,那么控制将会返回到你的过程中。当然啦,你的过程所在的事务或者子事务将被回滚(这可能看起来令人惊讶,因为据文档所说 SPI 函数大多数都有错误返回约定。但是那些约定只适用于在 SPI 函数本身内部检测到的错误)。通过在可能失败的 SPI 调用周围建立自己的子事务可以在错误之后恢复控制。当前文档中并未记载这些,因为所需的机制仍然在变化中。
SPI成功时返回一个非负结果(要么通过一个返回的整数值,要么如下所述放在全局变量SPI_result中)。错误时,将会返回一个负结果或者NULL。
使用 SPI 的源代码文件必须包括头文件executor/spi.h。