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
Returns the result status of the command.
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
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.
Converts the enumerated type returned by PQresultStatus into
a string constant describing the status code.
char *PQresStatus(ExecStatusType status);
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.
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.
Constructs an empty PGresult object with the given 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.
If you want to include strings that have been received
from a source that is not trustworthy (for example, because a random user
entered them), you cannot directly include them in SQL
queries for security reasons. Instead, you have to quote special
characters that are otherwise interpreted by the SQL parser.
PQescapeString performs this operation. The
from points to the first character of the string that
is to be escaped, and the length parameter counts the
number of characters in this string (a terminating zero byte is
neither necessary nor counted). to shall point to a
buffer that is able to hold at least one more character than twice
the value of length, otherwise the behavior is
undefined. A call to PQescapeString writes an escaped
version of the from string to the to
buffer, replacing 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 part of the result
PQescapeString returns the number of characters written
to to, not including the terminating zero byte.
Behavior is undefined when the to and from
Certain ASCII characters must
be escaped (but all characters may be escaped)
when used as part of a bytea
string literal in an SQL statement. In general, to
escape a character, it is converted into the three digit octal number
equal to the decimal ASCII value, and preceded by
two backslashes. The single quote (') and backslash (\) characters have
special alternate escape sequences. See the User's Guide
for more information. PQescapeBytea
performs this operation, escaping only the minimally
The from parameter points to the first
character of the string that is to be escaped, and the
from_length parameter reflects the number of
characters in this binary string (a terminating zero byte is
neither necessary nor counted). The to_length
parameter shall point to a buffer suitable to hold the resultant
escaped string length. The result string length includes the terminating
zero byte of the result.
PQescapeBytea returns an escaped version of the
from parameter binary string, to a caller-provided
buffer. 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.
Converts an escaped string representation of binary data into binary
data - the reverse of PQescapeBytea.
The from parameter points to an escaped string
such as might be returned by PQgetvalue of a
BYTEA column. PQunescapeBytea converts
this string representation into its binary representation, filling the supplied buffer.
It returns a pointer to the buffer which is NULL on error, and the size
of the buffer in to_length. The pointer may
subsequently be used as an argument to the function
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,
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.
Tests a field for a NULL entry.
Tuple and field indices start at 0.
int PQgetisnull(const PGresult *res,
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
Returns the length of a field (attribute) value in bytes.
Tuple and field indices start at 0.
int PQgetlength(const PGresult *res,
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.
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);
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 */
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.
Returns the command status string from the SQL command that
generated the PGresult.
char * PQcmdStatus(PGresult *res);
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.
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.
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.