↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

支持中的版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发中的版本: 19 / 20devel
已结束支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1
历史版本。 PostgreSQL 13 已结束支持。 2025-11-13. 请参阅 当前版本手册.

33.7. 快速路径接口 #

PostgreSQL 提供一种快速路径接口来向服务器发送简单的函数调用。

提示

此接口已显得有些过时,因为可以通过建立定义函数调用的预备语句,获得相近的性能和更多功能。随后使用二进制格式传输参数和结果来执行该语句,就可以替代快速路径函数调用。

函数 PQfn 请求通过快速路径接口执行服务器函数。

PGresult *PQfn(PGconn *conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct
{
    int len;
    int isint;
    union
    {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;

fnid 参数是要执行函数的 OID。args 和 nargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。)

PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 PQclear 释放 PGresult。

要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isint 和 u 字段便不再相关。(但这仅适用于使用协议 3.0 及更高版本的连接。)

如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。(这仅适用于使用协议 3.0 及更高版本的连接;在协议 2.0 中,既不修改 *result_len,也不修改 *result_buf。)

注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数、窗口函数或过程。

报告文档问题

阅读 上游文档. 反馈更正前请先核对 当前版本手册.