数据库编程接口Libpq

Libpq是PostgreSQL提供的C语言数据库编程接口，用户可以使用Libpq的API来访问数据库，开发应用程序。


1.1 数据库连接控制函数
应用程序在连接数据库时必须使用本节介绍的数据库连接控制函数。应用程序可以同时建立多个数据库连接，一个连接只能访问一个数据库中的数据。每个数据库连接用一个PGconn对象表示，函数PQconnectdb
或PQsetdbLogin会返回一个PGconn对象。函数PQconnectdb
和PQsetdbLogin总是返回一个非空的对象指针，除非整个内存都被耗尽，无法为PGconn对象分配存储空间。在向数据库发送SQL命令以前，可以用函数PQstatus检查是否成功地建立数据库连接。


PQconnectdb

建立一个新的数据库连接。


        PGconn *PQconnectdb(const char *conninfo);
这个函数使用参数conninfo中的信息建立一个新的数据库连接。conninfo中含有一个或多个参数的值, 每个参数的值用keyword = value的形式表示，keyword表示参数的名字，value表示参数的值，也可以省略keyword 和value之间的等号，不同的值用空格隔开。如果参数的值中含有空格或者值为空，则应该用双引号引起来，例如，keyword = 'a value'
。如果参数的值中含有单引号或反斜杠，则前面必须再加上一个反斜杠，例如，/'
和//分别表示单引号和反斜杠。如果conninfo是一个空串，函数将会使用默认的参数连接数据库。


当前，conninfo支持下列参数：
host

运行数据库的主机的名字。如果它以反斜杠开始，则表示客户端想通过Unix-domain socket与数据库通信，它表示存放Unix-domain socket文件的目录。


hostaddr

运行数据库的主机的IP地址。可以是IPv4和Ipv6。如果同时指定了参数host和hostaddr，参数host将被忽略。


port

数据库的端口。


dbname

数据库的名字。默认与用户名相同。


user

数据库用户的名字。默认与运行应用程序的操作系统用户相同。


password

数据库用户的密码。


connect_timeout

连接操作的最大的等待时间。如果超过了这个时间，连接仍然没有建立成功，则主动终止建立连接的操作。单位是秒，用十进制整数表示。0或不指定这个参数的值表示一值等待下去，直到连接建立成功。这个值应该不小于2秒钟。



sslmode

表示SSL的工作模式。一共有四种，分别是disable、allow、prefer和require，默认值是require。disable表示使用未加密的 SSL连接。allow先尝试使用非SSL连接，如果失败，再尝试使用SSL连接。prefer表示先尝试建立SSL连接，如果失败，再尝试建立非SSL连接。require只尝试建立SSL连接。sslmode对于使用Unix domain socket建立的连接没有没有任何作用，会被自动忽略。


PQfinish

关闭数据库连接，同时释放PGconn对象占有的内存。


        void PQfinish(PGconn *conn);
即使建立数据库连接的操作执行失败，应用程序也应该调用PQfinish来释放PGconn对象使用的内存。PQfinish执行结束以后，不应该再使用指针PGconn。


PQreset

重置数据库连接。


        void PQreset(PGconn *conn);
这个函数会关闭数据库连接，然后使用上次建立数据库连接的参数尝试重新建立数据库连接。在数据库连接丢失以后，可以用这个函数来重新建立数据库连接。

1.2 连接状态函数

本节的函数用来查询数据库连接的状态。

PQdb
返回连接的数据库的名字。


char *PQdb(const PGconn *conn);
PQuser
返回建立连接的数据库用户名。


char *PQuser(const PGconn *conn);
PQpass
返回建立连接的数据库用户的密码。


char *PQpass(const PGconn *conn);
PQhost
返回数据库运行的主机名。

char *PQhost(const PGconn *conn);
PQport
返回数据库监听的端口。


char *PQport(const PGconn *conn);

PQstatus

返回连接的状态。

ConnStatusType PQstatus(const PGconn *conn);

它有两个取值，分别是CONNECTION_OK和CONNECTION_BAD。CONNECTION_OK表示连接正常。CONNECTION_BAD表示连接已中断，在这种情况下，可以调用PQreset重新建立连接。

PQtransactionStatus

返回指定的连接上正在执行的事务的状态。


PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
PQTRANS_IDLE
表示连接处于空闲状态，没有执行任何事务。PQTRANS_ACTIVE
表示连接处于一个事务中，而且该事务正在执行命令。 PQTRANS_INTRANS
表示处于一个事务中，但事务处于空闲状态。PQTRANS_INERROR
表示处于一个事务中，但这个事务遇到错误，处于空闲状态，等待用户发一个COMMIT或ROLLBACK命令来结束它。
PQTRANS_UNKNOWN表示数据库连接已被终止。只有在用户发送了一个查询给数据库，而且这个查询仍然还在执行的情况下，才会返回PQTRANS_ACTIVE。

PQparameterStatus
查询指定的连接上数据库参数的值。


const char *PQparameterStatus(const PGconn *conn, const char *paramName);
如果指定的参数不存在，返回NULL。


PQserverVersion
返回数据库的版本号。

int PQserverVersion(const PGconn *conn);
数据库版本号由三部分表示，分别是major、minor和revision编号，每个部分用两个十进制位表示。例如，对于8.1.5的数据库调用这个函数将返回80105，对于8.2的数据库调用这个函数将返回80200。如果连接以被终止，函数将返回0。

PQerrorMessage
返回指定的连接最近一次收到的数据库错误信息。

char *PQerrorMessage(const PGconn *conn);
不要释放该函数返回的字符串占有的内存空间，在相关的PGconn对象被释放时，错误消息占的存储空间会被自动释放。另外，系统会自动在错误消息的末尾加上一个换行符。

PQsocket
得到用来建立连接的socket的文件描述符（file descriptor）。合法的文件描述符必须大于或等于0。如果数据库连接没有被打开，函数将返回-1。

int PQsocket(const PGconn *conn);
PQbackendPID
返回执行这个连接发出的所有SQL命令的数据库 backend进程的进程ID。


int PQbackendPID(const PGconn *conn);
PQconnectionNeedsPassword
返回1表示需要提供数据库用户的密码才能建立数据库连接，但是没有提供密码。其它情况下，返回0.


int PQconnectionNeedsPassword(const PGconn *conn);
在建立连接的操作失败以后，应该调用这个函数决定是否需要提供数据库用户的密码。

PQconnectionUsedPassword


该函数检测连接数据库时，提供的数据库用户密码是否被使用。返回1表示密码被使用。返回0表示密码没有被使用。


int PQconnectionUsedPassword(const PGconn *conn);

PQgetssl
返回SSL类型的连接的SSL信息。如果不是SSL类型的连接，返回null。


SSL *PQgetssl(const PGconn *conn);
SSL信息包括加密级别、服务器证书等。详细信息参考OpenSSL文档。

         PGresult *PQexec(PGconn *conn, const char *command);

PGresult *PQexecParams(PGconn *conn,

                       const char *command,

                       int nParams,

                       const Oid *paramTypes,

                       const char * const *paramValues,

                       const int *paramLengths,

                       const int *paramFormats,

                       int resultFormat);