创建一个新的数据库服务器连接。

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

该函数使用从两个以 NULL 结尾的数组获取的参数打开一个新的数据库连接。第一个数组 keywords 定义为字符串数组，每一个都是一个关键字。第二个数组 values 为每个关键字提供值。与下面的 PQsetdbLogin 不同，参数设置可以在不改变函数签名的前提下得到扩展，因此对于新的应用程序编程，优先使用这个函数（或其非阻塞类似函数 PQconnectStartParams 和 PQconnectPoll）。

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

传递的数组可以为空，表示使用所有默认参数，或者可以包含一个或多个参数设置。长度必须一致。处理将在 NULL 条目出现于 keywords 数组中的位置处停止。此外，如果与非 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);

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

以非阻塞方式建立与数据库服务器的连接。

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。如果结果为空，则 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 = "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 指针为 null 的条目结束。如果无法分配内存，则返回 null 指针。请注意，当前默认值（val 字段）取决于环境变量和其他上下文。将忽略缺失或无效的服务文件。调用方必须将连接选项数据视为只读。

在处理 options 数组之后，将其传递给 PQconninfoFree 以释放它。如果没有这样作，每次调用 PQconndefaults 会轻微泄漏一些内存。

返回实时连接使用的连接选项。

PQconninfoOption *PQconninfo(PGconn *conn);

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

返回提供的连接字符串中解析出的连接选项。

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

解析一个连接字符串并返回作为数组的结果选项；或者如果连接字符串存在问题，则返回 NULL。此函数可用于提取提供的连接字符串中的 PQconnectdb 选项。返回值指向一个 PQconninfoOption 结构体数组，该数组以一个 keyword 指针为 null 的条目结束。

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

如果 errmsg 不为 NULL，则在成功时将 *errmsg 设置为 NULL，否则将其设置为解释该问题的 malloc'd 错误字符串。（还可以将 *errmsg 设置为 NULL 且该函数返回 NULL；这表示内存不足情况。）

在处理 options 数组之后，将其传递给 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 允许应用程序使用 sslpassword 或交互式提示重写 libpq 的默认加密客户端证书密钥文件处理方式。

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);