Once a connection to a database server has been successfully established, the functions described here are used to perform SQL queries and commands.
PQexec submits a query to the Red Hat Database backend server and waits for the result.
PGresult *PQexec(PGconn *conn, const char *query); |
The PGresult structure encapsulates the query 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. (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 as well, but you should fix the code.) |
PQresultStatus returns the result status of the query.
ExecStatusType PQresultStatus(const PGresult *res) |
PGRES_COMMAND_OK — Successful completion of a command returning no data
PGRES_TUPLES_OK — The query was successfully executed
PGRES_EMPTY_QUERY — The string sent to the backend was empty
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
PQresStatus converts the enumerated type returned by PQresultStatus into a string constant that describes 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); |
PQclear frees the storage associated with the PGresult. Whenever a query result is no longer needed, free it with PQclear.
void PQclear(PQresult *res); |
PQmakeEmptyPGresult constructs an empty PGresult object with the given status.
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); |
PQescapeString Escapes a string for use within an SQL query.
size_t PQescapeString (char *to, const char *from, size_t length); |
PQescapeString performs this operation. Thefrom points to the first character of the string thatis to be escaped, and the length parameter counts thenumber of characters in this string (a terminating zero byte isneither necessary nor counted). to shall point to abuffer that is able to hold at least one more character than twicethe value of length, otherwise the behavior isundefined. A call to PQescapeString writes an escapedversion of the from string to the tobuffer, replacing special characters so that they cannot cause anyharm, and adding a terminating zero byte. The single quotes thatmust surround PostgreSQL string literals are not part of the resultstring.
PQescapeString returns the number of characters writtento to, not including the terminating zero byte.Behavior is undefined when the to and fromstrings overlap.
PQescapeBytea Escapes a binary string (bytea type) for use within an SQL query.
unsigned char *PQescapeBytea(unsigned char *from, size_t from_length, size_t *to_length); |
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 does not include 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.
PQntuples returns the number of tuples (rows) in the query result.
int PQntuples(const PGresult *res); |
PQnfields returns the number of fields (attributes) in each tuple of the query result.
int PQnfields(const PGresult *res); |
PQfname returns the field (attribute) name associated with the given field index. Field indexes start at 0.
char *PQfname(const PGresult *res, int field_index); |
PQfnumber returns the field (attribute) index associated with the given field name.
int PQfnumber(const PGresult *res, const char *field_name); |
A result of -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 indexes start at 0.
Oid PQftype(const PGresult *res, int field_index); |
PQfmod returns the type-specific modifier data of the field associated with the given field index. Field indexes 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 indexes start at 0.
int PQfsize(const PGresult *res, int field_index); |
PQbinaryTuples returns 1 if the PGresult contains binary tuple data, 0 if it contains ASCII data.
int PQbinaryTuples(const PGresult *res); |
PQgetvalue returns a single field (attribute) value of one tuple of a PGresult. Tuple and field indexes start at 0.
char* PQgetvalue(const PGresult *res, int tup_num, int field_num); |
PQgetisnull tests a field for a NULL entry. Tuple and field indexes start at 0.
int PQgetisnull(const PGresult *res, int tup_num, int field_num); |
PQgetlength returns the length of a field (attribute) value in bytes. Tuple and field indexes start at 0.
int PQgetlength(const PGresult *res, int tup_num, int field_num); |
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; |
PQcmdStatus returns the command status string associated with the SQL command that generated the PGresult.
char * PQcmdStatus(const PGresult *res); |
PQcmdTuples returns the number of rows affected by the SQL command.
char * PQcmdTuples(const PGresult *res); |
PQoidValue returns the object id of the tuple inserted, if the SQL command was an INSERT. Otherwise, returns InvalidOid.
Oid PQoidValue(const PGresult *res); |