向伺服器提交命令並等待結果。

PGresult *PQexec(PGconn *conn, const char *command);

返回一個 PGresult 指標，也可能返回一個空指標。通常會返回非空指標，除非在記憶體不足或嚴重錯誤（例如無法將命令傳送到伺服器）的情況下。應呼叫 PQresultStatus 函式檢查返回值的任何錯誤（包括空指標的值，在這種情況下它將返回 PGRES_FATAL_ERROR）。使用 PQerrorMessage 獲取有關此類錯誤的更多資訊。

向伺服器提交命令並等待結果，能夠將引數與 SQL 命令文字分開傳遞。

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

PQexecParams 類似於 PQexec，但提供額外的功能：引數值可以與命令字串本身分開指定，並且可以請求文字或二進位制格式的查詢結果。

函式引數是

提交建立具有給定引數的預處理語句的請求，並等待完成。

PGresult *PQprepare(PGconn *conn,
                    const char *stmtName,
                    const char *query,
                    int nParams,
                    const Oid *paramTypes);

PQprepare 建立一個預處理語句，供以後使用 PQexecPrepared 執行。此功能允許命令重複執行而無需每次都進行解析和規劃；有關詳細資訊，請參閱 PREPARE。

此函式從 query 字串建立名為 stmtName 的預處理語句，該字串必須包含單個 SQL 命令。stmtName 可以是 "" 以建立未命名的語句，在這種情況下，任何預先存在的未命名語句都會自動替換；否則，如果語句名稱已在當前會話中定義，則會出錯。如果使用任何引數，它們在查詢中以 $1、$2 等形式引用。nParams 是陣列 paramTypes[] 中預先指定型別的引數數量。（當 nParams 為零時，陣列指標可以為 NULL。）paramTypes[] 透過 OID 指定要分配給引數符號的資料型別。如果 paramTypes 為 NULL，或者陣列中的任何特定元素為零，則伺服器以與處理無型別文字字串相同的方式推斷引數符號的資料型別。此外，查詢可以使用編號高於 nParams 的引數符號；也將推斷這些符號的資料型別。（有關如何查詢推斷的資料型別的方法，請參閱 PQdescribePrepared。）

與 PQexec 一樣，結果通常是一個 PGresult 物件，其內容指示伺服器端的成功或失敗。空結果表示記憶體不足或根本無法傳送命令。使用 PQerrorMessage 獲取有關此類錯誤的更多資訊。

傳送執行具有給定引數的預處理語句的請求，並等待結果。

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPrepared 類似於 PQexecParams，但要執行的命令是透過命名先前準備好的語句而不是給出查詢字串來指定的。此功能允許重複使用的命令只解析和規劃一次，而不是每次執行時都解析和規劃。該語句必須已在當前會話中準備好。

引數與 PQexecParams 相同，只是給出了預處理語句的名稱而不是查詢字串，並且 paramTypes[] 引數不存在（因為在建立預處理語句時已確定其引數型別，所以不需要它）。

提交獲取指定預處理語句資訊的請求，並等待完成。

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

PQdescribePrepared 允許應用程式獲取有關先前預處理語句的資訊。

stmtName 可以是 "" 或 NULL 以引用未命名的語句，否則它必須是現有預處理語句的名稱。成功時，將返回一個狀態為 PGRES_COMMAND_OK 的 PGresult。函式 PQnparams 和 PQparamtype 可以應用於此 PGresult 以獲取有關預處理語句引數的資訊，並且函式 PQnfields、PQfname、PQftype 等提供有關語句結果列（如果有）的資訊。

提交獲取指定遊標資訊（portal）的請求，並等待完成。

PGresult *PQdescribePortal(PGconn *conn, const char *portalName);

PQdescribePortal 允許應用程式獲取有關先前建立的遊標的資訊。（libpq 不提供對遊標的任何直接訪問，但您可以使用此函式檢查使用 DECLARE CURSOR SQL 命令建立的遊標的屬性。）

portalName 可以是 "" 或 NULL 以引用未命名的遊標，否則它必須是現有遊標的名稱。成功時，將返回一個狀態為 PGRES_COMMAND_OK 的 PGresult。函式 PQnfields、PQfname、PQftype 等可以應用於此 PGresult 以獲取有關遊標結果列（如果有）的資訊。

提交關閉指定預處理語句的請求，並等待完成。

PGresult *PQclosePrepared(PGconn *conn, const char *stmtName);

PQclosePrepared 允許應用程式關閉先前準備好的語句。關閉語句會釋放伺服器上所有相關的資源，並允許其名稱被重用。

stmtName 可以是 "" 或 NULL 以引用未命名的語句。如果不存在此名稱的語句，則操作為空操作。成功時，將返回狀態為 PGRES_COMMAND_OK 的 PGresult。

提交關閉指定遊標的請求，並等待完成。

PGresult *PQclosePortal(PGconn *conn, const char *portalName);

PQclosePortal 允許應用程式觸發關閉先前建立的遊標。（libpq 不提供對遊標的任何直接訪問，但您可以使用此函式關閉使用 DECLARE CURSOR SQL 命令建立的遊標。）

portalName 可以是 "" 或 NULL 以引用未命名的遊標。如果不存在此名稱的遊標，則操作為空操作。成功時，將返回狀態為 PGRES_COMMAND_OK 的 PGresult。

返回命令的結果狀態。

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatus 可以返回以下值之一

如果結果狀態是 PGRES_TUPLES_OK、PGRES_SINGLE_TUPLE 或 PGRES_TUPLES_CHUNK，則可以使用下面描述的函式檢索查詢返回的行。請注意，一個恰好檢索零行的 SELECT 命令仍然顯示 PGRES_TUPLES_OK。PGRES_COMMAND_OK 適用於從不返回行的命令（沒有 RETURNING 子句的 INSERT 或 UPDATE 等）。PGRES_EMPTY_QUERY 的響應可能表示客戶端軟體中存在錯誤。

PQexec 或其他查詢執行函式絕不會直接返回狀態為 PGRES_NONFATAL_ERROR 的結果；此類結果會傳遞給通知處理器（請參閱 第 32.13 節）。

將 PQresultStatus 返回的列舉型別轉換為描述狀態程式碼的字串常量。呼叫者不應直接釋放結果。

char *PQresStatus(ExecStatusType status);

返回與命令關聯的錯誤訊息，如果沒有錯誤則返回空字串。

char *PQresultErrorMessage(const PGresult *res);

如果存在錯誤，返回的字串將包含一個尾隨換行符。呼叫者不應直接釋放結果。當相關的 PGresult 控制代碼傳遞給 PQclear 時，它將被釋放。

緊接在 PQexec 或 PQgetResult 呼叫之後，PQerrorMessage（在連線上）將返回與 PQresultErrorMessage（在結果上）相同的字串。但是，PGresult 將保留其錯誤訊息直到被銷燬，而連線的錯誤訊息將在後續操作完成後更改。當您想知道與特定 PGresult 關聯的狀態時，使用 PQresultErrorMessage；當您想知道連線上最新操作的狀態時，使用 PQerrorMessage。

返回與 PGresult 物件關聯的錯誤訊息的重新格式化版本。

char *PQresultVerboseErrorMessage(const PGresult *res,
                                  PGVerbosity verbosity,
                                  PGContextVisibility show_context);

在某些情況下，客戶端可能希望獲得先前報告錯誤的更詳細版本。PQresultVerboseErrorMessage 透過計算如果指定詳細程度設定在生成給定 PGresult 時已對連線生效，則 PQresultErrorMessage 將生成的訊息來解決此需求。如果 PGresult 不是錯誤結果，則報告“PGresult 不是錯誤結果”。返回的字串包含一個尾隨換行符。

與大多數其他從 PGresult 中提取資料的函式不同，此函式的結果是一個新分配的字串。當不再需要該字串時，呼叫者必須使用 PQfreemem() 釋放它。

如果記憶體不足，可能會返回 NULL。

返回錯誤報告的單個欄位。

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcode 是一個錯誤欄位識別符號；請參閱下面列出的符號。如果 PGresult 不是錯誤或警告結果，或者不包含指定欄位，則返回 NULL。欄位值通常不包含尾隨換行符。呼叫者不應直接釋放結果。當相關的 PGresult 控制代碼傳遞給 PQclear 時，它將被釋放。

以下欄位程式碼可用

客戶端負責根據其需求格式化顯示的資訊；特別是，它應根據需要斷開長行。錯誤訊息欄位中出現的換行符應視為段落分隔符，而不是換行符。

由 libpq 內部生成的錯誤將具有嚴重性和主要訊息，但通常沒有其他欄位。

請注意，錯誤欄位僅適用於 PGresult 物件，而不適用於 PGconn 物件；沒有 PQerrorField 函式。

釋放與 PGresult 關聯的儲存。不再需要時，每個命令結果都應透過 PQclear 釋放。

void PQclear(PGresult *res);

如果引數是 NULL 指標，則不執行任何操作。

您可以將 PGresult 物件保留所需的時間；它不會在您發出新命令時消失，即使您關閉連線也不會。要擺脫它，您必須呼叫 PQclear。不這樣做將導致您的應用程式出現記憶體洩漏。

返回查詢結果中的行（元組）數。（請注意，PGresult 物件最多隻能有 INT_MAX 行，因此 int 結果就足夠了。）

int PQntuples(const PGresult *res);

返回查詢結果中每行的列（欄位）數。

int PQnfields(const PGresult *res);

返回與給定列號關聯的列名。列號從 0 開始。呼叫者不應直接釋放結果。當相關的 PGresult 控制代碼傳遞給 PQclear 時，它將被釋放。

char *PQfname(const PGresult *res,
              int column_number);

如果列號超出範圍，則返回 NULL。

返回與給定列名關聯的列號。

int PQfnumber(const PGresult *res,
              const char *column_name);

如果給定名稱與任何列不匹配，則返回 -1。

給定名稱被視為 SQL 命令中的識別符號，也就是說，除非雙引號引起來，否則它會轉換為小寫。例如，給定從 SQL 命令生成的查詢結果

SELECT 1 AS FOO, 2 AS "BAR";

我們將得到以下結果

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

返回提取給定列的表的 OID。列號從 0 開始。

Oid PQftable(const PGresult *res,
             int column_number);

如果列號超出範圍，或者指定列不是對錶列的簡單引用，則返回 InvalidOid。您可以查詢系統表 pg_class 以準確確定引用了哪個表。

當您包含 libpq 標頭檔案時，將定義型別 Oid 和常量 InvalidOid。它們都將是某個整數型別。

返回構成指定查詢結果列的列的列號（在其表內）。查詢結果列號從 0 開始，但表列具有非零號。

int PQftablecol(const PGresult *res,
                int column_number);

如果列號超出範圍，或者指定列不是對錶列的簡單引用，則返回零。

返回指示給定列格式的格式程式碼。列號從 0 開始。

int PQfformat(const PGresult *res,
              int column_number);

格式程式碼零表示文字資料表示，而格式程式碼一表示二進位制表示。（其他程式碼保留供將來定義。）

返回與給定列號關聯的資料型別。返回的整數是型別的內部 OID 號。列號從 0 開始。

Oid PQftype(const PGresult *res,
            int column_number);

您可以查詢系統表 pg_type 以獲取各種資料型別的名稱和屬性。內建資料型別的OID在 PostgreSQL 安裝的 include 目錄中的檔案 catalog/pg_type_d.h 中定義。

返回與給定列號關聯的列的型別修飾符。列號從 0 開始。

int PQfmod(const PGresult *res,
           int column_number);

修飾符值的解釋是型別特定的；它們通常指示精度或大小限制。值 -1 用於指示“無可用資訊”。大多數資料型別不使用修飾符，在這種情況下，值始終為 -1。

返回與給定列號關聯的列的大小（以位元組為單位）。列號從 0 開始。

int PQfsize(const PGresult *res,
            int column_number);

PQfsize 返回資料庫行中為此列分配的空間，換句話說，是伺服器內部表示資料型別的大小。（因此，它對客戶端並不是很有用。）負值表示資料型別是變長型別。

如果 PGresult 包含二進位制資料則返回 1，如果包含文字資料則返回 0。

int PQbinaryTuples(const PGresult *res);

此函式已棄用（除了在與 COPY 結合使用時），因為單個 PGresult 可能在某些列中包含文字資料，在其他列中包含二進位制資料。PQfformat 更受青睞。PQbinaryTuples 僅當結果的所有列都是二進位制（格式 1）時才返回 1。

返回 PGresult 一行的單個欄位值。行號和列號從 0 開始。呼叫者不應直接釋放結果。當相關的 PGresult 控制代碼傳遞給 PQclear 時，它將被釋放。

char *PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

對於文字格式的資料，PQgetvalue 返回的值是欄位值的以空字元結尾的字串表示形式。對於二進位制格式的資料，該值是資料型別的 typsend 和 typreceive 函式確定的二進位制表示形式。（在這種情況下，該值實際上也後跟一個零位元組，但這通常沒有用，因為該值可能包含嵌入的空字元。）

如果欄位值為 null，則返回空字串。請參閱 PQgetisnull 以區分 null 值和空字串值。

PQgetvalue 返回的指標指向 PGresult 結構的一部分儲存。不應修改它指向的資料，如果要在 PGresult 結構的生命週期之外使用，則必須顯式將資料複製到其他儲存中。

測試欄位是否為 null 值。行號和列號從 0 開始。

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

如果欄位為 null，則此函式返回 1；如果它包含非 null 值，則返回 0。（請注意，PQgetvalue 將為 null 欄位返回空字串，而不是空指標。）

返回欄位值的實際長度（以位元組為單位）。行號和列號從 0 開始。

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

這是特定資料值的實際資料長度，即 PQgetvalue 指向的物件的大小。對於文字資料格式，這與 strlen() 相同。對於二進位制格式，這是必不可少的資訊。請注意，不應依賴 PQfsize 來獲取實際資料長度。

返回預處理語句的引數數量。

int PQnparams(const PGresult *res);

此函式僅在檢查 PQdescribePrepared 的結果時有用。對於其他型別的結果，它將返回零。

返回指定語句引數的資料型別。引數編號從 0 開始。

Oid PQparamtype(const PGresult *res, int param_number);

此函式僅在檢查 PQdescribePrepared 的結果時有用。對於其他型別的結果，它將返回零。

將所有行以及可選的列名列印到指定的輸出流。

void PQprint(FILE *fout,      /* output stream */
             const PGresult *res,
             const PQprintOpt *po);
typedef struct
{
    pqbool  header;      /* print output field headings and row count */
    pqbool  align;       /* fill align the fields */
    pqbool  standard;    /* old brain dead format */
    pqbool  html3;       /* output HTML tables */
    pqbool  expanded;    /* expand tables */
    pqbool  pager;       /* use pager for output if needed */
    char    *fieldSep;   /* field separator */
    char    *tableOpt;   /* attributes for HTML table element */
    char    *caption;    /* HTML table caption */
    char    **fieldName; /* null-terminated array of replacement field names */
} PQprintOpt;

此函式以前由 psql 用於列印查詢結果，但現在不再是這種情況。請注意，它假定所有資料都是文字格式。

從生成 PGresult 的 SQL 命令返回命令狀態標記。

char *PQcmdStatus(PGresult *res);

通常這只是命令的名稱，但它可能包含其他資料，例如處理的行數。呼叫者不應直接釋放結果。當相關的 PGresult 控制代碼傳遞給 PQclear 時，它將被釋放。

返回受 SQL 命令影響的行數。

char *PQcmdTuples(PGresult *res);

此函式返回一個字串，其中包含受SQL生成 PGresult 的語句影響的行數。此函式只能在執行 SELECT、CREATE TABLE AS、INSERT、UPDATE、DELETE、MERGE、MOVE、FETCH 或 COPY 語句，或包含 INSERT、UPDATE、DELETE 或 MERGE 語句的預處理查詢的 EXECUTE 之後使用。如果生成 PGresult 的命令是其他任何命令，則 PQcmdTuples 返回一個空字串。呼叫者不應直接釋放返回值。當相關的 PGresult 控制代碼傳遞給 PQclear 時，它將被釋放。

如果SQL命令是 INSERT 命令，並且僅向具有 OID 的表中插入了一行，或者包含合適的 INSERT 語句的預處理查詢的 EXECUTE 命令，則返回插入行的 OID。否則，此函式返回 InvalidOid。如果受 INSERT 語句影響的表不包含 OID，此函式也將返回 InvalidOid。

Oid PQoidValue(const PGresult *res);

此函式已被棄用，取而代之的是 PQoidValue，並且它不是執行緒安全的。它返回一個包含插入行 OID 的字串，而 PQoidValue 返回 OID 值。

char *PQoidStatus(const PGresult *res);

char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);

PQescapeLiteral 跳脫字元串以在 SQL 命令中使用。當將資料值作為文字常量插入 SQL 命令時，這很有用。某些字元（例如引號和反斜槓）必須轉義以防止它們被 SQL 解析器特殊解釋。PQescapeLiteral 執行此操作。

PQescapeLiteral 在使用 malloc() 分配的記憶體中返回 str 引數的轉義版本。當不再需要結果時，應使用 PQfreemem() 釋放此記憶體。不需要終止零位元組，也不應將其計入 length。（如果在處理 length 位元組之前找到終止零位元組，PQescapeLiteral 將在零處停止；因此行為更像是 strncpy。）返回字串中的所有特殊字元都已替換，以便 PostgreSQL 字串文字解析器可以正確處理它們。還會新增一個終止零位元組。PostgreSQL 字串文字必須圍繞的單引號包含在結果字串中。

如果發生錯誤，PQescapeLiteral 返回 NULL，並在 conn 物件中儲存適當的訊息。

請注意，當資料值作為單獨的引數在 PQexecParams 或其同級例程中傳遞時，無需進行轉義，也不正確。

char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);

PQescapeIdentifier 跳脫字元串以用作 SQL 識別符號，例如表名、列名或函式名。當用戶提供的識別符號可能包含特殊字元，否則 SQL 解析器不會將其解釋為識別符號的一部分，或者當識別符號可能包含應保留其大小寫的字元時，這很有用。

PQescapeIdentifier 返回 str 引數的轉義版本，作為 SQL 識別符號，儲存在用 malloc() 分配的記憶體中。當不再需要結果時，必須使用 PQfreemem() 釋放此記憶體。不需要終止零位元組，也不應計入 length。（如果在處理 length 位元組之前找到終止零位元組，PQescapeIdentifier 將在零處停止；因此行為更像是 strncpy。）返回字串中的所有特殊字元都已替換，以便它可以被正確地作為 SQL 識別符號處理。還會新增一個終止零位元組。返回字串也將被雙引號包圍。

如果發生錯誤，PQescapeIdentifier 返回 NULL，並在 conn 物件中儲存適當的訊息。

size_t PQescapeStringConn(PGconn *conn,
                          char *to, const char *from, size_t length,
                          int *error);

PQescapeStringConn 跳脫字元串文字，很像 PQescapeLiteral。與 PQescapeLiteral 不同，呼叫者負責提供適當大小的緩衝區。此外，PQescapeStringConn 不生成必須圍繞 PostgreSQL 字串文字的單引號；它們應在將結果插入的 SQL 命令中提供。引數 from 指向要轉義的字串的第一個字元，length 引數給出此字串中的位元組數。不需要終止零位元組，並且不應將其計入 length。（如果在處理 length 位元組之前找到終止零位元組，PQescapeStringConn 將在零處停止；因此行為更像是 strncpy。）to 應指向一個能夠容納至少兩倍於 length 值的位元組的緩衝區，否則行為未定義。如果 to 和 from 字串重疊，行為也未定義。

如果 error 引數不為 NULL，則成功時將 *error 設定為零，失敗時設定為非零。目前唯一可能的錯誤條件涉及源字串中的無效多位元組編碼。即使發生錯誤，輸出字串仍會生成，但可以預期伺服器會將其視為格式錯誤而拒絕。發生錯誤時，無論 error 是否為 NULL，都會在 conn 物件中儲存適當的訊息。

PQescapeStringConn 返回寫入 to 的位元組數，不包括終止零位元組。

PQescapeString 是 PQescapeStringConn 的舊版，已棄用。

size_t PQescapeString (char *to, const char *from, size_t length);

與 PQescapeStringConn 的唯一區別是 PQescapeString 不接受 PGconn 或 error 引數。因此，它無法根據連線屬性（例如字元編碼）調整其行為，因此它可能會給出錯誤的結果。此外，它無法報告錯誤情況。

PQescapeString 可以在一次只使用一個 PostgreSQL 連線的客戶端程式中安全使用（在這種情況下，它可以“幕後”找出它需要知道的資訊）。在其他情況下，它存在安全隱患，應避免使用，轉而使用 PQescapeStringConn。

轉義二進位制資料，以便在 SQL 命令中與 bytea 型別一起使用。與 PQescapeStringConn 一樣，這僅在將資料直接插入 SQL 命令字串時使用。

unsigned char *PQescapeByteaConn(PGconn *conn,
                                 const unsigned char *from,
                                 size_t from_length,
                                 size_t *to_length);

在SQL語句中，當某些位元組值用作 bytea 文字的一部分時，必須進行轉義。PQescapeByteaConn 使用十六進位制編碼或反斜槓轉義來轉義位元組。有關更多資訊，請參閱 第 8.4 節。

from 引數指向要轉義的字串的第一個位元組，from_length 引數給出此二進位制字串中的位元組數。（終止零位元組既不需要也不計算在內。）to_length 引數指向一個變數，該變數將儲存結果跳脫字元串的長度。此結果字串長度包括結果的終止零位元組。

PQescapeByteaConn 返回在用 malloc() 分配的記憶體中，from 引數二進位制字串的轉義版本。當不再需要結果時，應該使用 PQfreemem() 釋放此記憶體。返回的字串中所有特殊字元都已替換，以便 PostgreSQL 字串文字解析器和 bytea 輸入函式能夠正確處理它們。還會新增一個終止零位元組。必須包圍 PostgreSQL 字串文字的單引號不屬於結果字串。

如果發生錯誤，將返回一個空指標，並在 conn 物件中儲存一個適當的錯誤訊息。目前，唯一可能的錯誤是結果字串的記憶體不足。

PQescapeBytea 是 PQescapeByteaConn 的一個較舊的、已棄用的版本。

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

與 PQescapeByteaConn 唯一的區別是 PQescapeBytea 不接受 PGconn 引數。因此，PQescapeBytea 只能在每次使用單個 PostgreSQL 連線的客戶端程式中安全使用（在這種情況下，它可以透過“幕後”瞭解它需要知道的資訊）。如果在使用多個數據庫連線的程式中使用它，它可能會給出錯誤的結果（在這種情況下請使用 PQescapeByteaConn）。

將二進位制資料的字串表示形式轉換為二進位制資料 — 與 PQescapeBytea 相反。當以文字格式檢索 bytea 資料時需要此操作，但當以二進位制格式檢索時則不需要。

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

from 引數指向一個字串，例如當應用於 bytea 列時，PQgetvalue 可能返回的字串。PQunescapeBytea 將此字串表示形式轉換為其二進位制表示形式。它返回一個指向用 malloc() 分配的緩衝區的指標，或者在出錯時返回 NULL，並將緩衝區的大小放入 to_length 中。當不再需要結果時，必須使用 PQfreemem 釋放它。

此轉換並非 PQescapeBytea 的精確逆操作，因為從 PQgetvalue 接收到的字串不應該被“轉義”。特別是，這意味著無需考慮字串引用，因此也無需 PGconn 引數。