©
本文档使用 PHP中文网手册 发布
这些函数可以用于询问现存数据库连接对象的状态。
Tip: libpq应用程序员应该仔细维护PGconn结构。 使用下面的访问函数来获取PGconn的内容。 避免直接引用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参数,并且设置为关闭的PostgreSQL7.3版本的服务器,
那么 |
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。standard_conforming_strings在版本8.1之前没有报告。) 请注意server_version, server_encoding和 integer_datetimes不能在启动后修改。
协议版本3.0之前的服务器不会报告参数设置,但是libpq里包含一些逻辑用于
获取server_version和client_encoding的数值。我们鼓励应用里面使用PQparameterStatus
,
而不是使用特殊的代码来检测这些值。(不过要注意,在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版本的协议),或者零(连接错误)。在连接启动完成之后,这个数值将不会改变, 但是在连接重置的过程中,理论上是可能改变的。3.0协议通常将用于与PostgreSQL7.4或者更新版本的 服务器通讯;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
的时候自动进行的。我们不能假设在不同的PQfinish
结构操作中,
结果字串都是一样的。
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的话返回NULL。
SSL *PQgetssl(const PGconn *conn);
这个结构可以用于核实加密级别,检查服务器认证等信息。参考OpenSSL文档获取关于这个结构的更多信息。
为了获取这个函数的正确原形,你必须定义USE_SSL。 这样做会自动包含来自OpenSSL的ssl.h。