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 | 发生了一个致命错误 |
函数原型: char* PQresStatus(ExecStatusType status);
返回值: 返回值是一个字符串常量,调用者不能释放其内存。
3.3.4 PQresultErrorMessage 返回与查询关联的错误信息,如果没有错误则返回一个空字符串
函数原型: char* PQresultErrorMessage(const PGresult* res);
说明:PQexec和PQgetResult调用操作之后都会为PQresultErrorMessage设置一个信息。error message的内存在PGresult对象中进行管理,由PQclear调用时释放。
比较函数 | 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);
Kiumi