Chapter 2. libpq++ - C++ Binding Library

libpq++ is a set of classes that enable client programs to connect to the Red Hat Database backend server. This library encapsulates the libpq C library to make life easier for C++ programmers. Consequently, most of the operational details are established by libpq, so there will be references to the Chapter 1 chapter.

Note

With proper care, a C++ program can use libpq directly, as libpq++ actually does. (Look at the header files in the libpq++ source code for details on how this can be done.)

PGConnection

The PgConnection class represents a connection to the database. If you are only sending simple queries that do not return any data, this is all that you need. However, it is recommended that you use PgDatabase instead. Even in that case, the methods of PgConnection (discussed below) will be used through inheritance.

Table 2-1. PgConnection Interface

MethodDescription
PgConnectionMakes a new connection to a backend database server.
ConnectionBadTest if a connection failed.
StatusObtain the status of a connection
DBNameObtain the name of the current database
ExecSend a query
ExecCommandOKSend a command query and test the result
ExecTuplesOKSend a query and test the result
ErrorMessageObtain the last error message text received from the backend
NotifiesRetrieve the pending notifications
SetNoticeProcessorRegister a handler for notice and warning messages

PgConnection Database Connection Methods

PgConnection

PgConnection makes a new connection to a backend database server.

PgConnection::PgConnection(const char *conninfo)

Although typically called from one of the derived classes, it is possible to open a connection to a backend server by using PgConnection directly. However, only simple queries that return no data can be used in this case.

The conninfo string is the same as for the underlying libpq PQconnectdb function. (See Chapter 1 for details.) Environment variables are also checked to set default database names and default connection parameter values (see the Section called Environment Variables in Chapter 1).

ConnectionBad

ConnectionBad tests if a connection failed.

int PgConnection::ConnectionBad()

Returns TRUE if the connection to the backend server failed.

Status

Status returns the status of the connection.

ConnStatusType PgConnection::Status()

Returns the status of the connection to the backend server. It returns either CONNECTION_OK or CONNECTION_BAD, according to the current state of the connection.

DBName

DBName() gets the name of the current database.

const char *PgConnection::DBName()

Returns a pointer to a string that contains the name of the current database.

PgConnection Query Execution Methods

Exec

Exec sends a query.

ExecStatusType PgConnection::Exec(const char* query)

Exec is used to send a query to the backend server.

Among the possible results are:

PGRES_COMMAND_OK, if the query was a command and was successful
PGRES_TUPLES_OK, if the query successfully returned tuples. Note that this is returned even if there are zero tuples in the result.

Refer to the description of the libpq function PQresultStatus() for the complete set of possible status results and other details.

ExecCommandOk

ExecCommandOk sends a command query and tests result.

int PgConnection::ExecCommandOk(const char *query)

Sends a command query to the backend server. It returns TRUE if the command query succeeds. You can use this to set a backend configuration variable or to commit a transaction. Do not use it for queries that may return data.

ExecTuplesOk

ExecTuplesOk sends a query and the tests result.

int PgConnection::ExecTuplesOk(const char *query)

Sends a query to the backend server. It returns TRUE if the command query succeeds. Note that a query that can return data may succeed and still return zero tuples.

ErrorMessage

ErrorMessage returns the last error message text received from the backend.

const char *PgConnection::ErrorMessage()

Returns a pointer to a string containing the last error message text result received from the backend. You can use this to obtain user-readable information on errors.

PgConnection Asynchronous Notification Methods

Notifies

Notifies retrieves pending notifications.

PGnotify* PgConnection::Notifies()

Returns the next notification from the list of unhandled notification messages received from the backend server.

This method is just a wrapper for the libpq function PQnotify(). Refer to the Section called Asynchronous Notification in Chapter 1 for details, substituting PgConnection::Notifies() for PQnotify() where appropriate.

SetNoticeProcessor

SetNoticeProcessor registers a handler for notice and warning messages.

PQnoticeProcessor PgConnection::SetNoticeProcessor(PQnoticeProcessor proc, void *arg)

Registers a handler for notice and warning messages. This method is just a wrapper for the libpq function PQsetNoticeProcessor(). Refer to its description in the Section called libpq Control Functions in Chapter 1 for details.