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

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

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

在处理完选项数组后，将其传递给 PQconninfoFree 来释放它。如果不这样做，每次调用 PQconndefaults 都会泄漏少量内存。

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

PQconninfoOption *PQconninfo(PGconn *conn);

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

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

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

解析连接字符串并将结果选项作为数组返回；如果连接字符串有问题，则返回 NULL。此函数可用于提取提供的连接字符串中的 PQconnectdb 选项。返回值指向 PQconninfoOption 结构的数组，该数组以一个具有 null 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 允许应用程序使用 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);