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

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

该函数使用来自两个以NULL结尾的数组的参数打开一个新的数据库连接。 第一个，keywords，定义为字符串数组，每个元素都是一个关键字。 第二个，values，为每个关键字提供对应的值。与下面的 PQsetdbLogin 不同，参数集可以扩展而无需更改函数签名， 因此建议新应用程序编程使用此函数（或其非阻塞对应函数 PQconnectStartParams 和 PQconnectPoll）。

当前认可的参数关键字列在 Section 32.1.2中。

传入的数组可以为空，以使用所有默认参数，或者可以包含一个或多个参数设置。它们的长度必须匹配。 处理将在NULL条目首次出现时停止， 该条目位于keywords数组中。 此外，如果与非NULLkeywords条目相关联的 values条目是NULL或空字符串， 则该条目将被忽略，处理将继续进行下一对数组条目。

当 expand_dbname 非零时，会检查第一个 dbname 关键字的值，判断它是否是一个 连接字符串。如果是，它会被 “展开”为从字符串中提取的各个连接参数。该值被视为连接字符串， 而不仅仅是数据库名称，如果它包含等号 (=) 或以 URI 方案标识符开头。（有关连接字符串格式的更多细节，请参见 Section 32.1.1。） 只有第一个出现的 dbname 会以这种方式处理；任何后续的 dbname 参数都作为普通数据库名称处理。

通常参数数组从头到尾依次处理。如果任何关键字重复，使用最后一个（且不为 NULL或空）的值。此规则特别适用于连接字符串中出现的关键字 与keywords数组中关键字冲突的情况。因此，程序员可以确定数组 条目是否可以被连接字符串中的值覆盖，或被其覆盖。出现在扩展的 dbname条目前的数组条目可以被连接字符串字段覆盖， 而这些字段又会被出现在dbname之后的数组条目覆盖（但 前提是这些条目提供非空值）。

处理完所有数组条目和任何展开的连接字符串后，任何未设置的连接参数都会被填充为默认值。 如果未设置参数对应的环境变量（参见 Section 32.15）已设置，则使用其值。 如果环境变量也未设置，则使用该参数的内置默认值。

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

PGconn *PQconnectdb(const char *conninfo);

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

传入的字符串可以为空，以使用所有默认参数，或者它可以包含一个或多个由空白分隔的参数设置， 也可以包含一个URI。 详情请参见Section 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);

这是一个宏，它调用PQsetdbLogin，并为login和 pwd参数传入空指针。该宏是为了向后兼容非常旧的程序而提供的。

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

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()或类似系统函数指示）。 注意，如果系统支持，PQsocketPoll可以通过封装 select(2)或poll(2)的设置来减少样板代码。 然后再次调用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 = "正在连接...";
            break;

        case CONNECTION_MADE:
            feedback = "已连接到服务器...";
            break;
.
.
.
        default:
            feedback = "正在连接...";
}

当使用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乘以一百万）。 如果end_time为-1，则超时为无限。 如果end_time为0（或确切地说，任何早于当前时间的时间）， 则超时立即发生（无阻塞）。超时值可以通过将所需的微秒数加到 PQgetCurrentTimeUSec的结果上来方便计算。 注意，底层系统调用的精度可能低于微秒，因此实际延迟可能不精确。

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

PQsocketPoll 是使用 poll(2) 或 select(2) 实现的，具体取决于平台。请参阅 POLLIN 和 POLLOUT 来自 poll(2)，或来自 select(2) 的 readfds 和 writefds，以获取更多信息。

返回默认的连接选项。

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* 选项的关键字 */
    char   *envvar;    /* 备用的环境变量名称 */
    char   *compiled;  /* 备用的编译时默认值 */
    char   *val;       /* 选项的当前值，或NULL */
    char   *label;     /* 连接对话框中字段的标签 */
    char   *dispchar;  /* 指示如何在连接对话框中显示此字段。值为：
                          ""        按原样显示输入的值
                          "*"       密码字段 - 隐藏值
                          "D"       调试选项 - 默认不显示 */
    int     dispsize;  /* 对话框中字段的字符大小 */
} 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 分配的错误字符串来解释 问题。（也有可能 *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中的字符串必须以空字符结尾。回调函数必须返回 存储在buf中的密码长度，不包括空字符。 失败时，回调函数应设置buf[0] = '\0'并返回0。 详情请参见libpq源码中的 PQdefaultSSLKeyPassHook_OpenSSL示例。

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

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

回调不得通过异常、longjmp(...)等方式跳出正常的流程控制。 它必须正常返回。

PQgetSSLKeyPassHook_OpenSSL 返回当前客户端证书密钥密码钩子， 或者如果未设置则返回NULL。

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);