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

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

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

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

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

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

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

在处理所有数组条目和任何展开的连接字符串后，将用默认值填充所有仍未设置的连接参数。如果未设置的参数的相应环境变量（请参见 第 34.15 节）已设置，则使用其值。如果环境变量也没有设置，则使用参数的内置默认值。

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

PGconn *PQconnectdb(const char *conninfo);

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

传递的字符串可以为空以使用所有默认参数，或者可以包含一个或多个由空格分隔的参数设置，或者可以包含一个 URI。有关详细信息，请参见 第 34.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() 或类似系统函数所指示）。然后再次调用 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，以便处理结构和任何关联的内存块。即使连接尝试失败或被放弃，也必须执行此操作。

返回默认连接选项。

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。