31.1. 数据库联接函数

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

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

这个函数使用取自两个NULL终止数组的参数来开启一个新的数据库连接。 首先，被定义为一个字符串数组的keywords中的每个元素都是一个关键字。 其次，values为每个关键字赋值。不同于下面的PQsetdbLogin， 这个参数设置可以无需修改参数签名来扩展，因此，使用这个函数（或其非阻塞的变形PQconnectStartParams和PQconnectPoll） 更适合一个新的应用程序编程。

当expand_dbname非0时，dbname关键字值允许被确认为 一个conninfo字符串。

所有传递的数组可以被清空以用于所有的缺省参数，或用于包含一个或多个参数设置。 它们必须是等长的。进程会随着keywords数组中最后一个非NULL元素而终止。

目前可识别的参数键字是：

如果有任何没有声明的参数，那么将检查对应的环境变量 （参阅Section 31.13小节）。 如果环境变量也没有设置，那么使用编译时的指明的内置缺省。

如果expand_dbname非0，同时dbname中包含 一个=标记，它会看做是一个conninfo字符串， 以相同的方式传递到PQconnectdb中。之前的关键字会被conninfo 中的关键字代替。

通常情况下，关键字会从索引序列中的数组的开始进程处理。这样的话，如果关键字重复了，那么在这之前的最后一个 处理结果会被保留。因此，通过仔细防放置dbname关键字， 可以决定哪些方式可以通过conninfo字符串来覆盖，哪些不可以。

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

PGconn *PQconnectdb(const char *conninfo);

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

可以清空传递的字符串以使用所有的缺省参数，或包含一个或多个通过空格分开的参数设置。 每个参数设置是以keyword = value出现的。 等号两边的空格可以有，也可以没有。在写一个空值，或value中包含空格，可以在其两边使用单引号，如keyword = 'a value'。 在value中的单引号和反斜杠必须使用一个反斜杠来逃逸，如\'，\\。

目前公认的参数关键词是与上述相同。

Makes a new connection to the database server.

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包含=符号，它 作为的conninfo字符串完全相同的方式 如果它已通过PQconnectdb，其余 上述参数然后被应用。

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

PGconn *PQsetdb(char *pghost，
                char *pgport，
                char *pgoptions，
                char *pgtty，
                char *dbName);

这是一个调用PQsetdbLogin的宏， 只是login和pwd参数null代替。 提供这个函数是为了与非常老版本的程序兼容

与数据库服务器建立一次非阻塞的联接。

PGconn *PQconnectStartParams(const char **keywords，const char **values，int expand_dbname);


PGconn *PQconnectStart(const char *conninfo);


PostgresPollingStatusType PQconnectPoll(PGconn *conn);

这3个函数用于打开一个与数据库服务器之间的非阻塞的联接： 你的应用的执行线索在执行它的时候不会因远端的I/O而阻塞。 这个方法的要点是等待I/O结束可以发生在应用的主循环里， 而不是在PQconnectdbParams或PQconnectdb里， 这样应用可以把这件事与其它操作并发起来一起执行。

通过PQconnectStartParams，数据库连接使用来自keywords和 values数组的参数，并且通过expand_dbname控制，如在PQconnectdbParams 中的描述。

数据库联接是用从conninfo字符串里取得的参数传递给 PQconnectStart进行的。 这个字符串的格式与上面PQconnectdb里描述的一样

PQconnectStartParams， PQconnectStart，PQconnectPoll 都不会阻塞，只要有一些限制。

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

• 如果你调用了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;   /* 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结构的数组，该数组以一个有NULLkeyword指针的条目结束。 如果无法分配内存，则返回空指针。注意缺省值（val域）将依赖于环境变量和其他环境。 调用者必须把连接选项当作只读对待。

在处理完选项数组后，把数组交给PPQconninfoFree释放。如果没有这么做， 每次调用PQconndefaults都会有一小部分内存泄漏。

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

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

解析一个连接字符串，并返回结果选项为一个数组，或这，如果连接字符串有问题，那么返回一个NULL。 这个可以用于决定在提供的连接字符串中的PQconnectdb选项。 返回值指向一个PQconninfoOption结构的数组，这个结构一个带有空keyword指针 的条目结束。

需要注意的是，只有明确在字符串中声明的选项可以在结果数组中的设置中有参数值；没有缺省的话是插入。

如果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重置连接。