PostgreSQL数据库学习手册之libpq范本模板.docx

1、PostgreSQL数据库学习手册之libpq范本模板PostgreSQL数据库学习手册之libpq - C 库介绍（转）moreChapter 1. libpq - C 库Table of Contents1。1. 介绍1。2. 数据库联接函数1.3. 命令执行函数1.3。1. 主过程1。3.2. 为包含在 SQL 查询中逃逸字串1.3.3. 逃逸包含在 SQL 查询中的二进制字串1.3.4。 检索 SELECT 的结果信息1.3.5. 检索 SELECT 结果数值1。3.6. 检索非SELECT 结果信息1.4。 异步查询处理1.5. 捷径接口1。6。 异步通知1。7。 与 COPY 命令

2、相关的函数1.8。 libpq 跟踪函数1。9。 libpq 控制函数1.10. 环境变量1。11. 文件1。12. 线程特性1。13。 制作 Libpq 程序1。14。 例子程序1.1. 介绍libpq 是 PostgreSQL的 C 应用程序员的接口 libpq 是一套允许客户程序向 PostgreSQL 后端服务进程发送查询 并且获得查询返回的库过程 libpq 同时也是其他几个 PostgreSQL 应用接口下面的引擎， 包括 libpq+ （C+）， libpgtcl（Tcl)，Perl，和 ecpg所以如果你使用这些软件包， libpq某些方面的特性会对你非常重要本节末尾有三个小程

3、序显示如何利用 libpq书写程序 在下面目录里面有几个完整的 libpq 应用的例子：src/test/examplessrc/bin/psql使用 libpq 的前端程序必须包括头文件 libpq-fe。h 并且必须与 libpq 库链接PostgreSQL数据库学习手册之libpqC库-数据库联接函数(转)more1。2。 数据库联接函数下面的过程处理与 PostgreSQL 后端服务器联接的事情 一个应用程序一次可以与多个后端建立联接 (这么做的原因之一是访问多于一个数据库) 每个连接都是用一个从PQconnectdb（）或 PQsetdbLogin() 获得的PGconn对象表示 注

4、意,这些函数总是返回一个非空的对象指针, 除非存储器少得连个PGconn对象都分配不出来 在把查询发送给联接对象之前，可以调用PQstatus 函数来检查一下联接是否成功PQconnectdb 与后端数据库服务器建立一个新的联接PGconn PQconnectdb（const char conninfo)这个过程用从一个字符串 conninfo 来的参数与数据库打开一个新的联接 与下面的PQsetdbLogin(）不同的是, 我们可以不必更换函数签名（名字）就可以扩展参数集, 所以我们建议应用程序中使用这个函数或者是它的非阻塞的相似函数 PQconnectStart 和 PQconnectPo

5、ll 传入的参数可以为空，表明使用所有缺省的参数， 或者可以包含一个或更多个用空白间隔的参数设置每个参数以 关键字 = 数值的形式设置 (要写一个空值或者一个包含空白的值， 你可以用一对单引号包围它们，例如， keyword = a value 数值内部的单引号和反斜扛必须用一个反斜扛逃逸， 也就是说， 或) 等号周围的空白是可选的目前可识别的参数键字是：host要联接的主机（host ） 如果主机名以斜扛开头， 则它声明使用 Unix 域套接字通讯而不是 TCP/IP 通讯; 该值就是套接字文件所存储的目录 缺省时是与位于 /tmp 里面的 Unix域套接字联接 hostaddr与之联接的主

6、机的 IP 地址。这个可以是标准的数字-点的形式， 象在 BSD 函数inet_aton等里面用的那样. 如果声明了一个非零长的字符串,那么使用 TCP/IP 通讯机制。使用hostaddr取代 host 可以让应用避免一次主机名查找, 这一点对于那些有时间约束的应用来说可能是非常重要的。 不过，Kerberos 认证系统要求主机(host）名。因此，应用下面的规则。 如果声明了不带hostaddr的 host 那么就强制进行主机名查找. 如果声明中没有 host，hostaddr 的值给出远端的地址； 如果使用了 Kerberos， 将导致一次反向名字查询。如果同时声明了 host 和hos

7、taddr， 除非使用了 Kerberos，否则将使用hostaddr的值作为远端地址; host 的值将被忽略，如果使用了 Kerberos，host 的值用于 Kerberos 认证。 要注意如果传递给libpq的主机名（host） 不是地址hostaddr处的机器名，那么认证很有可能失败.如果主机名（host）和主机地址都没有， 那么libpq将使用一个本地的 Unix 域套接字进行通讯。 port主机服务器的端口号,或者在 Unix 域套接字联接时的套接字扩展文件名 dbname数据库名 user要联接的用户名。 password如果后端要求口令认证，所用的口令 connect_tim

8、eout给连接过程设置的时间范围，以秒计.零或者不设置表示无穷。 options发给后端的跟踪/调试选项 tty文件或控制台（tty)，用于从后端的可选调试输出 requiressl设为 1 要求与后端进行 SSL 联接如果服务器不支持 SSL, 那么Libpq将马上拒绝联接 设置为 0 （缺省)与服务器进行协商 如果有任何没有声明的参数，那么将检查对应的环境变量(参阅Section 1.10 小节)。 如果环境变量也没有设置，那么使用编译时的硬代码。 返回的值是一个指向代表与后端联接的抽象 struct指针.PQsetdbLogin 与后端数据库服务器建立一个新的联接PGconn *PQse

9、tdbLogin（const char pghost，const char *pgport，const char *pgoptions，const char *pgtty,const char *dbName,const char *login，const char pwd）这个函数是 PQconnectdb 前身， 它有固定个数的参数，但是有相同的功能。PQsetdb 与后端数据库服务器建立一个新的联接PGconn PQsetdb（char *pghost,char *pgport，char pgoptions,char pgtty,char *dbName)这是一个调用 PQsetdbLo

10、gin() 的宏，只是login和pwd参数用空（null ）代替 提供这个函数主要是为了与老版本的程序兼容PQconnectStart， PQconnectPoll 与数据库服务器建立一次非阻塞的联接.PGconn PQconnectStart（const char *conninfo）PostgreSQLPollingStatusType PQconnectPoll（PGconn *conn）这两个过程用于打开一个与数据库服务器之间的非阻塞的联接： 你的应用的执行线索在执行它的时候不会因远端的 I/O 而阻塞。数据库联接是用从 conninfo字符串里取得的参数传递给 PQconnectS

11、tart进行的。 这个字符串的格式与上面PQconnectdb里描述的一样。PQconnectStart 和PQconnectPoll 都不会阻塞（进程)，不过有一些条件：o必须正确提供hostaddr和host 参数以确保不会发生正向或者反向的名字查找。 参阅上面PQconnectdb里的这些参数的文档获取细节。o如果你调用了PQtrace， 确保你跟踪进入的流对象不会阻塞。o你必须在调用PQconnectPoll之前确保 socket 处于正确的状态，象下面描述的那样。 要开始(联接）,调用 conn=PQconnectStart（”connection_info_string） 如果co

12、nn是NULL, 表明libpq无法分配一个新的 PGconn 结构。 否则,返回一个有效的PGconn指针 (尽管还不一定代表一个与数据库有效联接）. PQconnectStart 一返回,调用 status=PQstatus(conn）. 如果 status 等于CONNECTION_BAD， PQconnectStart 失败。如果PQconnectStart成功了，下一个阶段是轮询 libpq， 这样它就可以继续进行后继的联接动作. 象这样循环：认为一个联接缺省时是”不活跃的。 如果PQconnectPoll的最后一个返回是 PGRES_POLLING_ACTIVE,则认为它是活跃的”

13、。 如果PQconnectPoll（conn)的最后一个返回是 PGRES_POLLING_READING，执行一个对 PQsocket(conn)的读select（)。 如果最后一个返回是PGRES_POLLING_WRITING， 执行一个对PQsocket（conn)的写select(）。 如果还要调用PQconnectPoll， 也就是调用完PQconnectStart之后, 把它当作最后返回PGRES_POLLING_WRITING那样对待。 如果select（)显示 socket 已经准备好， 那么认为它是活跃的。如果认为一个联接是 ”活跃的， 再次调用PQconnectPoll（

14、conn)。 如果这次调用返回PGRES_POLLING_FAILED， 联接过程失败，如果这次调用 返回PGRES_POLLING_OK，联接成功。要注意上面用select（）来确保一个 socket 准备好只是一个（近似）的例子； 还可以用其他方法,比如一个poll（）调用，来代替 select。在联接的任意时刻,我们都可以通过调用PQstatus 来检查联接的状态. 如果这是CONNECTION_BAD， 那么联接过程失败；如果是CONNECTION_OK, 那么联接已经做好。 这两种状态同样也可以从上面的PQconnectPoll 的返回值里检测到。 其他状态可能（也只能）在一次异步联

15、接过程中看到. 这些标识联接过程 的当前状态，因而可能对给用户提供反馈有帮助.这些状态可能包括：CONNECTION_STARTED等待进行联接. CONNECTION_MADE联接成功；等待发送。 CONNECTION_AWAITING_RESPONSE等待来自服务器的响应。 CONNECTION_AUTH_OK已收到认证；等待联接启动继续进行。 CONNECTION_SETENV协商环境(联接启动的一部分)。 注意，尽管这些常量将保持下去（为了维持兼容性）， 应用决不应该依赖于这些常量的某种特定顺序， 或者是根本不应依赖于这些常量, 或者是不应该依赖于这些状态总是某个文档声明的值。 一个应

16、用可能象象下面这样：switch（PQstatus（conn）case CONNECTION_STARTED:feedback = ”Connecting.。;break；case CONNECTION_MADE:feedback = ”Connected to server。.”；break;。.default:feedback = ”Connecting。;要注意如果PQconnectStart返回一个非空的指针， 你必须在使用完它（指针）之后调用PQfinish, 以处理那些结构和所有相关的存储块。 甚至调用PQconnectStart或者 PQconnectPoll失败时也要这样处理.

17、如果编译libpq时定义了USE_SSL 那么目前的PQconnectPoll将阻塞住。 这个限制可能在将来的版本移除。这些函数把 socket 置于一个非阻塞的状态，就好象调用了 PQsetnonblocking 一样。PQconndefaults 返回缺省的联接选项。PQconninfoOption PQconndefaults(void)struct PQconninfoOptionchar *keyword; / The keyword of the option /char *envvar; /* Fallback environment variable name */char *

18、compiled; /* Fallback compiled in default value /char val； /* Options current value， or NULL */char label; /* Label for field in connect dialog /char *dispchar; / Character to display for this fieldin a connect dialog。 Values are：” Display entered value as is*” Password field hide value”D” Debug opt

19、ion dont show by default /int dispsize; /* Field size in characters for dialog */返回联接选项结构的地址 可以用于获取所有可能的PQconnectdb选项和它们的当前缺省值 返回值指向一个PQconninfoOption struct 的数组， 该数组以一个有 NULL 关键字指针的条目结束注意缺省值（val 域）将 依赖于环境变量和其他上下文调用者必须把联接选项当作只读对待在处理完选项数组后，把数组交给PQconninfoFree（)释放 如果没有这么做，每次调用PQconndefaults（) 都会有一小部分内

20、存泄漏在PostgreSQL7.0 以前的版本， PQconndefaults() 返回一个指向静态数组的指针， 而不是一个动态分配的数组这样做是线程不安全的，因此这个特点被修改了PQfinish 关闭与后端的联接同时释放被PGconn 对象使用的存储器void PQfinish(PGconn conn)注意，即使与后端的联接尝试失败（可由PQstatus判断）， 应用也要调用PQfinish释放被PGconn 对象使用的存储器不应该在调用 PQfinish后再使用PGconn 指针*PQreset 重置与后端的通讯端口void PQreset(PGconn conn)此函数将关闭与后端的联接

21、并且试图与同一个服务器重建新的联接， 使用所有前面使用过的参数这在 失去工作联接后进行故障恢复时很有用PQresetStart PQresetPoll 以非阻塞模式重置与后端的通讯端口。int PQresetStart（PGconn conn）;PostgreSQLPollingStatusType PQresetPoll(PGconn *conn);此函数将关闭与后端的联接并且试图与同一个服务器重建新的联接， 使用所有前面使用过的参数这在 失去工作联接后进行故障恢复时很有用 它们和上面的PQreset的区别是它们工作在非阻塞模式。 这些函数的使用有与上面PQconnectStart和 PQc

22、onnectPoll一样的限制。调用PQresetStart。如果它返回 0,那么重置失败。 如果返回 1,用与使用PQconnectPoll 建立联接的同样的 方法使用PQresetPoll重置联接。 libpq应用程序员应该仔细维护PGconn结构使用下面的访问函数来获取PGconn的内容避免直接引用PGconn结构里的字段，因为这些字段在今后可能被改变(从 PostgreSQL 版本 6。4 开始, struct PGconn的定义甚至没有放在 libpq-fe。h里如果你有一些直接访问PGconn数据域的旧代码，你可以通过包含 libpq-int.h 来访问它们，但我们鼓励你赶快修改那

23、些代码）*PQdb 返回联接的数据库名char *PQdb（const PGconn *conn）PQdb 和下面几个函数返回联接时建立起来的几个值这些值在PGconn对象的生存期内是固定的*PQuser 返回联接的用户名char PQuser(const PGconn *conn）*PQpass 返回联接的口令char PQpass(const PGconn conn）*PQhost 返回联接的服务器主机名char PQhost(const PGconn conn）PQport 返回联接的端口号char *PQport（const PGconn conn)PQtty 返回联接的调试控制台（

24、tty )char PQtty(const PGconn conn)PQoptions 返回联接中使用的后端选项char PQoptions(const PGconn *conn）PQstatus 返回联接的状态ConnStatusType PQstatus（const PGconn *conn）这个状态可以是一些值之一. 不过,如果不是一次异步联接过程的话，我们只能看到其中的两个 CONNECTION_OK 或 CONNECTION_BAD.一个与数据库的成功的联接返回状态 CONNECTION_OK. 一次失败的企图用状态 CONNECTION_BAD 标识. 通常，一个 OK 状态保持到

25、 PQfinish，但是一个通讯失败可能会导致状态过早地改变为 CONNECTION_BAD 。这时应用可以试着调用 PQreset 来恢复参阅PQconnectStart和PQconnectPoll 条目看看可能出现的其他的状态码。*PQerrorMessage 返回联接中操作产生的最近的错误信息char *PQerrorMessage(const PGconn conn)；几乎所有libpq函数在失败时都会设置 PQerrorMessage注意libpq的传统是， 一个非空的 PQerrorMessage 将在结尾包含一个新行PQbackendPID 返回控制此联接的后端服务器的进程号ID

26、。int PQbackendPID(const PGconn *conn）;这个后端PID 在调试和对比 NOTIFY 信息（ 包含发出通知的后端的 PID )时很有用 注意该 PID 属于运行数据库服务器的主机的进程, 而不是本地主机!*PQgetssl 返回联接使用的 SSL 结构,或者如果 SSL 没有使用的话返回 NULLSSL PQgetssl(const PGconn conn）;这个结构可以用于核实加密级别,检查服务器认证等信息参考 SSL 文档获取关于这个结构的更多信息为了获取这个函数的原形，你必须定义 USE_SSL 这样做会自动包含来自OpenSSL的 ssl。h Post

27、greSQL数据库学习手册之libpqC库-命令执行函数(转）more1.3. 命令执行函数一旦与数据库服务器的联接成功建立,便可用这里描述的函数执行 SQL 查询和命令。1。3.1. 主过程*PQexec 给服务器提交一条命令并且等待结果PGresult *PQexec(PGconn conn，const char query）;返回一个PGresult指针或者也可能是一个 NULL 指针 通常返回一个非空（nonNULL）的指针， 除非没有内存或发生了象不能把命令发送到后端这样的严重错误 如果返回的是 NULL,它应该被当作PGRES_FATAL_ERROR结果处理 用PQerrorMes

28、sage获取有关错误的更多信息PGresult 结构封装了后端返回的结果 libpq 应用程序员应该仔细维护PGresult抽象用下面的访问函数来获取PGresult的内容避免直接引用 PGresult结构的数据域,因为这个结构可能会在未来被改变（从 PostgreSQL 版本 6。4 开始， struct PGresult的定义甚至都没有放在 libpqfe.h里如果你有一些直接访问 PGresult数据域的老代码,你可以通过包含libpq-int。h继续使用它们，但是我们鼓励你立刻修改代码）PQresultStatus 返回命令的结果状态ExecStatusType PQresultSta

29、tus（const PGresult res)PQresultStatus可以返回下面数值之一：oPGRES_EMPTY_QUERY - 发送给后端的字串是空的oPGRES_COMMAND_OK - 成功完成一个没有返回数据的命令oPGRES_TUPLES_OK - 成功执行查询oPGRES_COPY_OUT - （从服务器)Copy Out (拷贝出）数据传输开始oPGRES_COPY_IN - Copy In （拷贝入）(到服务器）数据传输开始oPGRES_BAD_RESPONSE 服务器的响应无法理解oPGRES_NONFATAL_ERRORoPGRES_FATAL_ERROR如果结果状

30、态是 PGRES_TUPLES_OK ，那么可以用下面的过程从查询的返回中抽取元组信息注意一个碰巧检索了零条元组的 SELECT 仍然显示 PGRES_TUPLES_OK。 PGRES_COMMAND_OK用于不返回元组的命令（INSERT，UPDATE，等）。返回 PGRES_EMPTY_QUERY 的响应通常意味着客户端软件里面的臭虫。PQresStatus 把PQresultStatus返回的枚举类型转换成一个描述状态码的字符串常量。char *PQresStatus(ExecStatusType status）;PQresultErrorMessage 返回与查询关联的错误信息，或在没

31、有错误时返回一个空字符串char PQresultErrorMessage（const PGresult *res）;紧跟在一个 PQexec 或 PQgetResult 调用后面，PQerrorMessage （对联接）将返回与 PQresultErrorMessage （对结果)一样的字符串不过,一个PGresult将保有其错误信息直到被删除，而连结的错误信息将在后续的操作完成时被改变当你想知道与某个 PGresult相关联的状态时用 PQresultErrorMessage ；当你想知道与联接的最近一个操作相关联的状态时用 PQerrorMessage；*PQclear 释放于PGresult相关联