Query Execution Functions

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 query to Postgres 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 query 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 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. (Beginning in Postgres release 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 query. PQresultStatus can return one of the following values:

  PGRES_EMPTY_QUERY,
  PGRES_COMMAND_OK,       /* the query was a command returning no data */
  PGRES_TUPLES_OK,        /* the query successfully returned tuples */
  PGRES_COPY_OUT,         /* Copy Out (from server) data transfer started */
  PGRES_COPY_IN,          /* Copy In (to server) data transfer started */
  PGRES_BAD_RESPONSE,     /* an unexpected response was received */
  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 tuples returned by the query. Note that a SELECT that happens to retrieve zero tuples still shows PGRES_TUPLES_OK. PGRES_COMMAND_OK is for commands that can never return tuples.

• PQresStatus Converts the enumerated type returned by PQresultStatus into a string constant describing the status code.

  const char *PQresStatus(ExecStatusType status);

  Older code may perform this same operation by direct access to a constant string array inside libpq,

  extern const char * const pgresStatus[];

  However, using the function is recommended instead, since it is more portable and will not fail on out-of-range values.

• PQresultErrorMessage returns the error message associated with the query, or an empty string if there was no error.

  const char *PQresultErrorMessage(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.

• PQntuples Returns the number of tuples (instances) in the query result.

  int PQntuples(PGresult *res);

• PQnfields Returns the number of fields (attributes) in each tuple of the query result.

  int PQnfields(PGresult *res);

• PQbinaryTuples Returns 1 if the PGresult contains binary tuple data, 0 if it contains ASCII data.

  int PQbinaryTuples(PGresult *res);

  Currently, binary tuple data can only be returned by a query that extracts data from a BINARY cursor.

• PQfname Returns the field (attribute) name associated with the given field index. Field indices start at 0.

  char *PQfname(PGresult *res,
                int field_index);

• PQfnumber Returns the field (attribute) index associated with the given field name.

  int PQfnumber(PGresult *res,
                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(PGresult *res,
              int field_num);

• PQfsize Returns the size in bytes of the field associated with the given field index. Field indices start at 0.

  int PQfsize(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.

• PQfmod Returns the type-specific modification data of the field associated with the given field index. Field indices start at 0.

  int PQfmod(PGresult *res,
             int field_index);

• PQgetvalue Returns a single field (attribute) value of one tuple of a PGresult. Tuple and field indices start at 0.

  char* PQgetvalue(PGresult *res,
                   int tup_num,
                   int field_num);

  For most queries, the value returned by PQgetvalue is a null-terminated ASCII string representation of the attribute value. But if PQbinaryTuples() is TRUE, 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.

• PQgetlength Returns the length of a field (attribute) in bytes. Tuple and field indices start at 0.

  int PQgetlength(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 ASCII-represented values, this size has little to do with the binary size reported by PQfsize.

• PQgetisnull Tests a field for a NULL entry. Tuple and field indices start at 0.

  int PQgetisnull(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.)

• 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.

  const 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.

• PQoidStatus Returns a string with the object id of the tuple inserted, if the SQL command was an INSERT. Otherwise, returns an empty string.

  char* PQoidStatus(PGresult *res);

• PQprint Prints out all the tuples and, optionally, the attribute names to the specified output stream.

  void PQprint(FILE* fout,      /* output stream */
               PGresult* res,
               PQprintOpt* po);
  
  struct _PQprintOpt
          {
                  pqbool  header;      /* print output field headings and row count */
                  pqbool  align;       /* fill align the fields */
                  pqbool  standard;    /* old brain dead format */
                  pqbool.shtml3;       /* 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 is intended to replace PQprintTuples(), which is now obsolete. The psql program uses PQprint() to display query results.

• PQprintTuples Prints out all the tuples and, optionally, the attribute names to the specified output stream.

  void PQprintTuples(PGresult* res,
                     FILE* fout,      /* output stream */
                     int printAttName,/* print attribute names or not*/
                     int terseOutput, /* delimiter bars or not?*/
                     int width);      /* width of column, variable width if 0*/

• PQdisplayTuples Prints out all the tuples and, optionally, the attribute names to the specified output stream.

  void PQdisplayTuples(PGresult* res,
                       FILE* fout,           /* output stream */
                       int fillAlign,        /* space fill to align columns */
                       const char *fieldSep, /* field separator */
                       int printHeader,      /* display headers? */
                       int quiet);           /* suppress print of row count at end */

  PQdisplayTuples() was intended to supersede PQprintTuples(), and is in turn superseded by PQprint().

• 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 errorMessage is copied into the PGresult. Note that PQclear should eventually be called on the object, just as with a PGresult returned by libpq itself.