Once a connection to a database server has been successfully established, the functions described here are used to perform SQL queries and commands.
PQexec Submit a command to
the server and wait for the result.
PGresult *PQexec(PGconn *conn,
const char *query);
Returns a PGresult 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
backend. If a NULL is returned, it should be treated like a
PGRES_FATAL_ERROR result. Use
PQerrorMessage to get more
information about the error.
The PGresult structure
encapsulates the result returned by the backend. libpq application programmers should be careful
to maintain the PGresult
abstraction. Use the accessor functions below to get at the
contents of PGresult. Avoid
directly referencing the fields of the PGresult structure because they are subject
to change in the future. (Beginning in PostgreSQL 6.4, the definition of
struct PGresult is not even provided in
libpq-fe.h. If you have old code that
accesses PGresult fields directly,
you can keep using it by including libpq-int.h too, but you are encouraged to fix
the code soon.)
PQresultStatus Returns the
result status of the command.
ExecStatusType PQresultStatus(const PGresult *res)
PQresultStatus can return
one of the following values:
PGRES_EMPTY_QUERY -- The string sent to the backend was empty.
PGRES_COMMAND_OK -- Successful completion of a command returning no data
PGRES_TUPLES_OK -- The query successfully executed
PGRES_COPY_OUT -- Copy Out (from server) data transfer started
PGRES_COPY_IN -- Copy In (to server) data transfer started
PGRES_BAD_RESPONSE -- The server's response was not understood
PGRES_NONFATAL_ERROR
PGRES_FATAL_ERROR
If the result status is PGRES_TUPLES_OK, then the routines described below can be used to retrieve the rows returned by the query. Note that a SELECT command that happens to retrieve zero rows still shows PGRES_TUPLES_OK. PGRES_COMMAND_OK is for commands that can never return rows (INSERT, UPDATE, etc.). A response of PGRES_EMPTY_QUERY often exposes a bug in the client software.
PQresStatus Converts the
enumerated type returned by PQresultStatus into a string constant
describing the status code.
char *PQresStatus(ExecStatusType status);
PQresultErrorMessage
returns the error message associated with the query, or an
empty string if there was no error.
char *PQresultErrorMessage(const PGresult *res);
Immediately following a PQexec or PQgetResult call, PQerrorMessage (on the connection) will
return the same string as PQresultErrorMessage (on the result).
However, a PGresult will retain
its error message until destroyed, whereas the connection's
error message will change when subsequent operations are
done. Use PQresultErrorMessage when you want to
know the status associated with a particular PGresult; use PQerrorMessage when you want to know the
status from the latest operation on the connection.
PQclear Frees the storage
associated with the PGresult.
Every query result should be freed via PQclear when it is no longer needed.
void PQclear(PQresult *res);
You can keep a PGresult
object around for as long as you need it; it does not go
away when you issue a new query, nor even if you close the
connection. To get rid of it, you must call PQclear. Failure to do this will result
in memory leaks in the frontend application.
PQmakeEmptyPGresult
Constructs an empty PGresult
object with the given status.
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
This is libpq's
internal routine to allocate and initialize an empty
PGresult object. It is exported
because some applications find it useful to generate result
objects (particularly objects with error status)
themselves. If conn is not
NULL and status indicates an error, the connection's
current error message is copied into the PGresult. Note that PQclear should eventually be called on
the object, just as with a PGresult returned by libpq itself.
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.
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 to 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.
The parameter 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 length. (If a terminating zero byte is found
before length bytes are
processed, PQescapeStringConn
stops at the zero; the behavior is thus rather like
strncpy.) 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 undefined. Behavior is likewise undefined if the
to and from strings overlap.
If the error parameter is not
NULL, then *error 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 error is NULL.
PQescapeStringConn returns the
number of bytes written to 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 take conn or
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 PQescapeStringConn.
PQescapeByteaConnEscapes binary data for use within an SQL command with the type bytea.
unsigned char *PQescapeByteaConn(PGconn *conn,
const unsigned char *from,
size_t from_length,
size_t *to_length);
Certain byte values must be escaped (but all
byte values can
be escaped) when used as part of a bytea literal in an SQL statement. In general, to escape
a byte, it is converted into the three digit octal number
equal to the octet value, and preceded by one or two
backslashes. The single quote (') and backslash (\) characters have special alternative
escape sequences. PQescapeByteaConn performs this
operation, escaping only the minimally required
bytes.
The from parameter
points to the first byte of the string that is to be
escaped, and the from_length parameter gives the number
of bytes in this binary string. (A terminating zero byte
is neither necessary nor counted.) The to_length parameter points to a
variable that will hold the resultant escaped string
length. This result string length includes the
terminating zero byte of the result.
PQescapeByteaConn
returns an escaped version of the from parameter binary string in memory
allocated with malloc().
This memory must be freed using free() when the result is no longer
needed. The return string has all special characters
replaced so that they can be properly processed by the
PostgreSQL string
literal parser, and the bytea input
function. A terminating zero byte is also added. The
single quotes that must surround PostgreSQL string literals are not
part of the result string.
On error, a NULL pointer is returned, and a suitable
error message is stored in the conn object. Currently, the only
possible error is insufficient memory for the result
string.
PQescapeByteaPQescapeBytea is an
older, deprecated version of PQescapeByteaConn.
unsigned char *PQescapeBytea(unsigned char *from,
size_t from_length,
size_t *to_length);
The only difference from PQescapeByteaConn is that PQescapeBytea does not take a
PGconn parameter. Because of
this, it cannot adjust its behavior depending on the
connection properties and therefore it may give the wrong
results. Also, it has no way to return an error
message on failure.
PQescapeBytea 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 PQescapeByteaConn.
PQunescapeByteaConverts a string representation of binary data into
binary data --- the reverse of PQescapeBytea. This is needed when
retrieving bytea data in text
format, but not when retrieving it in binary format.
unsigned char *PQunescapeBytea(unsigned char *from, size_t *to_length);
The from parameter
points to a string such as might be returned by
PQgetvalue when applied to
a bytea column. PQunescapeBytea converts this string
representation into its binary representation. It returns
a pointer to a buffer allocated with malloc(), or null on error, and puts
the size of the buffer in to_length. The result must be freed
using free() when it is no
longer needed.
This conversion is not exactly the inverse of
PQescapeBytea, because the
string is not expected to be "escaped" when received from PQgetvalue. In particular this means
there is no need for string quoting considerations, and
so no need for a PGconn
parameter.
PQntuples Returns the
number of tuples (rows) in the query result.
int PQntuples(const PGresult *res);
PQnfields Returns the
number of fields (columns) in each row of the query
result.
int PQnfields(const PGresult *res);
PQfname Returns the field
(column) name associated with the given field index. Field
indices start at 0.
char *PQfname(const PGresult *res,
int field_index);
PQfnumber Returns the
field (column) index associated with the given field
name.
int PQfnumber(const PGresult *res,
const char *field_name);
-1 is returned if the given name does not match any field.
PQftype Returns the field
type associated with the given field index. The integer
returned is an internal coding of the type. Field indices
start at 0.
Oid PQftype(const PGresult *res,
int field_index);
You can query the system table pg_type to obtain the name and properties of the various data types. The OIDs of the built-in data types are defined in src/include/catalog/pg_type.h in the source tree.
PQfmod Returns the
type-specific modification data of the field associated
with the given field index. Field indices start at 0.
int PQfmod(const PGresult *res,
int field_index);
PQfsize Returns the size
in bytes of the field associated with the given field
index. Field indices start at 0.
int PQfsize(const PGresult *res,
int field_index);
PQfsize returns the space
allocated for this field in a database tuple, in other
words the size of the server's binary representation of the
data type. -1 is returned if the field is variable
size.
PQbinaryTuples Returns 1
if the PGresult contains binary
tuple data, 0 if it contains ASCII data.
int PQbinaryTuples(const PGresult *res);
Currently, binary tuple data can only be returned by a query that extracts data from a binary cursor.
PQgetvalue Returns a
single field (column) value of one tuple (row) of a
PGresult. Tuple and field
indices start at 0.
char* PQgetvalue(const PGresult *res,
int tup_num,
int field_num);
For most queries, the value returned by PQgetvalue is a null-terminated character
string representation of the attribute value. But if
PQbinaryTuples() is 1, the
value returned by PQgetvalue
is the binary representation of the type in the internal
format of the backend server (but not including the size
word, if the field is variable-length). It is then the
programmer's responsibility to cast and convert the data to
the correct C type. The pointer returned by PQgetvalue points to storage that is part
of the PGresult structure. One
should not modify it, and one must explicitly copy the
value into other storage if it is to be used past the
lifetime of the PGresult
structure itself.
PQgetisnull Tests a field
for a NULL entry. Tuple and field indices start at 0.
int PQgetisnull(const PGresult *res,
int tup_num,
int field_num);
This function returns 1 if the field contains a NULL, 0
if it contains a non-null value. (Note that PQgetvalue will return an empty string,
not a null pointer, for a NULL field.)
PQgetlength Returns the
length of a field (attribute) value in bytes. Tuple and
field indices start at 0.
int PQgetlength(const PGresult *res,
int tup_num,
int field_num);
This is the actual data length for the particular data
value, that is the size of the object pointed to by
PQgetvalue. Note that for
character-represented values, this size has little to do
with the binary size reported by PQfsize.
PQprint Prints out all the
tuples and, optionally, the attribute names to the
specified output stream.
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;
This function was formerly used by psql to print query results, but this is no longer the case and this function is no longer actively supported.
PQcmdStatus Returns the
command status string from the SQL command that generated
the PGresult.
char * PQcmdStatus(PGresult *res);
PQcmdTuples Returns the
number of rows affected by the SQL command.
char * PQcmdTuples(PGresult *res);
If the SQL command that generated the PGresult was INSERT, UPDATE or DELETE, this returns a string containing the number of rows affected. If the command was anything else, it returns the empty string.
PQoidValue Returns the
object ID of the inserted row, if the SQL command was an INSERT that inserted
exactly one row into a table that has OIDs. Otherwise,
returns InvalidOid.
Oid PQoidValue(const PGresult *res);
The type Oid and the constant InvalidOid will be defined if you include the libpq header file. They will both be some integer type.
PQoidStatus Returns a
string with the object ID of the inserted row, if the
SQL command was an
INSERT. (The string will be 0 if
the INSERT did not insert exactly one row, or if the target
table does not have OIDs.) If the command was not an
INSERT, returns an empty string.
char * PQoidStatus(const PGresult *res);
This function is deprecated in favor of PQoidValue and is not thread-safe.