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

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

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

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

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