27.2. 连接状态函数 #
这些函数可用于查询现有数据库连接对象的状态。
提示
编写 libpq 应用程序时，应注意维护 PGconn 的抽象。请使用下述访问函数获取 PGconn 的内容。避免直接引用 PGconn 结构的字段，因为它们将来可能改变。（从 PostgreSQL 6.4 版开始，libpq-fe.h 中甚至不再提供 PGconn 背后的 struct 定义。如果你有直接访问 PGconn 字段的旧代码，可以通过同时包含 libpq-int.h 继续使用它，但我们建议你尽快修改这些代码。）
下面的函数返回在建立连接时确定的参数值。这些值在
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来恢复。关于可能见到的其他状态码，参见
PQconnectStart和PQconnectPoll的条目。PQtransactionStatus返回服务器当前的事务内状态。
PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
状态可以是
PQTRANS_IDLE（当前空闲）、PQTRANS_ACTIVE（一个命令正在执行）、PQTRANS_INTRANS（空闲，位于一个有效的事务块中）或PQTRANS_INERROR（空闲，位于一个失败的事务块中）。连接失效时报告PQTRANS_UNKNOWN。只有当查询已发送到服务器且尚未完成时才报告PQTRANS_ACTIVE。小心
当连接的是参数
autocommit设置为 off 的 PostgreSQL 7.3 服务器时，PQtransactionStatus会给出不正确的结果。服务器端的 autocommit 特性已被废弃，在后续服务器版本中不存在。PQparameterStatus查找服务器的一个当前参数设置。
const char *PQparameterStatus(const PGconn *conn, const char *paramName);
某些参数值会在连接启动时以及每当其值变化时由服务器自动报告。可以用
PQparameterStatus查询这些设置。它在参数已知时返回该参数的当前值，参数未知时返回NULL。截至当前版本会报告的参数包括
server_version（启动后不能变化）、client_encoding、is_superuser、session_authorization和DateStyle。3.0 之前协议的服务器不报告参数设置，但 libpq 内含获取
server_version和client_encoding值的逻辑。鼓励应用使用PQparameterStatus而不是自行编写代码来确定这些值。（但要注意，在 3.0 之前的连接上，连接启动后通过SET更改client_encoding不会反映到PQparameterStatus中。）PQprotocolVersion查询所使用的前端/后端协议。
int PQprotocolVersion(const PGconn *conn);
应用可能希望用它判断是否支持某些特性。目前可能的取值为 2（2.0 协议）、3（3.0 协议）或零（连接失效）。连接启动完成后此值不会变化，但在连接重置期间理论上可能变化。与 PostgreSQL 7.4 或更高版本的服务器通信时通常使用 3.0 协议；7.4 之前的服务器只支持 2.0 协议。（1.0 协议已过时，libpq 不支持。）
PQerrorMessagechar *PQerrorMessage(const PGconn* conn);
几乎所有 libpq 函数在失败时都会为
PQerrorMessage设置一条消息。注意，按照 libpq 的惯例，非空的PQerrorMessage结果会包含一个末尾换行符。PQsocket获取到服务器的连接套接字的文件描述符号。有效的描述符大于等于 0；结果为 -1 表示当前没有打开的服务器连接。（正常操作期间此值不会变化，但在连接建立或重置期间可能变化。）
int PQsocket(const PGconn *conn);
PQbackendPIDint PQbackendPID(const PGconn *conn);
后端 PID 可用于调试，也可用于与
NOTIFY消息（其中包含发出通知的后端进程的 PID）进行比较。注意，该 PID 属于数据库服务器主机上执行的进程，而不是本地主机上的进程！PQgetssl返回连接中使用的 SSL 结构；若未使用 SSL 则返回空。
SSL *PQgetssl(const PGconn *conn);
此结构可用于核实加密级别、检查服务器证书等。有关此结构的信息，请参阅 OpenSSL 文档。
必须定义
USE_SSL才能获得此函数的原型。这样做还会自动包含来自 OpenSSL 的ssl.h。