数据库编程接口Libpq

现在的位置: 首页 > 综合 > 正文

数据库编程接口Libpq

2013年09月10日 ⁄ 综合 ⁄ 共 6722字 ⁄ 字号小中大 ⁄ 评论关闭

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文档。

1.3 执行命令的函数

数据库连接成功地建立以后，可以用本节介绍的函数发送SQL命令给数据库执行。

1.3.1 主要的函数

PQexec

发送一个命令给数据库执行，然后等待命令执行结束。

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

如果返回值是一个空指针，表示遇到了错误，调用PQerrorMessage可以得到详细的错误信息。

可以在同一个命令字符串中包含多条SQL命令，不同的SQL命令用分号隔开。如果PQexec中的命令字符串含有多条命令，而且这些命令中没有BEGIN和COMMIT，这些命令将在同一个事务里面被执行,如果其中含有BEGIN和COMMIT，则这些命令将在多个事务中被执行。只要有一条命令执行失败，剩下的命令就会被停止执行，返回的PGresult中包含相应的错误信息。

PQexecParams

发送一个命令给数据库执行，然后等待命令执行结束。这个函数可以执行带参数的SQL命令。

PGresult *PQexecParams(PGconn *conn,

                       const char *command,

                       int nParams,

                       const Oid *paramTypes,

                       const char * const *paramValues,

                       const int *paramLengths,

                       const int *paramFormats,

                       int resultFormat);

PQexecParams与PQexec类似，但它还具备其它的功能，包括SQL命令可以带有参数，指定查询结果用二进制或文本的格式表示。

该函数的参数如下:

conn

数据库连接对象。

command

被执行的SQL命令。如果里面含有参数，用$1, $2,…，$n表示。

nParams

被执行的SQL命令中含有的参数的个数。它也是数组paramTypes[]、paramValues[]、paramLengths[]和paramFormats[]的长度，如果nParams的值是0，这些指针的值应该是NULL。

paramTypes[]

指定SQL命令中对应的参数的数据类型，用OID表示。如果paramTypes是一个空指针或者数组paramTypes的某个元素的值是0，数据库会自动推断对应的参数的数据类型。

paramValues[]

指定SQL命令中对应的参数的值。如果这个数组中的某个元素的值是一个空指针，意思是对应的参数的值是null，否则对应的参数的值是这个指针指向的一个以/0终止的字符串（文本格式），或者是二进制数据（二进制格式）。

paramLengths[]

指定二进制格式的参数的值的长度。对于文本格式的参数，它的值被忽略。如果SQL命令中没有二进制类型的参数，指针paramLengths可以为空。

paramFormats[]

指定参数的值的格式。0表示参数是文本格式，1表示是二进制格式。如果paramFormats是一个空指针，则表示所有的参数都是文本格式。

resultFormat

指定查询结果的格式。0表示是文本格式，1表示是二进制格式。

使用PqexecParams的另一个好处是，因为参数的值没有出现在SQL命令中，而是被另外指定，可以避免使用转义字符。

与PQexec不同的是，使用PQexecParams一次只能执行一条SQL命令，SQL命令字符串中可以出现分号，但里面只能有一个非空的命令。

提示: 使用OID来指定参数的数据类型是一个繁琐的工作，而且这样也会导致程序缺乏一致性，因为同一类型的OID在不同的数据库版本之间可能会发生变化。推荐在SQL命令中使用强制类型转换指定参数的数据类型。例如:

SELECT * FROM mytable WHERE x = $1::bigint;

在这个例子中，参数$1的类型将是bigint，默认的情况下，它与x的类型相同。

PQprepare

发一个请求给数据库，要求创建一个准备好的SQL语句。

PGresult *PQprepare(PGconn *conn,

                    const char *stmtName,

                    const char *query,

                    int nParams,

const Oid *paramTypes);

函数PQprepare创建一个准备好的语句，以后可以用PQexecPrepared执行这个准备好的语句。如果一条语句经常被执行，可以使用PQprepare为它创建查询计划，以后再用PQexecPrepared执行它时，就可以直接使用以前创建的查询计划，直接执行，提高了执行的效率。

参数stmtName指定准备好的语句的名字，如果它是一个空串，则创建一个未命名的语句，如果以前存在未命令的语句，则将用新的语句代替以前的语句。参数query指定具体的SQL命令，如果query中含有参数，则用$1，$2，…，$n表示。nParams是数组paramTypes的大小。数组paramTypes确定query中的参数的数据类型，用OID表示。如果nParams的值是0，paramTypes应该是一个空指针。如果paramTypes是一个空指针或者它的某个元素的值是0，数据库将自动推断query中对应的参数的数据类型。query中的参数的个数也可以大于nParams，数据库将自动推断多余的参数的数据类型。

函数的返回值是一个指向PGresult的指针。如果它为空，表示遇到错误，调用PQerrorMessage可以得到详细的错误信息。

也可以使用SQL命令PREPARE创建准备好的语句。libpq没有提供删除准备好的语句的函数，可以用SQL命令DEALLOCATE删除准备好的语句。

PQexecPrepared

执行一条准备好的语句。

PGresult *PQexecPrepared(PGconn *conn,

                         const char *stmtName,

                         int nParams,

                         const char * const *paramValues,

                         const int *paramLengths,

                         const int *paramFormats,

                         int resultFormat);

参数nParams、paramValues、paramLengths、paramFormats和resultFormat与函数PQexecParams中的参数是一样的。StmtName是已经准备好的语句的名字。

PQdescribePrepared

得到准备好的语句的相关信息。

PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);

stmtName 如果是NULL或""表示引用未命名的准备好的语句，否则引用指定的准备好的语句。如果执行成功，PGresult的状态是PGRES_COMMAND_OK。函数PQnparams和PQparamtype可以从PGresult中得到准备好的语句的参数的信息。函数PQnfields、PQfname和PQftype可以从PGresult中得到语句的查询结果包含的每个列的信息（准备好的语句也可能不返回任何列）。