31.2. 連接狀態函數 · PostgreSQL 中文文檔 9.3

# 31.2\. 連接狀態函數這些函數可以用于詢問現存數據庫連接對象的狀態。 > **Tip:** libpq應用程序員應該仔細維護`PGconn`結構。使用下面的訪問函數來獲取`PGconn`的內容。不建議使用`libpq-int.h` 引用`PGconn`內部的字段，因為這些字段在今后可能被改變。下面的函數返回連接建立時的參數值。這些參數在`PGconn`對象的生命期期間是固定的。 `PQdb` 返回連接的數據庫名。 ``` char *PQdb(const PGconn *conn); ``` `PQuser` 返回連接的用戶名。 ``` char *PQuser(const PGconn *conn); ``` `PQpass` 返回連接的口令。 ``` char *PQpass(const PGconn *conn); ``` `PQhost` 返回連接的服務器主機名。 ``` char *PQhost(const PGconn *conn); ``` `PQport` 返回連接的端口號。 ``` char *PQport(const PGconn *conn); ``` `PQtty` 返回連接的調試控制臺TTY。（這個已經過時了，因為服務器不再注意TTY設置，這個函數的存在是為了向下兼容。） ``` char *PQtty(const PGconn *conn); ``` `PQoptions` 返回連接請求中傳遞的命令行選項。 ``` char *PQoptions(const PGconn *conn); ``` 下面的函數返回那些在對`PGconn`對象進行操作的過程中可能變化的狀態數據。 `PQstatus` 返回連接的狀態。 ``` ConnStatusType PQstatus(const PGconn *conn); ``` 這個狀態可以是一系列值之一。不過，我們在一個異步連接過程外面只能看到其中的兩個： `CONNECTION_OK`和`CONNECTION_BAD`。成功連接到數據庫返回狀態`CONNECTION_OK`。失敗的連接嘗試用狀態`CONNECTION_BAD`標識。通常，一個OK狀態將保持到`PQfinish`，但是一個通訊失敗可能會導致狀態過早的改變為 `CONNECTION_BAD`。這時應用可以試著調用`PQreset`來恢復。參閱`PQconnectStartParams`、`PQconnectStart`和`PQconnectPoll` 條目看看可能出現的其他狀態碼。 `PQtransactionStatus` 返回服務器的當前事務內狀態。 ``` PGTransactionStatusType PQtransactionStatus(const PGconn *conn); ``` 狀態可以是`PQTRANS_IDLE`（當前空閑），`PQTRANS_ACTIVE` （正在處理一個命令），`PQTRANS_INTRANS`（空閑，在一個合法的事務塊內），或者`PQTRANS_INERROR`（空閑，在一個失敗的事務塊內）。如果連接有問題，則返回`PQTRANS_UNKNOWN`。只有在一個查詢發送給了服務器并且還沒有完成的時候才返回 `PQTRANS_ACTIVE`。 | **Caution** | |:--- | | 當使用參數`autocommit`設置為關閉的PostgreSQL 7.3服務器時， `PQtransactionStatus`將給出不正確的結果。服務器端自動提交特性已經廢棄了，并且在后來的服務器版本中不再存在。 | `PQparameterStatus` 查找服務器的一個當前參數設置。 ``` const char *PQparameterStatus(const PGconn *conn, const char *paramName); ``` 有些參數值在建立連接或者它們的值改變的時候會由服務器自動報告。 `PQparameterStatus`可以用查詢這些設置。如果參數已知，那么它返回當前值，否則返回`NULL`。當前版本報告的參數有`server_version`，`server_encoding`， `client_encoding`，`application_name`，`is_superuser`， `session_authorization`，`DateStyle`，`IntervalStyle`， `TimeZone`，`integer_datetimes`和`standard_conforming_strings`。（8.0之前的版本不報告`server_encoding`，`TimeZone`和 `integer_datetimes`；8.1之前的版本不報告`standard_conforming_strings`； 8.4之前的版本不報告`IntervalStyle`；9.0之前的版本不報告`application_name`。）請注意`server_version`，`server_encoding`和`integer_datetimes` 不能再啟動后修改。協議版本3.0之前的服務器不會報告參數設置，但是libpq 里包含一些邏輯用于獲取`server_version`和`client_encoding`的數值。我們鼓勵應用里面使用`PQparameterStatus`，而不是使用_ad hoc_ 代碼來檢測這些值。（不過要注意，在3.0之前的連接協議里，啟動后通過`SET` 改變了`client_encoding`將不會被`PQparameterStatus`反映出來。）對于`server_version`，又見`PQserverVersion`，它返回數值形式，更容易進行比較。如果沒有為`standard_conforming_strings`報告數值，應用可以假設它是`off`，也就是說，在字符串文本里，把反斜杠當做逃逸。同樣，如果出現了這個參數，就可以當作一個指示，表示接受逃逸字符串(`E'...'`)的語法。盡管返回的指針聲明為`const`，它實際上指向一個和`PGconn` 結構關聯的可變存儲區。因此假設這個指針跨查詢保持有效是不明智的。 `PQprotocolVersion` 查詢使用的前/后端協議。 ``` int PQprotocolVersion(const PGconn *conn); ``` 應用可能希望使用這個函數來判斷某些特性是否被支持。目前，可能的數值是2 （2.0協議），3（3.0協議）或0（連接錯誤）。在連接啟動完成之后，這個數值將不會改變，但是在連接重置的過程中，理論上是可能改變的。在與PostgreSQL 7.4 或更高版本溝通時，通常使用3.0協議；7.4以前的服務器只支持協議2.0。（協議1.0過時了，不被libpq支持。） `PQserverVersion` 返回一個整數，代表后端版本。 ``` int PQserverVersion(const PGconn *conn); ``` 應用可以使用這個函數判斷它們連接的數據庫服務器的版本。數字是通過把主、次及版本號轉換成兩位十進制數并且把它們連接在一起組成的。例如，版本8.1.5將被返回80105，版本8.2將被返回80200（前導零沒有顯示）。如果連接失敗，則返回零。 `PQerrorMessage` 返回連接中操作產生的最近的錯誤信息。 ``` char *PQerrorMessage(const PGconn *conn); ``` 幾乎所有libpq函數在失敗時都會為`PQerrorMessage` 設置一個信息。注意，libpq的傳統是，一個非空的 `PQerrorMessage`結果會由多行組成，并且將包含一個結尾的新行。調用者不應該直接釋放結果。結果的釋放是在將`PGconn`句柄傳遞給 `PQfinish`的時候自動進行的。我們不能假設在不同的`PGconn` 結構操作中，結果字串都是一樣的。 `PQsocket` 獲取與服務器連接的套接字的文件描述符編號。一個有效的描述符應該是大于或等于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); ``` 此功能可應用于失敗或成功連接后嘗試檢測服務器是否要求密碼。 `PQgetssl` 返回連接中使用的SSL結構，或者沒有使用SSL則返回null。 ``` void *PQgetssl(const PGconn *conn); ``` 這個結構可以用于核實加密級別，檢查服務器認證等信息。參考OpenSSL 文檔獲取關于這個結構的更多信息。實際返回值的類型是`SSL *`，而`SSL`的類型是由 OpenSSL庫定義的，但是沒有用這種方式聲明，以避免請求OpenSSL頭文件。要使用這個函數，可以使用下面的代碼行： ``` #include <libpq-fe.h> #include <openssl/ssl.h> ... SSL *ssl; dbconn = PQconnectdb(...); ... ssl = PQgetssl(dbconn); if (ssl) { /* use OpenSSL functions to access ssl */ } ```