支援版本:目前 (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 參數為 NULLPQhostaddr 會傳回 NULL。否則,如果產生主機資訊時發生錯誤(可能由於連線尚未完全建立或發生錯誤),則它會傳回一個空字串。

PQport #

傳回作用中連線的埠。

char *PQport(const PGconn *conn);

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

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

如果在連線參數中指定了多個埠,則在連線建立之前,無法依賴 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"

protocol

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

key_bits

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

cipher

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

compression

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

alpn

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

在特殊情況下,可以透過傳遞 NULL 作為 conn 參數來查詢 library 屬性,而無需連線。結果將是預設的 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

提交更正

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