| PostgreSQL 7.4.30 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Chapter 27. libpq - C Library | Fast Forward | Next |
These functions may be used to interrogate the status of an existing database connection object.
Tip: libpq application programmers should be careful to maintain the PGconn abstraction. Use the accessor functions described below to get at the contents of PGconn. Avoid directly referencing the fields of the PGconn structure because they are subject to change in the future. (Beginning in PostgreSQL release 6.4, the definition of the struct behind PGconn is not even provided in libpq-fe.h. If you have old code that accesses PGconn fields directly, you can keep using it by including libpq-int.h too, but you are encouraged to fix the code soon.)
The following functions return parameter values established at connection. These values are fixed for the life of the PGconn object.
PQdbReturns the database name of the connection.
char *PQdb(const PGconn *conn);
PQuserReturns the user name of the connection.
char *PQuser(const PGconn *conn);
PQpassReturns the password of the connection.
char *PQpass(const PGconn *conn);
PQhostReturns the server host name of the connection.
char *PQhost(const PGconn *conn);
PQportReturns the port of the connection.
char *PQport(const PGconn *conn);
PQttyReturns 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);
PQoptionsReturns 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.
PQstatusReturns 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 and CONNECTION_BAD. A good connection to the
database has the status CONNECTION_OK. A failed connection attempt
is signaled by status CONNECTION_BAD. Ordinarily, an OK status
will remain so until PQfinish, but a communications failure
might result in the status changing to CONNECTION_BAD prematurely. In that case the
application could try to recover by calling PQreset.
See the entry for PQconnectStart and PQconnectPoll with regards to other
status codes that might be seen.
PQtransactionStatusReturns 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.
| Caution |
|
|
PQparameterStatusLooks 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 (cannot change after startup); client_encoding, is_superuser, session_authorization, and DateStyle.
Pre-3.0-protocol servers do not report parameter
settings, but libpq
includes logic to obtain values for server_version, and client_encoding. Applications are encouraged
to use PQparameterStatus
rather than ad-hoc code to determine these values. (Beware
however that on a pre-3.0 connection, changing client_encoding via SET after connection startup will not be
reflected by PQparameterStatus.)
PQprotocolVersionInterrogates 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 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.)
PQerrorMessageReturns the error message most recently generated by an operation on the connection.
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.
PQsocketObtains 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);
PQbackendPIDReturns the process ID (PID) of the backend server process handling this connection.
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!
PQgetsslReturns the SSL structure used in the connection, or null if SSL is not in use.
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 prototype for this function. Doing this will also automatically include ssl.h from OpenSSL.