PostgreSQL数据库学习手册之libpq.docx
《PostgreSQL数据库学习手册之libpq.docx》由会员分享，可在线阅读，更多相关《PostgreSQL数据库学习手册之libpq.docx（86页珍藏版）》请在冰豆网上搜索。
PostgreSQL数据库学习手册之libpq
PostgreSQL数据库学习手册之libpq-C库——介绍（转）[＠more＠］
Chapter1。
libpq-C库
TableofContents
1.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命令相关的函数
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某些方面的特性会对你非常重要．
本节末尾有三个小程序显示如何利用libpq书写程序．在下面目录里面有几个完整的libpq应用的例子：
src/test/examples
src/bin/psql
使用libpq的前端程序必须包括头文件libpq—fe。
h并且必须与libpq库链接．
PostgreSQL数据库学习手册之libpq—C库---数据库联接函数（转）[＠more@]
1。
2。
数据库联接函数
下面的过程处理与PostgreSQL后端服务器联接的事情．一个应用程序一次可以与多个后端建立联接．（这么做的原因之一是访问多于一个数据库．）每个连接都是用一个从PQconnectdb（）或PQsetdbLogin（）获得的PGconn对象表示．注意，这些函数总是返回一个非空的对象指针，除非存储器少得连个PGconn对象都分配不出来．在把查询发送给联接对象之前，可以调用PQstatus函数来检查一下联接是否成功．
*
PQconnectdb与后端数据库服务器建立一个新的联接．
PGconn＊PQconnectdb（constchar＊conninfo）
这个过程用从一个字符串conninfo来的参数与数据库打开一个新的联接．与下面的PQsetdbLogin（）不同的是，我们可以不必更换函数签名（名字）就可以扩展参数集，所以我们建议应用程序中使用这个函数或者是它的非阻塞的相似函数PQconnectStart和PQconnectPoll．传入的参数可以为空，表明使用所有缺省的参数,或者可以包含一个或更多个用空白间隔的参数设置．
每个参数以关键字=数值的形式设置．（要写一个空值或者一个包含空白的值，你可以用一对单引号包围它们,例如,keyword='avalue’．数值内部的单引号和反斜扛必须用一个反斜扛逃逸，也就是说，’或．）等号周围的空白是可选的．目前可识别的参数键字是：
host
要联接的主机（host）．如果主机名以斜扛开头,则它声明使用Unix域套接字通讯而不是TCP/IP通讯；该值就是套接字文件所存储的目录．缺省时是与位于/tmp里面的Unix—域套接字联接．
hostaddr
与之联接的主机的IP地址。
这个可以是标准的数字-点的形式，象在BSD函数inet_aton等里面用的那样。
如果声明了一个非零长的字符串，那么使用TCP/IP通讯机制。
使用hostaddr取代host可以让应用避免一次主机名查找，这一点对于那些有时间约束的应用来说可能是非常重要的。
不过，Kerberos认证系统要求主机（host）名。
因此,应用下面的规则.如果声明了不带hostaddr的host那么就强制进行主机名查找。
如果声明中没有host，hostaddr的值给出远端的地址；如果使用了Kerberos,将导致一次反向名字查询。
如果同时声明了host和hostaddr，除非使用了Kerberos，否则将使用hostaddr的值作为远端地址;host的值将被忽略，如果使用了Kerberos，host的值用于Kerberos认证。
要注意如果传递给libpq的主机名（host）不是地址hostaddr处的机器名，那么认证很有可能失败.
如果主机名（host）和主机地址都没有,那么libpq将使用一个本地的Unix域套接字进行通讯。
port
主机服务器的端口号，或者在Unix域套接字联接时的套接字扩展文件名．
dbname
数据库名．
user
要联接的用户名。
password
如果后端要求口令认证,所用的口令．
connect_timeout
给连接过程设置的时间范围，以秒计。
零或者不设置表示无穷。
options
发给后端的跟踪/调试选项．
tty
文件或控制台（tty），用于从后端的可选调试输出．
requiressl
设为’1’要求与后端进行SSL联接．如果服务器不支持SSL，那么Libpq将马上拒绝联接．设置为'0’（缺省）与服务器进行协商．
如果有任何没有声明的参数，那么将检查对应的环境变量（参阅Section1.10小节）。
如果环境变量也没有设置，那么使用编译时的硬代码。
返回的值是一个指向代表与后端联接的抽象struct指针。
*
PQsetdbLogin与后端数据库服务器建立一个新的联接．
PGconn＊PQsetdbLogin（constchar＊pghost,
constchar＊pgport，
constchar*pgoptions，
constchar*pgtty,
constchar*dbName，
constchar*login,
constchar＊pwd）
这个函数是PQconnectdb前身，它有固定个数的参数，但是有相同的功能。
＊
PQsetdb与后端数据库服务器建立一个新的联接．
PGconn*PQsetdb（char＊pghost,
char*pgport,
char*pgoptions,
char*pgtty,
char＊dbName）
这是一个调用PQsetdbLogin（）的宏，只是login和pwd参数用空（null）代替．提供这个函数主要是为了与老版本的程序兼容．
*
PQconnectStart,PQconnectPoll与数据库服务器建立一次非阻塞的联接。
PGconn＊PQconnectStart（constchar*conninfo）
PostgreSQLPollingStatusTypePQconnectPoll（PGconn＊conn）
这两个过程用于打开一个与数据库服务器之间的非阻塞的联接：
你的应用的执行线索在执行它的时候不会因远端的I/O而阻塞。
数据库联接是用从conninfo字符串里取得的参数传递给PQconnectStart进行的.这个字符串的格式与上面PQconnectdb里描述的一样。
PQconnectStart和PQconnectPoll都不会阻塞（进程），不过有一些条件：
o
必须正确提供hostaddr和host参数以确保不会发生正向或者反向的名字查找。
参阅上面PQconnectdb里的这些参数的文档获取细节。
o
如果你调用了PQtrace，确保你跟踪进入的流对象不会阻塞。
o
你必须在调用PQconnectPoll之前确保socket处于正确的状态，象下面描述的那样.
要开始（联接），调用conn=PQconnectStart（”connection_info_string"）．如果conn是NULL,表明libpq无法分配一个新的PGconn结构。
否则，返回一个有效的PGconn指针（尽管还不一定代表一个与数据库有效联接）.PQconnectStart一返回,调用status=PQstatus（conn）.如果status等于CONNECTION_BAD，PQconnectStart失败.
如果PQconnectStart成功了，下一个阶段是轮询libpq，这样它就可以继续进行后继的联接动作.象这样循环：
认为一个联接缺省时是"不活跃”的.如果PQconnectPoll的最后一个返回是PGRES_POLLING_ACTIVE,则认为它是”活跃的”.如果PQconnectPoll（conn）的最后一个返回是PGRES_POLLING_READING,执行一个对PQsocket（conn）的读select（）。
如果最后一个返回是PGRES_POLLING_WRITING,执行一个对PQsocket（conn）的写select（）。
如果还要调用PQconnectPoll,也就是调用完PQconnectStart之后，把它当作最后返回PGRES_POLLING_WRITING那样对待.如果select（）显示socket已经准备好，那么认为它是"活跃的"。
如果认为一个联接是”活跃的"，再次调用PQconnectPoll（conn）。
如果这次调用返回PGRES_POLLING_FAILED，联接过程失败，如果这次调用返回PGRES_POLLING_OK，联接成功.
要注意上面用select（）来确保一个socket准备好只是一个（近似）的例子；还可以用其他方法，比如一个poll（）调用，来代替select。
在联接的任意时刻,我们都可以通过调用PQstatus来检查联接的状态。
如果这是CONNECTION_BAD，那么联接过程失败；如果是CONNECTION_OK，那么联接已经做好.这两种状态同样也可以从上面的PQconnectPoll的返回值里检测到。
其他状态可能（也只能）在一次异步联接过程中看到。
这些标识联接过程的当前状态，因而可能对给用户提供反馈有帮助.这些状态可能包括：
CONNECTION_STARTED
等待进行联接。
CONNECTION_MADE
联接成功;等待发送。
CONNECTION_AWAITING_RESPONSE
等待来自服务器的响应。
CONNECTION_AUTH_OK
已收到认证；等待联接启动继续进行。
CONNECTION_SETENV
协商环境（联接启动的一部分）。
注意，尽管这些常量将保持下去（为了维持兼容性）,应用决不应该依赖于这些常量的某种特定顺序，或者是根本不应依赖于这些常量，或者是不应该依赖于这些状态总是某个文档声明的值。
一个应用可能象象下面这样：
switch（PQstatus（conn））
｛
caseCONNECTION_STARTED：
feedback=”Connecting.。
。
”;
break；
caseCONNECTION_MADE：
feedback=”Connectedtoserver。
。
。
";
break；
。
。
.
default:
feedback=”Connecting。
。
."；
｝
要注意如果PQconnectStart返回一个非空的指针,你必须在使用完它（指针）之后调用PQfinish，以处理那些结构和所有相关的存储块。
甚至调用PQconnectStart或者PQconnectPoll失败时也要这样处理。
如果编译libpq时定义了USE_SSL那么目前的PQconnectPoll将阻塞住。
这个限制可能在将来的版本移除。
这些函数把socket置于一个非阻塞的状态，就好象调用了PQsetnonblocking一样。
*
PQconndefaults返回缺省的联接选项.
PQconninfoOption*PQconndefaults（void）
structPQconninfoOption
｛
char*keyword；/＊Thekeywordoftheoption*/
char＊envvar;/*Fallbackenvironmentvariablename*/
char＊compiled；/*Fallbackcompiledindefaultvalue*/
char＊val；/＊Option'scurrentvalue，orNULL*/
char*label;/*Labelforfieldinconnectdialog*/
char＊dispchar;/*Charactertodisplayforthisfield
inaconnectdialog.Valuesare：
""Displayenteredvalueasis
"＊"Passwordfield-hidevalue
"D"Debugoption—don’tshowbydefault＊/
intdispsize；/*Fieldsizeincharactersfordialog＊/
｝
返回联接选项结构的地址．可以用于获取所有可能的PQconnectdb选项和它们的当前缺省值．返回值指向一个PQconninfoOptionstruct的数组，该数组以一个有NULL关键字指针的条目结束．注意缺省值（val域）将依赖于环境变量和其他上下文．调用者必须把联接选项当作只读对待．
在处理完选项数组后，把数组交给PQconninfoFree（）释放．如果没有这么做，每次调用PQconndefaults（）都会有一小部分内存泄漏．
在PostgreSQL7.0以前的版本，PQconndefaults（）返回一个指向静态数组的指针,而不是一个动态分配的数组．这样做是线程不安全的，因此这个特点被修改了．
*
PQfinish关闭与后端的联接．同时释放被PGconn对象使用的存储器．
voidPQfinish（PGconn*conn）
注意，即使与后端的联接尝试失败（可由PQstatus判断），应用也要调用PQfinish释放被PGconn对象使用的存储器．不应该在调用PQfinish后再使用PGconn指针．
*
PQreset重置与后端的通讯端口．
voidPQreset（PGconn*conn）
此函数将关闭与后端的联接并且试图与同一个服务器重建新的联接，使用所有前面使用过的参数．这在失去工作联接后进行故障恢复时很有用．
＊
PQresetStartPQresetPoll以非阻塞模式重置与后端的通讯端口.
intPQresetStart（PGconn*conn）;
PostgreSQLPollingStatusTypePQresetPoll（PGconn＊conn）;
此函数将关闭与后端的联接并且试图与同一个服务器重建新的联接，使用所有前面使用过的参数．这在失去工作联接后进行故障恢复时很有用．它们和上面的PQreset的区别是它们工作在非阻塞模式。
这些函数的使用有与上面PQconnectStart和PQconnectPoll一样的限制。
调用PQresetStart。
如果它返回0，那么重置失败。
如果返回1，用与使用PQconnectPoll建立联接的同样的方法使用PQresetPoll重置联接.
libpq应用程序员应该仔细维护PGconn结构．使用下面的访问函数来获取PGconn的内容．避免直接引用PGconn结构里的字段，因为这些字段在今后可能被改变．（从PostgreSQL版本6.4开始,structPGconn的定义甚至没有放在libpq-fe。
h里．如果你有一些直接访问PGconn数据域的旧代码，你可以通过包含libpq-int.h来访问它们，但我们鼓励你赶快修改那些代码．）
＊
PQdb返回联接的数据库名．
char＊PQdb（constPGconn＊conn）
PQdb和下面几个函数返回联接时建立起来的几个值．这些值在PGconn对象的生存期内是固定的．
*
PQuser返回联接的用户名．
char*PQuser（constPGconn＊conn）
*
PQpass返回联接的口令．
char＊PQpass（constPGconn*conn）
＊
PQhost返回联接的服务器主机名．
char＊PQhost（constPGconn*conn）
＊
PQport返回联接的端口号．
char*PQport（constPGconn＊conn）
*
PQtty返回联接的调试控制台（tty）．
char＊PQtty（constPGconn＊conn）
＊
PQoptions返回联接中使用的后端选项．
char*PQoptions（constPGconn*conn）
*
PQstatus返回联接的状态．
ConnStatusTypePQstatus（constPGconn＊conn）
这个状态可以是一些值之一。
不过，如果不是一次异步联接过程的话，我们只能看到其中的两个-CONNECTION_OK或CONNECTION_BAD。
一个与数据库的成功的联接返回状态CONNECTION_OK。
一次失败的企图用状态CONNECTION_BAD标识。
通常，一个OK状态保持到PQfinish,但是一个通讯失败可能会导致状态过早地改变为CONNECTION_BAD.这时应用可以试着调用PQreset来恢复．
参阅PQconnectStart和PQconnectPoll条目看看可能出现的其他的状态码.
*
PQerrorMessage返回联接中操作产生的最近的错误信息．
char*PQerrorMessage（constPGconn*conn）;
几乎所有libpq函数在失败时都会设置PQerrorMessage．注意libpq的传统是，一个非空的PQerrorMessage将在结尾包含一个新行．
*
PQbackendPID返回控制此联接的后端服务器的进程号ID。
intPQbackendPID（constPGconn＊conn）;
这个后端PID在调试和对比NOTIFY信息（包含发出通知的后端的PID）时很有用．注意该PID属于运行数据库服务器的主机的进程，而不是本地主机!
＊
PQgetssl返回联接使用的SSL结构，或者如果SSL没有使用的话返回NULL．
SSL＊PQgetssl（constPGconn＊conn）;
这个结构可以用于核实加密级别，检查服务器认证等信息．参考SSL文档获取关于这个结构的更多信息．
为了获取这个函数的原形,你必须定义USE_SSL．这样做会自动包含来自OpenSSL的ssl.h．
PostgreSQL数据库学习手册之libpq—C库-———命令执行函数（转）[@more@］
1。
3.命令执行函数
一旦与数据库服务器的联接成功建立,便可用这里描述的函数执行SQL查询和命令。
1。
3.1。
主过程
*
PQexec给服务器提交一条命令并且等待结果．
PGresult＊PQexec（PGconn*conn，
constchar*query）;
返回一个PGresult指针或者也可能是一个NULL指针．通常返回一个非空（non-NULL）的指针，除非没有内存或发生了象不能把命令发送到后端这样的严重错误．如果返回的是NULL，它应该被当作PGRES_FATAL_ERROR结果处理．用PQerrorMessage获取有关错误的更多信息．
PGresult结构封装了后端返回的结果．libpq应用程序员应该仔细维护PGresult抽象．用下面的访问函数来获取PGresult的内容．避免直接引用PGresult结构的数据域，因为这个结构可能会在未来被改变．（从PostgreSQL版本6。
4开始，structPGresult的定义甚至都没有放在libpq—fe。
h里．如果你有一些直接访问PGresult数据域的老代码,你可以通过包含libpq-int。
h继续使用它们,但是我们鼓励你立刻修改代码．）
*
PQresultStatus返回命令的结果状态．
ExecStatusTypePQresultStatus（constPGresult*res）
PQresultStatus可以返回下面数值之一：
o
PGRES_EMPTY_QUERY—-发送给后端的字串是空的
o
PGRES_COMMAND_OK--成功完成一个没有返回数据的命令
o
PGRES_TUPLES_OK—-成功执行查询
o
PGRES_COPY_OUT-—（从服务器）CopyOut（拷贝出）数据传输开始
o
PGRES_COPY_IN—-CopyIn（拷贝入）（到服务器）数据传输开始
o
PGRES_BAD_RESPONSE—-服务器的响应无法理解
o
PGRES_NONFATAL_ERROR
o
PGRES_FATAL_ERROR
如果结果状态是PGRES_TUPLES_OK，那么可以用下面的过程从查询的返回中抽取元组信息．注意一个碰巧检索了零条元组的SELECT仍然显示PGRES_TUPLES_OK。
PGRES_COMMAND_OK用于不返回元组的命令（INSERT，UPDATE，等）。
返回PGRES_EMPTY_QUERY的响应通常意味着客户端软件里面的臭虫。
*
PQresStatus把PQresultStatus返回的枚举类型转换成一个描述状态码的字符串常量.
char*PQresStatus（ExecStatusTypestatus）;
*
PQresultErrorMessage返回与查询关联的错误信息，或在没有错误时返回一个空字符串．
char*PQresultErrorMessage（constPGresult＊res）；
紧跟在一个PQexec或PQgetResult调用后面，PQerrorMessage（对联接）将返回与PQresultErrorMessage（对结果）一样的字符串．不过,一个PGresult将保有其错误信息直到被删除，而连结的错误信息将在后续的操作完成时被改变．当你想知道与某个PGresult相关联的状态时用PQresultErrorMessage；当你想知道与联接的最近一个操作相关联的状态时用PQerrorMessage；
＊
PQclear释放于PGresult相关联的存储空
升级会员 