PostgreSQL 連接狀態(tài)函數(shù)

返回該連接的數(shù)據(jù)庫名。

char *PQdb(const PGconn *conn);

返回該連接的用戶名。

char *PQuser(const PGconn *conn);

返回該連接的口令。

char *PQpass(const PGconn *conn);

PQpass將返回連接參數(shù)中指定的口令，如果連接參數(shù)中沒有口令并且能從口令文件中得到口令，則它將返回得到的口令。 在后一種情況中，如果連接參數(shù)中指定了多個主機(jī)，在連接被建立之前都不能依賴 PQpass 的結(jié)果。連接的狀態(tài)可以用函數(shù)PQpass檢查。

返回活躍連接的服務(wù)器主機(jī)名?？赡苁侵鳈C(jī)名、IP 地址或者一個目錄路徑（如果通過 Unix 套接字連接，路徑的情況很容易區(qū)分，因為路徑總是一個絕對路徑，以/開始）。

char *PQhost(const PGconn *conn);

如果連接參數(shù)同時指定了host和hostaddr，則PQhost將返回host信息。 如果僅指定了hostaddr，則返回它。如果在連接參數(shù)中指定了多個主機(jī)， PQhost 返回實際連接到的主機(jī)。

如果conn參數(shù)是NULL，則PQhost返回NULL。否則，如果有一個錯誤產(chǎn)生主機(jī)信息（或許是連接沒有被完全建立或者有什么錯誤），它會返回一個空字符串。

如果在連接參數(shù)中指定了多個主機(jī)，則在連接建立之前都不能依賴于PQhost的結(jié)果。連接的狀態(tài)可以用函數(shù)PQstatus檢查。

返回活動連接的服務(wù)器 IP 地址。這可以是主機(jī)名解析出的地址，也可以是通過hostaddr參數(shù)提供的 IP 地址。

char *PQhostaddr(const PGconn *conn);

如果conn 參數(shù)為 NULL則 PQhostaddr 返回 NULL 。 否則，如果生成主機(jī)信息時出現(xiàn)錯誤（如果連接尚未完全建立或出現(xiàn)錯誤），則返回一個空字符串。

返回活躍連接的端口。

char *PQport(const PGconn *conn);

如果在連接參數(shù)中指定了多個端口，PQport返回實際連接到的端口。

如果conn參數(shù)是NULL，則PQport返回NULL。否則，如果有一個錯誤產(chǎn)生端口信息（或許是連接沒有被完全建立或者有什么錯誤），它會返回一個空字符串。

如果在連接參數(shù)中指定了多個端口，則在連接建立之前都不能依賴于PQport的結(jié)果。連接的狀態(tài)可以用函數(shù)PQstatus檢查。

返回該連接的調(diào)試TTY（這已被廢棄，因為服務(wù)器不再關(guān)心TTY設(shè)置，但這個函數(shù)保持了向后兼容）。

char *PQtty(const PGconn *conn);

返回被傳遞給連接請求的命令行選項。

char *PQoptions(const PGconn *conn);

返回該連接的狀態(tài)。

ConnStatusType PQstatus(const PGconn *conn);

該狀態(tài)可以是一系列值之一。不過，其中只有兩個在一個異步連接過程之外可見：CONNECTION_OK和CONNECTION_BAD。 一個到數(shù)據(jù)庫的完好連接的狀態(tài)為CONNECTION_OK。一個失敗的連接嘗試則由狀態(tài)CONNECTION_BAD表示。 通常，一個 OK 狀態(tài)將一直保持到PQfinish，但是一次通信失敗可能導(dǎo)致該狀態(tài)過早地改變?yōu)?code class="literal">CONNECTION_BAD。 在那種情況下，該應(yīng)用可以通過調(diào)用 PQreset 嘗試恢復(fù)。

關(guān)于其他可能會被返回的狀態(tài)代碼，請見PQconnectStartParams、PQconnectStart和PQconnectPoll的條目。

返回服務(wù)器的當(dāng)前事務(wù)內(nèi)狀態(tài)。

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

該狀態(tài)可能是PQTRANS_IDLE（當(dāng)前空閑）、PQTRANS_ACTIVE（一個命令運(yùn)行中）、PQTRANS_INTRANS（空閑，處于一個合法的事務(wù)塊中）或者PQTRANS_INERROR（空閑，處于一個失敗的事務(wù)塊中）。如果該連接損壞，將會報告PQTRANS_UNKNOWN。只有當(dāng)一個查詢已經(jīng)被發(fā)送給服務(wù)器并且還沒有完成時，才會報告 PQTRANS_ACTIVE。

查找服務(wù)器的一個當(dāng)前參數(shù)設(shè)置。

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

某一參數(shù)值會被服務(wù)器在連接開始或值改變時自動報告。PQparameterStatus可以被用來詢問這些設(shè)置。它為已知的參數(shù)返回當(dāng)前值，為未知的參數(shù)返回NULL。

自當(dāng)前發(fā)布開始會被報告的參數(shù)包括 server_version、 server_encoding、 client_encoding、 application_name、 is_superuser、 session_authorization、 DateStyle、 IntervalStyle、 TimeZone、 integer_datetimes以及 standard_conforming_strings（ server_encoding、 TimeZone以及integer_datetimes在 8.0 以前的發(fā)布中不被報告；standard_conforming_strings在 8.1 以前的發(fā)布中不被報告；IntervalStyle在 8.4 以前的發(fā)布中不被報告；application_name在 9.0 以前的發(fā)布中不被報告）。注意 server_version、 server_encoding以及 integer_datetimes在啟動之后無法改變。

3.0 之前協(xié)議的服務(wù)器不報告參數(shù)設(shè)置，但是libpq包括獲得server_version以及client_encoding值的邏輯。 我們鼓勵應(yīng)用使用PQparameterStatus而不是 ad hoc 代碼來確定這些值（不過注意在一個 3.0 之前的連接上，連接開始后通過SET改變client_encoding不會被PQparameterStatus反映）。 對于server_version（另見 PQserverVersion ），它以一種數(shù)字形式返回信息，這樣更容易進(jìn)行比較。

如果沒有為standard_conforming_strings報告值，應(yīng)用能假設(shè)它是off，也就是說反斜線會被視為字符串中的轉(zhuǎn)義。還有，這個參數(shù)的存在可以被作為轉(zhuǎn)義字符串語法（E'...'）被接受的指示。

盡管被返回的指針被聲明成const，它事實上指向與PGconn結(jié)構(gòu)相關(guān)的可變存儲。假定該指針在存儲之間保持有效是不明智的。

詢問所使用的 前端/后端協(xié)議。

int PQprotocolVersion(const PGconn *conn);

應(yīng)用可能希望用這個函數(shù)來確定某些特性是否被支持。當(dāng)前，可能值是 2（2.0 協(xié)議）、3（3.0 協(xié)議）或零（連接損壞）。協(xié)議版本在連接啟動完成后將不會改變，但是理論上在連接重置期間是可以改變的。當(dāng)與PostgreSQL 7.4 或以后的服務(wù)器通信時通常使用 3.0 協(xié)議，7.4 之前的服務(wù)器只支持協(xié)議 2.0（協(xié)議 1.0 已被廢棄并且不再被libpq支持）。

返回一個表示服務(wù)器版本的整數(shù)。

int PQserverVersion(const PGconn *conn);

應(yīng)用可能會使用這個函數(shù)來判斷它們連接到的數(shù)據(jù)庫服務(wù)器的版本。結(jié)果通過將服務(wù)器的主版本號乘以10000再加上次版本號形成。例如，版本10.1將被返回為100001，而版本11.0將被返回為110000。如果連接無效則返回零。

在主版本10之前，PostgreSQL采用一種由三個部分組成的版本號，其中前兩部分共同表示主版本。對于那些版本，PQserverVersion為每個部分使用兩個數(shù)字，例如版本9.1.5將被返回為90105，而版本9.2.0將被返回為90200。

因此，出于判斷特性兼容性的目的，應(yīng)用應(yīng)該將PQserverVersion的結(jié)果除以100而不是10000來判斷邏輯的主版本號。在所有的發(fā)行序列中，只有最后兩個數(shù)字在次發(fā)行（問題修正發(fā)行）之間不同。

返回連接上的一個操作最近產(chǎn)生的錯誤消息。

char *PQerrorMessage(const PGconn *conn);

幾乎所有的libpq在失敗時都會為PQerrorMessage設(shè)置一個消息。 注意按照libpq習(xí)慣，一個非空 PQerrorMessage 結(jié)果由多行構(gòu)成，并且將包括一個尾部新行。 調(diào)用者不應(yīng)該直接釋放結(jié)果。當(dāng)相關(guān)的PGconn句柄被傳遞給PQfinish時，它將被釋放。在PGconn結(jié)構(gòu)上的多個操作之間，不能指望結(jié)果字符串會保持不變。

獲得到服務(wù)器連接套接字的文件描述符號。一個合法的描述符將會大于等于零。結(jié)果為 -1 表示當(dāng)前沒有打開服務(wù)器連接（在普通操作期間這將不會改變，但是在連接設(shè)置或重置期間可能改變）。

int PQsocket(const PGconn *conn);

返回處理這個連接的后端進(jìn)程的進(jìn)程ID（PID）。

int PQbackendPID(const PGconn *conn);

后端PID有助于調(diào)試目的并且可用于與NOTIFY消息（它包括發(fā)出提示的后端進(jìn)程的PID）進(jìn)行比較。注意PID屬于一個在數(shù)據(jù)庫服務(wù)器主機(jī)上執(zhí)行的進(jìn)程，而不是本地主機(jī)進(jìn)程！

如果連接認(rèn)證方法要求一個口令但沒有可用的口令，返回真（1）。否則返回假（0）。

int PQconnectionNeedsPassword(const PGconn *conn);

這個函數(shù)可以在連接嘗試失敗后被應(yīng)用于決定是否向用戶提示要求一個口令。

如果連接認(rèn)證方法使用一個口令，返回真（1）。否則返回假（0）。

int PQconnectionUsedPassword(const PGconn *conn);

這個函數(shù)能在一次連接嘗試失敗或成功后用于檢測該服務(wù)器是否要求一個口令。

如果該連接使用了 SSL 則返回真（1），否則返回假（0）。

int PQsslInUse(const PGconn *conn);

返回關(guān)于該連接的有關(guān) SSL 的信息。

const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

可用的屬性列表取決于使用的 SSL 庫以及連接類型。如果一個屬性不可用， 會返回 NULL。

下列屬性通常是可用的：

返回一個可用的 SSL 名稱的數(shù)組。該數(shù)組以一個 NULL 指針終結(jié)。

const char * const * PQsslAttributeNames(const PGconn *conn);

返回一個描述該連接的 SSL 實現(xiàn)相關(guān)的對象指針。

void *PQsslStruct(const PGconn *conn, const char *struct_name);

可用的結(jié)構(gòu)，這些結(jié)構(gòu)取決于使用的 SSL 實現(xiàn)。對于 OpenSSL，有一個結(jié)構(gòu)可用， 其名稱為 "OpenSSL"。它返回一個指向該 OpenSSL SSL 結(jié)構(gòu) 的指針。要使用這個函數(shù)，可以用下面的代碼：

#include <libpq-fe.h>
#include <openssl/ssl.h>

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* 使用 OpenSSL 函數(shù)來訪問 ssl */
    }

這個結(jié)構(gòu)可以被用來驗證加密級別、檢查服務(wù)器證書等等。有關(guān)這個結(jié)構(gòu) 的信息請參考OpenSSL的文檔。

返回連接中使用的 SSL 結(jié)構(gòu)，如果沒有使用 SSL 則返回空。

void *PQgetssl(const PGconn *conn);

這個函數(shù)等效于PQsslStruct(conn, "OpenSSL")。 在新的應(yīng)用中不應(yīng)該使用它，因為被返回的結(jié)構(gòu)是 OpenSSL 專用的，如果使用了另一種 SSL 實現(xiàn)就不再可用。 要檢查一個連接是否使用 SSL，應(yīng)該調(diào)用PQsslInUse，而要得到有關(guān)連接的更多細(xì)節(jié)應(yīng)該使用 PQsslAttribute 。