?
This document uses PHP Chinese website manual Release
這些函數(shù)可以用于詢問現(xiàn)存數(shù)據(jù)庫連接對象的狀態(tài)。
Tip: libpq應(yīng)用程序員應(yīng)該仔細(xì)維護PGconn結(jié)構(gòu)。 使用下面的訪問函數(shù)來獲取PGconn的內(nèi)容。 避免直接引用PGconn結(jié)構(gòu)里的字段,因為這些字段在今后可能被改變。
下面的函數(shù)返回連接建立時的參數(shù)。這些參數(shù)在PGconn對象的生命期期間是固定的。
PQdb
返回連接的數(shù)據(jù)庫名。
char *PQdb(const PGconn *conn);
PQuser
返回連接的用戶名。
char *PQuser(const PGconn *conn);
PQpass
返回連接的口令。
char *PQpass(const PGconn *conn);
PQhost
返回連接的服務(wù)器主機名。
char *PQhost(const PGconn *conn);
PQport
返回連接的端口號。
char *PQport(const PGconn *conn);
PQtty
返回連接的調(diào)試控制臺TTY。(這個已經(jīng)過時了,因為服務(wù)器不再注意TTY設(shè)置, 這個函數(shù)存在是為了向下兼容。)
char *PQtty(const PGconn *conn);
PQoptions
返回連接請求中傳遞的命令行選項。
char *PQoptions(const PGconn *conn);
下面的函數(shù)返回那些在對PGconn對象進行操作的過程中可能變化的狀態(tài)數(shù)據(jù)。
PQstatus
返回連接的狀態(tài)。
ConnStatusType PQstatus(const PGconn *conn);
這個狀態(tài)可以是一系列值之一。不過,我們在一個異步連接過程外面只能看到其中的兩個:
CONNECTION_OK和
CONNECTION_BAD。一個與數(shù)據(jù)庫的成功的連接返回狀態(tài)CONNECTION_OK。
一次失敗的企圖用狀態(tài)CONNECTION_BAD標(biāo)識。通常,一個OK狀態(tài)將保持到PQfinish
,
但是一個通訊失敗可能會導(dǎo)致狀態(tài)過早地改變?yōu)?tt class="LITERAL">CONNECTION_BAD。
這時應(yīng)用可以試著調(diào)用PQreset
來恢復(fù)。
參閱PQconnectStartParams
,PQconnectStart
和PQconnectPoll
條目看看可能出現(xiàn)的其他的狀態(tài)碼。
PQtransactionStatus
返回當(dāng)前服務(wù)器的事務(wù)內(nèi)狀態(tài)。
PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
狀態(tài)可以是PQTRANS_IDLE(當(dāng)前空閑),PQTRANS_ACTIVE(正在處理一個命令), PQTRANS_INTRANS(空閑,在一個合法的事務(wù)塊內(nèi)), 或者PQTRANS_INERROR(空閑,在一個失敗的事務(wù)塊內(nèi))。 如果連接有問題,則返回PQTRANS_UNKNOWN。只有在一個查詢發(fā)送給了服務(wù)器并且還 沒有完成的時候才返回PQTRANS_ACTIVE。
Caution |
如果使用一個支持autocommit參數(shù),并且設(shè)置為關(guān)閉的PostgreSQL7.3版本的服務(wù)器,
那么 |
PQparameterStatus
查找服務(wù)器的一個當(dāng)前參數(shù)設(shè)置。
const char *PQparameterStatus(const PGconn *conn,const char *paramName);
有些參數(shù)在建立連接或者它們的值改變的時候會由服務(wù)器自動報告。PQparameterStatus
可以
用于查詢這些設(shè)置。如果它認(rèn)識這些參數(shù),那么它返回當(dāng)前值,否則返回NULL。
當(dāng)前版本報告的參數(shù)有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。standard_conforming_strings在版本8.1之前沒有報告。) 請注意server_version, server_encoding和 integer_datetimes不能在啟動后修改。
協(xié)議版本3.0之前的服務(wù)器不會報告參數(shù)設(shè)置,但是libpq里包含一些邏輯用于
獲取server_version和client_encoding的數(shù)值。我們鼓勵應(yīng)用里面使用PQparameterStatus
,
而不是使用特殊的代碼來檢測這些值。(不過要注意,在3.0之前的連接協(xié)議里,
啟動后通過 SET 改變了client_encoding將不會被PQparameterStatus
反映出來。)
對于server_version,又見PQserverVersion
,它返回數(shù)值形式,更容易進行比較。
如果沒有為standard_conforming_strings報告數(shù)值,應(yīng)用可以假設(shè)它是off,也就是說, 在字串文本里,把反斜扛當(dāng)作逃逸。同樣,如果出現(xiàn)了這個參數(shù),就可以當(dāng)作一個標(biāo)志, 表示接受逃逸字串(E'...')的語法。
盡管返回的指針聲明為const,它實際上指向一個和PGconn結(jié)構(gòu)關(guān)聯(lián)的可變的存儲區(qū)。 因此假設(shè)這個指針跨查詢保持有效是不明智的。
PQprotocolVersion
查詢所使用的前/后端協(xié)議。
int PQprotocolVersion(const PGconn *conn);
應(yīng)用可能希望使用這個函數(shù)來判斷某種特性是否被支持。目前,可能的數(shù)值是2(2.0版本的協(xié)議) ,3(3.0版本的協(xié)議),或者零(連接錯誤)。在連接啟動完成之后,這個數(shù)值將不會改變, 但是在連接重置的過程中,理論上是可能改變的。3.0協(xié)議通常將用于與PostgreSQL7.4或者更新版本的 服務(wù)器通訊;7.4以前的版本只支持2.0版本的協(xié)議。(1.0版本的協(xié)議已經(jīng)過時了, 不再被libpq支持。)
PQserverVersion
返回一個整數(shù),代表后端版本。
int PQserverVersion(const PGconn *conn);
應(yīng)用可以使用這個函數(shù)判斷它們連接的數(shù)據(jù)庫服務(wù)器的版本。數(shù)字是通過把主、次、 以及發(fā)布版本好轉(zhuǎn)換成兩位十進制數(shù)并且把它們連接在一起組成的。比如,版本8.1.5將轉(zhuǎn)換 為80105,而8.2將轉(zhuǎn)換為80200(不顯示前導(dǎo)的零)。如果連接失敗,則返回零。
PQerrorMessage
返回連接中操作產(chǎn)生的最近的錯誤信息。
char *PQerrorMessage(const PGconn *conn);
幾乎所有libpq函數(shù)在失敗時都會為PQerrorMessage
設(shè)置一個信息。
注意libpq的傳統(tǒng)是,一個非空的PQerrorMessage
將在結(jié)尾包含一個新行。
調(diào)用者不應(yīng)該直接釋放結(jié)果。
結(jié)果的釋放是在將PGconn句柄傳遞給PQfinish
的時候自動進行的。我們不能假設(shè)在不同的PQfinish
結(jié)構(gòu)操作中,
結(jié)果字串都是一樣的。
PQsocket
獲取與服務(wù)器連接的套接字的文件描述符編號。一個有效的描述符應(yīng)該是大于或等于0; 結(jié)果為-1表示當(dāng)前沒有與服務(wù)器的連接打開。(在正常的操作中,這個結(jié)果不會改變, 但是可能在啟動或者重置的過程中變化。)
int PQsocket(const PGconn *conn);
PQbackendPID
返回處理此連接的服務(wù)器服務(wù)器的進程號ID(PID)。
int PQbackendPID(const PGconn *conn);
這個服務(wù)器PID在調(diào)試和對比NOTIFY信息(包含發(fā)出通知的服務(wù)器進程的 PID)時很有用。 注意該PID屬于運行數(shù)據(jù)庫服務(wù)器的主機的進程,而不是本地主機!
PQconnectionNeedsPassword
如果連接的身份驗證方法 需要一個密碼返回true(1),但是沒有可用的。 返回False(0),如果沒有。
int PQconnectionNeedsPassword(const PGconn *conn);
此功能可用于連接嘗試失敗后 決定是否提示用戶輸入密碼。
PQconnectionUsedPassword
返回true(1),如果連接的身份驗證方法 使用密碼。如果不,返回False(0)。
int PQconnectionUsedPassword(const PGconn *conn);
此功能可應(yīng)用于失敗或成功后 嘗試連接到檢測服務(wù)器是否要求密碼。
PQgetssl
返回連接使用的結(jié)構(gòu), 或者如果沒有使用SSL的話返回NULL。
SSL *PQgetssl(const PGconn *conn);
這個結(jié)構(gòu)可以用于核實加密級別,檢查服務(wù)器認(rèn)證等信息。參考OpenSSL文檔獲取關(guān)于這個結(jié)構(gòu)的更多信息。
為了獲取這個函數(shù)的正確原形,你必須定義USE_SSL。 這樣做會自動包含來自OpenSSL的ssl.h。