Command Execution Functions

PostgreSQL 7.3.4 Documentation
Prev | Chapter 1. libpq - C Library | Next

# 1.3. Command 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.

## 1.3.1. Main Routines

- `PQexec` Submit a command to the server 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 command 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 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 PostgreSQL 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 command.

      ExecStatusType PQresultStatus(const PGresult *res)

  `PQresultStatus` 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.

- `PQresStatus` Converts the enumerated type returned by `PQresultStatus` into a string constant describing 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);

  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.

- `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 error message is copied into the `PGresult.` Note that `PQclear` 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

`PQescapeString` Escapes a string for use within an SQL query.

    size_t PQescapeString (char *to, const char *from, size_t length);

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.

`PQescapeString` performs this operation. The from points to the first character of the string that is to be escaped, and the length parameter counts the number of characters in this string (a terminating zero byte is neither necessary nor counted). to shall point to a buffer that is able to hold at least one more character than twice the value of length, otherwise the behavior is undefined. A call to `PQescapeString` writes an escaped version of the from string to the to buffer, replacing special characters so that they cannot cause any harm, and adding a terminating zero byte. The single quotes that must surround PostgreSQL string literals are not part of the result string.

`PQescapeString` returns the number of characters written to to, not including the terminating zero byte. Behavior is undefined when the to and from strings overlap.

## 1.3.3. Escaping binary strings for inclusion in SQL queries

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

Certain ASCII characters must be escaped (but all characters may be escaped) when used as part of a `bytea` string literal in an SQL statement. In general, to escape a character, it is converted into the three digit octal number equal to the decimal ASCII value, and preceded by two backslashes. The single quote (') and backslash (\) characters have special alternate escape sequences. See the User's Guide for more information. `PQescapeBytea` performs this operation, escaping only the minimally required characters.

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

`PQunescapeBytea` Converts an escaped string representation of binary data into binary data - the reverse of `PQescapeBytea`.

        unsigned char *PQunescapeBytea(unsigned char *from, size_t *to_length);

The from parameter points to an escaped string such as might be returned by `PQgetvalue` of a `BYTEA` column. `PQunescapeBytea` converts this string representation into its binary representation, filling the supplied buffer. It returns a pointer to the buffer which is NULL on error, and the size of the buffer in to_length. The pointer may subsequently be used as an argument to the function `free(3)`.

## 1.3.4. Retrieving SELECT Result Information

- `PQntuples` Returns the number of tuples (rows) in the query result.

      int PQntuples(const PGresult *res);

- `PQnfields` Returns the number of fields (columns) in each row of the query result.

      int PQnfields(const PGresult *res);

- `PQfname` Returns the field (column) name associated with the given field index. Field indices start at 0.

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

- `PQfnumber` Returns the field (column) index associated with the given field name.

      int PQfnumber(const PGresult *res,
                    const 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(const PGresult *res,
                  int 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.

- `PQfmod` Returns the type-specific modification data of the field associated with the given field index. Field indices 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 indices start at 0.

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

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

      int PQbinaryTuples(const PGresult *res);

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

## 1.3.5. Retrieving SELECT Result Values

- `PQgetvalue` Returns a single field (column) value of one tuple (row) of a `PGresult`. Tuple and field indices start at 0.

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

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

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

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

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

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

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

  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

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

      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.

- `PQoidValue` 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.

      Oid PQoidValue(const PGresult *res);

  The type `Oid` and the constant InvalidOid will be defined if you include the libpq header file. They will both be some integer type.

- `PQoidStatus` Returns a string with the object ID of the inserted row, if the SQL command was an INSERT. (The string will be 0 if the INSERT did not insert exactly one row, or if the target table does not have OIDs.) If the command was not an INSERT, returns an empty string.

      char * PQoidStatus(const PGresult *res);

  This function is deprecated in favor of `PQoidValue` and is not thread-safe.

Prev | Home | Next
Database Connection Functions | Up | Asynchronous Query Processing