Query Execution Functions

• PQexec Submit a query to Postgres. Returns a PGresult pointer if the query was successful or a NULL otherwise. If a NULL is returned, PQerrorMessage can be used to get more information about the error.

  PGresult *PQexec(PGconn *conn,
                   char *query);

  The PGresult structure encapsulates the query result returned by the backend. libpq programmers should be careful to maintain the PGresult abstraction. Use the accessor functions described below to retrieve the results of the query. Avoid directly referencing the fields of the PGresult structure as they are subject to change in the future.

• 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 */
  PGRES_TUPLES_OK,  /* the query successfully returned tuples */
  PGRES_COPY_OUT,
  PGRES_COPY_IN,
  PGRES_BAD_RESPONSE, /* an unexpected response was received */
  PGRES_NONFATAL_ERROR,
  PGRES_FATAL_ERROR

  If the result status is PGRES_TUPLES_OK, then the following routines can be used to retrieve the tuples returned by the query.

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

  int PQntuples(PGresult *res);

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

  int PQnfields(PGresult *res);

• 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);

• 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. If the size returned is -1, the field is a variable length field. Field indices start at 0.

  int2 PQfsize(PGresult *res,
               int field_index);

• PQgetvalue Returns the field (attribute) value. For most queries, the value returned by PQgetvalue is a null-terminated ASCII string representation of the attribute value. If the query was a result of a BINARY cursor, then the value returned by PQgetvalue is the binary representation of the type in the internal format of the backend server. It is the programmer's responsibility to cast and convert the data to the correct C type. The value returned by PQgetvalue points to storage that is part of the PGresult structure. One must explicitly copy the value into other storage if it is to be used past the lifetime of the PGresult structure itself.

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

• PQgetisnull Tests a field for a NULL entry.

  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 known value..

• PQgetlength Returns the length of a field (attribute) in bytes. If the field is a struct varlena, the length returned here does not include the size field of the varlena, i.e., it is 4 bytes less.

  int PQgetlength(PGresult *res,
                  int tup_num,
                  int field_num);

• PQcmdStatus Returns the command status associated with the last query command.

  char *PQcmdStatus(PGresult *res);

• PQcmdTuples Returns the number of rows affected by the last command.

  const char *PQcmdTuples(PGresult *res);

  If the last command was INSERT, UPDATE or DELETE, this returns a string containing the number of rows affected. If the last command was anything else, it returns the empty string.

• PQoidStatus Returns a string with the object id of the tuple inserted if the last query is an INSERT command. 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	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 funtion is intended to replace PQprintTuples(), which is now obsolete.

• PQprintTuples Prints out all the tuples and, optionally, the attribute names to the specified output stream. The programs psql and monitor both use PQprintTuples for output.

  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 properly freed when it is no longer used. Failure to do this will result in memory leaks in the frontend application.

  void PQclear(PQresult *res);