[笔记][Postgres]libpq C API学习笔记

1.libpq简述

   libpq是postgres提供的C接口函数库，允许客户端程序向postgres数据库服务器发送查询请求并返回查询结果。

2.libpq使用前准备

   使用libpq的程序必须包含“libpq-fe.h”头文件，并链接libpq.lib库文件。

3.libpq常用函数说明

   3.1 数据库连接函数

   3.1.1 PQconnectdb 与数据库服务器建立一个新的连接

            函数原型：PGconn* PQconnectdb(const char* conninfo);

    参数说明：conninfo是一个用于描述数据库连接参数的字符串（以空格为分隔符），例如：“hostaddr=192.168.1.2 port=5432 dbname=mydb user=postgres password=mypass”.其中常用关键字有host,hostaddr,port,dbname,user,password,sslmode等

            返回值：   PGconn是一个用于记录postgres连接状态的指针。函数成功执行时返回一个非空的指针，并可以使用PQstatus函数查询连接是否成功。

   3.1.2 PQfinish 关闭与数据库服务器的连接，并释放PGconn的内存

           函数原型： void PQfinish(PGconn* conn);

           说明：即使数据库连接失败，也要调用PQfinish函数以释放PGconn的内存；PQfinish调用之后不能再使用PGconn对象。         

  3.2 连接状态函数

  3.2.1 PQstatus 返回连接状态

          函数原型： ConnStatusType PQstatus(const PGconn* conn);

          返回值： ConnStatusType

          

连接状态说明

返回值	说明
CONNECTION_OK	连接状态正常
CONNECTION_BAD	连接中断

   3.2.2 PQerrorMessage 返回最近一次连接操作中产生的错误信息

          函数原型： char* PQerrorMessage(const PGconn* conn);

         说明：几乎所有的libpq操作失败时都会为PQerrorMessage设置一个错误信息。error message的内存在PGconn对象中进行管理，由PQfinish调用时释放。

    3.3 SQL命令执行函数

  前提条件：postgres数据库连接建立成功。

  3.3.1 PQexec 向数据库提交一条命令并等待结果

     函数原型： PQresult* PQexec(PGconn* conn, const char* command);

     参数说明： PGconn数据库连接成功后的返回值; command转换为字符串的sql命令，它可以一个或多个SQL命令。一次PQexec调用多个SQL命令时（除非其中有明确的BEGIN/COMMIT命令将字符串分割成多个事务），将做为一个事务进行处理。

     返回值：   PQresult当命令成功执行时返回一个非空的指针;

               如果返回值为NULL,说明发生了类似不能将命令发送到服务器的致命错误（PGRES_FATAL_ERROR），可以使用PQerrorMessage来获取错误信息。

               多个SQL命令执行时，当其中一个SQL失败时，整体处理就会停止，并且返回的PQresult会描述错条件。

               PQresult中封装了服务器的返回结果，要使用下面的函数来访问PQresult,避免直接访问其内部的字段（以后的版本可以会不兼容）。

  3.3.2 PQresultStatus 返回命令的结果状态

     函数原型： ExecStatusType PQresultStatus(const PQresult* res);

执行状态类型

返回值	说明
PGRES_EMPTY_QUERY	发送给服务器的字串是空的
PGRES_COMMAND_OK	成功完成一个不返回数据的命令(如：INSERT或UPDATE)
PGRES_TUPLES_OK	成功完成一个返回数据的查询（如：SELECT）
PGRES_COPY_OUT	从服务器（copy out）拷贝出数据传输开始
PGRES_COPY_IN	(copy in)向服务器拷贝数据传输开始
PGRES_BAD_RESPONSE	服务器的响应无法理解
PGRES_NONFATAL_ERROR	发生了一个非致命错误（通知或警告）
PGRES_FATAL_ERROR	发生了一个致命错误

      3.3.3 PQresStatus 将ExecStatusType转换成一个描述错误的字符串常量

            函数原型：  char* PQresStatus(ExecStatusType status);

            返回值： 返回值是一个字符串常量，调用者不能释放其内存。

     3.3.4 PQresultErrorMessage 返回与查询关联的错误信息，如果没有错误则返回一个空字符串

           函数原型：     char* PQresultErrorMessage(const PGresult* res);

           说明：PQexec和PQgetResult调用操作之后都会为PQresultErrorMessage设置一个信息。error message的内存在PGresult对象中进行管理，由PQclear调用时释放。

          

PQerrorMessage和PQresultErrorMessage的区别

比较函数	PQerrorMessage	PQresultErrorMessage
前置调用	几乎所有libpq调用	PQexec(), PQgetResult()
返回值	常量字符串，调用者不能直接释放	常量字符串，调用者不能直接释放
返回值内存	由PGconn对象管理，调用PQfinish时释放	由PQresult对象管理，调用PQclear时释放
效果	只能反映最近一次调用的错误信息，有其他处理时错误信息 会被替换掉。	反映当前查询的错误信息，在调用PQclear释放当前查询 的内存前一直能够使用。

          综上，当我们想知道与某个PGresult关联的查询状态时使用PQresultErrorMessage;

          当我们想知道某个与PQconn连接相关的操作状态时使用PQerrorMessage.

    3.3.5 PQclear 释放与PQresult关联的内存空间

          函数原型： void PQclear(PQresult* res); 

          说明： 任何不再需要的查询结果都需要用PQclear清空。

    3.4 检索查询结果函数

           PQresultStatus查询命令执行状态的函数返回类型为PGRES_TUPLES_OK时，可以使用下列函数检索查询结果。

  3.4.1 PQntuples 返回查询结果的行数

    函数原型： int PQntuples(const PQresult* res);

 

  3.4.2 PQnfields 返回查询结果的列数

    函数原型： int PQnfields(const PQresult* res);

  3.4.3 PQfnumber 返回查询结果中给定列名的列号

    函数原型： int PQfnumber(const PQresult* res, const char* column_name);

  

  3.4.4 PQgetvalue 返回查询结果中指定行列号的字段值,行列号从0开始编号，返回结果的内存由PQresult对象进行管理，调用者不能直接释放。

    函数原型： char* PQgetvalue(const PQresult* res, int row_number, int column_number);

  3.4.5 PQftype 返回查询结果中指定列号字段的数据类型,Oid可以通过查询系统表pg_type取得各种数据类型名称和属性。

    函数原型： Oid PQgetvalue(const PQresult* res, int column_number);

以上是libpq中一些最常用的函数，对于进一步的内容今后逐步追加。

                                                                    2013年11月16日

                                                                    Kiumi