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

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

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

1.3.5. Retrieving SELECT Result Values

1.3.6. Retrieving Non-SELECT Result Information