begriffs open source - ai-pg/blob - full-docs/txt/libpq-status.txt

   1
   2 32.2. Connection Status Functions #
   3
   4    These functions can be used to interrogate the status of an existing
   5    database connection object.
   6
   7 Tip
   8
   9    libpq application programmers should be careful to maintain the PGconn
  10    abstraction. Use the accessor functions described below to get at the
  11    contents of PGconn. Reference to internal PGconn fields using
  12    libpq-int.h is not recommended because they are subject to change in
  13    the future.
  14
  15    The following functions return parameter values established at
  16    connection. These values are fixed for the life of the connection. If a
  17    multi-host connection string is used, the values of PQhost, PQport, and
  18    PQpass can change if a new connection is established using the same
  19    PGconn object. Other values are fixed for the lifetime of the PGconn
  20    object.
  21
  22    PQdb #
  23           Returns the database name of the connection.
  24
  25 char *PQdb(const PGconn *conn);
  26
  27    PQuser #
  28           Returns the user name of the connection.
  29
  30 char *PQuser(const PGconn *conn);
  31
  32    PQpass #
  33           Returns the password of the connection.
  34
  35 char *PQpass(const PGconn *conn);
  36
  37           PQpass will return either the password specified in the
  38           connection parameters, or if there was none and the password was
  39           obtained from the password file, it will return that. In the
  40           latter case, if multiple hosts were specified in the connection
  41           parameters, it is not possible to rely on the result of PQpass
  42           until the connection is established. The status of the
  43           connection can be checked using the function PQstatus.
  44
  45    PQhost #
  46           Returns the server host name of the active connection. This can
  47           be a host name, an IP address, or a directory path if the
  48           connection is via Unix socket. (The path case can be
  49           distinguished because it will always be an absolute path,
  50           beginning with /.)
  51
  52 char *PQhost(const PGconn *conn);
  53
  54           If the connection parameters specified both host and hostaddr,
  55           then PQhost will return the host information. If only hostaddr
  56           was specified, then that is returned. If multiple hosts were
  57           specified in the connection parameters, PQhost returns the host
  58           actually connected to.
  59
  60           PQhost returns NULL if the conn argument is NULL. Otherwise, if
  61           there is an error producing the host information (perhaps if the
  62           connection has not been fully established or there was an
  63           error), it returns an empty string.
  64
  65           If multiple hosts were specified in the connection parameters,
  66           it is not possible to rely on the result of PQhost until the
  67           connection is established. The status of the connection can be
  68           checked using the function PQstatus.
  69
  70    PQhostaddr #
  71           Returns the server IP address of the active connection. This can
  72           be the address that a host name resolved to, or an IP address
  73           provided through the hostaddr parameter.
  74
  75 char *PQhostaddr(const PGconn *conn);
  76
  77           PQhostaddr returns NULL if the conn argument is NULL. Otherwise,
  78           if there is an error producing the host information (perhaps if
  79           the connection has not been fully established or there was an
  80           error), it returns an empty string.
  81
  82    PQport #
  83           Returns the port of the active connection.
  84
  85 char *PQport(const PGconn *conn);
  86
  87           If multiple ports were specified in the connection parameters,
  88           PQport returns the port actually connected to.
  89
  90           PQport returns NULL if the conn argument is NULL. Otherwise, if
  91           there is an error producing the port information (perhaps if the
  92           connection has not been fully established or there was an
  93           error), it returns an empty string.
  94
  95           If multiple ports were specified in the connection parameters,
  96           it is not possible to rely on the result of PQport until the
  97           connection is established. The status of the connection can be
  98           checked using the function PQstatus.
  99
 100    PQtty #
 101           This function no longer does anything, but it remains for
 102           backwards compatibility. The function always return an empty
 103           string, or NULL if the conn argument is NULL.
 104
 105 char *PQtty(const PGconn *conn);
 106
 107    PQoptions #
 108           Returns the command-line options passed in the connection
 109           request.
 110
 111 char *PQoptions(const PGconn *conn);
 112
 113    The following functions return status data that can change as
 114    operations are executed on the PGconn object.
 115
 116    PQstatus #
 117           Returns the status of the connection.
 118
 119 ConnStatusType PQstatus(const PGconn *conn);
 120
 121           The status can be one of a number of values. However, only two
 122           of these are seen outside of an asynchronous connection
 123           procedure: CONNECTION_OK and CONNECTION_BAD. A good connection
 124           to the database has the status CONNECTION_OK. A failed
 125           connection attempt is signaled by status CONNECTION_BAD.
 126           Ordinarily, an OK status will remain so until PQfinish, but a
 127           communications failure might result in the status changing to
 128           CONNECTION_BAD prematurely. In that case the application could
 129           try to recover by calling PQreset.
 130
 131           See the entry for PQconnectStartParams, PQconnectStart and
 132           PQconnectPoll with regards to other status codes that might be
 133           returned.
 134
 135    PQtransactionStatus #
 136           Returns the current in-transaction status of the server.
 137
 138 PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
 139
 140           The status can be PQTRANS_IDLE (currently idle), PQTRANS_ACTIVE
 141           (a command is in progress), PQTRANS_INTRANS (idle, in a valid
 142           transaction block), or PQTRANS_INERROR (idle, in a failed
 143           transaction block). PQTRANS_UNKNOWN is reported if the
 144           connection is bad. PQTRANS_ACTIVE is reported only when a query
 145           has been sent to the server and not yet completed.
 146
 147    PQparameterStatus #
 148           Looks up a current parameter setting of the server.
 149
 150 const char *PQparameterStatus(const PGconn *conn, const char *paramName);
 151
 152           Certain parameter values are reported by the server
 153           automatically at connection startup or whenever their values
 154           change. PQparameterStatus can be used to interrogate these
 155           settings. It returns the current value of a parameter if known,
 156           or NULL if the parameter is not known.
 157
 158           Parameters reported as of the current release include:
 159
 160           application_name              scram_iterations
 161           client_encoding               search_path
 162           DateStyle                     server_encoding
 163           default_transaction_read_only server_version
 164           in_hot_standby                session_authorization
 165           integer_datetimes             standard_conforming_strings
 166           IntervalStyle                 TimeZone
 167           is_superuser
 168
 169           (default_transaction_read_only and in_hot_standby were not
 170           reported by releases before 14; scram_iterations was not
 171           reported by releases before 16; search_path was not reported by
 172           releases before 18.) Note that server_version, server_encoding
 173           and integer_datetimes cannot change after startup.
 174
 175           If no value for standard_conforming_strings is reported,
 176           applications can assume it is off, that is, backslashes are
 177           treated as escapes in string literals. Also, the presence of
 178           this parameter can be taken as an indication that the escape
 179           string syntax (E'...') is accepted.
 180
 181           Although the returned pointer is declared const, it in fact
 182           points to mutable storage associated with the PGconn structure.
 183           It is unwise to assume the pointer will remain valid across
 184           queries.
 185
 186    PQfullProtocolVersion #
 187           Interrogates the frontend/backend protocol being used.
 188
 189 int PQfullProtocolVersion(const PGconn *conn);
 190
 191           Applications might wish to use this function to determine
 192           whether certain features are supported. The result is formed by
 193           multiplying the server's major version number by 10000 and
 194           adding the minor version number. For example, version 3.2 would
 195           be returned as 30002, and version 4.0 would be returned as
 196           40000. Zero is returned if the connection is bad. The 3.0
 197           protocol is supported by PostgreSQL server versions 7.4 and
 198           above.
 199
 200           The protocol version will not change after connection startup is
 201           complete, but it could theoretically change during a connection
 202           reset.
 203
 204    PQprotocolVersion #
 205           Interrogates the frontend/backend protocol major version.
 206
 207 int PQprotocolVersion(const PGconn *conn);
 208
 209           Unlike PQfullProtocolVersion, this returns only the major
 210           protocol version in use, but it is supported by a wider range of
 211           libpq releases back to version 7.4. Currently, the possible
 212           values are 3 (3.0 protocol), or zero (connection bad). Prior to
 213           release version 14.0, libpq could additionally return 2 (2.0
 214           protocol).
 215
 216    PQserverVersion #
 217           Returns an integer representing the server version.
 218
 219 int PQserverVersion(const PGconn *conn);
 220
 221           Applications might use this function to determine the version of
 222           the database server they are connected to. The result is formed
 223           by multiplying the server's major version number by 10000 and
 224           adding the minor version number. For example, version 10.1 will
 225           be returned as 100001, and version 11.0 will be returned as
 226           110000. Zero is returned if the connection is bad.
 227
 228           Prior to major version 10, PostgreSQL used three-part version
 229           numbers in which the first two parts together represented the
 230           major version. For those versions, PQserverVersion uses two
 231           digits for each part; for example version 9.1.5 will be returned
 232           as 90105, and version 9.2.0 will be returned as 90200.
 233
 234           Therefore, for purposes of determining feature compatibility,
 235           applications should divide the result of PQserverVersion by 100
 236           not 10000 to determine a logical major version number. In all
 237           release series, only the last two digits differ between minor
 238           releases (bug-fix releases).
 239
 240    PQerrorMessage #
 241           Returns the error message most recently generated by an
 242           operation on the connection.
 243
 244 char *PQerrorMessage(const PGconn *conn);
 245
 246           Nearly all libpq functions will set a message for PQerrorMessage
 247           if they fail. Note that by libpq convention, a nonempty
 248           PQerrorMessage result can consist of multiple lines, and will
 249           include a trailing newline. The caller should not free the
 250           result directly. It will be freed when the associated PGconn
 251           handle is passed to PQfinish. The result string should not be
 252           expected to remain the same across operations on the PGconn
 253           structure.
 254
 255    PQsocket #
 256           Obtains the file descriptor number of the connection socket to
 257           the server. A valid descriptor will be greater than or equal to
 258           0; a result of -1 indicates that no server connection is
 259           currently open. (This will not change during normal operation,
 260           but could change during connection setup or reset.)
 261
 262 int PQsocket(const PGconn *conn);
 263
 264    PQbackendPID #
 265           Returns the process ID (PID) of the backend process handling
 266           this connection.
 267
 268 int PQbackendPID(const PGconn *conn);
 269
 270           The backend PID is useful for debugging purposes and for
 271           comparison to NOTIFY messages (which include the PID of the
 272           notifying backend process). Note that the PID belongs to a
 273           process executing on the database server host, not the local
 274           host!
 275
 276    PQconnectionNeedsPassword #
 277           Returns true (1) if the connection authentication method
 278           required a password, but none was available. Returns false (0)
 279           if not.
 280
 281 int PQconnectionNeedsPassword(const PGconn *conn);
 282
 283           This function can be applied after a failed connection attempt
 284           to decide whether to prompt the user for a password.
 285
 286    PQconnectionUsedPassword #
 287           Returns true (1) if the connection authentication method used a
 288           password. Returns false (0) if not.
 289
 290 int PQconnectionUsedPassword(const PGconn *conn);
 291
 292           This function can be applied after either a failed or successful
 293           connection attempt to detect whether the server demanded a
 294           password.
 295
 296    PQconnectionUsedGSSAPI #
 297           Returns true (1) if the connection authentication method used
 298           GSSAPI. Returns false (0) if not.
 299
 300 int PQconnectionUsedGSSAPI(const PGconn *conn);
 301
 302           This function can be applied to detect whether the connection
 303           was authenticated with GSSAPI.
 304
 305    The following functions return information related to SSL. This
 306    information usually doesn't change after a connection is established.
 307
 308    PQsslInUse #
 309           Returns true (1) if the connection uses SSL, false (0) if not.
 310
 311 int PQsslInUse(const PGconn *conn);
 312
 313    PQsslAttribute #
 314           Returns SSL-related information about the connection.
 315
 316 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
 317
 318           The list of available attributes varies depending on the SSL
 319           library being used and the type of connection. Returns NULL if
 320           the connection does not use SSL or the specified attribute name
 321           is not defined for the library in use.
 322
 323           The following attributes are commonly available:
 324
 325         library
 326                 Name of the SSL implementation in use. (Currently, only
 327                 "OpenSSL" is implemented)
 328
 329         protocol
 330                 SSL/TLS version in use. Common values are "TLSv1",
 331                 "TLSv1.1" and "TLSv1.2", but an implementation may return
 332                 other strings if some other protocol is used.
 333
 334         key_bits
 335                 Number of key bits used by the encryption algorithm.
 336
 337         cipher
 338                 A short name of the ciphersuite used, e.g.,
 339                 "DHE-RSA-DES-CBC3-SHA". The names are specific to each SSL
 340                 implementation.
 341
 342         compression
 343                 Returns "on" if SSL compression is in use, else it returns
 344                 "off".
 345
 346         alpn
 347                 Application protocol selected by the TLS Application-Layer
 348                 Protocol Negotiation (ALPN) extension. The only protocol
 349                 supported by libpq is postgresql, so this is mainly useful
 350                 for checking whether the server supported ALPN or not.
 351                 Empty string if ALPN was not used.
 352
 353           As a special case, the library attribute may be queried without
 354           a connection by passing NULL as the conn argument. The result
 355           will be the default SSL library name, or NULL if libpq was
 356           compiled without any SSL support. (Prior to PostgreSQL version
 357           15, passing NULL as the conn argument always resulted in NULL.
 358           Client programs needing to differentiate between the newer and
 359           older implementations of this case may check the
 360           LIBPQ_HAS_SSL_LIBRARY_DETECTION feature macro.)
 361
 362    PQsslAttributeNames #
 363           Returns an array of SSL attribute names that can be used in
 364           PQsslAttribute(). The array is terminated by a NULL pointer.
 365
 366 const char * const * PQsslAttributeNames(const PGconn *conn);
 367
 368           If conn is NULL, the attributes available for the default SSL
 369           library are returned, or an empty list if libpq was compiled
 370           without any SSL support. If conn is not NULL, the attributes
 371           available for the SSL library in use for the connection are
 372           returned, or an empty list if the connection is not encrypted.
 373
 374    PQsslStruct #
 375           Returns a pointer to an SSL-implementation-specific object
 376           describing the connection. Returns NULL if the connection is not
 377           encrypted or the requested type of object is not available from
 378           the connection's SSL implementation.
 379
 380 void *PQsslStruct(const PGconn *conn, const char *struct_name);
 381
 382           The struct(s) available depend on the SSL implementation in use.
 383           For OpenSSL, there is one struct, available under the name
 384           OpenSSL, and it returns a pointer to OpenSSL's SSL struct. To
 385           use this function, code along the following lines could be used:
 386
 387 #include <libpq-fe.h>
 388 #include <openssl/ssl.h>
 389
 390 ...
 391
 392     SSL *ssl;
 393
 394     dbconn = PQconnectdb(...);
 395     ...
 396
 397     ssl = PQsslStruct(dbconn, "OpenSSL");
 398     if (ssl)
 399     {
 400         /* use OpenSSL functions to access ssl */
 401     }
 402
 403           This structure can be used to verify encryption levels, check
 404           server certificates, and more. Refer to the OpenSSL
 405           documentation for information about this structure.
 406
 407    PQgetssl #
 408           Returns the SSL structure used in the connection, or NULL if SSL
 409           is not in use.
 410
 411 void *PQgetssl(const PGconn *conn);
 412
 413           This function is equivalent to PQsslStruct(conn, "OpenSSL"). It
 414           should not be used in new applications, because the returned
 415           struct is specific to OpenSSL and will not be available if
 416           another SSL implementation is used. To check if a connection
 417           uses SSL, call PQsslInUse instead, and for more details about
 418           the connection, use PQsslAttribute.