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.
 | 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
| Method | Description |
|---|---|
| PgConnection | Makes a new connection to a backend database server. |
| ConnectionBad | Test if a connection failed. |
| Status | Obtain the status of a connection |
| DBName | Obtain the name of the current database |
| Exec | Send a query |
| ExecCommandOK | Send a command query and test the result |
| ExecTuplesOK | Send a query and test the result |
| ErrorMessage | Obtain the last error message text received from the backend |
| Notifies | Retrieve the pending notifications |
| SetNoticeProcessor | Register 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.