开启一个到数据库服务器的新连接。

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.14 节>）已经设置，就使用该环境变量的值； 否则使用该参数的内置默认值。

开启一个到数据库服务器的新连接。

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 的规则应用其余参数。

开启一个到数据库服务器的新连接。

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都不会阻塞，只要满足以下限制：

注意：PQconnectStartParams的用法与下文展示的PQconnectStart类似。

要开始无阻塞的连接请求，可调用conn = PQconnectStart("connection_info_string")。如果conn为空，则libpq无法分配一个新的PGconn结构体。否则，一个有效的PGconn指针会被返回（不过还没有表示一个到数据库的有效连接）。从PQconnectStart返回后，调用status = PQstatus(conn)。如果status等于CONNECTION_BAD，则PQconnectStart失败。

如果PQconnectStart成功，下一个阶段是轮询libpq，这样它能够继续进行连接序列。使用PQsocket(conn)来获得该数据库连接底层的套接字描述符。这样循环：如果PQconnectPoll(conn)上一次返回PGRES_POLLING_READING，等到该套接字准备好读取（按照select()、poll()或类似的系统函数所指示的）。则再次调用PQconnectPoll(conn)。反之，如果PQconnectPoll(conn)上一次返回PGRES_POLLING_WRITING，等到该套接字准备好写入，则再次调用PQconnectPoll(conn)。如果你还没有调用过PQconnectPoll，即刚刚调用过PQconnectStart之后，行为就像是它上次返回了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返回一个非空的指针，你必须在用完它之后调用PQfinish来处理该结构体和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。

返回默认连接选项。

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 相同。