↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4
历史版本PostgreSQL 7.4 已于 2010 年 10 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本。

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 不支持。)

PQerrorMessage

返回连接上最近一次操作所产生的错误消息。

char *PQerrorMessage(const PGconn* conn);

几乎所有 libpq 函数在失败时都会为 PQerrorMessage 设置一条消息。注意,按照 libpq 的惯例,非空的 PQerrorMessage 结果会包含一个末尾换行符。

PQsocket

获取到服务器的连接套接字的文件描述符号。有效的描述符大于等于 0;结果为 -1 表示当前没有打开的服务器连接。(正常操作期间此值不会变化,但在连接建立或重置期间可能变化。)

int PQsocket(const PGconn *conn);
PQbackendPID

返回处理此连接的后端服务器进程的进程 ID(PID)。

int PQbackendPID(const PGconn *conn);

后端 PID 可用于调试,也可用于与 NOTIFY 消息(其中包含发出通知的后端进程的 PID)进行比较。注意,该 PID 属于数据库服务器主机上执行的进程,而不是本地主机上的进程!

PQgetssl

返回连接中使用的 SSL 结构;若未使用 SSL 则返回空。

SSL *PQgetssl(const PGconn *conn);

此结构可用于核实加密级别、检查服务器证书等。有关此结构的信息,请参阅 OpenSSL 文档。

必须定义 USE_SSL 才能获得此函数的原型。这样做还会自动包含来自 OpenSSL 的 ssl.h。

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。