PostgreSQL 数据库连接控制函数

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

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

这个函数使用从两个以NULL结尾的数组中取得的参数打开一个新的数据库连接。第一个数组keywords被定义为一个字符串数组，每一个元素是一个关键词。第二个数组values给出了每个关键词的值。和下面的 PQsetdbLogin 不同，可以在不改变函数签名的情况下扩展参数集合，因此使用这个函数（或者与之相似的非阻塞的PQconnectStartParams和PQconnectPoll）对于新应用编程要更好。

当前能被识别的参数关键词被列举在本文中第 33.1.2 节中。

当expand_dbname为非零时，dbname关键词的值被允许识别为一个连接字符串。只有dbname的第一次出现会按这种方式扩展，任何后续dbname值会被当做一个普通数据库名处理。有关可能的连接字符串格式的详情可见 本文中第 33.1.1 节。

被传递的数组可以为空，这样就会使用所有默认参数。也可以只包含一个或几个参数设置。两个参数数组应该在长度上匹配。对于参数数组的处理将会停止于keywords数组中第一个非-NULL元素。

如果任何一个参数是NULL或者一个空字符串，那么将会检查相应的环境变量（见第 33.14 节）。如果该环境变量也没有被设置，那么将使用内建的默认值。

通常，关键词的处理是从这些数组的头部开始并且以索引顺序进行。这样做的效果就是，当关键词有重复时，只会保留最后一个被处理的值。因此，通过小心地放置关键词dbname，可以决定什么会被一个conninfo字符串所重载，以及什么不会被重载。

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

PGconn *PQconnectdb(const char *conninfo);

这个函数使用从字符串conninfo中得到的参数开启一个新的数据库连接。

被传递的字符串可以为空，这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置，还可以包含一个URI。详见本文中第 33.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都不会阻塞：

要开始无阻塞的连接请求，可调用PQconnectStart或者PQconnectStartParams。如果结果为空，则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;   /* 该选项的关键词 */
    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的 default handling of encrypted client certificate key files ， 使用sslpassword 或交互提示方式。

void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);

应用程序传递一个指针到带签名的回调函数：

int callback_fn(char *buf, int size, PGconn *conn);

libpq将调用而不是（instead of）它的默认PQdefaultSSLKeyPassHook_OpenSSL处理程序。 回调函数应该确定密钥的密码并将其复制到大小为size的结果缓冲区buf中。 buf 中的字符串必须以空终止符(null-terminated)。 回调函数必须返回存储在buf中的密码的长度，不包括空终止符。 如果失败，回调函数应该设置buf[0] = '\0'并返回0。 参见libpq源代码中的PQdefaultSSLKeyPassHook_OpenSSL以获得示例。

如果用户指定了一个显式的密钥位置，那么当调用回调时，它的路径将在conn->sslkey中。 如果使用默认密钥路径，则这将为空。对于作为引擎说明符的密钥，由引擎实现决定它们是使用OpenSSL密码回调还是定义自己的处理方式。

应用回调可能会选择将未处理的案例委派给PQdefaultSSLKeyPassHook_OpenSSL，或者先调用它，并且如果它返回0时再尝试其他方法，或者完全覆盖它。

除了例外、longjmp(...)等，回调务必不可逃避正常的流控制。它必须正常返回。

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

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);