PostgreSQL-libpq-执行命令的函数

postgres_fan

http://www.wohedb.com/db_html_doc/libpq_api/libpq_3_exec.htm
http://www.wohedb.com/index.html  中文数据库管理系统




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中得到语句的查询结果包含的每个列的信息（准备好的语句也可能不返回任何列）。





    PGresult结构封装了服务器返回的结果的所有信息。可以使用下面列出的函数来得到PGresult的具体内容。不要直接引用PGresult的成员，因为PGresult的结构在将来可能会发生变化。



PQresultStatus

得到命令的执行结果的状态。

         ExecStatusType PQresultStatus(const PGresult *res);
        
该函数可能放回下面的值:

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，它不会被PQexec或其它查询执行函数直接返回，而是返回给注意消息处理函数，详细信息参考第1.6节。



PQresStatus

将函数PQresultStatus返回的结果转换成描述它的字符串。这个函数的调用者不要试图释放结果字符串所占的存储空间。

         char *PQresStatus(ExecStatusType status);
        
PQresultErrorMessage

返回相关的命令的错误信息。如果没有错误，则返回一个空串。



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



注意，PQerrorMessage返回指定的连接最近一次收到的数据库错误信息。对同一个数据库连接，多次执行PQerrorMessage得到的结果会不一样。而PQresultErrorMessage返回指定的PGresult对象包含的错误信息。对于同一个PGresult对象，它包含的错误信息是不会改变的。



PQresultErrorField

返回错误报告的单个的域的值。



         char *PQresultErrorField(const PGresult *res, int fieldcode);
        
fieldcode是错误报告的域代码（下面有详细介绍）。如果PGresult不包含错误或警告信息，该函数返回NULL。如果PGresult不包含指定的域，该函数也返回NULL。域的值的末尾没有换行符号。函数的调用者不要试图自己释放返回的域的值占有的内存空间，它会在调用PQclear释放相关的PGresult对象占用的存储空间时被自动释放。



错误报告的域代码有下列取值：



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

报告错误的源代码所在的函数的名字。



PQclear

释放与PGresult相关的存储空间。不再需要的PGresult应该用PQclear释放它占的内存空间。

         void PQclear(PGresult *res);
        
PGresult对象占的存储空间在数据库连接被关闭以后，仍然不会被自动释放，所以要用PQclear释放不再需要的PGresult对象占的存储空间，否则会引起内存泄漏。



PQmakeEmptyPGresult

用给定的状态创建一个空的PGresult对象。

         PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
        
如果无法分配足够的内存，这个函数返回NULL。注意。必须用PQclear释放创建的PGresult对象所占的存储空间。如果conn不是NULL，同时status是一个表示错误的状态，则指定的连接的当前的错误消息被复制到创建的PGresult对象里。



1.3.2 得到查询结果的信息
    查询执行成功以后（状态为PGRES_TUPLES_OK），可以使用下面的函数从返回的PGresult对象中得到查询返回的数据行的个数、返回的列的个数等信息。也可以使用这些函数得到PQdescribePrepared返回的结果中包含的列的信息。



PQntuples

返回查询结果中包含的数据行的个数。

        int PQntuples(const PGresult *res);
      
PQnfields

返回查询结果中每个数据行包含的列的个数。



        int PQnfields(const PGresult *res);
      
PQfname

返回指定的列编号对应的列的名字。列编号从0开始。函数的调用者不要释放该函数返回的字符串占用的存储空间，相关的PGresult对象被释放以后，该函数返回的字符串占用的存储空间会被自动释放。


        char *PQfname(const PGresult *res,
                      int column_number);
      
如果列编号越界，函数将返回NULL。



PQfnumber

返回指定的列的名字对应的列的编号。



        int PQfnumber(const PGresult *res,
                      const char *column_name);
      
如果指定的列不存在，则函数返回-1。



指定的列的名字的处理方式与 SQL命令中的标识符一样，如果没有用双引号引起来，它会被转换成小写的形式。

例如，对于下面的查询

SELECT 1 AS FOO, 2 AS "BAR";
下面是一些调用这个函数的例子:

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1


PQftable

返回指定的列所在的表的OID。列编号从0开始。



        Oid PQftable(const PGresult *res,
                     int column_number);
      
如果指定的列编号越界或者指定的列不是数据库的表中的列（可能是函数返回的结果的别名），函数返回InvalidOid。可以查询系统表pg_class得到OID对应的表的名字。





PQftablecol

返回查询结果中的列在该列所在的数据库表中的编号。查询结果中的列的编号从0开始。数据库表中的列的编号不能是0。

       int PQftablecol(const PGresult *res,
                       int column_number);
      
如果查询结果中的列的编号越界或者指定的列不是数据库的表中的列（可能是函数返回的结果的别名），函数返回0。



PQfformat

返回指定的列的格式。0表示是文本格式。1表示是二进制格式。列编号从0开始。

        int PQfformat(const PGresult *res,
                      int column_number);
      
PQftype

返回指定的列的数据类型（用类型的OID表示）。列编号从0开始。



        Oid PQftype(const PGresult *res,
                    int column_number);
      
可以查询系统表pg_type得到类型OID对应的类型的名字。



PQfmod

返回指定的列的数据类型的修饰符（用类型的OID表示）。列编号从0开始。

        int PQfmod(const PGresult *res,
                   int column_number);
      
不同的类型的修饰符有不同的含义。一般表示类型的精度或大小限制。-1表示类型没有修饰符。大部分类型都没有修饰符。





PQgetvalue

得到数据行的指定的列的值。数据行和列的编号从0开始。函数的调用者不要释放该函数返回的值占用的存储空间，相关的PGresult对象被释放以后，该函数返回的值占用的存储空间会被自动释放。



        char *PQgetvalue(const PGresult *res,
                         int row_number,
                         int column_number);
      
对于文本格式的数据，函数返回的是一个以\0结束的字符串。对于二进制类型的数据，函数的返回的是列的数据类型的typsend和typreceive函数使用的二进制表示形式。



如果列的值是空值，函数将返回一个空串。可以用函数PQgetisnull判断列的值是空值还是空串。



不要修改该函数返回的指针指向的数据，因为这些数据是PGresult结构的一部分。



PQgetisnull

测试数据行的某个列是否是空值。数据行和列的编号从0开始。

        int PQgetisnull(const PGresult *res,
                        int row_number,
                        int column_number);
      
返回1表示指定的列是空值。返回1表示指定的列不是空值。



PQgetlength

返回数据行的某个列的值的长度。单位是字节。数据行和列的编号从0开始。



        int PQgetlength(const PGresult *res,
                        int row_number,
                        int column_number);
      
对于文本类型的数据，函数的返回值与strlen()相同。



PQnparams

返回准备好的语句中的参数的个数。

        int PQnparams(const PGresult *res);
      
这个函数只对PQdescribePrepared返回的结果有用。对于其它类型的查询的结果，该函数返回0。



PQparamtype

返回准备好的语句的参数的数据类型。参数的编号从0开始。



        Oid PQparamtype(const PGresult *res, int param_number);
      
这个函数只对PqdescribePrepared返回的结果有用。对于其它类型的查询的结果，该函数返回0。





PQprint

输出查询返回的所有数据行。如果参数pqbool的值为真，同时也会输出列的名字。

void PQprint(FILE *fout,      /* output stream */
             const PGresult *res,
             const PQprintOpt *po);
typedef struct {
  pqbool  header;      /* print output field headings and row count */
  pqbool  align;       /* fill align the fields */
  pqbool  standard;    /* old brain dead format */
  pqbool  html3;       /* output HTML tables */
  pqbool  expanded;    /* expand tables */
  pqbool  pager;       /* use pager for output if needed */
  char    *fieldSep;   /* field separator */
  char    *tableOpt;   /* attributes for HTML table element */
  char    *caption;    /* HTML table caption */
  char    **fieldName; /* null-terminated array of replacement field names */
} PQprintOpt;
      
这个函数主要被psql使用，用来输出查询结果，其它的应用程序也可以使用这个函数。该函数假定所有的数据都是文本格式。





1.3.4 字符串转义函数
    如果SQL命令中的字符串含有单引号和反斜杠这样的特殊字符，必须对这些字符进行转义操作。函数PQescapeStringConn可以将一个需要转义的字符串变换成转义以后的形式。



size_t PQescapeStringConn (PGconn *conn,
                                char *to, const char *from, size_t length,
                                int *error);



    没有必要也不能对PQexecParams这样的函数中使用的SQL语句的参数值进行转义操作。


    参数from指向需要被转义的字符串，字符串的长度由参数length指定，单位是字节， 这个字符串的末尾不需要有字符\0。参数to指向转义以后的字符串，它的末尾会被自动加上\0。


    如果from指向的字符串的中间出现了字符\0，则\0后面的所有字符会被自动忽略。另外，to指向的缓冲区的大小必须至少是2* length+1，否则函数返回的结果将难以预测。



    to和from指向的内存空间也不能互相重叠。



    如果参数error的值不是NULL，函数执行成功，*error 的值是0，函数执行失败，*error 的值不是0。当前只有在from指向的字符串是多字节编码类型，其中包含非法的字符的情况下才会出现错误。如果函数执行的时候遇到遇到错误，不管参数error的值是不是NULL，错误消息都会被存放在conn对象中。函数即使没有执行成功，to指向的缓冲区中也会包含一个无效的字符串，这个字符串如果传递给数据库，会被数据库识别出是一个非法的字符串。



    函数PQescapeStringConn 返回to指向的结果字符串的长度，这个长度不包括字符串末尾的字符\0。




1.3.5 二进制字符串转义函数
PQescapeByteaConn

对SQL命令内使用的bytea类型的数据进行转义操作。与函数PqescapeStringConn一样，只有将bytea类型的数据直接插入到SQL命令中时才需要使用这个函数。



        unsigned char *PQescapeByteaConn(PGconn *conn,
                                         const unsigned char *from,
                                         size_t from_length,
                                         size_t *to_length);
      
参数from指向需要被转义的二进制字符串，它的长度由参数from_length指定，单位是字节，没有必要在字符串的末尾加上\0。参数to_length指向的变量存放转义以后的二进制字符串的长度，包括二进制字符串末尾的字符\0。



函数返回值是指向转义以后的二进制字符串的指针。转义以后的字符串的存储空间是用函数malloc()分配的，当转义以后的二进制字符串不再被需要时，应该用函数PQfreemem()释放它所占的存储空间。转义以后的字符串的末尾会被自动加上一个\0。



函数如果执行失败，返回NULL，conn对象中会存放相应的错误信息。当前，只有在内存被耗尽，无法为转义以后的字符串分配存储空间时，函数才会执行失败。



PQfreemem

释放libpq的函数（例如PQescapeByteaConn）分配的内存空间。

        void PQfreemem(void *ptr);