Postgresql 中文操作指南

34.2. Connection Status Functions #

这些函数可用于询问现有数据库连接对象的状况。

Tip

libpq 应用程序程序员应小心维护 PGconn 抽象。使用下面描述的访问函数检索 PGconn 的内容。不建议使用 libpq-int.h 引用内部 PGconn 字段，因为它们将来可能会发生更改。

以下函数返回在连接时建立的参数值。这些值在连接的生命周期内固定不变。如果使用多主机连接字符串，如果使用同一 PGconn 对象建立新连接，则 PQhost 、 PQport 和 PQpass 的值可能会更改。其他值在 PGconn 对象的生命周期内不变。

  • PQdb #

    • 返回连接的数据库名称。

char *PQdb(const PGconn *conn);

  • PQuser #

    • 返回连接的用户名。

char *PQuser(const PGconn *conn);

  • PQpass #

    • 返回连接的密码。

char *PQpass(const PGconn *conn);

  • PQpass 将返回连接参数中指定的密码，或者如果没有并且密码是从 password file 获取的，则将返回该密码。在后一种情况下，如果在连接参数中指定了多个主机，则在建立连接之前无法依赖 PQpass 的结果。可以使用函数 PQstatus 检查连接状态。

    • PQhost #

  • 返回活动连接的服务器主机名。如果连接通过 Unix 套接字进行，则这可以是主机名、IP 地址或目录路径。（可以通过它总是以 / 开始的绝对路径来区分路径情况。）

char *PQhost(const PGconn *conn);

  • 如果连接参数同时指定 host 和 hostaddr ，则 PQhost 将返回 host 信息。如果仅指定 hostaddr ，则返回该值。如果在连接参数中指定了多个主机， PQhost 返回实际连接到的主机。

  • 如果 conn 参数为 NULL ， PQhost 返回 NULL 。否则，如果为生成主机信息制造错误（可能是在连接尚未完全建立的时候或者有错误的情况下），则返回一个空字符串。

  • 如果在连接参数中指定了多个主机，则在连接建立之前无法依赖 PQhost 的结果。可以使用函数 PQstatus 检查连接状态。

    • PQhostaddr #

  • 返回活动连接的服务器 IP 地址。这可以是主机名解析到的地址，或通过 hostaddr 参数提供的 IP 地址。

char *PQhostaddr(const PGconn *conn);

  • 如果 conn 参数为 NULL ， PQhostaddr 返回 NULL 。否则，如果为生成主机信息制造错误（可能是在连接尚未完全建立的时候或者有错误的情况下），则返回一个空字符串。

    • PQport #

  • 返回活动连接的端口。

char *PQport(const PGconn *conn);

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

  • 如果 conn 参数为 NULL ， PQport 返回 NULL 。否则，如果为生成端口信息制造错误（可能是在连接尚未完全建立的时候或者有错误的情况下），则返回一个空字符串。

  • 如果在连接参数中指定了多个端口，则在建立连接之前无法依赖 PQport 的结果。可以使用函数 PQstatus 检查连接状态。

    • PQtty #

  • 此函数不再执行任何操作，但它仍然存在以保持向后兼容性。该函数始终返回空字符串，或者在 conn 参数为 NULL 时返回 NULL。

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 来恢复。

  • 参见 PQconnectStartParams 、 PQconnectStart 和 PQconnectPoll 的条目以查看可能返回的其他状态代码。

    • PQtransactionStatus #

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

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

  • 状态可以是 PQTRANS_IDLE（当前空闲）、PQTRANS_ACTIVE（正在执行命令）、PQTRANS_INTRANS（空闲，处于有效事务块中）或 PQTRANS_INERROR（空闲，处于失败的事务块中）。如果连接不良，则报告 PQTRANS_UNKNOWN。仅当查询已发送到服务器但尚未完成时，才会报告 PQTRANS_ACTIVE。

    • PQparameterStatus #

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

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

  • 服务器在连接启动时或只要其值更改时自动报告某些参数值。 PQparameterStatus 可用于询问这些设置。如果已知，它返回参数的当前值，或者如果参数未知，则返回 NULL 。

  • 当前版本报告的参数包括：

  • （在 8.0 之前的版本中没有报告 server_encoding、TimeZone 和 integer_datetimes；在 8.1 之前的版本中没有报告 standard_conforming_strings；在 8.4 之前的版本中没有报告 IntervalStyle；在 9.0 之前的版本中没有报告 application_name；在 14 之前的版本中没有报告 default_transaction_read_only 和 in_hot_standby；在 16 之前的版本中没有报告 scram_iterations）。请注意，server_version、server_encoding 和 integer_datetimes 在启动后无法更改。

  • 如果未报告 standard_conforming_strings 的值，应用程序可以假设其为 off ，即在字符串字面中反斜杠被视为转义符。此外，可以将这个参数的存在视为接受转义字符串语法（ E'…​' ）的标志。

  • 尽管返回的指针声明为 const，但它实际上指向与 PGconn 结构关联的可变存储。假设该指针在所有查询中都保持有效是不明智的。

    • PQprotocolVersion #

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

int PQprotocolVersion(const PGconn *conn);

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

    • PQserverVersion #

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

int PQserverVersion(const PGconn *conn);

  • 应用程序可能使用此函数来确定他们连接的数据库服务器的版本。结果是将服务器的主版本号乘以 10000，并添加次要版本号。例如，版本 10.1 将返回 100001，版本 11.0 将返回 110000。如果连接断开，则返回零。

  • 在第 10 个主要版本之前，PostgreSQL 使用三位版本号，其中前两部分共同表示主要版本。对于这些版本， PQserverVersion 对每部分使用两位数字；例如，版本 9.1.5 将返回 90105，版本 9.2.0 将返回 90200。

  • 因此，为了确定功能兼容性，应用程序应将 PQserverVersion 的结果除以 100，而不是 10000，来确定一个逻辑的主要版本号。在所有版本系列中，只有最后两位数字在次要版本（错误修复版本）中有所不同。

    • PQerrorMessage #

  • 返回因连接操作而最近生成的一个错误消息。

char *PQerrorMessage(const PGconn *conn);

  • 几乎所有 libpq 函数在失败时都会为 PQerrorMessage 设置一个消息。请注意，按照 libpq 约定，非空 PQerrorMessage 结果可能包含多行，并且结尾处会有一个换行符。调用者不应直接释放结果。在将关联的 PGconn 句柄传给 PQfinish 时，它会释放。不应期望结果字符串在对 PGconn 结构执行的操作之间保持不变。

    • PQsocket #

  • 获取与服务器的连接套接字的文件描述符号。有效描述符将大于或等于 0；-1 的结果表示当前未打开服务器连接。（在正常操作期间不会更改，但在连接建立或重置期间可能会更改。）

int PQsocket(const PGconn *conn);

  • PQbackendPID #

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

int PQbackendPID(const PGconn *conn);

  • 后端 PID 用于调试目的，并与 NOTIFY 消息进行比较（其中包含通知后端进程的 PID）。请注意，PID 属于在数据库服务器主机上执行的进程，而不是本地主机！

    • PQconnectionNeedsPassword #

  • 如果连接认证方法需要密码，但没有密码可用，则返回真 (1)。如果没有，则返回假 (0)。

int PQconnectionNeedsPassword(const PGconn *conn);

  • 可以将此函数应用于失败的连接尝试之后，以决定是否提示用户输入密码。

    • PQconnectionUsedPassword #

  • 如果连接认证方法使用了密码，则返回真 (1)。如果没有，则返回假 (0)。

int PQconnectionUsedPassword(const PGconn *conn);

  • 此功能可在尝试连接后（无论是成功还是失败）应用，以检测服务器是否要求输入密码。

    • PQconnectionUsedGSSAPI #

  • 如果连接认证方法使用 GSSAPI，则返回 true (1)。如果不使用，则返回 false (0)。

int PQconnectionUsedGSSAPI(const PGconn *conn);

  • 此功能可用于检测连接是否已通过 GSSAPI 进行认证。

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

  • PQsslInUse #

    • 如果连接使用 SSL，则返回 true (1)，如果不使用，则返回 false (0)。

int PQsslInUse(const PGconn *conn);

  • PQsslAttribute #

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

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

  • 可用属性的列表取决于所使用的 SSL 库和连接类型。如果连接不使用 SSL 或所指定的属性名称未在所使用的库中定义，则返回 NULL。

  • 通常提供以下属性：

  • 作为特例，无需连接即可通过将 NULL 传递为 _conn_参数来查询 _library_属性。结果将是默认 SSL 库名称，如果在不提供任何 SSL 支持的情况下编译 libpq，则为 NULL。（在 PostgreSQL 版本 15 之前，将 NULL 传递为 _conn_参数始终会得到 NULL。需要区分这种情况下较新和较旧实现的客户端程序可以检查 _LIBPQ_HAS_SSL_LIBRARY_DETECTION_特性宏。）

    • PQsslAttributeNames #

  • 返回可在 _PQsslAttribute()_中使用的 SSL 属性名称数组。数组以 NULL 指针结尾。

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

  • 如果 _conn_为 NULL，则返回可用于默认 SSL 库的属性，如果在不提供任何 SSL 支持的情况下编译 libpq，则返回空列表。如果 _conn_不为 NULL，则返回用于连接的 SSL 库提供的属性，如果连接没有加密，则返回空列表。

    • PQsslStruct #

  • 返回一个指针，指向描述连接的 SSL 实现特定对象的连接。如果该连接未加密或请求的类型在该连接的 SSL 实现中不可用，则返回 NULL。

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 ，并且如要获取连接的更多详细信息，请使用 PQsslAttribute 。

    • library

  • 所用 SSL 实现的名称。（目前，仅实现了 "OpenSSL"）

    • protocol

  • 使用的 SSL/TLS 版本。常见的值为 "TLSv1"、"TLSv1.1"_和 _"TLSv1.2"，但如果使用其他协议，实现可能会返回其他字符串。

    • key_bits

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

    • cipher

  • 使用的密码套件的简短名称，例如 "DHE-RSA-DES-CBC3-SHA"。名称特定于每个 SSL 实现。

    • compression

  • 如果正在使用 SSL 压缩，则返回“已启用”，否则返回“已禁用”。