支援的版本:目前 (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

32.2. 連線狀態函式 #

這些函式可用於查詢現有資料庫連線物件的狀態。

提示

libpq 應用程式設計師應小心維護 PGconn 抽象化。使用以下描述的存取函式來取得 PGconn 的內容。不建議使用 libpq-int.h 參考內部 PGconn 欄位,因為它們在未來可能會變更。

以下函式會傳回連線時建立的參數值。這些值在連線的生命週期內是固定的。如果使用多主機連線字串,則如果使用相同的 PGconn 物件建立新的連線,PQhostPQportPQpass 的值可能會變更。其他值在 PGconn 物件的生命週期內是固定的。

PQdb #

傳回連線的資料庫名稱。

char *PQdb(const PGconn *conn);
PQuser #

傳回連線的使用者名稱。

char *PQuser(const PGconn *conn);
PQpass #

傳回連線的密碼。

char *PQpass(const PGconn *conn);

PQpass 將傳回在連線參數中指定的密碼,如果沒有指定,且密碼是從密碼檔案取得,則會傳回該密碼。在後一種情況下,如果在連線參數中指定了多個主機,則在建立連線之前,無法依賴 PQpass 的結果。可以使用函式 PQstatus 檢查連線狀態。

PQhost #

傳回作用中連線的伺服器主機名稱。如果連線是透過 Unix socket 建立,則這可以是主機名稱、IP 位址或目錄路徑。(路徑案例可以區分,因為它始終是絕對路徑,以 / 開頭。)

char *PQhost(const PGconn *conn);

如果連線參數同時指定了 hosthostaddr,則 PQhost 將傳回 host 資訊。如果僅指定了 hostaddr,則傳回該資訊。如果在連線參數中指定了多個主機,則 PQhost 會傳回實際連線的主機。

如果 conn 參數是 NULL,則 PQhost 傳回 NULL。否則,如果產生主機資訊時發生錯誤(可能在連線尚未完全建立或發生錯誤時),它會傳回空字串。

如果在連線參數中指定了多個主機,則在建立連線之前,無法依賴 PQhost 的結果。可以使用函式 PQstatus 檢查連線狀態。

PQhostaddr #

傳回作用中連線的伺服器 IP 位址。這可以是主機名稱解析到的位址,或透過 hostaddr 參數提供的 IP 位址。

char *PQhostaddr(const PGconn *conn);

如果 conn 參數是 NULL,則 PQhostaddr 傳回 NULL。否則,如果產生主機資訊時發生錯誤(可能在連線尚未完全建立或發生錯誤時),它會傳回空字串。

PQport #

傳回作用中連線的埠。

char *PQport(const PGconn *conn);

如果在連線參數中指定了多個埠,則 PQport 會傳回實際連線的埠。

如果 conn 參數為 NULLPQport 會回傳 NULL。否則,如果在產生 Port 資訊時發生錯誤(可能如果連線尚未完全建立或發生錯誤),它會回傳一個空字串。

如果在連線參數中指定了多個 Port,在建立連線之前,無法依賴 PQport 的結果。可以使用 PQstatus 函式檢查連線的狀態。

PQtty #

此函式不再執行任何操作,但為了向後相容性而保留。如果 conn 參數為 NULL,則該函式始終回傳一個空字串,或 NULL

char *PQtty(const PGconn *conn);
PQoptions #

回傳在連線請求中傳遞的命令列選項。

char *PQoptions(const PGconn *conn);

以下函式回傳的狀態資料可能會隨著 PGconn 物件上執行的操作而改變。

PQstatus #

回傳連線的狀態。

ConnStatusType PQstatus(const PGconn *conn);

狀態可以是多個值之一。但是,只有兩個會在非同步連線程序之外看到:CONNECTION_OKCONNECTION_BAD。與資料庫的良好連線具有狀態 CONNECTION_OK。連線嘗試失敗會以狀態 CONNECTION_BAD 表示。通常,OK 狀態會保持如此,直到 PQfinish,但是通訊故障可能會導致狀態提前更改為 CONNECTION_BAD。在這種情況下,應用程式可以嘗試透過呼叫 PQreset 來恢復。

有關可能回傳的其他狀態碼,請參閱 PQconnectStartParamsPQconnectStartPQconnectPoll 的條目。

PQtransactionStatus #

回傳伺服器目前的事務內狀態。

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

狀態可以是 PQTRANS_IDLE (目前閒置)、PQTRANS_ACTIVE (命令正在進行中)、PQTRANS_INTRANS (閒置,在有效的事務區塊中) 或 PQTRANS_INERROR (閒置,在失敗的事務區塊中)。如果連線不良,則回報 PQTRANS_UNKNOWN。只有在查詢已傳送到伺服器且尚未完成時,才會回報 PQTRANS_ACTIVE

PQparameterStatus #

查找伺服器的目前參數設定。

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

伺服器會在連線啟動時或每當其值變更時自動回報某些參數值。PQparameterStatus 可用於查詢這些設定。如果已知參數,則回傳參數的目前值,如果未知參數,則回傳 NULL

截至目前版本回報的參數包括

application_name is_superuser
client_encoding scram_iterations
DateStyle server_encoding
default_transaction_read_only server_version
in_hot_standby session_authorization
integer_datetimes standard_conforming_strings
IntervalStyle TimeZone

(default_transaction_read_onlyin_hot_standby 未由 14 之前的版本回報;scram_iterations 未由 16 之前的版本回報。) 請注意,server_versionserver_encodinginteger_datetimes 在啟動後無法變更。

如果未回報 standard_conforming_strings 的值,應用程式可以假設它是 off,也就是說,反斜線在字串文字中被視為逸出字元。此外,此參數的存在可以被視為表示接受逸出字串語法 (E'...')。

雖然回傳的指標宣告為 const,但實際上它指向與 PGconn 結構相關聯的可變儲存體。假設指標在查詢之間保持有效是不明智的。

PQprotocolVersion #

詢問正在使用的前端/後端協定。

int PQprotocolVersion(const PGconn *conn);

應用程式可能希望使用此函式來判斷是否支援某些功能。目前,可能的值為 3(3.0 協定)或零(連線不良)。協定版本在連線啟動完成後不會變更,但在理論上可能會在連線重設期間變更。PostgreSQL 伺服器版本 7.4 及更高版本支援 3.0 協定。

PQserverVersion #

回傳一個表示伺服器版本的整數。

int PQserverVersion(const PGconn *conn);

應用程式可以使用此函式來判斷其連線到的資料庫伺服器的版本。結果的形成方式是將伺服器的主版本號乘以 10000 並加上次要版本號。例如,版本 10.1 將以 100001 回傳,而版本 11.0 將以 110000 回傳。如果連線不良,則回傳零。

在主要版本 10 之前,PostgreSQL 使用三部分版本號,其中前兩部分共同表示主要版本。對於這些版本,PQserverVersion 為每個部分使用兩位數;例如,版本 9.1.5 將以 90105 回傳,而版本 9.2.0 將以 90200 回傳。

因此,為了確定功能相容性,應用程式應將 PQserverVersion 的結果除以 100 而不是 10000,以確定邏輯主要版本號。在所有發布系列中,只有最後兩位數在次要版本(錯誤修復版本)之間有所不同。

PQerrorMessage #

回傳最近由連線上的操作產生的錯誤訊息。

char *PQerrorMessage(const PGconn *conn);

幾乎所有 libpq 函式都會在失敗時為 PQerrorMessage 設定訊息。請注意,按照 libpq 慣例,非空的 PQerrorMessage 結果可以包含多行,並且將包含尾隨換行符。呼叫者不應直接釋放結果。當相關的 PGconn 句柄傳遞給 PQfinish 時,它將被釋放。不應期望結果字串在 PGconn 結構上的操作之間保持不變。

PQsocket #

取得連線到伺服器的連線 socket 的檔案描述符號碼。有效的描述符號將大於或等於 0;結果為 -1 表示目前沒有開啟任何伺服器連線。(在正常操作期間這不會改變,但在連線設定或重置期間可能會改變。)

int PQsocket(const PGconn *conn);
PQbackendPID #

傳回處理此連線的後端處理程序的ID(PID)

int PQbackendPID(const PGconn *conn);

後端PID對於除錯目的以及與 NOTIFY 訊息(包含通知後端處理程序的PID)進行比較非常有用。請注意,此PID屬於在資料庫伺服器主機上執行的處理程序,而不是在本機主機上!

PQconnectionNeedsPassword #

如果連線驗證方法需要密碼,但沒有可用的密碼,則傳回 true (1)。如果不是,則傳回 false (0)。

int PQconnectionNeedsPassword(const PGconn *conn);

此函式可以在連線嘗試失敗後使用,以決定是否提示使用者輸入密碼。

PQconnectionUsedPassword #

如果連線驗證方法使用了密碼,則傳回 true (1)。如果不是,則傳回 false (0)。

int PQconnectionUsedPassword(const PGconn *conn);

此函式可以在連線嘗試失敗或成功後使用,以偵測伺服器是否要求密碼。

PQconnectionUsedGSSAPI #

如果連線驗證方法使用了 GSSAPI,則傳回 true (1)。如果不是,則傳回 false (0)。

int PQconnectionUsedGSSAPI(const PGconn *conn);

此函式可用於偵測連線是否已透過 GSSAPI 進行驗證。

以下函式傳回與 SSL 相關的資訊。這些資訊通常在建立連線後不會改變。

PQsslInUse #

如果連線使用 SSL,則傳回 true (1),如果不是,則傳回 false (0)。

int PQsslInUse(const PGconn *conn);
PQsslAttribute #

傳回有關連線的 SSL 相關資訊。

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

可用屬性的清單取決於正在使用的 SSL 函式庫和連線類型。如果連線未使用 SSL 或未定義正在使用的函式庫的指定屬性名稱,則傳回 NULL。

以下屬性通常可用

函式庫

正在使用的 SSL 實作的名稱。(目前,僅實作了 "OpenSSL"

協定

正在使用的 SSL/TLS 版本。常見值為 "TLSv1""TLSv1.1""TLSv1.2",但如果使用其他協定,實作可能會傳回其他字串。

金鑰位元

加密演算法使用的金鑰位元數。

加密算法

使用的密碼套件的簡短名稱,例如 "DHE-RSA-DES-CBC3-SHA"。名稱特定於每個 SSL 實作。

壓縮

如果正在使用 SSL 壓縮,則傳回 "on",否則傳回 "off"。

alpn

由 TLS 應用程式層協定協商 (ALPN) 延伸所選取的應用程式協定。libpq 支援的唯一協定是 postgresql,因此這主要用於檢查伺服器是否支援 ALPN。如果未使用 ALPN,則為空字串。

作為特例,可以查詢 library 屬性,而無需連線,方法是將 NULL 作為 conn 引數傳遞。結果將是預設的 SSL 函式庫名稱,如果 libpq 在編譯時沒有任何 SSL 支援,則為 NULL。(在 PostgreSQL 15 版之前,將 NULL 作為 conn 引數傳遞總是導致 NULL。需要區分此案例的新版和舊版實作的用戶端程式可以檢查 LIBPQ_HAS_SSL_LIBRARY_DETECTION 功能巨集。)

PQsslAttributeNames #

傳回可用於 PQsslAttribute() 的 SSL 屬性名稱陣列。陣列以 NULL 指標終止。

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

如果 conn 為 NULL,則傳回預設 SSL 函式庫可用的屬性,如果 libpq 在編譯時沒有任何 SSL 支援,則傳回空清單。如果 conn 不為 NULL,則傳回連線使用的 SSL 函式庫可用的屬性,如果連線未加密,則傳回空清單。

PQsslStruct #

傳回指向描述連線的 SSL 實作特定物件的指標。如果連線未加密,或連線的 SSL 實作無法使用所要求的物件類型,則傳回 NULL。

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

可用的 struct 取決於正在使用的 SSL 實作。對於 OpenSSL,有一個 struct,可在名稱 OpenSSL 下使用,它傳回指向 OpenSSLSSL struct 的指標。要使用此函式,可以使用以下程式碼:

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

...

    SSL *ssl;

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

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }

此結構可用於驗證加密等級、檢查伺服器憑證等。有關此結構的資訊,請參閱 OpenSSL 文件。

PQgetssl #

傳回連線中使用的 SSL 結構,如果未使用 SSL,則傳回 NULL。

void *PQgetssl(const PGconn *conn);

此函式等同於 PQsslStruct(conn, "OpenSSL")。不應在新應用程式中使用它,因為傳回的結構特定於 OpenSSL,如果使用另一個SSL實作,則無法使用。要檢查連線是否使用 SSL,請改為呼叫 PQsslInUse,有關連線的更多詳細資訊,請使用 PQsslAttribute

提交更正

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