PostgreSQL使用方法
发布时间:2020-12-13 17:35:27 所属栏目:百科 来源:网络整理
导读:1.3. 命令执行函数 一旦与数据库服务器的联接成功建立,便可用这里描述的函数执行 SQL 查询和命令。 1.3.1. 主过程 * PQexec 给服务器提交一条命令并且等待结果. PGresult *PQexec(PGconn *conn, const char *query); 返回一个PGresult指针或者也可能是一个
1.3. 命令执行函数
一旦与数据库服务器的联接成功建立,便可用这里描述的函数执行 SQL 查询和命令。 1.3.1. 主过程 * PQexec 给服务器提交一条命令并且等待结果. PGresult *PQexec(PGconn *conn, const char *query); 返回一个PGresult指针或者也可能是一个 NULL 指针. 通常返回一个非空(non-NULL)的指针, 除非没有内存或发生了象不能把命令发送到后端这样的严重错误. 如果返回的是 NULL,它应该被当作PGRES_FATAL_ERROR结果处理. 用PQerrorMessage获取有关错误的更多信息. PGresult 结构封装了后端返回的结果. libpq 应用程序员应该仔细维护PGresult抽象.用下面的访问函数来获取PGresult的内容.避免直接引用 PGresult结构的数据域,因为这个结构可能会在未来被改变.(从 PostgreSQL 版本 6.4 开始, struct PGresult的定义甚至都没有放在 libpq-fe.h里.如果你有一些直接访问 PGresult数据域的老代码,你可以通过包含libpq-int.h继续使用它们,但是我们鼓励你立刻修改代码.) * PQresultStatus 返回命令的结果状态. ExecStatusType PQresultStatus(const PGresult *res) PQresultStatus可以返回下面数值之一: o PGRES_EMPTY_QUERY -- 发送给后端的字串是空的 o PGRES_COMMAND_OK -- 成功完成一个没有返回数据的命令 o PGRES_TUPLES_OK -- 成功执行查询 o PGRES_COPY_OUT -- (从服务器)Copy Out (拷贝出)数据传输开始 o PGRES_COPY_IN -- Copy In (拷贝入)(到服务器)数据传输开始 o PGRES_BAD_RESPONSE -- 服务器的响应无法理解 o PGRES_NONFATAL_ERROR o PGRES_FATAL_ERROR 如果结果状态是 PGRES_TUPLES_OK ,那么可以用下面的过程从查询的返回中抽取元组信息.注意一个碰巧检索了零条元组的 SELECT 仍然显示 PGRES_TUPLES_OK。 PGRES_COMMAND_OK用于不返回元组的命令(INSERT,UPDATE,等)。返回 PGRES_EMPTY_QUERY 的响应通常意味着客户端软件里面的臭虫。 * PQresStatus 把PQresultStatus返回的枚举类型转换成一个描述状态码的字符串常量。 char *PQresStatus(ExecStatusType status); * PQresultErrorMessage 返回与查询关联的错误信息,或在没有错误时返回一个空字符串. char *PQresultErrorMessage(const PGresult *res); 紧跟在一个 PQexec 或 PQgetResult 调用后面,PQerrorMessage (对联接)将返回与 PQresultErrorMessage (对结果)一样的字符串.不过,一个PGresult将保有其错误信息直到被删除,而连结的错误信息将在后续的操作完成时被改变.当你想知道与某个 PGresult相关联的状态时用 PQresultErrorMessage ;当你想知道与联接的最近一个操作相关联的状态时用 PQerrorMessage; * PQclear 释放于PGresult相关联的存储空间. 任何不再需要的查询结果在不需要的时候都应该用 PQclear释放掉. void PQclear(PQresult *res); 你可以保留PGresult对象任意长的时间; 当你提交新的查询时它并不消失, 甚至你断开联接后也是这样.要删除它,你必须调用 PQclear.不这么做将导致前端的存储器泄漏. * PQmakeEmptyPGresult 构造一个给出状态的为空的PGresult对象. PGresult* PQmakeEmptyPGresult(PGconn *conn,ExecStatusType status); 这是libpq的内部过程, 用于分配和初始化一个空PGresult对象. 它被输出是因为一些应用需要自行生成结 果对象(尤其是特定的带有错误状态的对象). 如果conn非空(NULL)并且状态指示一个错误, 联接当前的错误信息被拷贝到PGresult. 注意最终对该对象要调用PQclear, 正如libpq本身返回的PGresult一样. 1.3.2. 为包含在 SQL 查询中逃逸字串 PQescapeString 为在 SQL 查询中使用逃逸一个字串. size_t PQescapeString (char *to,const char *from,size_t length); 如果你需要在查询字串中包含一个从不可靠的源头接收的字串 (比如,它们是随机用户输入的),那么,出于安全原因,你不能把它们直接包含在 SQL 查询里.你应该把特殊字符引起来,否则它们就会被 SQL 分析器代换. PQescapeString 执行这个操作.from 指向将要逃逸的字串的第一个字符,length 参数计算在这个字串里的字符数量(字串结尾的字节零不是必须的,也不计入长度). to 应该指向一个缓冲区,这个缓冲区至少能保存 length 数值的两倍还多一个的字符,否则该函数行为将不可预测.调用 PQescapeString 就会把逃逸的 from 字串转换到 to 缓冲区,把特殊字符替换掉以免发生意外,并且追加终止的字节零.那些必须包围在PostgreSQL 字串文本周围的单引号不算结果字串的一部分. PQescapeString 返回写到 to 里面的字符数目,不包括结尾的字节零.如果 to 和 from 字串相互重叠,那么其行为不可预测. 1.3.3. 逃逸包含在 SQL 查询中的二进制字串 PQescapeBytea 逃逸那些在 SQL 查询中使用二进制字串(bytea 类型). unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length, size_t *to_length); 在 SQL 语句中用做 BYTEA 字串文本的 一部分的时候, 有些 ASCII 字符必需被逃逸 (但是对于所有字符而言是可以逃逸). 通常,要逃逸一个字符,它是被转换成一个三位八进制数字, 该数字数值等于相应的十进制 ASCII 数值,然后前缀 两个反斜扛.单引号(’)和反斜扛字符(\)有自己特殊的逃逸序列.参阅 用户手册获取更多信息. PQescapeBytea 执行这个操作,它只逃逸需要逃逸 的最少的字符. from 参数指向需要逃逸的字串的第一个字符, from_length 参数反映在这个二进制字串 (那种字节零既不必要也不计算在内的字串)里字符的个数. to_length 参数应该是一个指向某个缓冲区的指针, 它的空间应该能够保存逃逸后的结果字串长度. 结果字串长度不包括结果结尾的字节零. PQescapeBytea 返回一个 from 参数的二进制字串的逃逸后的版本,返回给调用者提供的缓冲区. 返回的字串已经把所有特殊的字符替换调了,这样他们就可以由 PostgreSQL的字串文本分析器以及 bytea 的输入函数 正确地处理.同时还追加了一个结尾的字节零.那些必需包围在 PostgreSQL字串文本周围的单引号不算结果字串的一部分. PQunescapeBytea 把一个二进制数据的逃逸后的字串表现形式转换成二进制数据 - PQescapeBytea 的反作用. unsigned char *PQunescapeBytea(const unsigned char *from,size_t *to_length); from 参数指向一个逃逸后的字串, 比如 PQgetvalue 从一个 BYTEA 字段返回的.PQunescapeBytea 把 它的字串表现形式转换成二进制形式,填充到一个缓冲区. 它返回一个指向该缓冲区的指针,若为 NULL 则出错, 缓冲区的尺寸放在 to_length 里. 该指针随后可以用做 free(3) 的参数. 1.3.4. 检索 SELECT 的结果信息 * PQntuples 返回查询结果里的元组(元组)个数. int PQntuples(const PGresult *res); * PQnfields 返回查询结果里每个元组的数据域(字段)的个数. int PQnfields(const PGresult *res); * PQfname 返回与给出的数据域编号相关联的数据域(字段)的名称.数据域编号从 0 开始 char *PQfname(const PGresult *res, int field_index); * PQfnumber 返回与给出的数据域名称相关联的数据域(字段)的编号. int PQfnumber(const PGresult *res, const char *field_name); 如果给出的名字不匹配任何域,返回-1. * PQftype 返回与给定数据域编号关联的数据域类型. 整数返回值是一个该类型的内部编码.数据域编号从0 开始. Oid PQftype(const PGresult *res, int field_index); 你可以查询系统表 pg_type 以获取各种数据类型的名称和属性。内建的数据类型的 OID 在源码树的 src/include/catalog/pg_type.h 文件里定义。 * PQfmod 返回与给定数据域编号相关联的类型相关的修正数据(??). 数据域编号从 0 开始. int PQfmod(const PGresult *res, int field_index); * PQfsize 返回一个PGresult 里面的一条元组的单独的一个数据域(字段)的值. 元组和数据域编号从0 开始. int PQfsize(const PGresult *res, int field_index); PQfsize返回在数据库元组里面给该数据域分配的空间, 换句话说就是该数据类型在服务器里的二进制形式的大小(尺寸). 如果该数据域是可变尺寸,返回 -1. * PQbinaryTuples 如果PGresult包含二进制元组数据时返回 1, 如果包含 ASCII 数据返回 0. int PQbinaryTuples(const PGresult *res); 目前,二进制元组数据只能从一个二进制游标里抽取数据的查询返回. 1.3.5. 检索 SELECT 结果数值 * PQgetvalue 返回一个PGresult 里面一个元组单独的一个数据域(字段)的值. 元组和数据域编号从 0 开始. char* PQgetvalue(const PGresult *res, int tup_num, int field_num); 对大多数查询而言, PQgetvalue 返回的值是一个表示字段值的空(NULL)结尾的字符串.但是如果 PQbinaryTuples() 为 1, PQgetvalue 返回的值就是该类型在后端服务器内部的二进制表现形式(但是不包括尺寸字--如果数据域是变长的).这样,把数据转换成对应的 C 类型就是程序员的责任了. PQgetvalue 返回的指针指向一个本身是 PGresult结构的一部分的存储区域.我们不能更改它,并且如果 我们要在PGresult结构的生存期后还要使用它的话, 我们必须明确地把该数值拷贝到其他存储器中. * PQgetisnull 测试一个数据域是否为空(NULL).元组和数据域编号从 0 开始. int PQgetisnull(const PGresult *res, int field_num); 如果该域包含 NULL,函数返回 1,如果包含非空(non-null )值,返回 0. (注意,对一个 NULL 数据域,PQgetvalue 将返回一个空字符串, 不是一个空指针.) * PQgetlength 返回以字节计的数据域(字段)的长度.元组和数据域编号从 0 开始. int PQgetlength(const PGresult *res, int field_num); 这是某一特定数据值的实际数据长度,也就是由PQgetvalue 指向的对象的尺寸.注意,对于 ASCII 表示的数值,这个尺寸与PQfsize 报告的二进制尺寸无关. * PQprint 向指定的输出流打印所有的元组和(可选的)字段名称. void PQprint(FILE* fout,/* output stream */ const PGresult *res, const PQprintOpt *po); 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; /* insert to HTML table ... */ char *caption; /* HTML caption */ char **fieldName; /* null terminated array of replacement field names */ } PQprintOpt; 这个函数以前被 psql 用于打印查询结果,但是现在已经不用这个函数了,并且此函数不再有活跃的支持。 1.3.6. 检索非-SELECT 结果信息 * PQcmdStatus 返回产生PGresult的 SQL 命令的命令状态字符串. char * PQcmdStatus(PGresult *res); * PQcmdTuples 返回被 SQL 命令影响的行的数量. char * PQcmdTuples(PGresult *res); 如果产生PGresult的SQL 命令是 INSERT, UPDATE 或 DELETE, 这里返回涉及行的行数.如果是其他命令返回一个空字符串. * PQoidValue 返回一个插入的元组的对象标识(OID)??如果 SQL 命令是 INSERT.否则,返回 InvalidOid. Oid PQoidValue(const PGresult *res); 如果你包含了 libpq头文件,那么 Oid 和常量 InvalidOid 的类型将被定义。他们都是某种整型类型。 * PQoidStatus 返回一个被插入的元组的对象标识的字串, 如果 SQL 命令是 INSERT。 否则. 返回一个空字串。 char * PQoidStatus(const PGresult *res); 因为有了 PQoidValue ,我们不建议使用这个函数,而且它在线程里使用也是不安全的。 以上内容由 华夏名网 搜集整理,如转载请注明原文出处,并保留这一部分内容。 (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |