Libpq是PostgreSQL提供的C语言数据库编程接口,用户可以使用Libpq的API来访问数据库,开发应用程序。
1.2 连接状态函数 本节的函数用来查询数据库连接的状态。
|
1.3 执行命令的函数数据库连接成功地建立以后,可以用本节介绍的函数发送SQL命令给数据库执行。
1.3.1 主要的函数 发送一个命令给数据库执行,然后等待命令执行结束。 如果返回值是一个空指针,表示遇到了错误,调用
可以在同一个命令字符串中包含多条SQL命令,不同的SQL命令用分号隔开。如果PQexec中的命令字符串含有多条命令,而且这些命令中没有BEGIN和COMMIT,这些命令将在同一个事务里面被执行,如果其中含有BEGIN和COMMIT,则这些命令将在多个事务中被执行。只要有一条命令执行失败,剩下的命令就会被停止执行,返回的PGresult中包含相应的错误信息。
发送一个命令给数据库执行,然后等待命令执行结束。这个函数可以执行带参数的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表示是二进制格式。
与 提示: 使用OID来指定参数的数据类型是一个繁琐的工作,而且这样也会导致程序缺乏一致性,因为同一类型的OID在不同的数据库版本之间可能会发生变化。推荐在SQL命令中使用强制类型转换指定参数的数据类型。例如: 在这个例子中,参数$1的类型将是bigint,默认的情况下,它与x的类型相同。 发一个请求给数据库,要求创建一个准备好的SQL语句。 参数stmtName指定准备好的语句的名字,如果它是一个空串,则创建一个未命名的语句,如果以前存在未命令的语句,则将用新的语句代替以前的语句。参数query指定具体的SQL命令,如果query中含有参数,则用$1,$2,…,$n表示。nParams是数组paramTypes的大小。数组paramTypes确定query中的参数的数据类型,用OID表示。如果nParams的值是0,paramTypes应该是一个空指针。如果paramTypes是一个空指针或者它的某个元素的值是0,数据库将自动推断query中对应的参数的数据类型。query中的参数的个数也可以大于nParams,数据库将自动推断多余的参数的数据类型。
函数的返回值是一个指向PGresult的指针。如果它为空,表示遇到错误,调用
也可以使用SQL命令PREPARE创建准备好的语句。libpq没有提供删除准备好的语句的函数,可以用SQL命令DEALLOCATE删除准备好的语句。
执行一条准备好的语句。
参数nParams、paramValues、paramLengths、paramFormats和resultFormat与函数
得到准备好的语句的相关信息。
stmtName 如果是NULL或""表示引用未命名的准备好的语句,否则引用指定的准备好的语句。如果执行成功,PGresult的状态是PGRES_COMMAND_OK。函数
PGresult结构封装了服务器返回的结果的所有信息。可以使用下面列出的函数来得到PGresult的具体内容。不要直接引用PGresult的成员,因为PGresult的结构在将来可能会发生变化。 得到命令的执行结果的状态。 PGRES_EMPTY_QUERY 送给服务器的查询字符串为空。
PGRES_COMMAND_OK 成功地执行命令,并且没有返回任何数据。
PGRES_TUPLES_OK 成功地执行命令,并且返回了数据(例如SELECT和SHOW命令)。
PGRES_COPY_OUT 服务器已经开始向客户端传送数据。
PGRES_COPY_IN 客户端已经开始向服务器传送数据。
PGRES_BAD_RESPONSE 无法识别服务器返回的信息。
PGRES_NONFATAL_ERROR 出现一个非致命的错误(提示或警告)。
PGRES_FATAL_ERROR 出现一个致命的错误。
如果结果的状态是PGRES_TUPLES_OK,可以用下面描述的函数获取查询返回的数据行。注意,如果SELECT命令执行成功,但没有返回任何数据行,结果状态也是PGRES_TUPLES_OK。
对于从来不返回数据行的命令(如没有RETURNING子句的INSERT、UPDATE),执行成功以后,结果状态是PGRES_COMMAND_OK。结果状态是PGRES_EMPTY_QUERY,表明客户端软件可能有缺陷,企图执行空的命令。
如果结果的状态是PGRES_NONFATAL_ERROR,它不会被
将函数 返回相关的命令的错误信息。如果没有错误,则返回一个空串。
不要释放该函数返回的字符串占有的内存空间,在相关的PGresult对象被释放时,错误消息占的存储空间会被自动释放。另外,系统会自动在错误消息的末尾加上一个换行符(如果是空串,不加换行符)。
注意,
返回错误报告的单个的域的值。
fieldcode是错误报告的域代码(下面有详细介绍)。如果PGresult不包含错误或警告信息,该函数返回NULL。如果PGresult不包含指定的域,该函数也返回NULL。域的值的末尾没有换行符号。函数的调用者不要试图自己释放返回的域的值占有的内存空间,它会在调用
错误报告的域代码有下列取值:
PG_DIAG_SEVERITY 错误的严重程度,取值可能是ERROR、FATAL、PANIC 、WARNING、NOTICE、DEBUG、INFO、LOG。错误报告总是包含这个域。
PG_DIAG_SQLSTATE 错误的SQLSTATE代码。附录1中列出了所有的错误代码。错误报告总是包含这个域。
PG_DIAG_MESSAGE_PRIMARY 消息的具体内容。错误报告总是包含这个域。
PG_DIAG_MESSAGE_DETAIL 消息的细节。错误报告中可能没有这个域。
PG_DIAG_MESSAGE_HINT 如何解决错误的提示信息。错误报告中可能没有这个域。
PG_DIAG_STATEMENT_POSITION 错误的具体位置。它表示的客户端发出的命令中发生错误的位置。
PG_DIAG_INTERNAL_POSITION 错误的具体位置。它与PG_DIAG_STATEMENT_POSITION类似,但它表示的是数据库自己产生的命令中发生错误的位置。如果错误报告中包含这个域,那也一定包含PG_DIAG_INTERNAL_QUERY。
PG_DIAG_INTERNAL_QUERY 执行失败的数据库自己产生的命令。可能是SQL,也可能是PL/pgSQL函数。
PG_DIAG_CONTEXT 产生错误的上下文。
PG_DIAG_SOURCE_FILE 报告错误的源代码所在的文件的名称。
PG_DIAG_SOURCE_LINE 报告错误的源代码所在的行的编号。
PG_DIAG_SOURCE_FUNCTION 报告错误的源代码所在的函数的名字。 释放与PGresult相关的存储空间。不再需要的PGresult应该用 PGresult对象占的存储空间在数据库连接被关闭以后,仍然不会被自动释放,所以要用 用给定的状态创建一个空的PGresult对象。 如果无法分配足够的内存,这个函数返回NULL。注意。必须用
1.3.2 得到查询结果的信息 查询执行成功以后(状态为PGRES_TUPLES_OK),可以使用下面的函数从返回的PGresult对象中得到查询返回的数据行的个数、返回的列的个数等信息。也可以使用这些函数得到
返回查询结果中包含的数据行的个数。 返回查询结果中每个数据行包含的列的个数。
返回指定的列编号对应的列的名字。列编号从0开始。函数的调用者不要释放该函数返回的字符串占用的存储空间,相关的PGresult对象被释放以后,该函数返回的字符串占用的存储空间会被自动释放。 如果列编号越界,函数将返回NULL。
返回指定的列的名字对应的列的编号。
如果指定的列不存在,则函数返回-1。
指定的列的名字的处理方式与 SQL命令中的标识符一样,如果没有用双引号引起来,它会被转换成小写的形式。 例如,对于下面的查询 下面是一些调用这个函数的例子: 返回指定的列所在的表的OID。列编号从0开始。
如果指定的列编号越界或者指定的列不是数据库的表中的列(可能是函数返回的结果的别名),函数返回InvalidOid。可以查询系统表pg_class得到OID对应的表的名字。
返回查询结果中的列在该列所在的数据库表中的编号。查询结果中的列的编号从0开始。数据库表中的列的编号不能是0。 如果查询结果中的列的编号越界或者指定的列不是数据库的表中的列(可能是函数返回的结果的别名),函数返回0。 返回指定的列的格式。0表示是文本格式。1表示是二进制格式。列编号从0开始。 返回指定的列的数据类型(用类型的OID表示)。列编号从0开始。
可以查询系统表pg_type得到类型OID对应的类型的名字。
返回指定的列的数据类型的修饰符(用类型的OID表示)。列编号从0开始。 不同的类型的修饰符有不同的含义。一般表示类型的精度或大小限制。-1表示类型没有修饰符。大部分类型都没有修饰符。
得到数据行的指定的列的值。数据行和列的编号从0开始。函数的调用者不要释放该函数返回的值占用的存储空间,相关的PGresult对象被释放以后,该函数返回的值占用的存储空间会被自动释放。
对于文本格式的数据,函数返回的是一个以/0结束的字符串。对于二进制类型的数据,函数的返回的是列的数据类型的
如果列的值是空值,函数将返回一个空串。可以用函数
不要修改该函数返回的指针指向的数据,因为这些数据是PGresult结构的一部分。
测试数据行的某个列是否是空值。数据行和列的编号从0开始。 返回1表示指定的列是空值。返回1表示指定的列不是空值。
返回数据行的某个列的值的长度。单位是字节。数据行和列的编号从0开始。
对于文本类型的数据,函数的返回值与
返回准备好的语句中的参数的个数。 这个函数只对 返回准备好的语句的参数的数据类型。参数的编号从0开始。
这个函数只对
输出查询返回的所有数据行。如果参数pqbool的值为真,同时也会输出列的名字。 这个函数主要被psql使用,用来输出查询结果,其它的应用程序也可以使用这个函数。该函数假定所有的数据都是文本格式。
1.3.4 字符串转义函数
int *error);
没有必要也不能对
to和from指向的内存空间也不能互相重叠。
如果参数error的值不是NULL,函数执行成功,*error 的值是0,函数执行失败,*error 的值不是0。当前只有在from指向的字符串是多字节编码类型,其中包含非法的字符的情况下才会出现错误。如果函数执行的时候遇到遇到错误,不管参数error的值是不是NULL,错误消息都会被存放在conn对象中。函数即使没有执行成功,to指向的缓冲区中也会包含一个无效的字符串,这个字符串如果传递给数据库,会被数据库识别出是一个非法的字符串。
1.3.5 二进制字符串转义函数 对SQL命令内使用的bytea类型的数据进行转义操作。与函数
参数from指向需要被转义的二进制字符串,它的长度由参数from_length指定,单位是字节,没有必要在字符串的末尾加上/0。参数to_length指向的变量存放转义以后的二进制字符串的长度,包括二进制字符串末尾的字符/0。
函数返回值是指向转义以后的二进制字符串的指针。转义以后的字符串的存储空间是用函数
函数如果执行失败,返回NULL,conn对象中会存放相应的错误信息。当前,只有在内存被耗尽,无法为转义以后的字符串分配存储空间时,函数才会执行失败。
释放libpq的函数(例如 |