2025年9月25日: PostgreSQL 18 发布!
支持的版本: 当前 (18) / 17 / 16 / 15 / 14 / 13
开发版本: devel
不支持的版本: 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

32.8. 快速路径接口 #

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。argsnargs 定义要传递给函数的参数;它们必须与声明的函数参数列表匹配。当参数结构中的 isint 字段为 true 时,u.integer 值将作为指定长度的整数(必须是 2 或 4 字节)发送到服务器;会发生正确的字节交换。当 isint 为 false 时,将发送 *u.ptr 的指定字节数,而不进行任何处理;数据必须符合服务器对函数参数数据类型二进制传输的预期格式。(u.ptr 的声明为 int * 类型是历史原因;最好将其视为 void *。) result_buf 指向用于存放函数返回值的缓冲区。调用者必须分配足够的空间来存储返回值。(没有检查!)实际结果长度(字节)将存储在 result_len 指向的整数中。如果预期返回 2 或 4 字节整数,则将 result_is_int 设置为 1,否则设置为 0。将 result_is_int 设置为 1 会导致 libpq 在必要时进行字节交换,以便将其作为客户端机器的正确 int 值传递;请注意,对于允许的两种结果大小,都会将 4 字节整数传递到 *result_buf 中。当 result_is_int 为 0 时,服务器发送的二进制格式字节字符串将保持不变。(在这种情况下,最好将 result_buf 视为 void * 类型。)

PQfn 始终返回一个有效的 PGresult 指针,状态为 PGRES_COMMAND_OK 表示成功,或 PGRES_FATAL_ERROR 表示遇到问题。在结果使用之前应检查结果状态。调用者负责在使用完 PGresult 后使用 PQclear 清理它。

要将 NULL 参数传递给函数,请将该参数结构中的 len 字段设置为 -1;此时 isintu 字段无关紧要。

如果函数返回 NULL,则将 *result_len 设置为 -1,并且 *result_buf 不会改变。

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

提交更正

如果您在文档中发现任何不正确、与您对特定功能的使用经验不符或需要进一步澄清的内容,请使用 此表单 报告文档问题。