1.3. Command Execution Functions

1.3.1. Main Routines

• PQ-exec submits a command to the server and waits for the result.

  (PQ-exec conn query)
  

  Returns a PGresult pointer or possibly #f. A non-#f 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 #f is returned, it should be treated like a PGRES-FATAL-ERROR result. Use PQ-error-message 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. (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.)

• PQ-result-status returns the result status of the command.

  (PQ-result-status res)
  

  PQ-result-status 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

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

• PQ-res-status converts the enumerated type returned by PQ-result-status into a string constant describing the status code.

  (PQ-res-status status)
  

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

  (PQ-result-error-message res)
  

  Immediately following a PQ-exec or PQgetResult call, PQ-error-message (on the connection) will return the same string as PQ-result-error-message (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 PQ-result-error-message when you want to know the status associated with a particular PGresult; use PQ-error-message when you want to know the status from the latest operation on the connection.

• PQ-clear frees the storage associated with the PGresult. Every query result should be freed via PQclear when it is no longer needed.

  (PQ-clear 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 PQ-clear. Failure to do this will result in memory leaks in the frontend application.

• PQ-make-empty-pgresult constructs an empty PGresult object with the given status.

  (PQ-make-empty-PGresult conn 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 #f and status indicates an error, the connection's current error message is copied into the PGresult. Note that PQ-clear should eventually be called on the object, just as with a PGresult returned by libpq itself.

1.3.2. Escaping strings for inclusion in SQL queries

PQ-escape-string escapes a string for use within an SQL query.

(PQescapeString from)

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.

PQ-escape-string performs this operation. The from points to the string that is to be escaped. A call to PQ-escape-string returns an escaped version of the from string to the to buffer, replacing special characters so that they cannot cause any harm. The single quotes that must surround PostgreSQL string literals are not part of the result string.

1.3.4. Retrieving SELECT Result Information

• PQ-ntuples returns the number of tuples (rows) in the query result.

  (PQ-ntuples res)
  

• PQ-nfields returns the number of fields (columns) in each row of the query result.

  (PQ-nfields res)
  

• PQ-fname returns the field (column) name associated with the given field index. Field indices start at 0.

  (PQ-fname res field-index)
  

• PQ-fnumber returns the field (column) index associated with the given field name.

  (PQ-fnumber res field-name)
  

  -1 is returned if the given name does not match any field.

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

  (PQ-ftype res field-index)
  

  You can query the system table pg_type to obtain the name and properties of the various data types. The OIDs of the built-in data types are defined in src/include/catalog/pg_type.h in the source tree.

• PQ-fmod returns the type-specific modification data of the field associated with the given field index. Field indices start at 0.

  (PQ-fmod res field-index)
  

• PQ-fsize returns the size in bytes of the field associated with the given field index. Field indices start at 0.

  (PQ-fsize res field-index)
  

  PQ-fsize 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.

1.3.5. Retrieving SELECT Result Values

• PQ-getvalue returns a single field (column) value of one tuple (row) of a PGresult. Tuple and field indices start at 0.

  (PQ-getvalue res tup-num field-num)
  

  For most queries, the value returned by PQ-getvalue is a character string representation of the attribute value. It is then the programmer's responsibility to cast and convert the data to the correct Scheme type.

• PQ-getisnull tests a field for a NULL entry. Tuple and field indices start at 0.

  (PQ-getisnull res tup-num field-num)
  

  This function returns #t if the field contains a NULL, #f if it contains a non-null value. (Note that PQ-getvalue will return an empty string, not a null pointer, for a NULL field.)

• PQ-print prints out all the tuples and, optionally, the attribute names to the specified output stream.

  (PQ-print output-stream res
            print-options)
  
  (define-struct PQ-print-opt
    (header        ;print output field headings and row count
     align         ;align fields
  
     html3         ;output as HTML tables
  
     field-sep     ;field separator
  
    ))
  

  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.

1.3.6. Retrieving Non-SELECT Result Information

• PQ-cmd-status returns the command status string from the SQL command that generated the PGresult.

  (PQ-cmd-status res)
  

• PQ-cmd-tuples returns the number of rows affected by the SQL command.

  (PQ-cmd-tuples 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.

• PQ-oid-value 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.

   (PQ-oid-value resres)