Redrock Postgres 搜索 英文
版本: 9.3 / 9.4 / 9.5 / 9.6 / 10 / 11 / 12 / 13 / 14 / 15 / 16

34.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 字段为真时,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 值传递;请注意,对于允许的结果大小,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

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