## 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 the`PGconn`abstraction. Use the accessor functions described below to get at the contents of`PGconn`. Reference to internal`PGconn`fields using`libpq-int.h`is 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 of[`PQhost`](libpq-status.html#LIBPQ-PQHOST),[`PQport`](libpq-status.html#LIBPQ-PQPORT), and[`PQpass`](libpq-status.html#LIBPQ-PQPASS)can change if a new connection is established using the same`PGconn`object. Other values are fixed for the lifetime of the`PGconn`object.

`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`](libpq-status.html#LIBPQ-PQPASS)将返回连接参数中指定的密码，或者如果没有密码并且密码是从[密码文件](libpq-pgpass.html)，它会返回那个。在后一种情况下，如果在连接参数中指定了多个主机，则无法依赖于[`通行证`](libpq-status.html#LIBPQ-PQPASS)直到建立连接。可以使用该功能检查连接状态[`PQ状态`](libpq-status.html#LIBPQ-PQSTATUS).

`主机`[](<>)

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

```
char *PQhost(const PGconn *conn);
```

如果连接参数同时指定`主持人`和`主机地址`， 然后[`主机`](libpq-status.html#LIBPQ-PQHOST)将返回`主持人`信息。要是`主机地址`被指定，然后返回。如果在连接参数中指定了多个主机，[`主机`](libpq-status.html#LIBPQ-PQHOST)返回实际连接的主机。

[`主机`](libpq-status.html#LIBPQ-PQHOST)返回`空值`如果*`康恩`*论据是`空值`.否则，如果生成主机信息时出错（可能连接尚未完全建立或出现错误），则返回一个空字符串。

如果在连接参数中指定了多个主机，则无法依赖于[`主机`](libpq-status.html#LIBPQ-PQHOST)直到建立连接。可以使用该功能检查连接状态[`PQ状态`](libpq-status.html#LIBPQ-PQSTATUS).

`PQhostaddr`[](<>)

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

```
char *PQhostaddr(const PGconn *conn);
```

[`PQhostaddr`](libpq-status.html#LIBPQ-PQHOSTADDR)返回`空值`如果*`康恩`*论据是`空值`.否则，如果生成主机信息时出错（可能连接尚未完全建立或出现错误），则返回一个空字符串。

`端口`[](<>)

返回活动连接的端口。

```
char *PQport(const PGconn *conn);
```

如果在连接参数中指定了多个端口，[`端口`](libpq-status.html#LIBPQ-PQPORT)返回实际连接的端口。

[`端口`](libpq-status.html#LIBPQ-PQPORT)返回`空值`如果*`康恩`*论据是`空值`.否则，如果生成端口信息时出错（可能连接尚未完全建立或出现错误），则返回一个空字符串。

如果在连接参数中指定了多个端口，则无法依赖于[`端口`](libpq-status.html#LIBPQ-PQPORT)直到建立连接。可以使用该功能检查连接状态[`PQ状态`](libpq-status.html#LIBPQ-PQSTATUS).

`数量`[](<>)

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

```
char *PQtty(const PGconn *conn);
```

`PQ选项`[](<>)

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

```
char *PQoptions(const PGconn *conn);
```

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

`PQ状态`[](<>)

返回连接的状态。

```
ConnStatusType PQstatus(const PGconn *conn);
```

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

请参阅条目[`PQconnectStartParams`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS),`PQconnectStart`和`PQconnect 轮询`关于可能返回的其他状态代码。

`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参数状态`](libpq-status.html#LIBPQ-PQPARAMETERSTATUS)可用于询问这些设置。如果已知，则返回参数的当前值，或者`空值`如果参数未知。

截至当前版本报告的参数包括`服务器版本`,`server_encoding`,`客户端编码`,`应用名称`,`default_transaction_read_only`,`in_hot_standby`,`is_superuser`,`session_authorization`,`日期样式`,`间隔样式`,`时区`,`整数日期时间`， 和`standard_conforming_strings`.(`server_encoding`,`时区`， 和`整数日期时间`8.0 之前的版本未报告；`standard_conforming_strings`8.1 之前的版本未报告；`间隔样式`8.4 之前的版本未报告；`应用名称`9.0 之前的版本未报告；`default_transaction_read_only`和`in_hot_standby`14 之前的版本没有报告。）请注意`服务器版本`,`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版本[`每个部分使用两位数字；`](libpq-status.html#LIBPQ-PQSERVERVERSION)例如版本 9.1.5 将返回为 90105，版本 9.2.0 将返回为 90200。因此，为了确定功能兼容性，应用程序应该划分结果

PQserver版本[`通过 100 而不是 10000 来确定逻辑主版本号。`](libpq-status.html#LIBPQ-PQSERVERVERSION)在所有版本系列中，次要版本（错误修复版本）之间只有最后两位数不同。PQerrorMessage

`返回由对连接的操作最近生成的错误消息。`[](<>)

[](<>)几乎所有的 libpq 函数都会为

```
char *PQerrorMessage(const PGconn *conn);
```

PQerrorMessage[`如果他们失败了。`](libpq-status.html#LIBPQ-PQERRORMESSAGE)请注意，根据 libpq 约定，非空PQerrorMessage[`结果可以由多行组成，并且将包含一个尾随换行符。`](libpq-status.html#LIBPQ-PQERRORMESSAGE)调用者不应直接释放结果。当关联的时候它会被释放PGconn`句柄被传递给`PQ完成[`.`](libpq-connect.html#LIBPQ-PQFINISH)不应期望结果字符串在`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`](libpq-status.html#LIBPQ-PQSSLINUSE)相反，有关连接的更多详细信息，请使用[`PQssl属性`](libpq-status.html#LIBPQ-PQSSLATTRIBUTE).