These functions can be used to interrogate the status of an existing database connection object.
libpq application programmers should be
careful to maintain the PGconn
abstraction. Use the accessor functions described below to get at
the contents of PGconn
. Reference
to internal PGconn
fields 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 connection.
If a multi-host connection string is used, the values of
PQhost
, PQport
, and PQpass
can change if a new connection is established using the same
PGconn
object. Other values are
fixed for the lifetime of the PGconn
object.
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. This can be a
host name, an IP address, or a directory path if the connection is
via Unix socket. (The path case can be distinguished because it
will always be an absolute path, beginning with /
.)
char *PQhost(const PGconn *conn);
PQport
Returns the port of the connection.
char *PQport(const PGconn *conn);
PQtty
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 backward compatibility.)
char *PQtty(const PGconn *conn);
PQoptions
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.
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
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 PQconnectStartParams
, PQconnectStart
and PQconnectPoll
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 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.
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, or NULL
if the
parameter is not known.
Parameters reported as of the current release include
server_version
, server_encoding
, client_encoding
, application_name
, is_superuser
, session_authorization
, DateStyle
, IntervalStyle
, 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; IntervalStyle
was
not reported by releases before 8.4; application_name
was not reported by releases
before 9.0.) 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 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
.) For 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_strings
is 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 PGconn
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 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.)
PQserverVersion
Returns an integer representing the server version.
int PQserverVersion(const PGconn *conn);
Applications might use this function to determine the version of the database server they are connected to. The result is formed by multiplying the server's major version number by 10000 and adding the minor version number. For example, version 10.1 will be returned as 100001, and version 11.0 will be returned as 110000. Zero is returned if the connection is bad.
Prior to major version 10, PostgreSQL used three-part version numbers in
which the first two parts together represented the major version.
For those versions, PQserverVersion
uses two digits for each part; for example version 9.1.5 will be
returned as 90105, and version 9.2.0 will be returned as 90200.
Therefore, for purposes of determining feature compatibility,
applications should divide the result of PQserverVersion
by 100 not 10000 to determine a
logical major version number. In all release series, only the last
two digits differ between minor releases (bug-fix releases).
PQerrorMessage
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 PQerrorMessage
if
they fail. Note that by libpq
convention, a nonempty PQerrorMessage
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 associated PGconn
handle is passed to PQfinish
. The
result string should not be expected to remain the same across
operations on the PGconn
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 process ID (PID) of the backend 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!
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.
The following functions return information related to SSL. This information usually doesn't change after a connection is established.
PQsslInUse
Returns true (1) if the connection uses SSL, false (0) if not.
int PQsslInUse(const PGconn *conn);
PQsslAttribute
Returns SSL-related information about the connection.
const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
The list of available attributes varies depending on the SSL library being used, and the type of connection. If an attribute is not available, returns NULL.
The following attributes are commonly available:
library
Name of the SSL implementation in use. (Currently, only
"OpenSSL"
is implemented)
protocol
SSL/TLS version in use. Common values are "TLSv1"
, "TLSv1.1"
and "TLSv1.2"
, but an implementation
may return other strings if some other protocol is used.
key_bits
Number of key bits used by the encryption algorithm.
cipher
A short name of the ciphersuite used, e.g. "DHE-RSA-DES-CBC3-SHA"
. The names are specific to
each SSL implementation.
compression
If SSL compression is in use, returns the name of the compression algorithm, or "on" if compression is used but the algorithm is not known. If compression is not in use, returns "off".
PQsslAttributeNames
Return an array of SSL attribute names available. The array is terminated by a NULL pointer.
const char * const * PQsslAttributeNames(const PGconn *conn);
PQsslStruct
Return a pointer to an SSL-implementation-specific object describing the connection.
void *PQsslStruct(const PGconn *conn, const char *struct_name);
The struct(s) available depend on the SSL implementation in use.
For OpenSSL, there is one struct, available under the name
"OpenSSL", and it returns a pointer to the OpenSSL SSL
struct. 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 = PQsslStruct(dbconn, "OpenSSL"); if (ssl) { /* use OpenSSL functions to access ssl */ }
This structure can be used to verify encryption levels, check server certificates, and more. Refer to the OpenSSL documentation for information about this structure.
PQgetssl
Returns the SSL structure used in the connection, or null if SSL is not in use.
void *PQgetssl(const PGconn *conn);
This function is equivalent to PQsslStruct(conn, "OpenSSL")
. It should not be
used in new applications, because the returned struct is specific
to OpenSSL and will not be available if another SSL implementation
is used. To check if a connection uses SSL, call PQsslInUse
instead, and for more details about
the connection, use PQsslAttribute
.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.