第 53 章 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 库链接。
53.1. 数据库连接函数
下面的例程用于建立与 Postgres 后端服务器的连接。一个应用程序可以同时打开多个后端连接（原因之一是需要访问多个数据库）。每个连接由一个 PGconn 对象表示，该对象通过 PQconnectdb() 或 PQsetdbLogin() 获得。注意，除非内存太少以至于连 PGconn 对象都无法分配，这些函数总是返回一个非空的对象指针。在通过连接对象发送查询之前，应当调用 PQstatus 函数检查连接是否成功建立。
PQsetdbLogin与后端建立一个新连接。PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, const char *pgtty, const char *dbName, const char *login, const char *pwd)如果任何参数为 NULL，则检查相应的环境变量（见"环境变量"一节）。如果环境变量也未设置，则使用硬编码的默认值。返回值是指向一个抽象 struct 的指针，该结构表示到后端的连接。
PQsetdb与后端建立一个新连接。PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName)这是一个宏，以空指针作为 login 和 pwd 参数调用 PQsetdbLogin()。它主要是为了与旧程序保持向后兼容而保留。
PQconnectdb与后端建立一个新连接。PGconn *PQconnectdb(const char *conninfo)
此例程使用从一个字符串中取得的参数打开一个新的数据库连接。与 PQsetdbLogin() 不同，该例程的参数集可以在不改变函数签名的情况下扩展，因此新的应用程序编程鼓励使用此例程。传入的字符串可以为空以使用全部默认参数，也可以包含一个或多个用空白分隔的参数设置。每个参数设置的形式为 keyword = value。（要写入空值或包含空格的值，请用单引号包围，例如 keyword = 'a value'。值中的单引号必须写作 \'. 等号两边的空格是可选的。）目前可识别的参数关键字有：
host —— 要连接的主机。如果指定了非零长度的字符串，则使用 TCP/IP 通信。没有主机名时，libpq 将使用本地 Unix 域套接字连接。
port —— 服务器主机上要连接的端口号，或 Unix 域连接的套接字文件名扩展。
dbname —— 数据库名。
user —— 用于认证的用户名。
password —— 当后端要求密码认证时使用的密码。
authtype —— 授权类型。（已不再使用，因为现在由后端自行选择如何对用户进行认证。为了向后兼容，libpq 仍接受并忽略此关键字。）
options —— 要发送给后端的跟踪/调试选项。
tty —— 用于后端可选调试输出的文件或 tty。
与 PQsetdbLogin 一样，PQconnectdb 对未指定的选项使用环境变量或内建默认值。
PQconndefaults返回默认的连接选项。PQconninfoOption *PQconndefaults(void) struct PQconninfoOption { char *keyword; /* The keyword of the option */ char *envvar; /* Fallback environment variable name */ char *compiled; /* Fallback compiled in default value */ char *val; /* Option's value */ char *label; /* Label for field in connect dialog */ char *dispchar; /* Character to display for this field in a connect dialog. Values are: "" Display entered value as is "*" Password field - hide value "D" Debug options - don't create a field by default */ int dispsize; /* Field size in characters for dialog */ };返回连接选项结构的地址。它可用来确定 PQconnectdb 的所有可用选项及其当前默认值。返回值指向一个 PQconninfoOption struct 数组，该数组以一个 keyword 指针为 NULL 的条目结尾。注意，默认值（"val" 字段）依赖于环境变量和其他上下文。调用者必须将连接选项数据视为只读。
PQfinish关闭与后端的连接，同时释放 PGconn 对象使用的内存。void PQfinish(PGconn *conn)
注意，即使与后端的连接尝试失败（由 PQstatus 指示），应用也应调用 PQfinish 释放 PGconn 对象使用的内存。调用过 PQfinish 之后，不应再使用该 PGconn 指针。
PQreset重置与后端的通信端口。void PQreset(PGconn *conn)
此函数将关闭与后端的连接，并尝试使用先前使用的全部相同参数与同一个 postmaster 重新建立新连接。如果工作中的连接丢失，这可用于错误恢复。
libpq
应用程序员应注意维护
PGconn 的抽象。请使用下面的访问函数获取
PGconn 的内容。避免直接引用
PGconn 结构的字段，因为它们将来可能改变。（从
Postgres 6.4 版开始，libpq-fe.h
中甚至不再提供 struct
PGconn 的定义。如果你有直接访问
PGconn 字段的旧代码，可以通过同时包含
libpq-int.h
继续使用它，但我们建议你尽快修改这些代码。）
PQdb返回连接的数据库名。char *PQdb(PGconn *conn)
PQdb 及其后面几个函数返回在建立连接时确定的值。这些值在 PGconn 对象的整个生命周期内保持不变。
PQuser返回连接的用户名。char *PQuser(PGconn *conn)
PQpass返回连接的密码。char *PQpass(PGconn *conn)
PQhost返回连接的服务器主机名。char *PQhost(PGconn *conn)
PQport返回连接的端口。char *PQport(PGconn *conn)
PQtty返回连接的调试 tty。char *PQtty(PGconn *conn)
PQoptions返回连接中使用的后端选项。char *PQoptions(PGconn *conn)
PQstatus返回连接的状态。状态可以是 CONNECTION_OK 或 CONNECTION_BAD。ConnStatusType *PQstatus(PGconn *conn)
失败的连接尝试由状态 CONNECTION_BAD 表示。通常，OK 状态会一直保持到调用 PQfinish 为止，但通信故障可能导致状态提前变为 CONNECTION_BAD。此时应用可以尝试调用 PQreset 来恢复。
PQerrorMessage返回连接上最近一次操作所产生的错误消息。char *PQerrorMessage(PGconn* conn);
几乎所有 libpq 函数在失败时都会设置 PQerrorMessage。注意，按照 libpq 的惯例，非空的 PQerrorMessage 会包含一个末尾换行符。
PQbackendPID返回处理此连接的后端服务器的进程 ID。int PQbackendPID(PGconn *conn);
后端 PID 可用于调试，也可用于与 NOTIFY 消息（其中包含发出通知的后端的 PID）进行比较。注意，该 PID 属于数据库服务器主机上执行的进程，而不是本地主机上的进程！