PostgreSQL7.0手册-接口-53. libpq - C 库
减小字体
增大字体第五十三章. libpq - C 库
内容
数据库联接函数
查询执行函数
异步查询处理
捷径
异步通知
与 COPY 命令相关的函数
libpq 跟踪函数
libpq 控制函数
环境变量
线程特性
例子程序
libpq 是 Postgres 的 C 应用程序员的接口．libpq 是一套允许客户程序向 Postgres 后端服务进程发送查询并且获得查询返回的库过程．libpq 同时也是其他几个 Postgres 应用接口下面的引擎，包括 libpq++ （C++），libpgtcl （Tcl）， perl5，和 ecpg．所以如果你使用这些软件包，libpq 某些方面的特性会对你非常重要．
本节末尾有三个小程序显示如何利用 libpq 书写程序．在下面目录里面有几个完整的 libpq 应用的例子：
../src/test/regress
../src/test/examples
../src/bin/psql
使用 libpq 的前端程序必须包括头文件 libpq-fe.h 并且必须与 libpq 库链接．
数据库联接函数
下面的过程处理与 Postgres 后端服务器联接的事情．一个应用程序一次可以与多个后端建立联接．（这么做的原因之一是访问多于一个数据库．）每个连接都是用一个从 PQconnectdb() 或 PQsetdbLogin()获得的 PGconn 对象表示．注意，这些函数总是返回一个非空的对象指针，除非存储器少得连个 PGconn 对象都分配不出来．在把查询发送给联接对象之前，可以调用 PQstatus 函数来检查一下联接是否成功．
PQconnectdb 与后端数据库服务器建立一个新的联接．
PGconn *PQconnectdb(const char *conninfo)
这个过程用从一个字符串 conninfo 来的参数与数据库打开一个新的联接．与下面的 PQsetdbLogin() 不同的是，我们可以不必更换函数签名（名字）就可以扩展参数集，所以我们建议应用程序中使用这个函数或者是它的非阻塞的相似函数 PQconnectStart / PQconnectPoll．传入的参数可以为空，表明使用所有缺省的参数，或者可以包含一个或更多个用空白间隔的参数设置．
每个参数设置以 关键字=数值 keyword = value 的形式设置．（要写一个空值或者一个包含空白的值，你可以用一对单引号包围它们，例如，keyword = 'a value' ．数值内部的单引号必须书写为 \'．等号周围的空白是可选的．）目前可识别的参数值是：
host
要联接的主机（host ）．如果声明了一个非零长字符串，就将使用 TCP/IP 通讯．使用这个参数导致一个主机名的查找。参阅 hostaddr。
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
如果后端要求口令认证，所用的口令．
options
发给后端的跟踪/调试选项．
tty
文件或控制台，用于从后端的可选调试输出．
如果有任何没有声明的参数，那么将检查对应的环境变量（参阅"环境变量"章）。如果环境变量也没有设置，那么使用编译时的硬代码。返回的值是一个指向代表与后端联接的抽象结构的指针。
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 前身，它有固定个数的参数，但是有相同的功能。
PQsetdb 与后端数据库服务器建立一个新的联接．
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName)
这是一个调用 PQsetdbLogin() 的宏，只是 login 和 pwd 参数用空（null ）代替．提供这个函数主要是为了与老版本的程序兼容．
PQconnectStart PQconnectPoll 与数据库服务器建立一次非阻塞的联接。
PGconn *PQconnectStart(const char *conninfo)
PostgresPollingStatusType *PQconnectPoll(PQconn *conn)
着两个过程用于打开一个与数据库服务器之间的非阻塞的联接：你的应用的执行线索在运行的时候不会阻塞远端的 I/O。
数据库联接是用从 conninfo 字符串里取得的参数传递给 PQconnectStart 进行的。这个字符串的格式与上面 PQconnectdb 里描述的一样。
PQconnectStart 和 PQconnectPoll 都不会阻塞（进程），不过有一些限制：
必须正确提供 hostaddr 和 host 参数以确保不会发生正向或者反向的名字查找。参阅上面 PQconnectdb 里的这些参数的文档获取细节。
如果你调用了 PQtrace，确保你跟踪进入的流对象不会阻塞。
你必须在调
内容
数据库联接函数
查询执行函数
异步查询处理
捷径
异步通知
与 COPY 命令相关的函数
libpq 跟踪函数
libpq 控制函数
环境变量
线程特性
例子程序
libpq 是 Postgres 的 C 应用程序员的接口．libpq 是一套允许客户程序向 Postgres 后端服务进程发送查询并且获得查询返回的库过程．libpq 同时也是其他几个 Postgres 应用接口下面的引擎，包括 libpq++ （C++），libpgtcl （Tcl）， perl5，和 ecpg．所以如果你使用这些软件包，libpq 某些方面的特性会对你非常重要．
本节末尾有三个小程序显示如何利用 libpq 书写程序．在下面目录里面有几个完整的 libpq 应用的例子：
../src/test/regress
../src/test/examples
../src/bin/psql
使用 libpq 的前端程序必须包括头文件 libpq-fe.h 并且必须与 libpq 库链接．
数据库联接函数
下面的过程处理与 Postgres 后端服务器联接的事情．一个应用程序一次可以与多个后端建立联接．（这么做的原因之一是访问多于一个数据库．）每个连接都是用一个从 PQconnectdb() 或 PQsetdbLogin()获得的 PGconn 对象表示．注意，这些函数总是返回一个非空的对象指针，除非存储器少得连个 PGconn 对象都分配不出来．在把查询发送给联接对象之前，可以调用 PQstatus 函数来检查一下联接是否成功．
PQconnectdb 与后端数据库服务器建立一个新的联接．
PGconn *PQconnectdb(const char *conninfo)
这个过程用从一个字符串 conninfo 来的参数与数据库打开一个新的联接．与下面的 PQsetdbLogin() 不同的是，我们可以不必更换函数签名（名字）就可以扩展参数集，所以我们建议应用程序中使用这个函数或者是它的非阻塞的相似函数 PQconnectStart / PQconnectPoll．传入的参数可以为空，表明使用所有缺省的参数，或者可以包含一个或更多个用空白间隔的参数设置．
每个参数设置以 关键字=数值 keyword = value 的形式设置．（要写一个空值或者一个包含空白的值，你可以用一对单引号包围它们，例如，keyword = 'a value' ．数值内部的单引号必须书写为 \'．等号周围的空白是可选的．）目前可识别的参数值是：
host
要联接的主机（host ）．如果声明了一个非零长字符串，就将使用 TCP/IP 通讯．使用这个参数导致一个主机名的查找。参阅 hostaddr。
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
如果后端要求口令认证，所用的口令．
options
发给后端的跟踪/调试选项．
tty
文件或控制台，用于从后端的可选调试输出．
如果有任何没有声明的参数，那么将检查对应的环境变量（参阅"环境变量"章）。如果环境变量也没有设置，那么使用编译时的硬代码。返回的值是一个指向代表与后端联接的抽象结构的指针。
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 前身，它有固定个数的参数，但是有相同的功能。
PQsetdb 与后端数据库服务器建立一个新的联接．
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName)
这是一个调用 PQsetdbLogin() 的宏，只是 login 和 pwd 参数用空（null ）代替．提供这个函数主要是为了与老版本的程序兼容．
PQconnectStart PQconnectPoll 与数据库服务器建立一次非阻塞的联接。
PGconn *PQconnectStart(const char *conninfo)
PostgresPollingStatusType *PQconnectPoll(PQconn *conn)
着两个过程用于打开一个与数据库服务器之间的非阻塞的联接：你的应用的执行线索在运行的时候不会阻塞远端的 I/O。
数据库联接是用从 conninfo 字符串里取得的参数传递给 PQconnectStart 进行的。这个字符串的格式与上面 PQconnectdb 里描述的一样。
PQconnectStart 和 PQconnectPoll 都不会阻塞（进程），不过有一些限制：
必须正确提供 hostaddr 和 host 参数以确保不会发生正向或者反向的名字查找。参阅上面 PQconnectdb 里的这些参数的文档获取细节。
如果你调用了 PQtrace，确保你跟踪进入的流对象不会阻塞。
你必须在调
