pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
这些函数可用于查询现有数据库连接对象的状态。
编写 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。
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。