新建到数据库服务器的连接。

PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);

此函数使用从两个 NULL 终止的数组中获取的参数打开一个新的数据库连接。第一个 keywords 定义为一种字符串数组，其中每一个都是一个关键字。第二个 values 为每个关键字提供值。与下面的 PQsetdbLogin 不同，参数设置可在不更改函数签名的情况下得到扩展，因此，首选将此函数（或其非阻塞类似项 PQconnectStartParams 和 PQconnectPoll）用于新的应用程序编程。

当前识别的参数关键字列在第 32.1.2 节中。

为了使用所有默认参数，传递的数组可以为空，也可以包含一个或多个参数设置。这些参数的长度必须相匹配。处理会在 keywords 数组中的第一个 NULL 条目处停止。此外，如果与非 NULL keywords 条目关联的 values 条目为 NULL 或空字符串，那么将忽略该条目，并继续处理下一组数组条目。

当 expand_dbname 为非零时，将检查用于第一个 dbname 关键字的值，以查看其是否是一个 连接字符串。如果它是，那么将使用从字符串提取的各个连接参数将其 “扩展” 到各个连接参数中。如果值中包含一个等号 (=) 或以 URI 方案标志符开头，则该值将被视为一个连接字符串，而不仅仅是一个数据库名。（连接字符串格式的更多详细信息出现在 第 32.1.1 节中。）仅第一个出现的 dbname 将以这种方式进行对待；任何随后的 dbname 参数都将被视为一个普通的数据库名进行处理。

总的来说，参数数组会从开始到结束进行处理。如果任何关键字重复出现，则将使用最后一个值（不是 NULL 或空的值）。当连接字符串中发现的关键字与 keywords 数组中出现的关键字冲突时，此规则尤其适用。因此，程序员可以确定数组条目是否可以覆盖或被连接字符串中的值覆盖。在 dbname 条目扩展之前出现的数组条目可以通过连接字符串字段覆盖，而这些字段又会被 dbname 之后出现的数组条目覆盖（但前提是这些条目提供非空值）。

处理所有数组条目及任何扩展连接字符串之后，所有仍未设置的连接参数均填充为默认值。如果已设置未设置参数的相应环境变量（见 第 32.15 节），则使用其值。如果未设置环境变量，则使用参数的内置默认值。

新建到数据库服务器的连接。

PGconn *PQconnectdb(const char *conninfo);

该函数使用从字符串 conninfo 中获取的参数打开一个新的数据库连接。

传递的字符串可以为空，以使用所有默认参数，或者它可以包含一个或多个由空格分隔的参数设置，或者它可以包含一个URI。有关详情，请参阅 第 32.1.1 节。

新建到数据库服务器的连接。

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);

这是 PQconnectdb 的前身，具有固定的一组参数。它具有相同的功能，不同之处在于缺失的参数将始终采用默认值。对于要设置为默认值的所有固定参数，请写入 NULL 或空字符串。

如果 dbName 包含 = 符号或具有有效的连接URI前缀，则它将被视为一个 conninfo 字符串，与将其传递给 PQconnectdb 的方式完全相同，然后将剩余参数根据 PQconnectdbParams 的说明进行应用。

pgtty 不再使用，传递的任何值都将被忽略。

新建到数据库服务器的连接。

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);

这是一个宏，它为 login 和 pwd 参数调用 PQsetdbLogin，其中包含空指针。它是为了向后兼容非常旧的程序。

以非阻塞方式连接到数据库服务器。

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                             int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);

这三个函数用于打开与数据库服务器的连接，目的是在执行此操作时，应用程序的执行线程不会被远端 I/O 阻塞。这种方式的目的是，等待 I/O 完成的操作发生在应用程序的主循环中，而不是在 PQconnectdbParams 或 PQconnectdb 中，以便应用程序可以与其他活动并行处理此操作。

使用 PQconnectStartParams，将使用从 keywords 和 values 数组中获取的参数建立数据库连接，并受 expand_dbname 控制，如上述 PQconnectdbParams 所述。

使用 PQconnectStart，将使用从字符串 conninfo 中获取的参数建立数据库连接，如上述 PQconnectdb 所述。

只要满足一些限制，PQconnectStartParams、PQconnectStart 和 PQconnectPoll 都不会阻塞

要开始一个非阻塞连接请求，请调用 PQconnectStart 或 PQconnectStartParams。如果结果为 null，则 libpq 无法分配一个新的 PGconn 结构。否则，会返回一个有效的 PGconn 指针（虽然它还不表示与数据库的有效连接）。接下来调用 PQstatus(conn)。如果结果为 CONNECTION_BAD，那么连接尝试已经失败，通常是因为连接参数无效。

如果 PQconnectStart 或 PQconnectStartParams 成功，下一步是对 libpq 进行轮询以便其能继续连接序列。使用 PQsocket(conn) 获得基础数据库连接的套接字的描述符。（谨慎：不要假设套接字在 PQconnectPoll 调用时保持不变。）因此进行循环：如果 PQconnectPoll(conn) 上次返回 PGRES_POLLING_READING，则一直等到套接字准备读取（由 select()、poll() 或类似系统函数指示）。请注意，如果系统上提供了 select(2) 或 poll(2)，PQsocketPoll 可通过抽取设置来帮助减少样板文件。然后再次调用 PQconnectPoll(conn)。相反，如果 PQconnectPoll(conn) 上次返回 PGRES_POLLING_WRITING，则一直等到套接字准备写入，然后再次调用 PQconnectPoll(conn)。在第一次迭代（即如果你尚未调用 PQconnectPoll）中，请像其上次返回 PGRES_POLLING_WRITING 一样行事。继续此循环，直到 PQconnectPoll(conn) 返回 PGRES_POLLING_FAILED（指示连接过程已失败）或返回 PGRES_POLLING_OK（指示连接已成功建立）。

在连接期间的任何时候，都可以通过调用 PQstatus 检查连接状态。如果此调用返回 CONNECTION_BAD，则连接过程失败；如果调用返回 CONNECTION_OK，则连接准备就绪。以上述所述 PQconnectPoll 的返回值可以等量地检测到这两种状态。在异步连接过程中（且只在该过程中），也可能出现其他状态。这些状态可指示连接过程的当前阶段，并且可能可用于向用户提供反馈，例如，这些状态是

请注意，尽管这些常量将保留（为了保持兼容性），但应用程序切勿依赖于这些常量按特定顺序（或按任意顺序）发生，也切勿依赖于状态始终为这些记录值之一。应用程序可以执行类似于以下操作

switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

使用 PQconnectPoll 时，忽略 connect_timeout 连接参数；应用程序负责决定是否过了过长的时间。否则，PQconnectStart 后跟 PQconnectPoll 循环等效于 PQconnectdb。

请注意，当 PQconnectStart 或 PQconnectStartParams 返回一个非空指针时，在使用完指针后必须调用 PQfinish 以处置结构体和任何关联的内存块。即使连接尝试失败或被终止，也必须执行此操作。

轮询使用 PQsocket 检索的连接基础套接字描述符。此函数的主要用途是遍历 PQconnectStartParams 文档中介绍的连接序列。

typedef pg_int64 pg_usec_time_t;

int PQsocketPoll(int sock, int forRead, int forWrite,
                 pg_usec_time_t end_time);

此函数会轮询一个文件描述符（可以带超时设置）。如果 forRead 为非零，则当套接字可供读取时，函数将终止。如果 forWrite 为非零，则当套接字可供写入时，函数将终止。

超时由end_time指定，它是在 Unix 时间戳（即time_t乘以 100 万）后停止等待的时间数（以微秒为单位）。如果end_time为-1，则超时时间为无限。如果 end_time 为 0（或实际上是任何时间，只要在当前时间之前），那么超时时间为立即（无阻塞）。可以通过将所需的微秒数添加到PQgetCurrentTimeUSec 的结果中来方便地计算超时值。请注意，底层系统调用可能精确度低于微秒，因此实际延迟可能不准确。

如果满足指定条件，该函数将返回大于0 的值；如果发生超时，则返回0；如果出错，则返回-1。可以通过检查errno(3) 值来检索错误。在forRead 和forWrite 同时为零时，该函数将立即返回超时指示。

PQsocketPoll 使用 poll(2) 或 select(2)（取决于平台）实现。请参阅poll(2)中的POLLIN 和POLLOUT，或select(2)中的readfds 和writefds，以了解更多信息。

返回默认连接选项。

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Indicates how to display this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
} PQconninfoOption;

返回连接选项数组。可用于确定所有可能的PQconnectdb 选项及其当前默认值。返回值指向PQconninfoOption 结构的数组，该数组以具有空keyword 指针的条目结尾。如果无法分配内存，则返回空指针。请注意，当前默认值（val 字段）将取决于环境变量和其他上下文。将忽略缺少或无效的服务文件。调用方必须将连接选项数据视为只读。

处理选项数组后，通过将其传递给PQconninfoFree 来释放。如果不执行此操作，那么每次调用PQconndefaults 都会泄漏少量内存。

返回活动连接所使用的连接选项。

PQconninfoOption *PQconninfo(PGconn *conn);

返回连接选项数组。这可用于确定所有可能的 PQconnectdb 选项以及用于连接到服务器的值。返回值指向 PQconninfoOption 结构的数组，其以一个具有空 keyword 指针的条目结尾。对于 PQconndefaults 的所有上述说明也适用于 PQconninfo 的结果。

从提供的连接字符串返回已解析的连接选项。

PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);

解析连接字符串并返回所得选项作为数组；或在连接字符串出现问题时返回 NULL。该函数可用于提取提供的连接字符串中的 PQconnectdb 选项。返回值指向 PQconninfoOption 结构的数组，其以一个具有空 keyword 指针的条目结尾。

所有合法选项都将在结果数组中出现，但连接字符串中不存在的任何选项的 PQconninfoOption 将使 val 设置为 NULL；不会插入默认值。

如果 errmsg 不为 NULL，则 *errmsg 在成功时将被设置为 NULL，否则被设置为解释该问题的一个 malloc'd 错误字符串。（也有可能 *errmsg 被设置为 NULL 且函数返回 NULL；这表明内存不足。）

处理选项数组后，通过将其传递给 PQconninfoFree 来释放该数组。如果没有这样做，则对于 PQconninfoParse 的每次调用，都会泄露一些内存。相反，如果出错并且 errmsg 不为 NULL，请务必使用 PQfreemem 释放错误字符串。

关闭与服务器的连接。还释放 PGconn 对象所使用的内存。

void PQfinish(PGconn *conn);

请注意，即使服务器连接尝试失败（如 PQstatus 所示），应用程序也应该调用 PQfinish 释放 PGconn 对象使用的内存。在调用了 PQfinish 之后，PGconn 指针不得再次使用。

重置与服务器的通信通道。

void PQreset(PGconn *conn);

该函数会关闭与服务器的连接并尝试建立一个新连接，使用此前使用的所有相同参数。如果工作连接中断，这对于错误修复可能很有用。

以非阻塞的方式重置与服务器的通信通道。

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

这些函数会关闭与服务器的连接并尝试建立一个新连接，使用此前使用的所有相同参数。如果工作连接中断，这对于错误修复可能很有用。它们与上述 PQreset 的不同之处在于，它们以非阻塞的方式起作用。这些函数受到与 PQconnectStartParams、PQconnectStart 和 PQconnectPoll 相同的限制。

要启动连接重置，请调用 PQresetStart。如果它返回 0，则重置失败。如果它返回 1，则使用 PQresetPoll 轮询重置，其方式与使用 PQconnectPoll 创建连接时完全相同。

PQpingParams 报告服务器状态。它接受与 PQconnectdbParams 完全相同的连接参数，如上所述。获取服务器状态无需提供正确的用户名、密码或数据库名称值；但是，如果提供了不正确的参数，服务器将记录一个连接尝试失败。

PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);

该函数返回以下值之一

PQping 报告服务器状态。它接受与上面描述的 PQconnectdb 相同的连接参数。无需提供正确的用户名、密码或数据库名称值即可获取服务器状态；但是，如果提供了不正确的值，服务器将记录失败的连接尝试。

PGPing PQping(const char *conninfo);

返回值与 PQpingParams 相同。

PQsetSSLKeyPassHook_OpenSSL 允许应用程序使用 默认处理加密客户端证书密钥文件 或交互式提示，覆盖 libpq 的 sslpassword。

void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);

应用程序传递一个具有签名回调函数的指针

int callback_fn(char *buf, int size, PGconn *conn);

然后，libpq 将调用它而不是其默认 PQdefaultSSLKeyPassHook_OpenSSL 处理程序。回调函数应确定密钥的密码，并将其复制到大小为 size 的结果缓冲区 buf。buf 中的字符串必须以 null 结尾。回调函数必须返回存储在 buf 中的密码的长度（不包括 null 结尾符）。如果失败，回调函数应设置 buf[0] = '\0' 并返回 0。有关示例，请参阅 libpq 源代码中的 PQdefaultSSLKeyPassHook_OpenSSL。

如果用户指定了显式密钥位置，当调用回调函数时，其路径将在 conn->sslkey 中。如果使用默认密钥路径，则此处将为空。对于引擎说明符密钥，是否使用 OpenSSL 密码回调函数或定义自己的处理方式由引擎实现决定。

应用程序回调可以选择委托 PQdefaultSSLKeyPassHook_OpenSSL 处理未处理的情况，或先调用它，如果它返回 0 则尝试其他操作，或完全覆盖它。

回调 绝不能 使用异常、longjmp(...) 等来转义正常的流控制。它必须正常返回。

PQgetSSLKeyPassHook_OpenSSL 返回当前客户端证书密钥密码钩子，如果没有设置任何密码钩子，则返回 NULL。

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);