# 34.2. Connection Status Functions

These functions can be used to interrogate the status of an existing database connection object.

# Tip

libpq application programmers should be careful to maintain thePGconnabstraction. Use the accessor functions described below to get at the contents ofPGconn. Reference to internalPGconnfields usinglibpq-int.his not recommended because they are subject to change in the future.

The following functions return parameter values established at connection. These values are fixed for the life of the connection. If a multi-host connection string is used, the values ofPQhost,PQport, andPQpasscan change if a new connection is established using the samePGconnobject. Other values are fixed for the lifetime of thePGconnobject.

PQdb

Returns the database name of the connection.

char *PQdb(const PGconn *conn);

PQuser

Returns the user name of the connection.

char *PQuser(const PGconn *conn);

PQpass

Returns the password of the connection.

char *PQpass(const PGconn *conn);

PQpass将返回连接参数中指定的密码,或者如果没有密码并且密码是从密码文件,它会返回那个。在后一种情况下,如果在连接参数中指定了多个主机,则无法依赖于通行证直到建立连接。可以使用该功能检查连接状态PQ状态.

主机

返回活动连接的服务器主机名。如果连接是通过 Unix 套接字,这可以是主机名、IP 地址或目录路径。(路径情况可以区分,因为它始终是绝对路径,以/.)

char *PQhost(const PGconn *conn);

如果连接参数同时指定主持人主机地址, 然后主机将返回主持人信息。要是主机地址被指定,然后返回。如果在连接参数中指定了多个主机,主机返回实际连接的主机。

主机返回空值如果*康恩*论据是空值.否则,如果生成主机信息时出错(可能连接尚未完全建立或出现错误),则返回一个空字符串。

如果在连接参数中指定了多个主机,则无法依赖于主机直到建立连接。可以使用该功能检查连接状态PQ状态.

PQhostaddr

返回活动连接的服务器 IP 地址。这可以是主机名解析到的地址,也可以是通过主机地址范围。

char *PQhostaddr(const PGconn *conn);

PQhostaddr返回空值如果*康恩*论据是空值.否则,如果生成主机信息时出错(可能连接尚未完全建立或出现错误),则返回一个空字符串。

端口

返回活动连接的端口。

char *PQport(const PGconn *conn);

如果在连接参数中指定了多个端口,端口返回实际连接的端口。

端口返回空值如果*康恩*论据是空值.否则,如果生成端口信息时出错(可能连接尚未完全建立或出现错误),则返回一个空字符串。

如果在连接参数中指定了多个端口,则无法依赖于端口直到建立连接。可以使用该功能检查连接状态PQ状态.

数量

这个函数不再做任何事情,但它仍然是为了向后兼容。该函数总是返回一个空字符串,或者空值如果*康恩*论据是空值.

char *PQtty(const PGconn *conn);

PQ选项

返回连接请求中传递的命令行选项。

char *PQoptions(const PGconn *conn);

以下函数返回状态数据,这些数据可以随着在PGconn目的。

PQ状态

返回连接的状态。

ConnStatusType PQstatus(const PGconn *conn);

状态可以是多个值之一。但是,在异步连接过程之外只能看到其中两个:CONNECTION_OKCONNECTION_BAD.与数据库的良好连接具有状态CONNECTION_OK.失败的连接尝试由状态发出信号CONNECTION_BAD.通常,OK 状态会一直保持到PQ完成,但通信失败可能会导致状态更改为CONNECTION_BAD过早地。在这种情况下,应用程序可以尝试通过调用来恢复复位.

请参阅条目PQconnectStartParams,PQconnectStartPQconnect 轮询关于可能返回的其他状态代码。

PQ事务状态

返回服务器当前的事务中状态。

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

状态可以是PQTRANS_IDLE(目前空闲),PQTRANS_ACTIVE(一个命令正在进行中),PQTRANS_INTRANS(空闲,在有效的交易块中),或PQTRANS_INERROR(空闲,在失败的事务块中)。PQTRANS_UNKNOWN如果连接不好,则报告。PQTRANS_ACTIVE仅当查询已发送到服务器但尚未完成时才报告。

PQ参数状态

查找服务器的当前参数设置。

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

服务器会在连接启动时或每当它们的值发生变化时自动报告某些参数值。PQ参数状态可用于询问这些设置。如果已知,则返回参数的当前值,或者空值如果参数未知。

截至当前版本报告的参数包括服务器版本,server_encoding,客户端编码,应用名称,default_transaction_read_only,in_hot_standby,is_superuser,session_authorization,日期样式,间隔样式,时区,整数日期时间, 和standard_conforming_strings.(server_encoding,时区, 和整数日期时间8.0 之前的版本未报告;standard_conforming_strings8.1 之前的版本未报告;间隔样式8.4 之前的版本未报告;应用名称9.0 之前的版本未报告;default_transaction_read_onlyin_hot_standby14 之前的版本没有报告。)请注意服务器版本,server_encoding整数日期时间启动后无法更改。

如果没有价值standard_conforming_strings被报告,应用程序可以假设它是离开,也就是说,反斜杠在字符串文字中被视为转义。此外,此参数的存在可以视为转义字符串语法 (E'...') 被接受。

虽然声明了返回的指针常量,它实际上指向与PGconn结构体。假设指针在查询中保持有效是不明智的。

PQ协议版本

询问正在使用的前端/后端协议。

int PQprotocolVersion(const PGconn *conn);

应用程序可能希望使用此功能来确定是否支持某些功能。目前,可能的值为 3(3.0 协议)或零(连接不良)。协议版本在连接启动完成后不会改变,但理论上可以在连接重置期间改变。PostgreSQL 服务器版本 7.4 及更高版本支持 3.0 协议。

PQserver版本

返回一个表示服务器版本的整数。

int PQserverVersion(const PGconn *conn);

应用程序可能会使用此函数来确定它们所连接的数据库服务器的版本。结果是通过将服务器的主要版本号乘以 10000 并加上次要版本号形成的。例如,版本 10.1 将返回为 100001,版本 11.0 将返回为 110000.如果连接不良,则返回零。在主要版本 10 之前,PostgreSQL 使用三部分版本号,其中前两部分一起代表主要版本。

对于那些版本,PQserver版本每个部分使用两位数字;例如版本 9.1.5 将返回为 90105,版本 9.2.0 将返回为 90200.因此,为了确定功能兼容性,应用程序应该划分结果

PQserver版本通过 100 而不是 10000 来确定逻辑主版本号。在所有版本系列中,次要版本(错误修复版本)之间只有最后两位数不同。PQerrorMessage

返回由对连接的操作最近生成的错误消息。

几乎所有的 libpq 函数都会为

char *PQerrorMessage(const PGconn *conn);

PQerrorMessage如果他们失败了。请注意,根据 libpq 约定,非空PQerrorMessage结果可以由多行组成,并且将包含一个尾随换行符。调用者不应直接释放结果。当关联的时候它会被释放PGconn句柄被传递给PQ完成.不应期望结果字符串在PGconn结构体。

PQsocket

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

int PQsocket(const PGconn *conn);

PQbackendPID

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

int PQbackendPID(const PGconn *conn);

后端 PID 可用于调试目的和比较通知消息(包括通知后端进程的 PID)。请注意,PID 属于在数据库服务器主机上执行的进程,而不是本地主机!

PQconnectionNeedsPassword

如果连接身份验证方法需要密码,但没有可用密码,则返回 true (1)。如果不是,则返回 false (0)。

int PQconnectionNeedsPassword(const PGconn *conn);

此功能可在连接尝试失败后应用,以决定是否提示用户输入密码。

PQconnectionUsedPassword

如果连接身份验证方法使用密码,则返回 true (1)。如果不是,则返回 false (0)。

int PQconnectionUsedPassword(const PGconn *conn);

此功能可以在连接尝试失败或成功后应用,以检测服务器是否要求输入密码。

以下函数返回与 SSL 相关的信息。建立连接后,此信息通常不会更改。

PQsslInUse

如果连接使用 SSL,则返回 true (1),否则返回 false (0)。

int PQsslInUse(const PGconn *conn);

PQssl属性

返回有关连接的 SSL 相关信息。

const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

可用属性列表因使用的 SSL 库和连接类型而异。如果属性不可用,则返回 NULL。

以下属性通常可用:

图书馆

正在使用的 SSL 实现的名称。(目前只有“OpenSSL”已实施)

协议

正在使用的 SSL/TLS 版本。共同的价值观是“TLSv1”,“TLSv1.1”“TLSv1.2”,但如果使用其他协议,实现可能会返回其他字符串。

关键位

加密算法使用的密钥位数。

密码

使用的密码套件的简称,例如,“DHE-RSA-DES-CBC3-SHA”.这些名称特定于每个 SSL 实现。

压缩

如果正在使用 SSL 压缩,则返回压缩算法的名称,如果使用了压缩但算法未知,则返回“on”。如果未使用压缩,则返回“关闭”。

PQsslAttributeNames

返回可用的 SSL 属性名称数组。数组由 NULL 指针终止。

const char * const * PQsslAttributeNames(const PGconn *conn);

PQssl结构

返回指向描述连接的特定于 SSL 实现的对象的指针。

void *PQsslStruct(const PGconn *conn, const char *struct_name);

可用的结构取决于使用的 SSL 实现。对于 OpenSSL,有一个名为“OpenSSL”的结构,它返回一个指向 OpenSSL 的指针SSL结构。要使用此功能,可以使用以下代码:

#include <libpq-fe.h>
#include <openssl/ssl.h>

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }

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

PQgetssl

返回连接中使用的 SSL 结构,如果 SSL 未使用,则返回 null。

void *PQgetssl(const PGconn *conn);

这个函数相当于PQsslStruct(conn, "OpenSSL").它不应该在新的应用程序中使用,因为返回的结构是特定于 OpenSSL 的,并且如果使用另一个 SSL 实现将不可用。要检查连接是否使用 SSL,请调用PQsslInUse相反,有关连接的更多详细信息,请使用PQssl属性.