|The PostgreSQL 9.0 Reference Manual - Volume 2 - Programming Guide
by The PostgreSQL Global Development Group
Paperback (6"x9"), 478 pages
RRP £14.95 ($19.95)
Sales of this book support the PostgreSQL project! Get a printed copy>>>
1.2 Connection Status Functions
These functions can be used to interrogate the status of an existing database connection object.
Tip: libpq application programmers should be careful to maintain the
PGconnabstraction. Use the accessor functions described below to get at the contents of
PGconn. Reference to internal
PGconnfields using ‘libpq-int.h’ is not recommended because they are subject to change in the future.
The following functions return parameter values established at connection.
These values are fixed for the life of the
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
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
CONNECTION_BAD. Ordinarily, an OK status will remain so until
PQfinish, but a communications failure might result in the status changing to
CONNECTION_BADprematurely. In that case the application could try to recover by calling
PQreset. See the entry for
PQconnectPollwith 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_ACTIVE(a command is in progress),
PQTRANS_INTRANS(idle, in a valid transaction block), or
PQTRANS_INERROR(idle, in a failed transaction block).
PQTRANS_UNKNOWNis reported if the connection is bad.
PQTRANS_ACTIVEis reported only when a query has been sent to the server and not yet completed.
PQtransactionStatuswill give incorrect results when using a PostgreSQL 7.3 server that has the parameter
autocommitset to off. The server-side autocommit feature has been deprecated and does not exist in later server versions.
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.
PQparameterStatuscan be used to interrogate these settings. It returns the current value of a parameter if known, or
NULLif the parameter is not known. Parameters reported as of the current release include
integer_datetimeswere not reported by releases before 8.0;
standard_conforming_stringswas not reported by releases before 8.1;
IntervalStylewas not reported by releases before 8.4;
application_namewas not reported by releases before 9.0.) Note that
integer_datetimescannot change after startup. Pre-3.0-protocol servers do not report parameter settings, but libpq includes logic to obtain values for
client_encodinganyway. Applications are encouraged to use
PQparameterStatusrather than ad hoc code to determine these values. (Beware however that on a pre-3.0 connection, changing
SETafter connection startup will not be reflected by
server_version, see also
PQserverVersion, which returns the information in a numeric form that is much easier to compare against. If no value for
standard_conforming_stringsis reported, applications can assume it is
off, 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 declared
const, it in fact points to mutable storage associated with the
PGconnstructure. 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 might 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 might 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.
Returns 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
PQerrorMessageif they fail. Note that by libpq convention, a nonempty
PQerrorMessageresult can be multiple lines, and will include a trailing newline. The caller should not free the result directly. It will be freed when the associated
PGconnhandle 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);
Returns the process ID
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
NOTIFYmessages (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!
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.
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.
Returns 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_SSLin order to get the correct prototype for this function. Doing so will also automatically include ‘ssl.h’ from OpenSSL.
|ISBN 9781906966065||The PostgreSQL 9.0 Reference Manual - Volume 2 - Programming Guide||See the print edition|