These functions may be used to interrogate the status of an existing database connection object.
The following functions return parameter values established at connection. These values are fixed for the life of the PGconn object.
Returns the database name of the connection.
char *PQdb(const PGconn *conn);
Returns the user name of the connection.
char *PQuser(const PGconn *conn);
Returns the password of the connection.
char *PQpass(const PGconn *conn);
Returns the server host name of the connection.
char *PQhost(const PGconn *conn);
Returns the port of the connection.
char *PQport(const PGconn *conn);
Returns the debug TTY of the connection. (This is obsolete, since the server no longer pays attention to the TTY setting, but the function remains for backwards compatibility.)
char *PQtty(const PGconn *conn);
Returns the command-line options passed in the connection request.
char *PQoptions(const PGconn *conn);
The following functions return status data that can change as operations are executed on the PGconn object.
Returns the status of the connection.
ConnStatusType PQstatus(const PGconn *conn);
The status can be one of a number of values.
However, only two of these are
seen outside of an asynchronous connection procedure:
CONNECTION_BAD. A good
connection to the database has the status CONNECTION_OK.
A failed connection
attempt is signaled by status
Ordinarily, an OK status will remain so until
PQfinish, but a
communications failure might result in the status changing to
In that case the application
could try to recover by calling
See the entry for
PQconnectPoll with regards
to other status codes
that might be seen.
Returns the current in-transaction status of the server.
PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
The status can be PQTRANS_IDLE (currently idle), PQTRANS_ACTIVE (a command is in progress), PQTRANS_INTRANS (idle, in a valid transaction block), or PQTRANS_INERROR (idle, in a failed transaction block). PQTRANS_UNKNOWN is reported if the connection is bad. PQTRANS_ACTIVE is reported only when a query has been sent to the server and not yet completed.
Looks up a current parameter setting of the server.
const char *PQparameterStatus(const PGconn *conn, const char *paramName);
Certain parameter values are reported by the server automatically at
connection startup or whenever their values change.
PQparameterStatus can be used to interrogate these settings.
It returns the current value of a parameter if known, or NULL
if the parameter is not known.
Parameters reported as of the current release include server_version, server_encoding, client_encoding, is_superuser, session_authorization, DateStyle, TimeZone, integer_datetimes, and standard_conforming_strings. (server_encoding, TimeZone, and integer_datetimes were not reported by releases before 8.0; standard_conforming_strings was not reported by releases before 8.1.) Note that server_version, server_encoding and integer_datetimes cannot change after startup.
Pre-3.0-protocol servers do not report parameter settings, but
libpq includes logic to obtain values for
server_version and client_encoding anyway.
Applications are encouraged to use
rather than ad hoc code to determine these values.
that on a pre-3.0 connection, changing client_encoding via
SET after connection startup will not be reflected by
PQparameterStatus.) For server_version,
PQserverVersion, which returns the information
in a numeric form that is much easier to compare against.
If no value for standard_conforming_strings is reported, applications may assume it is off, that is, backslashes are treated as escapes in string literals. Also, the presence of this parameter may be taken as an indication that the escape string syntax (E'...') is accepted.
Although the returned pointer is declared const, it in fact points to mutable storage associated with the PGconn structure. It is unwise to assume the pointer will remain valid across queries.
Interrogates the frontend/backend protocol being used.
int PQprotocolVersion(const PGconn *conn);
Applications may wish to use this to determine whether certain features are supported. Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol), or zero (connection bad). This will not change after connection startup is complete, but it could theoretically change during a connection reset. The 3.0 protocol will normally be used when communicating with PostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0. (Protocol 1.0 is obsolete and not supported by libpq.)
Returns an integer representing the backend version.
int PQserverVersion(const PGconn *conn);
Applications may use this to determine the version of the database server they are connected to. The number is formed by converting the major, minor, and revision numbers into two-decimal-digit numbers and appending them together. For example, version 8.1.5 will be returned as 80105, and version 8.2 will be returned as 80200 (leading zeroes are not shown). Zero is returned if the connection is bad.
char *PQerrorMessage(const PGconn *conn);
Nearly all libpq functions will set a message for
PQerrorMessage if they fail.
Note that by libpq convention, a nonempty
PQerrorMessage result will
include a trailing newline. The caller should not free the result
directly. It will be freed when the associated PGconn
handle is passed to
PQfinish. The result string
should not be expected to remain the same across operations on the
Obtains the file descriptor number of the connection socket to the server. A valid descriptor will be greater than or equal to 0; a result of -1 indicates that no server connection is currently open. (This will not change during normal operation, but could change during connection setup or reset.)
int PQsocket(const PGconn *conn);
int PQbackendPID(const PGconn *conn);
The backend PID is useful for debugging purposes and for comparison to NOTIFY messages (which include the PID of the notifying backend process). Note that the PID belongs to a process executing on the database server host, not the local host!
SSL *PQgetssl(const PGconn *conn);
This structure can be used to verify encryption levels, check server certificates, and more. Refer to the OpenSSL documentation for information about this structure.
You must define USE_SSL in order to get the correct prototype for this function. Doing this will also automatically include ssl.h from OpenSSL.