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 不會改變。

請注意,使用此介面無法處理集合值結果。此外,函式必須是普通函式,而不是聚合函式、視窗函式或過程。

提交更正

如果您在文件中發現任何不正確、與您對特定功能的使用經驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。