Tip:libpq application programmers should be careful to maintain thePGconn abstraction. Use the accessor functions described below to get at the contents ofPGconn. Reference to internalPGconn fields usinglibpq-int.h is not recommended because they are subject to change in the future.

PQdb

Returns the database name of the connection.

char *PQdb(const PGconn *conn);

PQuser

Returns the user name of the connection.

char *PQuser(const PGconn *conn);

PQpass

Returns the password of the connection.

char *PQpass(const PGconn *conn);

PQhost

Returns the server host name of the connection.

char *PQhost(const PGconn *conn);

PQport

Returns the port of the connection.

char *PQport(const PGconn *conn);

PQtty

Returns the debugTTY of the connection. (This is obsolete, since the server no longer pays attention to theTTY setting, but the function remains for backward compatibility.)

char *PQtty(const PGconn *conn);

PQoptions

Returns the command-line options passed in the connection request.

char *PQoptions(const PGconn *conn);

PQstatus

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_OK andCONNECTION_BAD. A good connection to the database has the statusCONNECTION_OK. A failed connection attempt is signaled by statusCONNECTION_BAD. Ordinarily, an OK status will remain so untilPQfinish, but a communications failure might result in the status changing toCONNECTION_BAD prematurely. In that case the application could try to recover by callingPQreset.

See the entry forPQconnectStartParams,PQconnectStart andPQconnectPoll with regards to other status codes that might be returned.

PQtransactionStatus

Returns the current in-transaction status of the server.

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

The status can bePQTRANS_IDLE (currently idle),PQTRANS_ACTIVE (a command is in progress),PQTRANS_INTRANS (idle, in a valid transaction block), orPQTRANS_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.

PQparameterStatus

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, orNULL if the parameter is not known.

Parameters reported as of the current release includeserver_version,server_encoding,client_encoding,application_name,is_superuser,session_authorization,DateStyle,IntervalStyle,TimeZone,integer_datetimes, andstandard_conforming_strings. (server_encoding,TimeZone, andinteger_datetimes were not reported by releases before 8.0;standard_conforming_strings was not reported by releases before 8.1;IntervalStyle was not reported by releases before 8.4;application_name was not reported by releases before 9.0.) Note thatserver_version,server_encoding andinteger_datetimes cannot change after startup.

Pre-3.0-protocol servers do not report parameter settings, butlibpq includes logic to obtain values forserver_version andclient_encoding anyway. Applications are encouraged to usePQparameterStatus rather thanad hoc code to determine these values. (Beware however that on a pre-3.0 connection, changingclient_encoding viaSET after connection startup will not be reflected byPQparameterStatus.) Forserver_version, see alsoPQserverVersion, which returns the information in a numeric form that is much easier to compare against.

If no value forstandard_conforming_strings is reported, applications can assume it isoff, that is, backslashes are treated as escapes in string literals. Also, the presence of this parameter can be taken as an indication that the escape string syntax (E'...') is accepted.

Although the returned pointer is declaredconst, it in fact points to mutable storage associated with thePGconn structure. It is unwise to assume the pointer will remain valid across queries.

PQprotocolVersion

Interrogates the frontend/backend protocol being used.

int PQprotocolVersion(const PGconn *conn);

Applications might wish to use this function to determine whether certain features are supported. Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol), or zero (connection bad). The protocol version 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 withPostgreSQL 7.4 or later servers; pre-7.4 servers support only protocol 2.0. (Protocol 1.0 is obsolete and not supported bylibpq.)

PQserverVersion

Returns an integer representing the backend version.

int PQserverVersion(const PGconn *conn);

Applications might use this function 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.

PQerrorMessage

Returns the error message most recently generated by an operation on the connection.

char *PQerrorMessage(const PGconn *conn);

Nearly alllibpq functions will set a message forPQerrorMessage if they fail. Note that bylibpq convention, a nonemptyPQerrorMessage result can consist of multiple lines, and will include a trailing newline. The caller should not free the result directly. It will be freed when the associatedPGconn handle is passed toPQfinish. The result string should not be expected to remain the same across operations on thePGconn structure.

PQsocket

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

PQbackendPID

Returns the processID (PID) of the backend process handling this connection.

int PQbackendPID(const PGconn *conn);

The backendPID is useful for debugging purposes and for comparison toNOTIFY messages (which include thePID of the notifying backend process). Note that thePID belongs to a process executing on the database server host, not the local host!

PQconnectionNeedsPassword

Returns true (1) if the connection authentication method required a password, but none was available. Returns false (0) if not.

int PQconnectionNeedsPassword(const PGconn *conn);

This function can be applied after a failed connection attempt to decide whether to prompt the user for a password.

PQconnectionUsedPassword

Returns true (1) if the connection authentication method used a password. Returns false (0) if not.

int PQconnectionUsedPassword(const PGconn *conn);

This function can be applied after either a failed or successful connection attempt to detect whether the server demanded a password.

PQgetssl

Returns the SSL structure used in the connection, or null if SSL is not in use.

void *PQgetssl(const PGconn *conn);

This structure can be used to verify encryption levels, check server certificates, and more. Refer to theOpenSSL documentation for information about this structure.

The actual return value is of typeSSL *, whereSSL is a type defined by theOpenSSL library, but it is not declared this way to avoid requiring theOpenSSL header files. To use this function, code along the following lines could be used:

#include <libpq-fe.h>#include <openssl/ssl.h>...    SSL *ssl;    dbconn = PQconnectdb(...);    ...    ssl = PQgetssl(dbconn);    if (ssl)    {        /* use OpenSSL functions to access ssl */    }