Question

libpq 是PostgreSQL的 C 应用程序接口。 libpq 是一套允许客户程序向 PostgreSQL 服务器服务进程发送查询并且获得查询返回的库函数。

libpq 同时也是其他几个 PostgreSQL 应用接口下面的引擎， 包括 C++，Perl，Python，Tcl 和 ECPG。 所以如果你使用这些软件包，libpq某些方面的特性会对你非常重要。 特别是 Section 28.11， Section 28.12 和 Section 28.13 描述了任何使用 libpq 的应用的用户可见的行为。

本章末尾有三个小程序显示如何利用 libpq 书写程序。（Section 28.16）在源代码发布的 src/test/examples 目录里面有几个完整的 libpq 应用的例子。

使用 libpq 的前端程序必须包括头文件 libpq-fe.h 并且必须与 libpq 库链接。

28.1. 数据库联接函数

下面的函数处理与 PostgreSQL 服务器服务器联接的事情。一个应用程序一次可以与多个服务器建立联接。（这么做的原因之一是访问多于一个数据库。）每个连接都是用一个从函数PQconnectdb()或 PQsetdbLogin()获得的 PGconn 对象表示。注意，这些函数总是返回一个非空的对象指针，除非存储器少得连个PGconn对象都分配不出来。在把查询发送给联接对象之前，可以调用PQstatus函数来检查一下联接是否成功。

PQconnectdb

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

PGconn *PQconnectdb(const char *conninfo);

这个函数用从一个字符串 conninfo来的参数与数据库打开一个新的联接。与下面的PQsetdbLogin()不同的是，我们可以不必更换函数签名（名字）就可以扩展参数集，所以我们建议应用程序中使用这个函数（或者是它的类似的非阻塞的变种PQconnectStart 和 PQconnectPoll）。

传入的参数可以为空，表明使用所有缺省的参数，或者可以包含一个或更多个用空白间隔的参数设置。每个参数以 关键字 = 数值的形式设置。等号周围的空白是可选的。要写一个空值或者一个包含空白的值，你可以用一对单引号包围它们，例如，keyword = 'a value' 。数值内部的单引号和反斜杠必须用一个反斜杠逃逸，比如， \'或\\。

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

host

要联接的主机名。如果主机名以斜杠开头，则它声明使用 Unix 域套接字通讯而不是 TCP/IP 通讯；该值就是套接字文件所存储的目录。如果没有声明 host，那么缺省时是与位于share/pg_service.conf.sample 获取如何设置这个文件的信息。

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

PQsetdbLogin

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

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 或者一个空字串给它们。

PQsetdb

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

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

这是一个调用 PQsetdbLogin() 的宏，只是PGconn *PQconnectStart(const char *conninfo);

PostgreSQLPollingStatusType PQconnectPoll(PGconn *conn);

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

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

PQconnectStart 和PQconnectPoll 都不会阻塞（进程），不过有一些条件：

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

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

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

要开始一次非阻塞连接请求，调用 conn=PQconnectStart("conn是空，表明libpq无法分配一个新的PQconnectPoll(conn)的最后一个返回是PGRES_POLLING_READING，那么就等到套接字准备好被读取了的时候（就像系统函数 select()，poll()，或者类似的系统调用声明的那样）。然后再次调用 PQconnectPoll(conn)。同样，如果 PQconnectPoll(conn) 最后返回 PGRES_POLLING_WRITING，那么就等到套接字准备好可以写了，然后再次调用 PQconnectPoll(conn)。如果你还没调用 PQconnectPoll，比如，刚刚调用完 PQconnectStart，那么按照它刚返回 PQconnectPoll(conn) 返回 PGRES_POLLING_FAILED，表明连接失败，或者 PGRES_POLLING_OK，表明连接成功建立。

在联接的任意时刻，我们都可以通过调用PQstatus来检查联接的状态。如果这是PQconnectPoll的返回值里检测到。其他状态可能（也只能）在一次异步联接过程中发生。这些标识联接过程的当前状态，因而可能对给用户提供反馈有帮助。这些状态可能包括：

switch(PQstatus(conn)){ case CONNECTION_STARTED:feedback = "正在连接...";break; case CONNECTION_MADE:feedback = "与服务器连接已建立...";break;... default:feedback = "正在连接...";}

在使用 PQconnectPoll 的时候，连接参数 connect_timeout 将被忽略；判断是否超时是应用的责任。否则，后面跟着一个 PQconnectPoll 循环的 PQconnectStart 等效于 PQconnectdb。

要注意如果PQconnectStart返回一个非空的指针，你必须在使用完它（指针）之后调用PQfinish，以处理那些结构和所有相关的存储块。甚至调用PQconnectStart或者PQconnectPoll失败时也要这样处理。

PQconndefaults

返回缺省的联接选项。

PQconninfoOption *PQconndefaults(void);typedef struct PQconninfoOption{    char   *keyword;   /* 选项的键字 */    char   *envvar;    /* 退守的环境变量名 */    char   *compiled;  /* 退守的编译时缺省值 */    char   *val;       /* 选项的当前值，或者 NULL */    char   *label;     /* 连接对话里字段的标识 */    char   *dispchar;  /* 在连接对话里为此字段显示的字符。  数值有：  ""原样现实输入的数值  "*"   口令字段 － 隐藏数值  "D"   调试选项 － 缺省的时候不显示 */    int     dispsize;  /* 对话中字段的以字符计的大小 */}PQconninfoOption;

返回一个连接选项数组。可以用于获取所有可能的PQconnectdb选项和它们的当前缺省值。返回值指向一个PQconninfoOption 结构的数组，该数组以一个有 NULL keyword 指针的条目结束。如果无法分配内存，则返回空指针。注意缺省值（val 域）将依赖于环境变量和其他环境。调用者必须把连接选项当作只读对待。

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

PQfinish

关闭与服务器的连接。同时释放被void PQfinish(PGconn *conn);

注意，即使与服务器的连接尝试失败（可由PQstatus判断），应用也要调用PQfinish释放被void PQreset(PGconn *conn);

此函数将关闭与服务器的连接并且试图与同一个服务器重建新的连接，使用所有前面使用过的参数。这在失去工作连接后进行故障恢复时很有用。

PQresetStart
PQresetPoll

以非阻塞模式重置与服务器的通讯端口。

int PQresetStart(PGconn *conn);

PostgreSQLPollingStatusType PQresetPoll(PGconn *conn);

此函数将关闭与服务器的连接并且试图与同一个服务器重建新的连接，使用所有前面使用过的参数。这在失去工作连接后进行故障恢复时很有用。它们和上面的PQreset的区别是它们工作在非阻塞模式。这些函数的使用有与上面PQconnectStart和PQconnectPoll一样的限制。

要发起一次连接重置，调用PQresetStart。如果它返回 0，那么重置失败。如果返回 1，用与使用PQconnectPoll 建立连接的同样的方法使用PQresetPoll重置连接。

---

Prev	Home	Next
客户端接口	Up	连接状态函数