Postgresql 中文操作指南

34.8. The Fast-Path Interface #

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

Tip

此接口有些过时，因为可以通过设置预定义语句来定义函数调用以获得类似的性能和更强大的功能。然后，使用二进制方式传输参数和结果来执行此语句，代替快速路径函数调用。

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 值发送给客户端计算机；请注意，对于任何允许的结果大小，4 字节整数将被发送到 *result_buf 中。当 result_is_int 为 0 时，服务器发送的二进制格式字节字符串将原样返回。（在这种情况下，最好将 result_buf 视为 void * 类型。）

PQfn 始终返回有效的 PGresult 指针，其中 PGRES_COMMAND_OK 表示成功， PGRES_FATAL_ERROR 表示遇到某些问题。使用结果之前，应检查结果状态。在不再需要 PGresult 时，调用方负责使用 PQclear 释放它。

要将 NULL 参数传递给函数，请将该参数结构的 len 字段设置为 -1；则 isint 和 u 字段将不相关。

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

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