# 34.3. Command Execution Functions
34.3.2. Retrieving Query Result Information
34.3.3. Retrieving Other Result Information
34.3.4. Escaping Strings for Inclusion in SQL Commands
Once a connection to a database server has been successfully established, the functions described here are used to perform SQL queries and commands.
# 34.3.1. Main Functions
Submits a command to the server and waits for the result.
PGresult *PQexec(PGconn *conn, const char *command);
Returns aPGresult
pointer or possibly a null pointer. A non-null pointer will generally be returned except in out-of-memory conditions or serious errors such as inability to send the command to the server. ThePQresultStatus
function should be called to check the return value for any errors (including the value of a null pointer, in which case it will returnPGRES_FATAL_ERROR
). UsePQerrorMessage
to get more information about such errors.
The command string can include multiple SQL commands (separated by semicolons). Multiple queries sent in a singlePQexec
call are processed in a single transaction, unless there are explicitBEGIN
/COMMIT
commands included in the query string to divide it into multiple transactions. (SeeSection 53.2.2.1for more details about how the server handles multi-query strings.) Note however that the returnedPGresult
structure describes only the result of the last command executed from the string. Should one of the commands fail, processing of the string stops with it and the returnedPGresult
描述错误情况。
向服务器提交命令并等待结果,能够将参数与 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);
PQexec 参数
就好像执行程序
, 但提供了额外的功能:参数值可以与命令字符串分开指定,查询结果可以以文本或二进制格式请求。
函数参数是:
康恩
发送命令的连接对象。
命令
要执行的 SQL 命令字符串。如果使用参数,它们在命令字符串中被称为1美元
,2美元
, 等等。
参数
提供的参数数量;它是数组的长度*参数类型[]
,参数值[]
,参数长度[]
, 和参数格式[]
.(数组指针可以是空值
什么时候参数
*为零。)
参数类型[]
通过 OID 指定要分配给参数符号的数据类型。如果*参数类型
*是空值
,或数组中的任何特定元素为零,服务器推断参数符号的数据类型与它对无类型文字字符串所做的相同。
参数值[]
指定参数的实际值。该数组中的空指针表示对应的参数为空;否则,指针指向以零结尾的文本字符串(对于文本格式)或服务器预期格式的二进制数据(对于二进制格式)。
参数长度[]
指定二进制格式参数的实际数据长度。对于空参数和文本格式参数,它会被忽略。当没有二进制参数时,数组指针可以为空。
参数格式[]
指定参数是文本(在相应参数的数组条目中放置一个零)还是二进制(在相应参数的数组条目中放置一个)。如果数组指针为空,则假定所有参数都是文本字符串。
以二进制格式传递的值需要了解后端期望的内部表示。例如,整数必须按网络字节顺序传递。通过数字
值需要了解服务器存储格式,如在src/backend/utils/adt/numeric.c::numeric_send()
和src/backend/utils/adt/numeric.c::numeric_recv()
.
结果格式
指定零以获取文本格式的结果,或指定一以获取二进制格式的结果。(目前没有规定以不同格式获取不同的结果列,尽管在底层协议中这是可能的。)
的主要优势PQexec 参数
超过执行程序
是参数值可以从命令字符串中分离出来,从而避免了繁琐且容易出错的引用和转义。
不像执行程序
,PQexec 参数
allows at most one SQL command in the given string. (There can be semicolons in it, but not more than one nonempty command.) This is a limitation of the underlying protocol, but has some usefulness as an extra defense against SQL-injection attacks.
# Tip
Specifying parameter types via OIDs is tedious, particularly if you prefer not to hard-wire particular OID values into your program. However, you can avoid doing so even in cases where the server by itself cannot determine the type of the parameter, or chooses a different type than you want. In the SQL command text, attach an explicit cast to the parameter symbol to show what data type you will send. For example:
SELECT * FROM mytable WHERE x = $1::bigint;
This forces parameter$1
to be treated asbigint
, whereas by default it would be assigned the same type asx
. Forcing the parameter type decision, either this way or by specifying a numeric type OID, is strongly recommended when sending parameter values in binary format, because binary format has less redundancy than text format and so there is less chance that the server will detect a type mismatch mistake for you.
Submits a request to create a prepared statement with the given parameters, and waits for completion.
PGresult *PQprepare(PGconn *conn,
const char *stmtName,
const char *query,
int nParams,
const Oid *paramTypes);
PQprepare
creates a prepared statement for later execution withPQexecPrepared
. This feature allows commands to be executed repeatedly without being parsed and planned each time; seePREPAREfor details.
The function creates a prepared statement named*stmtName
from thequery
string, which must contain a single SQL command.stmtName
can be""
to create an unnamed statement, in which case any pre-existing unnamed statement is automatically replaced; otherwise it is an error if the statement name is already defined in the current session. If any parameters are used, they are referred to in the query as$1
,$2
, 等等。参数
是在数组中预先指定类型的参数的数量参数类型[]
.(数组指针可以是空值
什么时候参数
为零。)参数类型[]
通过 OID 指定要分配给参数符号的数据类型。如果参数类型
是空值
,或者数组中的任何特定元素为零,服务器将数据类型分配给参数符号,其方式与对无类型文字字符串的处理方式相同。此外,查询可以使用数字大于的参数符号参数
*;还将为这些符号推断数据类型。(看PQdescribePrepared
找出推断出哪些数据类型的方法。)
与执行程序
,结果通常是PG结果
其内容指示服务器端成功或失败的对象。空结果表示内存不足或根本无法发送命令。采用PQerrorMessage
获取有关此类错误的更多信息。
准备好的语句用于PQexec 准备
也可以通过执行SQL来创建准备陈述。此外,虽然没有用于删除准备好的语句的 libpq 函数,但 SQL解除分配声明可用于此目的。
发送请求以执行具有给定参数的准备好的语句,并等待结果。
PGresult *PQexecPrepared(PGconn *conn,
const char *stmtName,
int nParams,
const char * const *paramValues,
const int *paramLengths,
const int *paramFormats,
int resultFormat);
PQexec 准备
就好像PQexec 参数
,但要执行的命令是通过命名先前准备的语句来指定的,而不是给出查询字符串。此功能允许将重复使用的命令仅解析和计划一次,而不是每次执行。该声明必须在当前会话中事先准备好。
参数与PQexec 参数
,除了给出的是准备好的语句的名称而不是查询字符串,并且*参数类型[]
*参数不存在(不需要,因为准备语句的参数类型是在创建时确定的)。
提交请求以获取有关指定准备好的语句的信息,并等待完成。
PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
PQdescribePrepared
允许应用程序获取有关先前准备好的语句的信息。
*名称
*可“”
或者空值
引用未命名的语句,否则它必须是现有准备好的语句的名称。成功时,一个PG结果
有状态PGRES_COMMAND_OK
被退回。功能PQn参数
和PQ参数类型
可以应用到这个PG结果
获取有关准备好的语句的参数和函数的信息量子场
,名称
,PQf型
等提供有关语句的结果列(如果有)的信息。
提交请求以获取有关指定门户的信息,并等待完成。
PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
PQdescribePortal
允许应用程序获取有关先前创建的门户的信息。(libpq 不提供对门户的任何直接访问,但您可以使用此函数检查使用声明光标
SQL 命令。)
*门户名称
*可“”
或者空值
引用未命名的门户,否则它必须是现有门户的名称。成功时,一个PG结果
有状态PGRES_COMMAND_OK
被退回。功能量子场
,名称
,PQf型
等可以应用于PG结果
获取有关门户的结果列(如果有)的信息。
这PG结果
结构封装了服务器返回的结果。libpq 应用程序程序员应该小心维护PG结果
抽象。使用下面的访问器函数来获取PG结果
.避免直接引用PG结果
结构,因为它们将来可能会发生变化。
返回命令的结果状态。
ExecStatusType PQresultStatus(const PGresult *res);
PQresult状态
可以返回以下值之一:
PGRES_EMPTY_QUERY
发送到服务器的字符串为空。
PGRES_COMMAND_OK
成功完成不返回数据的命令。
PGRES_TUPLES_OK
成功完成返回数据的命令(例如选择
或者显示
)。
PGRES_COPY_OUT
复制输出(从服务器)数据传输开始。
PGRES_COPY_IN
Copy In(到服务器)数据传输开始。
PGRES_BAD_RESPONSE
无法理解服务器的响应。
PGRES_NONFATAL_ERROR
发生非致命错误(通知或警告)。
PGRES_FATAL_ERROR
发生致命错误。
PGRES_COPY_BOTH
复制输入/输出(到和从服务器)数据传输开始。此功能目前仅用于流式复制,因此在普通应用程序中不应出现此状态。
PGRES_SINGLE_TUPLE
这PG结果
包含来自当前命令的单个结果元组。仅当为查询选择了单行模式时才会出现此状态(请参阅第 34.6 节)。
PGRES_PIPELINE_SYNC
这PG结果
表示管道模式下的同步点,由PQpipelineSync
.This status occurs only when pipeline mode has been selected.
PGRES_PIPELINE_ABORTED
这PG结果
表示从服务器收到错误的管道。PQgetResult
必须重复调用,每次都会返回这个状态码,直到当前流水线结束,此时才会返回PGRES_PIPELINE_SYNC
并且可以恢复正常处理。
如果结果状态是PGRES_TUPLES_OK
或者PGRES_SINGLE_TUPLE
,那么下面描述的函数可用于检索查询返回的行。请注意,一个选择
碰巧检索零行的命令仍然显示PGRES_TUPLES_OK
.PGRES_COMMAND_OK
适用于永远不能返回行的命令(插入
或者更新
没有返回
条款等)。的回应PGRES_EMPTY_QUERY
可能表明客户端软件中存在错误。
状态的结果PGRES_NONFATAL_ERROR
永远不会被直接退回执行程序
或其他查询执行功能;这种类型的结果被传递给通知处理器(参见第 34.13 节)。
转换返回的枚举类型PQresult状态
成描述状态码的字符串常量。调用者不应释放结果。
char *PQresStatus(ExecStatusType status);
返回与命令关联的错误消息,如果没有错误,则返回空字符串。
char *PQresultErrorMessage(const PGresult *res);
如果出现错误,返回的字符串将包含一个尾随换行符。调用者不应直接释放结果。当关联的时候它会被释放PG结果
句柄被传递给PQclear
.
紧接着一个执行程序
或者PQgetResult
称呼,PQerrorMessage
(在连接上)将返回相同的字符串PQresultErrorMessage
(关于结果)。然而,一个PG结果
将保留其错误消息直到销毁,而连接的错误消息将在后续操作完成时更改。采用PQresultErrorMessage
当您想知道与特定的关联的状态时PG结果
;采用PQerrorMessage
当您想从连接上的最新操作中了解状态时。
返回与 a 关联的错误消息的重新格式化版本PG结果
目的。
char *PQresultVerboseErrorMessage(const PGresult *res,
PGVerbosity verbosity,
PGContextVisibility show_context);
在某些情况下,客户可能希望获得先前报告的错误的更详细版本。PQresultVerboseErrorMessage
通过计算本应由PQresultErrorMessage
如果指定的详细设置在给定时对连接有效PG结果
生成了。如果PG结果
不是错误结果,而是报告“PGresult 不是错误结果”。返回的字符串包含一个尾随换行符。
与大多数其他用于从PG结果
,这个函数的结果是一个新分配的字符串。调用者必须使用释放它PQfreemem()
当不再需要该字符串时。
如果内存不足,则可能返回 NULL。
返回错误报告的单个字段。
char *PQresultErrorField(const PGresult *res, int fieldcode);
*域代码
*是错误字段标识符;请参阅下面列出的符号。空值
如果返回PG结果
不是错误或警告结果,或不包含指定字段。字段值通常不包括尾随换行符。调用者不应直接释放结果。当关联的时候它会被释放PG结果
句柄被传递给PQclear
.
以下字段代码可用:
PG_DIAG_SEVERITY
严重程度;字段内容是错误
,致命的
, 或者恐慌
(在错误消息中),或警告
,注意
,调试
,信息
, 或者日志
(在通知消息中),或其中之一的本地化翻译。一直在场。
PG_DIAG_SEVERITY_NONLOCALIZED
严重程度;字段内容是错误
,致命的
, 或者恐慌
(在错误消息中),或警告
,注意
,调试
,信息
, 或者日志
(在通知消息中)。这与PG_DIAG_SEVERITY
字段,但内容从未本地化。这仅存在于 PostgreSQL 9.6 及更高版本生成的报告中。
错误的 SQLSTATE 代码。SQLSTATE 代码标识已发生的错误类型;前端应用程序可以使用它来执行特定操作(例如错误处理)以响应特定的数据库错误。有关可能的 SQLSTATE 代码的列表,请参见附录 A.该字段不可本地化,并且始终存在。
PG_DIAG_MESSAGE_PRIMARY
主要的人类可读错误消息(通常是一行)。一直在场。
PG_DIAG_MESSAGE_DETAIL
详细信息:可选的辅助错误消息,包含有关问题的更多详细信息。可能会跑到多行。
PG_DIAG_MESSAGE_HINT
提示:一个可选的建议如何处理这个问题。这旨在与细节不同,因为它提供建议(可能不合适)而不是确凿的事实。可能会跑到多行。
PG_DIAG_STATEMENT_POSITION
一个包含十进制整数的字符串,指示错误光标位置作为原始语句字符串的索引。第一个字符的索引为 1,位置以字符而不是字节为单位。
PG_DIAG_INTERNAL_POSITION
这与定义相同PG_DIAG_STATEMENT_POSITION
字段,但当光标位置指向内部生成的命令而不是客户端提交的命令时使用。这PG_DIAG_INTERNAL_QUERY
当该字段出现时,该字段将始终出现。
PG_DIAG_INTERNAL_QUERY
失败的内部生成命令的文本。例如,这可能是由 PL/pgSQL 函数发出的 SQL 查询。
PG_DIAG_CONTEXT
指示发生错误的上下文。目前,这包括活动过程语言函数和内部生成的查询的调用堆栈回溯。跟踪是每行一个条目,最近的第一个。
PG_DIAG_SCHEMA_NAME
如果错误与特定数据库对象相关联,则包含该对象的模式的名称(如果有)。
PG_DIAG_TABLE_NAME
如果错误与特定表相关联,则为表的名称。(有关表模式的名称,请参阅模式名称字段。)
PG_DIAG_COLUMN_NAME
如果错误与特定表列相关联,则为该列的名称。(参考架构和表名字段来识别表。)
PG_DIAG_DATATYPE_NAME
如果错误与特定数据类型相关联,则为数据类型的名称。(有关数据类型模式的名称,请参阅模式名称字段。)
PG_DIAG_CONSTRAINT_NAME
如果错误与特定约束相关联,则为约束的名称。有关关联的表或域,请参阅上面列出的字段。(为此,索引被视为约束,即使它们不是使用约束语法创建的。)
PG_DIAG_SOURCE_FILE
报告错误的源代码位置的文件名。
PG_DIAG_SOURCE_LINE
报告错误的源代码位置的行号。
PG_DIAG_SOURCE_FUNCTION
报告错误的源代码函数的名称。
# 笔记
模式名称、表名称、列名称、数据类型名称和约束名称的字段仅提供给有限数量的错误类型;看附录 A.不要假设任何这些字段的存在保证了另一个字段的存在。核心错误源观察到上面提到的相互关系,但用户定义的函数可能会以其他方式使用这些字段。同样,不要假设这些字段表示当前数据库中的当代对象。
客户负责格式化显示的信息以满足其需求;特别是它应该根据需要打破长线。出现在错误消息字段中的换行符应被视为换行符,而不是换行符。
libpq 内部生成的错误将具有严重性和主要消息,但通常没有其他字段。
请注意,错误字段仅可从PG结果
对象,不是PGconn
物体;没有PQerror字段
功能。
释放与 a 关联的存储空间PG结果
.每个命令结果都应该通过PQclear
当不再需要它时。
void PQclear(PGresult *res);
你可以保留一个PG结果
只要你需要它就可以对象;当您发出新命令时它不会消失,即使您关闭连接也不会消失。要摆脱它,您必须致电PQclear
.不这样做将导致应用程序中的内存泄漏。
# 34.3.2.
检索查询结果信息这些函数用于从
PG结果表示成功查询结果的对象(即具有状态的对象)
PGRES_TUPLES_OK或者
PGRES_SINGLE_TUPLE)。它们还可用于从成功的 Describe 操作中提取信息:Describe 的结果具有与实际执行查询所提供的所有相同的列信息,但它有零行。
对于具有其他状态值的对象,这些函数的行为就像结果具有零行和零列一样。
元组返回查询结果中的行数(元组)。(注意
PG结果对象限于不超过
INT_MAX行,所以
整数
int PQntuples(const PGresult *res);
量子场
int PQnfields(const PGresult *res);
名称返回与给定列号关联的列名。列号从 0 开始。调用者不应直接释放结果。当关联的时候它会被释放PG结果
句柄被传递给PQclear
.
char *PQfname(const PGresult *res,
int column_number);
空值
如果列号超出范围,则返回。
返回与给定列名关联的列号。
int PQfnumber(const PGresult *res,
const char *column_name);
-如果给定名称与任何列都不匹配,则返回 1.
给定的名称被视为 SQL 命令中的标识符,也就是说,除非双引号,否则它是小写的。例如,给定从 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
返回从中获取给定列的表的 OID。列号从 0 开始。
Oid PQftable(const PGresult *res,
int column_number);
无效
如果列号超出范围,或者指定的列不是对表列的简单引用,则返回。可以查询系统表pg_class
以确定究竟引用了哪个表。
方式样的
和常数无效
将在包含 libpq 头文件时定义。它们都将是某种整数类型。
返回构成指定查询结果列的列的列号(在其表中)。查询结果列编号从 0 开始,但表列具有非零编号。
int PQftablecol(const PGresult *res,
int column_number);
如果列号超出范围,或者指定的列不是对表列的简单引用,则返回零。
返回指示给定列格式的格式代码。列号从 0 开始。
int PQfformat(const PGresult *res,
int column_number);
格式代码 0 表示文本数据表示,而格式代码 1 表示二进制表示。(其他代码保留供将来定义。)
返回与给定列号关联的数据类型。返回的整数是该类型的内部 OID 编号。列号从 0 开始。
Oid PQftype(const PGresult *res,
int column_number);
可以查询系统表pg_type
获取各种数据类型的名称和属性。内置数据类型的 OID 在文件中定义目录/pg_type_d.h
in the PostgreSQL installation'sinclude
directory.
Returns the type modifier of the column associated with the given column number. Column numbers start at 0.
int PQfmod(const PGresult *res,
int column_number);
The interpretation of modifier values is type-specific; they typically indicate precision or size limits. The value -1 is used to indicate “no information available”. Most data types do not use modifiers, in which case the value is always -1.
Returns the size in bytes of the column associated with the given column number. Column numbers start at 0.
int PQfsize(const PGresult *res,
int column_number);
PQfsize
returns the space allocated for this column in a database row, in other words the size of the server's internal representation of the data type. (Accordingly, it is not really very useful to clients.) A negative value indicates the data type is variable-length.
Returns 1 if thePGresult
contains binary data and 0 if it contains text data.
int PQbinaryTuples(const PGresult *res);
This function is deprecated (except for its use in connection withCOPY
), because it is possible for a singlePGresult
to contain text data in some columns and binary data in others.PQfformat
is preferred.PQbinaryTuples
returns 1 only if all columns of the result are binary (format 1).
Returns a single field value of one row of aPGresult
. Row and column numbers start at 0. The caller should not free the result directly. It will be freed when the associatedPGresult
handle is passed toPQclear
.
char *PQgetvalue(const PGresult *res,
int row_number,
int column_number);
对于文本格式的数据,返回值PQgetvalue
是字段值的以空字符结尾的字符串表示形式。对于二进制格式的数据,值是由数据类型决定的二进制表示打字发送
和预感
职能。(在这种情况下,该值实际上也跟着一个零字节,但这通常没有用,因为该值可能包含嵌入的空值。)
如果字段值为空,则返回空字符串。看PQgetisnull
区分空值和空字符串值。
返回的指针PQgetvalue
指向作为一部分的存储PG结果
结构体。一个人不应该修改它指向的数据,并且如果要在数据的生命周期之后使用它,则必须明确地将数据复制到其他存储中。PG结果
结构本身。
测试一个字段的空值。行号和列号从 0 开始。
int PQgetisnull(const PGresult *res,
int row_number,
int column_number);
如果字段为空,此函数返回 1,如果它包含非空值,则返回 0.(注意PQgetvalue
将为空字段返回一个空字符串,而不是空指针。)
返回字段值的实际长度(以字节为单位)。行号和列号从 0 开始。
int PQgetlength(const PGresult *res,
int row_number,
int column_number);
这是特定数据值的实际数据长度,即指向的对象的大小PQgetvalue
.对于文本数据格式,这与strlen()
.对于二进制格式,这是必不可少的信息。请注意,应notrely onPQfsize
to obtain the actual data length.
Returns the number of parameters of a prepared statement.
int PQnparams(const PGresult *res);
This function is only useful when inspecting the result ofPQdescribePrepared
. For other types of queries it will return zero.
Returns the data type of the indicated statement parameter. Parameter numbers start at 0.
Oid PQparamtype(const PGresult *res, int param_number);
This function is only useful when inspecting the result ofPQdescribePrepared
. For other types of queries it will return zero.
Prints out all the rows and, optionally, the column names to the specified output stream.
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;
This function was formerly used by psql to print query results, but this is no longer the case. Note that it assumes all the data is in text format.
# 34.3.3. Retrieving Other Result Information
These functions are used to extract other information fromPGresult
objects.
Returns the command status tag from the SQL command that generated thePGresult
.
char *PQcmdStatus(PGresult *res);
Commonly this is just the name of the command, but it might include additional data such as the number of rows processed. The caller should not free the result directly. It will be freed when the associatedPGresult
handle is passed toPQclear
.
返回受 SQL 命令影响的行数。
char *PQcmdTuples(PGresult *res);
此函数返回一个字符串,其中包含受生成的 SQL 语句影响的行数PG结果
.此功能只能在执行后使用选择
,创建表为
,插入
,更新
,删除
,移动
,拿来
, 或者复制
声明,或执行
包含一个准备好的查询插入
,更新
, 或者删除
陈述。如果生成的命令PG结果
was anything else,PQcmdTuples
returns an empty string. The caller should not free the return value directly. It will be freed when the associatedPGresult
handle is passed toPQclear
.
Returns the OIDof the inserted row, if the SQL command was anINSERT
that inserted exactly one row into a table that has OIDs, or aEXECUTE
of a prepared query containing a suitableINSERT
statement. Otherwise, this function returnsInvalidOid
. This function will also returnInvalidOid
if the table affected by theINSERT
statement does not contain OIDs.
Oid PQoidValue(const PGresult *res);
This function is deprecated in favor ofPQoidValue
and is not thread-safe. It returns a string with the OID of the inserted row, whilePQoidValue
returns the OID value.
char *PQoidStatus(const PGresult *res);
# 34.3.4. Escaping Strings for Inclusion in SQL Commands
char *PQescapeLiteral(PGconn *conn, const char *str, size_t length);
PQescape 字面量
转义字符串以在 SQL 命令中使用。这在将数据值作为文字常量插入 SQL 命令时很有用。某些字符(例如引号和反斜杠)必须转义以防止它们被 SQL 解析器专门解释。PQescape 字面量
执行此操作。
PQescape 字面量
返回的转义版本*字符串
分配的内存中的参数malloc()
.应该使用释放此内存PQfreemem()
当不再需要结果时。不需要终止零字节,也不应计入长度
.(如果之前找到终止零字节长度
*字节被处理,PQescape 字面量
停在零;因此,这种行为很像字符串
.) 返回字符串已替换所有特殊字符,以便 PostgreSQL 字符串文字解析器可以正确处理它们。还添加了一个终止零字节。必须围绕 PostgreSQL 字符串文字的单引号包含在结果字符串中。
出错时,PQescape 字面量
返回空值
并且合适的消息存储在*康恩
*目的。
# 提示
在处理从不可靠来源收到的字符串时,进行适当的转义尤为重要。否则存在安全风险:您很容易受到“SQL 注入”攻击,其中不需要的 SQL 命令被馈送到您的数据库。
请注意,当数据值作为单独的参数传递时,进行转义既没有必要也不正确PQexec 参数
或其兄弟例程。
char *PQescapeIdentifier(PGconn *conn, const char *str, size_t length);
PQescape标识符
转义字符串以用作 SQL 标识符,例如表、列或函数名。当用户提供的标识符可能包含特殊字符时,这很有用,否则 SQL 解析器不会将其解释为标识符的一部分,或者当标识符可能包含应保留大小写的大写字符时。
PQescape标识符
返回一个版本的*字符串
参数在分配的内存中转义为 SQL 标识符malloc()
.必须使用释放此内存PQfreemem()
当不再需要结果时。不需要终止零字节,也不应计入长度
.(如果之前找到终止零字节长度
*字节被处理,PQescape标识符
停在零;因此,这种行为很像字符串
.) 返回字符串已替换所有特殊字符,以便将其作为 SQL 标识符正确处理。还添加了一个终止零字节。返回字符串也将被双引号括起来。
出错时,PQescape标识符
返回空值
并且合适的消息存储在*康恩
*目的。
# 提示
与字符串文字一样,为了防止 SQL 注入攻击,当从不可靠的来源接收到 SQL 标识符时,必须对其进行转义。
size_t PQescapeStringConn(PGconn *conn,
char *to, const char *from, size_t length,
int *error);
PQescapeStringConn
转义字符串文字,很像PQescape 字面量
.不像PQescape 字面量
,调用者负责提供适当大小的缓冲区。此外,PQescapeStringConn
不生成必须围绕 PostgreSQL 字符串文字的单引号;它们应该在插入结果的 SQL 命令中提供。参数*从
指向要转义的字符串的第一个字符,并且长度
参数给出此字符串中的字节数。不需要终止零字节,也不应计入长度
.(如果之前找到终止零字节长度
字节被处理,PQescapeStringConn
停在零;因此,这种行为很像字符串
.)到
应指向一个缓冲区,该缓冲区能够保存至少比值的两倍多一个字节长度
,否则行为未定义。行为同样是未定义的,如果到
和从
*字符串重叠。
如果*错误
参数不是空值
, 然后*错误
成功时设置为零,错误时设置为非零。目前唯一可能的错误条件涉及源字符串中的无效多字节编码。输出字符串仍然会在错误时生成,但可以预期服务器会因为格式错误而拒绝它。出错时,将适当的消息存储在康恩
对象,无论是否错误
*是空值
.
PQescapeStringConn
返回写入的字节数*到
*,不包括终止的零字节。
PQescapeString
是旧的,已弃用的版本PQescapeStringConn
.
size_t PQescapeString (char *to, const char *from, size_t length);
唯一的区别是PQescapeStringConn
就是它PQescapeString
不采取PGconn
或者*错误
参数。因此,它无法根据连接属性(例如字符编码)调整其行为,因此它可能会给出错误的结果*.此外,它无法报告错误情况。
PQescapeString
可以在一次只使用一个 PostgreSQL 连接的客户端程序中安全地使用(在这种情况下,它可以找出“幕后”需要知道的内容)。在其他情况下,这是一种安全隐患,应避免使用PQescapeStringConn
.
转义二进制数据以在 SQL 命令中使用,类型为拜茶
.与PQescapeStringConn
, 这仅在将数据直接插入 SQL 命令字符串时使用。
unsigned char *PQescapeByteaConn(PGconn *conn,
const unsigned char *from,
size_t from_length,
size_t *to_length);
某些字节值在用作拜茶
SQL 语句中的文字。PQescapeByteaConn
使用十六进制编码或反斜杠转义来转义字节。看第 8.4 节了解更多信息。
这*从
参数指向要转义的字符串的第一个字节,并且from_length
参数给出此二进制字符串中的字节数。(终止零字节既不需要也不计数。)to_length
*参数指向一个变量,该变量将保存结果转义字符串长度。此结果字符串长度包括结果的终止零字节。
PQescapeByteaConn
返回的转义版本*从
*分配的内存中的参数二进制字符串malloc()
.应该使用释放此内存PQfreemem()
当不再需要结果时。返回字符串已替换所有特殊字符,以便它们可以被 PostgreSQL 字符串文字解析器正确处理,并且拜茶
输入功能。还添加了一个终止零字节。必须围绕 PostgreSQL 字符串文字的单引号不是结果字符串的一部分。
出错时,返回一个空指针,并将适当的错误消息存储在*康恩
*目的。目前,唯一可能的错误是结果字符串的内存不足。
PQescapeBytea
是旧的,已弃用的版本PQescapeByteaConn
.
unsigned char *PQescapeBytea(const unsigned char *from,
size_t from_length,
size_t *to_length);
唯一的区别是PQescapeByteaConn
就是它PQescapeBytea
不采取PGconn
范围。因为这,PQescapeBytea
只能在一次使用单个 PostgreSQL 连接的客户端程序中安全使用(在这种情况下,它可以找出“幕后”需要知道的内容)。它可能会给出错误的结果如果在使用多个数据库连接的程序中使用(使用PQescapeByteaConn
在这种情况下)。
将二进制数据的字符串表示形式转换为二进制数据——与PQescapeBytea
.这是检索时需要的拜茶
文本格式的数据,但在以二进制格式检索时则不然。
unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
这*从
参数指向一个字符串,例如可能由PQgetvalue
当应用于拜茶
柱子。PQunescapeBytea
将此字符串表示形式转换为其二进制表示形式。它返回一个指向分配的缓冲区的指针malloc()
, 或者空值
出错时,将缓冲区的大小放入to_length
*.结果必须使用PQfreemem
当不再需要它时。
这种转换不完全是相反的PQescapeBytea
,因为从PQgetvalue
.特别是这意味着不需要考虑字符串引用,因此不需要PGconn
范围。