PostgreSQL 7.4beta4 Documentation
Prev | Fast Backward | Chapter 27. libpq - C Library | Fast Forward | Next

# 27.2. Connection Status Functions

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.

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

`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 `PQconnectStart` and `PQconnectPoll` with regards to other status codes that might be seen.

`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.

  Caution
  `PQtransactionStatus` will give incorrect results when using a PostgreSQL 7.3 server that has AUTOCOMMIT set to OFF. The server-side autocommit feature has been deprecated and does not exist in later server versions.

`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 (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`.)

`PQprotocolVersion`

  Interrogates 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.)

`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 will include a trailing newline.

`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 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!

`PQgetssl`

  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_SSL` in order to get the prototype for this function. Doing this will also automatically include `ssl.h` from OpenSSL.

Prev | Home | Next
libpq - C Library | Up | Command Execution Functions