|PostgreSQL Reference Manual - Volume 2 - Programming Guide|
by The PostgreSQL Global Development Group
Paperback (6"x9"), 408 pages
RRP £19.95 ($34.95)
Sales of this book support the PostgreSQL project! Get a printed copy>>>
1.3.4 Escaping Strings for Inclusion in SQL Commands
PQescapeStringConn escapes a string for use within an SQL
command. This is useful when inserting data values as literal constants
in SQL commands. Certain characters (such as quotes and backslashes) must
be escaped to prevent them from being interpreted specially by the SQL parser.
PQescapeStringConn performs this operation.
Tip: It is especially important to do proper escaping when handling strings that were received from an untrustworthy source. Otherwise there is a security risk: you are vulnerable to “SQL injection” attacks wherein unwanted SQL commands are fed to your database.
Note that it is not necessary nor correct to do escaping when a data
value is passed as a separate parameter in
its sibling routines.
size_t PQescapeStringConn (PGconn *conn, char *to, const char *from, size_t length, int *error);
PQescapeStringConn writes an escaped
version of the
from string to the
buffer, escaping special characters so that they cannot cause any
harm, and adding a terminating zero byte. The single quotes that
must surround PostgreSQL string literals are not
included in the result string; they should be provided in the SQL
command that the result is inserted into.
from points to the first character of the string
that is to be escaped, and the
length parameter gives the
number of bytes in this string. A terminating zero byte is not
required, and should not be counted in
a terminating zero byte is found before
length bytes are
PQescapeStringConn stops at the zero; the behavior
is thus rather like
to shall point to a
buffer that is able to hold at least one more byte than twice
the value of
length, otherwise the behavior is
Behavior is likewise undefined if the
error parameter is not NULL, then
is set to zero on success, nonzero on error. Presently the only possible
error conditions involve invalid multibyte encoding in the source string.
The output string is still generated on error, but it can be expected that
the server will reject it as malformed. On error, a suitable message is
stored in the
conn object, whether or not
PQescapeStringConn returns the number of bytes written
to, not including the terminating zero byte.
size_t PQescapeString (char *to, const char *from, size_t length);
PQescapeString is an older, deprecated version of
PQescapeStringConn; the difference is that it does not
error parameters. Because of this,
it cannot adjust its behavior depending on the connection properties (such as
character encoding) and therefore it may give the wrong results.
Also, it has no way to report error conditions.
PQescapeString can be used safely in single-threaded client
programs that work with only one PostgreSQL connection at
a time (in this case it can find out what it needs to know “behind the
scenes”). In other contexts it is a security hazard and should be avoided
in favor of
|ISBN 0954612035||PostgreSQL Reference Manual - Volume 2 - Programming Guide||See the print edition|