31.1. 数据库连接控制函数

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

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

这个函数用从两个NULL结束的数组中来的参数打开一个新的数据库连接。 第一个，keywords，定义为一个字符串的数组，每个都成为一个关键字。 第二个，values，给每个关键字一个值。与下面的PQsetdbLogin 不同的是，我们可以不必更换函数签名（名字）就可以扩展参数集， 所以我们建议应用程序中使用这个函数（或者它的类似的非阻塞变种 PQconnectStartParams和PQconnectPoll）。

目前公认的参数关键字在第 31.1.2 节中列出。

当expand_dbname是非零的时，允许将dbname 的关键字值看做一个连接字符串。只有第一个出现的dbname 是这样展开的，任何随后的dbname值作为纯数据库名处理。 可能的格式的更详细信息在第 31.1.1 节 中显示。

传入的参数可以为空，表明使用所有缺省的参数，或者可以包含一个或更多个参数设置。 它们的长度应该匹配。处理将会在keywords数组的第一个 NULL元素停止。

如果任意参数是NULL或空字符串，则检查对应的环境变量（参阅第 31.14 节）。 如果环境变量也没有设置，则使用指出的内建缺省。

通常，关键字是从这些数组的开始以索引的顺序处理的。这样的影响是，当关键字重复时， 获得最后处理的值。因此，通过小心的放置dbname关键字， 有可能决定哪个被conninfo字符串覆盖，哪个不被覆盖。

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

PGconn *PQconnectdb(const char *conninfo);

这个函数用从一个字符串conninfo来的参数与数据库打开一个新的联接。

传入的参数可以为空，表明使用所有缺省的参数，或者可以包含一个或更多个用空白间隔的参数设置， 或者它可以包含一个URI。参阅第 31.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都不会阻塞（进程），不过有一些条件：

• 必须正确提供hostaddr和host参数以确保不会发生正向或者反向的名字查找。 参阅第 31.1.2 节里的这些参数的文档获取细节。

• 如果你调用了PQtrace，确保你跟踪进入的流对象不会阻塞。

• 你必须在调用PQconnectPoll之前确保 socket 处于正确的状态， 像下面描述的那样。

注意：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 将被忽略；判断是否超时是应用的责任。否则，后面跟着一个PQconnectPoll 循环的PQconnectStart等效于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 结构的数组，该数组以一个有 NULL keyword指针的条目结束。 如果无法分配内存，则返回空指针。注意当前缺省值（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的解释问题的错误字符串。（*errmsg设置为NULL 并且函数返回NULL是可能的；这表示一个内存溢出条件。）

在处理完选项数组后，把数组交给PQconninfoFree释放。 如果没有这么做，每次调用PQconndefaults都会有一小部分内存泄漏。 相反的，如果错误发生了并且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 建立连接的同样的方法使用PQresetPoll重置连接。

PQpingParams报告服务器的状态。它接受和PQconnectdbParams 一样的连接参数，在下面描述。不需要应用正确的用户名、密码或数据库名的值获取服务器状态； 不过，如果提供了不正确的值，服务器将记录一次失败的连接尝试。

PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);

该函数返回下列的值之一：

PQping报告服务器的状态。它接受和PQconnectdb 一样的连接参数，在下面描述。不需要应用正确的用户名、密码或数据库名的值获取服务器状态； 不过，如果提供了不正确的值，服务器将记录一次失败的连接尝试。

PGPing PQping(const char *conninfo);

返回值和PQpingParams的相同。